mirror of
https://github.com/servalproject/serval-dna.git
synced 2024-12-22 22:42:28 +00:00
137 lines
4.9 KiB
Markdown
137 lines
4.9 KiB
Markdown
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.
|
|
|
|
|
|
[Bourne shell]: http://en.wikipedia.org/wiki/Bourne_shell
|