serval-dna/doc/Servald-Configuration.md

Configuring servald
===================

The examples in this document are [Bourne shell][] commands, using standard
quoting and variable expansion.  Commands issued by the user are prefixed with
the shell prompt `$` to distinguish them from the output of the command.
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** 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
and target platform:

* as specified by the `./configure --enable-instance-path=PATH` option when
  **servald** was built from source
* on Android `/data/data/org.servalproject/var/serval-node`
* on other platforms `/var/serval-node`

Running many daemons
--------------------

To run more than one **servald** daemon process on the same device, each daemon
must have its own instance path (and hence its own `serval.conf`).  Set the
`SERVALINSTANCE_PATH` environment variable to a different directory path before
starting each daemon.  Each **servald** daemon will create its own instance
directory (and all enclosing parent directories) if it does not already exist.

Configuration persistence
-------------------------

**servald** stores its configuration option settings in a file called
`serval.conf` in its instance directory, which it reads upon every invocation.
This means that each instance's own option settings persist until changed or
until its `serval.conf` file is altered or removed.

Invalid configuration
---------------------

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 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.

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
periodically checks whether `serval.conf` has changed (by comparing size and
modification time) and attempts to re-load it if it detects a change.  If the
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
---------------------

**servald** logging is controlled by the following config options:

    log.file=PATH
    log.show_pid=BOOLEAN
    log.show_time=BOOLEAN

The `log.file` option names a file to which log messages are appended using the
O\_APPEND option of [open(2)][].  If the file does not exist, **servald** will
create it.  If the `log.file` PATH is not absolute (ie, does not start with
`/`) then it is relative to the instance directory.  If `log.file` is not set
then log messages are sent to standard error.  This will mean that background
**servald** daemons will not log anything, since the standard input, output and
error streams of all background daemon processes are closed.

The `log.show_pid` option, if true, causes all log lines to be prefixed with
the process ID of the logging process.  This can help distinguish between log
messages from different daemon processes sharing the same log file, or, more
commonly, between a daemon process and other **servald** invocations.  The
`log.show_pid` option is true by default.

The `log.show_time` option, if true, causes all log lines to be prefixed with
the date and time, to millisecond resolution if available, of the log message.
The `log.show_time` option is true by default.

Network interfaces
------------------

The **servald** daemon periodically scans its operating system's network
interfaces and uses its `interfaces` configuration option to select which to
ignore and which to use.

For example, the following configuration will use any interface whose name
starts with `eth` (eg, `eth0`, `eth1`) as a 230 MiB/s Ethernet on port 7333,
and any interface whose name starts with `wifi` or `wlan` but is not `wifi0` or
`wlan0` as a 1,000,000 B/s WiFi on the default port number:

    $ servald config set interfaces.0.match 'eth*' \
                     set interfaces.0.type ethernet \
                     set interfaces.0.port 7333 \
                     set interfaces.0.speed 230M \
                     set interfaces.1.match 'wifi0,wlan0' \
                     set interfaces.1.exclude true \
                     set interfaces.2.match 'wifi*,wlan*' \
                     set interfaces.2.type wifi \
                     set interfaces.2.speed 1m

The following configuration is equivalent to the above example, but uses the
“legacy”, single-option syntax (see below):

    $ servald config set interfaces '+eth=ethernet:7333:230M,-wifi0,-wlan0,+wifi=wifi::1m,+wlan=wifi::1m'

The following two equivalent configurations use all available interfaces,
treating all as WiFi 1 MB/s (the default type and speed):

    $ servald config set interfaces.0.match '*'
    $ servald config set interfaces '+'

Network interface rules
-----------------------

As shown in the first example above, the `interfaces` config option contains a
numbered list of *rules* that are applied to all detected system interfaces in
order of ascending number.  The general form of an interface rule is:

    interfaces.UINT.match=PATTERN[, PATTERN ...]
    interfaces.UINT.exclude=BOOLEAN
    interfaces.UINT.type=IFTYPE
    interfaces.UINT.port=PORT
    interfaces.UINT.speed=SPEED
    interfaces.UINT.mdp_tick_ms=UINT_NONZERO
    interfaces.UINT.default_route=BOOLEAN
    interfaces.UINT.dummy=PATH
    interfaces.UINT.dummy_address=IN_ADDR
    interfaces.UINT.dummy_netmask=IN_ADDR
    interfaces.UINT.dummy_filter_broadcasts=BOOLEAN

where:

 * `BOOLEAN` is one of `true`, `false`, `1`, `0`, `yes`, `no`, `on` or `off`
 * `UINT` is an unsigned decimal integer (with no `+` or `-` prefix)
 * `UINT_NONZERO` is an unsigned decimal integer ≥ 1
 * `PATTERN` is a [shell wildcard][] pattern that is matched against the
   interface name using the [fnmatch(3)][] standard library function
 * `PATH` is an absolute or relative file path
 * `IFTYPE` is one of `wifi`, `ethernet`, `catear` or `other`
 * `PORT` is an unsigned decimal integer in the range 1 to 65535
 * `SPEED` is `UINT[SCALE]`, where `SCALE` is a single-letter multiplying
   factor, one of `k` (10^3), `K` (2^10), `m` (10^6), `M` (2^20), `g` (10^9) or
   `G` (2^30)
 * `IN_ADDR` is an Internet address as accepted by [inet_aton(3)][], ie,
   `N.N.N.N` where `N` is an integer in the range 0 to 255.

The `match` and `dummy` options are mutually incompatible.  If both are
specified, it is an error; the rule is omitted from the configuration and
`serval.conf` is treated as invalid (see above).

If a rule specifies a `match` option, then it is used to match real system
interfaces, and if any PATTERN matches, the rule is applied and the interface
is used (or excluded if the rule has a true `exclude` option).

If a rule specifies a `dummy` path, then a dummy interface (see below) is
created if the given file exists.

If the `type` option is given, it sets the IFTYPE of the interface, which will
affect the default settings of the other options, such as `speed` and
`mdp_tick_ms`.  In future it may also change the way the interface behaves, for
example, an `ethernet` interface may automatically assume that broadcast
packets will be filtered out, so will start using MDP unicast protocols
immediately rather than waiting to detect that broadcast packets are not
acknowledged.

The `mdp_tick_ms` option, if set, controls the time interval in milliseconds
between MDB broadcast announcements on the interface.  If set to zero, it
disables MDP announcements altogether on the interface (called “tickless”
mode).  If not set, then the value of the `mdp.iftype.IFTYPE.tick_ms` option is
used.  If that is not set, then **servald** uses a built-in interval that
depends on the IFTYPE.

Network interface “legacy” syntax
---------------------------------

Instead of using the multi-option schema described above, the `interfaces`
configuration option can be set using a less capable “legacy” format, for
compatibility with older config files.  The “legacy” interfaces syntax is a
single text string consisting of a comma-separated list of rule stanzas, each
stanza having one of the following forms:

    +
    -
    +PREFIX=IFTYPE
    +PREFIX=IFTYPE:PORT
    +PREFIX=IFTYPE:PORT:SPEED
    -PREFIX
    +>PATH

The rule `+` matches all interfaces.

The rule `-` excludes all interfaces.

Rules beginning with `+PREFIX` match any interface whose name starts with
`PREFIX`; so for example a rule starting with `+foo` is equivalent to a `match`
option with a single PATTERN of `foo*`

The rule `-PREFIX` excludes interfaces whose name starts with `PREFIX`.

The rule `+>PATH` specifies a dummy interface (see below) with no address or
netmask or broadcast filter.

Interface rules are numbered in the order they appear, and hence applied in
that order.  For example, an `interfaces` option of `+,-eth0` will not reject
the *eth0* interface because the leading `+` will match it first, but `-eth0,+`
will reject *eth0* and accept all others.

The “legacy” format is only provided for backward compatibility and will
eventually be deprecated and removed.  The “legacy” interfaces configuration is
incompatible with the modern form; an instance that uses one cannot use the
other.

Dummy network interface
-----------------------

Sometimes it is helpful to run an isolated group of connected **servald**
instances on a single machine for testing purposes.  To make this possible,
**servald** supports a *dummy* network interface.

A dummy interface is simply a regular file to which all instances append their
network packets.  The file grows without limit.  Each instance advances its own
read pointer through the file, packet by packet.  This simulates a lossless
mesh network with 100% connectivity, ie, all nodes are neighbours.

To use a dummy interface, first create an empty file, eg, `/tmp/dummy`, and for
each servald instance, include the dummy file in its *interfaces* list, eg:

    $ servald config set interfaces.0.dummy '/tmp/dummy'

NOTE: Because dummynets are files, not sockets, the [poll(2)][] system call
does not work on them.  As a result the **servald** daemon main loop has
slightly different behaviour and timing characteristics when a dummynet is in
use.

If a dummy interface's PATH is not absolute (ie, does not start with `/`) then
the PATH is relative to the `server.dummy_interface_dir` config option if set,
otherwise relative to the instance directory.

The following config options adorn a dummy interface with properties that real
interfaces normally obtain directly from the operating system:

    interfaces.UINT.dummy_address=IN_ADDR
    interfaces.UINT.dummy_netmask=IN_ADDR
    interfaces.UINT.dummy_filter_broadcasts=BOOLEAN

If the `dummy_filter_broadcasts` option is true, then the dummy interface will
not carry broadcast packets, to simulate the effect of the WiFi drivers on some
Android devices which filter out broadcast packets.

[Bourne shell]: http://en.wikipedia.org/wiki/Bourne_shell
[open(2)]: http://www.kernel.org/doc/man-pages/online/pages/man2/open.2.html
[shell wildcard]: http://www.kernel.org/doc/man-pages/online/pages/man7/glob.7.html
[fnmatch(3)]: http://www.kernel.org/doc/man-pages/online/pages/man3/fnmatch.3.html
[inet_aton(3)]: http://www.manpagez.com/man/3/inet_aton
[poll(2)]: http://www.kernel.org/doc/man-pages/online/pages/man2/poll.2.html