mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-01-28 08:03:36 +00:00
51 lines
1.9 KiB
Markdown
51 lines
1.9 KiB
Markdown
<!-- -*- mode: markdown; mode: refill; fill-column: 80 -*- -->
|
|
|
|
# Plinth's Design
|
|
|
|
Structurally, Plinth is very simple. It's nothing more than a modular system to
|
|
hook a web UI to the command line and the underlying system.
|
|
|
|
Users enable modules which turn on features on the box and run actions. The
|
|
only data Plinth itself should store are the modules users have and haven't
|
|
enabled. The rest of the information that Plinth interacts with is read from
|
|
and written to the appropriate system configuration files.
|
|
|
|
The most important files in the Plinth project are the modules (in the
|
|
`plinth/modules` directory). Those files create web pages that present
|
|
configuration options to the user and, when the user accepts the configuration,
|
|
runs the relevant action scripts.
|
|
|
|
In the simplest case, the user navigates to http://freedombox.lan/plinth/hello,
|
|
which runs the `plinth/modules/hello` file and displays the output as a web
|
|
page. When the user hits "Submit" on the hello page's form, the hello module
|
|
runs the `plinth/actions/hello` script, which takes the user's input, escapes
|
|
it, removes any suspect input or dangerous options (by applying a **whitelist**
|
|
to the user's input) and then passing the remaining, safe, options to the
|
|
`/bin/hello` program. The module chooses whether or not to display the output,
|
|
and the process is complete.
|
|
|
|
For example:
|
|
|
|
1. User requests http://freedombox.lan/plinth/hello
|
|
|
|
2. Plinth returns the response from `plinth/modules/hello`.
|
|
|
|
3. User submits Hello form.
|
|
|
|
4. Hello module runs `plinth/actions/hello`.
|
|
|
|
5. Hello action removes unsafe input.
|
|
|
|
6. Hello action runs hello system binary with only safe input.
|
|
|
|
7. Hello module may display output from hello binary.
|
|
|
|
8. The hello configuration process is complete.
|
|
|
|
In the above example, control flows in one of two ways:
|
|
|
|
1. `URL -> Module -> User`, where the user hasn't performed an action.
|
|
|
|
2. `URL -> Module -> Action -> Binary -> User`, where the user configures the
|
|
system.
|