From 74adb2038ad5c34a0ad7f57b9131c544825a37b4 Mon Sep 17 00:00:00 2001 From: Andrew Bettison Date: Wed, 20 Mar 2013 20:44:12 -0700 Subject: [PATCH] Document 'config dump' command Re-order the documentation sections and add more explanation of how an invalid config file is handled. --- doc/Servald-Configuration.md | 161 ++++++++++++++++++++++------------- 1 file changed, 104 insertions(+), 57 deletions(-) diff --git a/doc/Servald-Configuration.md b/doc/Servald-Configuration.md index cccf093c..cbf26c1d 100644 --- a/doc/Servald-Configuration.md +++ b/doc/Servald-Configuration.md @@ -8,10 +8,19 @@ Single and double quotes around arguments are part of the shell syntax, so are not seen by the command. Lines ending in backslash `\` continue the command on the next line. +Configuration options +--------------------- + +The **servald** configuration is a set of label-value pairs called *options*. +A label is a sequence of one or more alphanumeric words separated by period +characters `.`. A value is a string of characters which is parsed according +to the option's type, for example a decimal integer, a boolean, or an internet +address. + Instance path ------------- -By default, **servald** keeps its configuration, keyring, and other temporary +By default, **servald** stores its configuration, keyring, and other temporary files in its *instance directory*. The instance directory is set at run time by the `SERVALINSTANCE_PATH` environment variable. If this is not set, then **servald** uses a built-in default path which depends on its build-time option @@ -31,54 +40,6 @@ must have its own instance path (and hence its own `serval.conf`). Set the starting each daemon. Each **servald** daemon will create its own instance directory (and all enclosing parent directories) if it does not already exist. -Configuration options ---------------------- - -The **servald** configuration is a set of label-value pairs called *options*. -A label is a sequence of one or more alphanumeric words separated by period -characters `.`. A value is a string of characters which is parsed according -to the option's type, for example a decimal integer, a boolean, or an internet -address. - -To set a configuration option: - - $ servald config set name.of.option 'value' - $ - -To unset a configuration option, returning it to its default value: - - $ servald config del name.of.option - $ - -To examine an option's current value: - - $ servald config get name.of.option - name.of.option=value - $ - -To examine all configuration option settings: - - $ servald config get - interfaces=+eth0,+wifi0 - name.of.option=value - name.of.other_option=value2 - $ - -To list all supported configuration options: - - $ servald config schema - debug.broadcasts=(boolean) - debug.dnahelper=(boolean) - debug.dnaresponses=(boolean) - ... - server.chdir=(absolute_path) - server.dummy_interface_dir=(str_nonempty) - server.respawn_on_crash=(boolean) - $ - -The configuration schema is defined in the [conf_schema.h](../conf_schema.h) -source header file. - Configuration persistence ------------------------- @@ -90,21 +51,36 @@ until its `serval.conf` file is altered or removed. Invalid configuration --------------------- -If `serval.conf` is syntactically malformed or refers to an unsupported option -or contains an invalid value or inconsistency, then every invocation of -**servald** will log explanatory warnings and reject the file, failing with an -error instead of performing the command. The warnings will be logged according -to any valid logging options found in `serval.conf`. +Although `serval.conf` is usually written and read only by **servald**, in +fact it is an external file which could be modified by other means, so +**servald** has no control over its contents. The semantics of the +configuration loading anticipate the possibility of encountering a +syntactically malformed file or an unsupported option or an option with an +invalid value: + + * If `serval.conf` is syntactically malformed, then **servald** will log a + warning, skip the malformed line and continue parsing; + + * If an unsupported configuration option is encountered (which could be a mis- + spelling of a proper option), then **servald** will log a warning and + ignore the option, leaving it with the built-in default value; + + * If a configuration option has an invalid value, then **servald** will log + a warning and ignore the option, leaving it with the built-in default value. + +In all the above cases, **servald** will usually reject the file and the command +will fail with an error instead of executing. The warnings are logged according +to any valid logging options that were successfully parsed. The only exceptions to this rule are the `help` and `stop` commands and the -various `config` commands described above. Those commands will proceed instead +various `config` commands described below. Those commands will proceed instead of failing by omitting the offending config options and using built-in defaults in their place. This means that despite an invalid `serval.conf`, **servald** may still be used to inspect and correct the configuration, and to stop a running daemon. -Configuration of daemons ------------------------- +Invalid configuration of daemons +-------------------------------- As described above, an invalid `serval.conf` will prevent the **servald** `start` command from starting a daemon process. Once the daemon is running, it @@ -114,6 +90,77 @@ re-loaded file is invalid, the daemon rejects it, logs an error, and continues execution with unchanged configuration. However, if the daemon is stopped or killed, it cannot be re-started while the invalid `serval.conf` persists. +Configuration commands +---------------------- + +To set a configuration option: + + $ servald config set name.of.option 'value' + $ + +To unset (remove) a configuration option, returning it to its default value: + + $ servald config del name.of.option + $ + +To examine an option's current value as defined in the `serval.conf` file +(even invalid and unsupported options may be examined): + + $ servald config get name.of.option + name.of.option=value + $ + +To examine all configuration option settings as defined in the `serval.conf` +file (even invalid and unsupported options are included, unlike `config dump` +shown later): + + $ servald config get + interfaces=+eth0,+wifi0 + name.of.option=value + name.of.other_option=value2 + $ + +To list the names and types of all supported configuration options: + + $ servald config schema + debug.broadcasts=(boolean) + debug.dnahelper=(boolean) + debug.dnaresponses=(boolean) + ... + server.chdir=(absolute_path) + server.interface_path=(str_nonempty) + server.respawn_on_crash=(boolean) + $ + +To examine all current *valid* configuration option settings, omitting +invalid and unsupported options from `serval.conf`, shows exactly the effect +that the current configuration would have if used: + + $ servald config dump --full + debug.broadcasts=false + debug.dnahelper=false + debug.dnaresponses=false + ... + rhizome.rhizome_mdp_block_size=512 + server.chdir=/ + server.respawn_on_crash=true + $ + +Omitting the `--full` argument omits all options which have their default +value, leaving only the minimal settings that need be present in `serval.conf` +to produce the current configuration: + + $ servald config dump + debug.rhizome=true + interfaces.0.file=/var/serval-node/dummy + interfaces.0.socket_type=file + rhizome.direct.peer.0.host=129.128.127.126 + server.respawn_on_crash=true + $ + +The configuration schema, with default values, is defined in the +[conf_schema.h](../conf_schema.h) source header file. + Logging configuration ---------------------