Actions

FreedomBox’s web front does not directly change any aspect of the underlying operating system. Instead, it calls upon actions, as shell commands. Actions live in /usr/share/plinth/actions directory. They require no interaction beyond passing command line arguments or taking sensitive arguments via stdin. They change the operation of the services and apps of the FreedomBox and nothing else. These actions are also directly usable by a skilled administrator.

The following documentation for the actions module.

Framework to run specified actions with elevated privileges.

plinth.actions.privileged(func)

Mark a method as allowed to be run as privileged method.

This decorator is to mark any method as needing to be executed with superuser privileges. This is necessary because the primary FreedomBox service daemon runs as a regular user and has no special privileges. When performing system operations, FreedomBox service will either communicate with privileged daemons such as NetworkManager and systemd, or spawns a separate process with higher privileges. When spawning a separate process all the action parameters need to serialized, communicated to the process and then de-serialized inside the process. The return value also need to undergo such serialization and de-serialization. This decorator makes this task simpler.

A call to a decorated method will be serialized into a sudo call (or later into a D-Bus call). The method arguments are turned to JSON and method is called with superuser privileges. As arguments are de-serialized, they are verified for type before the actual call as superuser. Return values are serialized and returned where they are de-serialized. Exceptions are also serialized and de-serialized. The decorator wrapper code will either return the value or raise exception.

For a method to be decorated, the method must have type annotations for all of its parameters and should not use keyword-only arguments. It must also be in a module named privileged.py directly under the application similar to models.py, views.py and urls.py. Currently supported types are bool, int, float, str, dict/Dict, list/List, Optional and Union.

Privileged methods many not output to the stdout as it interferes with the serialization and de-serialization process.