plinth - a web front end for administering every aspect of a Freedom Box.
The Freedom Box is a net appliance conceived by Eben Moglen. It contains free software and is designed to allow you to interface with the rest of the net under conditions of protected privacy and data security.
The Plinth front end is a web interface to administer the functions of the Freedom Box. For example, the Freedom Box is a wireless router, and the front end is where you can adjust its settings.
The front end is an extensible web platform for forms and menus. It allows authenticated users to fill out forms. The interface saves the form data and from them generates configuration files for the various services running on the box.
The interface is pluggable. Drop modules into place to add new capabilities to Plinth and your Freedom Box. Replace existing modules to get newer, better shinier functions. The modules will automatically integrate into the existing menu system so you can control all of the box's parts from one central location.
See the INSTALL file for additional details and dependencies. To install run:
$ sudo python3 setup.py install
Run Plinth on the local system with:
$ sudo plinth
See the HACKING file for contributing to Plinth.
The visual look and feel of the front end is described in theme files while Django templates handle layout.
Themes are stored in /themes
. Themes consist entirely of static files (e.g. css, images and javascript) and templates. The default or active theme is linked from /static/default
and templates/default
. If your theme needs to change anything other than these items, you'll need a module (perhaps you'll need both).
There is not currently any support for dynamically choosing a theme at runtime, but it is theoretically possible.
Plinth uses the Django templating system. Templates are stored in /templates
. Template requirements are not specified.
TODO: formalize the template spec so template writers know what they need to implement and where they can deviate.
In this section, I'll attempt to document some of the assumptions the program has about templates. The goal is that if you write a tempate that implements the spec, it should work just fine.
The template is a hierarchical stack, where some templates extend on others. At the base of this stack is base.tmpl
. It should specify sections as blocks (rather than using the variables). This allows other templates to easily override the base template.
err.tmpl
builds on top of page.tmpl
by adding some decoration to the title field.
Plinth expects a content
block. This is where the meat of the content goes. It is the center pane in the default layout. There is a title
block that the program will fill with text describing the current page. There are two bars on the left side: submenu
for the menu and sidebar
where short help texts go. The lowest layer in the navigation is subsubmenu
, displayed on top of the content pane.
All these items are inside of blocks and can be overwritten.
Instead of running "setup.py install" after every source modification, run the following command:
$ sudo python3 setup.py develop
This will install the python package in a special development mode. Run it normally. Any updates to the code (and core package data files) do not require re-installation after every modification.
CherryPy web server also monitors changes to the source files and reloads the server as soon as a file is modified. Hence it is usually sufficient to modify the source and refresh the browser page to see the changes.
Plinth also support running without installing (as much as possible). Simply run it as:
$ sudo ./run --no-daemon --debug
In this mode, Plinth runs in working directory without need for installation. It uses the plinth.conf config file in the working directory if no regular config file (/etc/plinth/plinth.conf) is found. It creates all that data and runtime files in data/var/*.
Note: This mode is supported only in a limited manner. The following are the unknown issues with it:
Help pages are also not built. Run 'make -C doc' manually.
Actions do not work when running as normal user without 'sudo' prefix. You need to add 'actions' directory to be allowed for 'sudo' commands. See data/etc/sudoers.d/plinth for a hint.
Run tests:
$ python3 setup.py test
Run the coverage tool:
$ python3 setup.py test_coverage
Invoking this command generates a binary-format '.coverage' data file in the top-level project directory which is recreated with each run, and writes a set of HTML and other supporting files which comprise the browsable coverage report to the 'plinth/tests/coverage/report' directory. Index.html presents the coverage summary, broken down by module. Data columns can be sorted by clicking on the column header or by using mnemonic hot-keys specified in the keyboard widget in the upper-right corner of the page. Clicking on the name of a particular source file opens a page that displays the contents of that file, with color-coding in the left margin to indicate which statements or branches were executed via the tests (green) and which statements or branches were not executed (red).
Checkout source on the host.
Share the source folder and mount it on virtual machine. This could be done over NFS, SSH-fs or 'Shared Folders' feature on VirtualBox.
Run 'setup.py develop' or 'setup.py install' as described above on guest machine.
Access the guest machine's Plinth web UI from host after setting bridging or NATing for guest virtual machine.
Documentation has been collected into a PDF. It also gets built into smaller files and other formats, including one suitable for install as a man page.
To build the documentation separately, run:
$ make -C doc
Plinth is available from GitHub.
You can report bugs on Plinth's issue tracker.
Feel free to pickup a task by announcing it on the issue. Once you are done, request a merge. For information on placing a merge request, consult GitHub documentation.
Plinth confirms to PEP 8 Python coding standard. You should check your code with pep8 and pylint tools before placing a merge request.
Every module should from gettext import gettext as _
and wrap displayed strings with _(). We don't have the language stuff in place yet (we have no translation files), but we need to put the infrastructure in place for it from the start. Use it like this:
log.error(_("Couldn't import %s: %s"), path, e)
Augeas - Round trip configuration editing utilities
Bootstrap Form - Render Django forms for Twitter Bootstrap
CherryPy3 - WSGI web server since Django does not have proper web server
Coverage - Test coverage measurement and reporting tool
Django - Web application framework for Plinth
Django Stronghold - Middleware to make all views default login required
JQuery - Javascript framework used for convenience
LDAPscripts - Scripts to manage LDAP users and groups
Modernizer - HTML5 and CSS3 feature detection
Python3 - Requires minimum 3.3, tested with version 3.4.1
Twitter Bootstrap - A responsive, mobile first front-end framework
The documentation has the following dependencies:
Markdown - format and style docs
Pandoc - Convert markdown to various formats
PDFLatex - Generate PDF versions of the documentation
GNU Make - Process doc/Makefile.
plinth/main.py: server_dir is actually a url prefix; use a better variable name
Almost all of the front end's functionality is contained in small, separate modules that reside in the directory tree beneath plinth/modules
. Some are installed by default, some are required for operation, and some are entirely optional.
Eventually, the goal is for module to be separate Debian package so installation is as simple as aptitude install freedombox-foo
. As an intermediate step, we'll start scripting module installation. But until then, we can install them manually.
A Plinth module is a Django application with some additional Plinth specific extensions. To enable a module, create a file containing its Python module path into data/etc/plinth/modules-enabled/
. During installation, this file will be copied to /etc/plinth/modules-enabled/
. The file in /etc
will be read during normal execution of Plinth. The file in data/etc/
in the source code directory will be used when running Plinth under the run-without-install mode. Plinth will read the module path from the file in one of these paths during start-up and configure Django to use it as a Django application. With this approach, you can install your Plinth module anywhere on the system and use it in Plinth (just like in Django).
TODO: automatically prune dead links to clear out old module installs. This is something the install scripts should do.
All the coding practices for hacking on the front end also apply to modules. In addition, I try to stick to the other practices listed in this section.
from gettext import gettext as _
and wrap displayed strings with _().The Plinth front end should not directly change any aspect of the underlying operating system. Instead, it should call upon scripts, either by shell command or (for python modules) via import.
Scripts live in /scripts
. They should have the following characteristics:
Do only one thing
Require no interaction beyond passing parameters or commandline arguments
Change the operation of the services and applications of the Freedom Plug and nothing else.
If a script is a python file, it should be both usable from the commandline and importable as a python module.
The scripts should be of general utility. They should be usable to admin and configure the system even in the absence of Plinth. These scripts are the only supported method of making changes to a Freedom Plug, whtether by SSH or via Plinth.
The Freedom Plug is .... insert links...
The Freedom Plug is based on the GNU/Debian operating system. It is not a Linux distribution. It is a network appliance that depends on a series of Debian packages that configure a plug computer to behave as a Freedom Plug.
Plinth is the web-based GUI administration front end for the Freedom Plug.
The current targets are the Guru Plug and the Dream Plug.
If ssh listens on port 2222, bots and scripts will forever attempt to guess your username and password. Maybe your password isn't so strong. Maybe the bots get lucky. Either way, if you allow ssh access on port 22, you're taking a chance that can be avoided quite easily by moving your ssh activity to a slightly more obscure port.
Because ssh activity on these boxes will be limited to programs configured to work specifically with Freedom Plugs as well relatively few people generally using ssh, the coordination necessary to use a non-standard port is easily achieved.
Plinth is Copyright 2011, 2012, 2013, 2014, 2015 Plinth Authors. See Git log in the source repository for a full list of authors. It is distributed under the GNU Affero General Public License, Version 3 or later. A copy of AGPLv3 is available from the Free Software Foundation.
In addition, the documentation to this software is distributed under a Creative Commons Attribution-ShareAlike 3.0 Unported, Version 3 license. This CC-By-SA license is available in both full and summarized versions from Creative Commons.
The documentation to this software is also distributed under the GNU Free Documentation License, version 1.3 or later.
This manual was typed in emacs, formatted using markdown and converted to pdf, html, troff and latex using pandoc and pdflatex.
The complete source code to this manual is available in the 'doc' directory of the Freedom Box front end source distribution.