From 53d1d8f2801d8142b28877a639c1d6920d5fb950 Mon Sep 17 00:00:00 2001 From: bnewbold Date: Thu, 26 Jul 2012 12:30:29 -0700 Subject: add exmachina HOWTO --- exmachina/HOWTO | 59 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 59 insertions(+) create mode 100644 exmachina/HOWTO diff --git a/exmachina/HOWTO b/exmachina/HOWTO new file mode 100644 index 0000000..f76b344 --- /dev/null +++ b/exmachina/HOWTO @@ -0,0 +1,59 @@ + +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 -- cgit v1.2.3