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, not part of the argument itself.

Instance path

By default, servald keeps its configuration, keyring, and other temporary files in its instance directory. The default instance directory depends on the target platform:

on Android /data/data/org.servalproject/var/serval-node
on other platforms /var/serval-node

The default instance directory is overridden by the SERVALINSTANCE_PATH environment variable.

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. If an option is given an invalid value, eg, an option that requires a positive decimal integer value is given a non-decimal string, then servald will log an error or warning and use the option's default setting instead.

To set a configuration option:

$ servald config set name.of.option 'value'
$

To examine an option's current setting:

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

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

Running many daemons

To run more than one servald daemon process on the same device, each daemon must have its own instance path. 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.

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.

Eg, to use two interfaces, eth0 a 230 MiB/s ethernet on port 7333 and wifi0 a 1 MB/s WiFi device:

$ servald config set interfaces '+eth0=ethernet:7333:230M,+wifi0=wifi'

Eg, to use all available interfaces, treating all as WiFi 1 MB/s

$ servald config set interfaces '+'

The interfaces configuration option accepts a comma-separated list of interface specifications, each having one of the following forms:

+
-name
+name=type
+name=type:port
+name=type:port:speed
+>path

where:

name is the operating system's label for a network interface,
type is one of wifi, ethernet, other, catear (default is wifi)
port is a TCP port number (default is 4110)
speed is the interface's bytes per second capacity (default 1 MB/s), expressed in the form Nu where N is a decimal integer and u is a unit, one of k (10^3), K (2^10), m (10^6), M (2^20), g (10^9) or G (2^30)

The form + matches all interfaces.

The form -name rejects any interfaces called name.

The forms beginning with +name match any interface called name.

The form +>path specifies a dummy interface (see below).

Interface specifications are applied in the order they appear. For example, an interfaces list of +,-eth0 will not reject the eth0 interface because the leading + will match it first, but -eth0,+ will reject eth0 and accept all others.

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 '+>/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.

4.9 KiB Raw Blame History