mirror of
https://github.com/freedombox/FreedomBox.git
synced 2026-07-22 11:59:33 +00:00
60 lines
2.9 KiB
Plaintext
60 lines
2.9 KiB
Plaintext
|
|
HOWTO: Use exmachina in Plinth to Change Configuration and Restart Services
|
|
-----------------------------------------------------------------------------
|
|
|
|
exmachina is the name of a small and simple privilege separation layer that
|
|
lets Plinth (running as a web application with user/group www-data) edit
|
|
FreedomBox system configuration (which requires root privileges). The Augeas
|
|
library is used to provide a uniform interface to *most* configuration files in
|
|
/etc/, and a wrapper around init.d scripts allows services to be restarted
|
|
(which is often the way to have configuration changes go live).
|
|
|
|
The exmachina daemon and client library is initialized when Plinth starts, and
|
|
is accessible in Plinth code through the "cfg" global variable:
|
|
|
|
import cfg
|
|
cfg.exmachina.initd.restart("networking")
|
|
|
|
Existing on-disk configuration settings can be read back through the "get"
|
|
action, and files/settings can be found with the "match" method. For example,
|
|
the following would print out a list of all the files in /etc/ with
|
|
augeas-editing support, and then print the system's hostname according to
|
|
/etc/hostname (a minimal one-line configuration file):
|
|
|
|
for fname in c.call.augeas_match("/files/etc/*"):
|
|
print fname
|
|
cfg.exmachina.augeas.get("/files/etc/hostname/*")
|
|
|
|
The mutating Augeas actions ("set", "insert", "remove", etc) operate on an
|
|
in-memory cache of the configuration files; to commit all changes (for all
|
|
modified files) to disk, use the "save" action. The following would set the
|
|
local hostname to fluffy.example.net, and then commit that change to disk.
|
|
|
|
cfg.exmachina.augeas.set("/files/etc/hostname/*", "fluffy.example.net")
|
|
cfg.exmachina.augeas.save()
|
|
|
|
After the above, the /etc/hostname file will be updated, but running network
|
|
services will not have picked up on the change. To have changes that have been
|
|
written to disk actually take effect, the "initd" module allows access to
|
|
restarting system services. In the case of hostnames, in debian there exists a
|
|
helper script called "/etc/init.d/hostname.sh", so the following would be used
|
|
to update all network daemons to a new hostname:
|
|
|
|
cfg.exmachina.initd.restart("hostname.sh")
|
|
|
|
Augeas makes some effort to prevent partial writes or configuration file
|
|
corruption, and in some cases provides basic type checking. However, it does
|
|
not do any logical error detection or correction. For example, two separate
|
|
services could be configured to try and listen on the same port, or an invalid
|
|
hostname could be specified (eg, "&.^$#"). Application code in Plinth is
|
|
responsible for ensuring the logical correctness of configuration changes.
|
|
|
|
If there is a serious problem executing an exmachina method call (eg, tried to
|
|
restart a non-existent service), a bjsonrpc.exceptions.ServerError exception
|
|
will be raised, with the actual exception message (but not the traceback)
|
|
passed through.
|
|
|
|
Reading:
|
|
- Augeas API notes: http://augeas.net/docs/api.html
|
|
- exmachina repository: https://github.com/bnewbold/exmachina
|