Improve tech doc of MDP and servald config

README.md

@@ -192,12 +192,12 @@ This document is available under the [Creative Commons Attribution 4.0 Internati
 [individ]: http://developer.servalproject.org/files/serval_project_inc-individual.pdf
 [entity]: http://developer.servalproject.org/files/serval_project_inc-entity.pdf
 [DNA]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:dna
-[Serval Keyring]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:keyring
+[Serval Keyring]: ./doc/REST-API-Keyring.md
-[MDP]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:mdp
+[MDP]: ./doc/Mesh-Datagram-Protocol.md
 [VoMP]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:vomp
-[Rhizome]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:rhizome
 [MeshMS]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:meshms
-[Serval Infrastructure]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:serval_infrastructure
+[Rhizome]: ./doc/REST-API-Rhizome.md
+[Serval Infrastructure]: ./doc/Serval-Infrastructure.md
 [JNI]: http://en.wikipedia.org/wiki/Java_Native_Interface
 [Bash]: http://en.wikipedia.org/wiki/Bash_(Unix_shell)
 [pipe]: http://www.kernel.org/doc/man-pages/online/pages/man2/pipe.2.html

doc/Mesh-Datagram-Protocol.md

@@ -1,43 +1,241 @@
 Mesh Datagram Protocol (MDP)
 ============================
-[Serval Project], May 2014
+[Serval Project], March 2016
 
-The [Mesh Datagram Protocol][MDP] is a network protocol developed for the
+The [Mesh Datagram Protocol][MDP] is a [layer 3][] network protocol developed
-[Serval mesh network][], with characteristics that make it particularly
+for the [Serval mesh network][], with characteristics that make it particularly
 suitable for use in Ad Hoc wireless networks, which can suffer high levels of
 packet loss due to weak signal, interference and congestion.
 
-MDP carries [datagram][] packets sent from an originating node to a single
+MDP carries [messages](#mdp-message) from [sender](#sender) to [recipient](#recipient)
-destination node or broadcast to all nodes, guaranteeing only that packet
+[node](#node)s, or [broadcasts](#broadcast) to all nodes, guaranteeing only that
-contents will be verbatim if delivered.  MDP is similar to [UDP][] in terms of
+message contents will be correct if delivered, like a traditional [datagram][]
-the service it provides to applications, but it uses per-hop retransmission and
+service.  MDP is similar to [UDP][] in this respect, but it uses per-[link](#link)
-adaptive link-state routing to boost packet delivery rates, which largely
+retransmission and adaptive link-state routing to boost packet delivery
-immunises it from the cumulative packet loss effect typical of multi-hop
+rates, which largely immunises it from the cumulative packet loss effect
-wireless networks.  This means that its end-to-end, multi-hop packet delivery
+typical of multi-hop wireless networks.  This means that, unlike [Internet
-rate remains usefully high despite adverse network conditions.
+protocols][] its end-to-end, multi-hop packet delivery rate remains usefully
+high despite adverse and changing network conditions.
 
-Overlay Mesh
+Basic concepts
-------------
+--------------
 
-MDP packets are transmitted over a network link using the [Overlay Mesh][]
+### Node
-packet format, which aggregates packets into *overlay frames* which are
-designed to minimise packet size.  Each overlay frame uses back references to
-avoid repeating [SID][] addresses unnecessarily within the frame, and [SID
-abbreviation][] to significantly shorten [SID][] addresses that have been used
-in prior frames.
 
-MDP Interface
+A **node** in the [Serval mesh network][] is a single device having one or more
--------------
+[network interfaces][], running exactly one instance of the [Serval DNA][]
+daemon process that is [configured][] to use those network interfaces.
+
+If a single device were to run several [Serval DNA][] daemon processes, then
+each daemon process would be treated as a separate node, and they should be
+[configured][] to share the device's [network interfaces][] and communicate
+with each other using device-local interfaces such as [local sockets][] or
+[pipes][].
+
+### Link
+
+A **link** in the [Serval mesh network][] is a direct network connection
+between two [node](#node)s, making it possible for a packet sent by the [Serval
+DNA][] daemon on one node to be received directly by the daemon on the other
+node, without traversing any other node.  In other words, a link is a direct
+connection between nodes that supports [layer 2][] protocol functions.
+
+Note that this definition does not rule out an MDP packet passing through a
+non-Serval multi-hop route.  For example, if an [overlay packet](#overlay-packet)
+is routed through a multi-hop [layer 3][] or [layer 4][] network service, such
+as [UDP][], that is still a *single link* as far as MDP is concerned, because
+the packet does not pass through a Serval [node](#node).
+
+### MDP Address
+
+Every [node](#node) in the [Serval mesh network][] uses a unique [Serval ID][]
+(abbreviated to **SID**) as its **MDP address**.
+
+The [Serval DNA][] daemon can have one or many identities in its [keyring][],
+and each identity has its own unique [SID][].  The daemon chooses the first
+identity that it unlocks as the *principal* identity, and that identity's SID
+becomes the node's MDP Address.  If that identity is ever locked, then the
+daemon will choose another currently unlocked identity and change its MDP
+Address to be that SID.
+
+Since each [SID][] identifies a distinct *user* of the network (sometimes
+called a *subscriber*), then strictly speaking, the Serval mesh network could
+be said to carry messages between *users* not between *devices*.  There is
+nothing to prevent a [keyring][] entry from being copied from one device to
+another, thus it is possible for two or more devices to have the same MDP
+Address.  At present, Serval routing does not handle this case, so it could
+cause unwanted effects such as route flapping or dropped messages.
+
+In practice, the “duplicate MDP Address” problem is rare for the time being,
+because the [Serval Mesh][] app for Android does not provide any way for a
+non-expert user to copy the [keyring][] file from one device to another, and
+other Serval devices such as the [Mesh Extender][] are not operated by
+end-users.
+
+### Transmitter
+
+Whenever an [MDP message](#mdp-message) is carried over a single [link](#link)
+from one [node](#node) to another, the **transmitter** link, identified by its
+[MDP address](#mdp-address), is responsible for encapsulating the message in
+such a way as to guarantee its content (error detection) and possibly guarantee
+or at least improve its probability of arrival (retransmission or error
+correction).  The most common encapsulation is the [MDP overlay
+packet](#overlay-packet).
+
+*Transmitter* is a [layer 2][] concept because it concerns data transfer across
+a single [link](#link).
+
+### Receiver
+
+Whenever an [MDP message](#mdp-message) is carried over a single [link](#link)
+from one [node](#node) to another, the **receiver** link, identified by its
+[MDP address](#mdp-address), is responsible for decoding the encapsulated
+message, dealing with data corruption (error checking or correction),
+cooperating with the [transmitter](#transmitter) (ACK to prevent
+retransmission) and de-duplication.
+
+*Receiver* is a [layer 2][] concept because it concerns data transfer across a
+single [link](#link).
+
+### Sender
+
+Every [MDP message](#mdp-message) originates from a single **sender**
+[node](#node), identified by its [MDP address](#mdp-address).  As the message
+passes through many [nodes](#node) to reach its [recipient](#recipient), it
+keeps the same sender address.
+
+*Sender* is a [layer 3][] concept because it specifies an end point of a
+multi-[link](#link) route.
+
+### Recipient
+
+Every [MDP message](#mdp-message) that is not a [broadcast](#broadcast) message
+is destined for a single **recipient** [node](#node), identified by its [MDP
+address](#mdp-address).  The message may pass through many [nodes](#node) to
+reach its recipient.
+
+*Recipient* is a [layer 3][] concept because it specifies an end point of a
+multi-[link](#link) route.
+
+### MDP message
+
+The smallest unit of data transported by MDP is the **MDP message**.  The MDP
+message is a [layer 3][], or end-to-end concept: the [Serval mesh network][]
+carries each MDP message from its [sender](#sender) to its
+[recipient](#recipient), routing via as many intermediate [nodes](#node) as
+necessary, without the messages having to specify any intermediate nodes.
+
+An MDP message consists of a variable-length header, followed by a
+variable-length payload which may be [encrypted][] and [signed][].  Most fields
+in the MDP message header are optional, depending on the initial byte of bit
+flags:
+
+| bytes  | name               | present if              | meaning                                               |
+|:------:|:--------------     |:----------------------- |:----------------------------------------------------- |
+| 1      | FLAGS              |                         | [message flags](#mdp-message-flags)                   |
+| 1-33   | Sender SID         | `!SENDER_SAME`          | the [sender's](#sender) [address](#mdp-address)       |
+| 1-33   | Recipient SID      | `!BROADCAST`            | the [recipient's](#recipient) [address](#mdp-address) |
+| 8      | broadcast sequence | `BROADCAST && !ONE_HOP` | [broadcast](#broadcast) message's sequence number     |
+| 1      | TTL and QoS        | `!ONE_HOP`              | time-to-live counter and service type                 |
+| 2      | payload size       |                         | number of bytes in payload                            |
+| 0-max  | payload            |                         |                                                       |
+
+### MDP message flags
+
+The single FLAGS byte at the start of the [MDP message](#mdp-message) header
+contains the following bits (bit numbers start with 0 = LSB):
+
+|  bit  | symbol        | meaning                                                                                       |
+|:-----:|:------------- | --------------------------------------------------------------------------------------------- |
+|   0   | `SENDER_SAME` | the [transmitter](#transmitter) is the [sender](#sender)                                      |
+|   1   | `BROADCAST`   | message is [broadcast](#broadcast); has no [recipient](#recipient)                            |
+|   2   | `ONE_HOP`     | message is on last [link](#link), so the [receiver](#receiver) is the [recipient](#recipient) |
+|   3   | (unused)      | transmitter must set to zero; recipient must ignore                                           |
+|   4   | `CIPHERED`    | payload is [encrypted][]                                                                      |
+|   5   | `SIGNED`      | payload is [signed][]                                                                         |
+|   6   | `ACK_SOON`    | transmitter will re-transmit very soon                                                        |
+|   7   | (unused)      | transmitter must set to zero; recipient must ignore                                           |
+
+* The `SENDER_SAME` flag is set on the first outbound [link](#link) of a message's
+  trajectory if the message is encapsulated in an [overlay
+  packet](#overlay-packet); ie, the [Sender SID](#sender) is identical to the
+  overlay packet's [Transmitter SID](#transmitter).  In this case the *Sender
+  SID* field is omitted from the message's header, to avoid unnecessary
+  duplication.
+
+* The `BROADCAST` flag indicates a [broadcast](#broadcast) message that is sent
+  to all nodes.  If the `BROADCAST` flag is set, the [Recipient
+  SID](#recipient) message header field is absent, and the *broadcast sequence*
+  header field is present unless the `ONE_HOP` flag is also set (see below).
+
+* The `ONE_HOP` flag is set to indicate that the message is not to be forwarded
+  by the receiver; this occurs in the following cases:
+
+  * The message is on the last [link](#link) of its trajectory to its
+    [recipient](#recipient) and is encapsulated in an [overlay
+    packet](#overlay-packet); ie, the [Recipient SID](#sender) is identical to
+    the overlay packet's [Receiver SID](#receiver).  In this case the
+    *Recipient SID* field is omitted from the message's header, to avoid
+    unnecessary duplication.
+
+  * The message is a [broadcast](#broadcast) message that need not propagate
+    beyond the [receiver](#receiver); ie, it only has one [link](#link) to live
+    (TTL = 1).  In this case, the *broadcast sequence* and *TTL and QoS* fields
+    are omitted from the message's header to save space.
+
+* The `CIPHERED` flag is set if the message's payload is [encrypted][] using
+  the [Recipient SID](#recipient) as public key; only the recipient possesses
+  the private key (secret), so only the recipient can decrypt the payload.  The
+  `CIPHERED` and `BROADCAST` flags are mutually exclusive; all
+  [broadcast](#broadcast) messages are unciphered.
+
+* The `SIGNED` flag is set if the message's payload is [signed][] by the
+  sender; anyone can verify the signature using the [Sender SID](#sender)
+  public key, but only the sender possesses the private key (secret), so only
+  the sender can produce the signature.
+
+* The `ACK_SOON` flag is set if the [transmitter](#transmitter) will re-send
+  the message unless receiving an ACK for the message within the next few
+  [overlay packet](#overlay-packet)s.  This flag is typically used on
+  low-latency, high quality links to maximise throughput by avoiding redundant
+  re-transmissions.
+
+### Broadcast
+
+TBC
+
+### Overlay Packet
+
+MDP transmits a [MDP message](#mdp-message) over a [link](#link) by
+encapsulating it into an **overlay packet** (also called **MDP packet** or
+**overlay frame**).  The MDP overlay packet is a [layer 2][] concept; it is
+only concerned with transporting MDP messages across a single link to a
+neighbouring *peer* node.  Once an overlay packet arrives, the receiver
+unpacks all of its MDP messages, consumes those for which it (or one of its
+zero-hop identities) is the [recipient](#recipient) and independently
+routes each of the remaining messages to its next appropriate peer.
+
+Every overlay packet contains the [MDP address](#mdp-address)es of its
+[transmitter](#transmitter) and [receiver](#receiver).
+
+An overlay packet may contain many MDP messages.  The header of each MDP
+message in an overlay packet is constructed afresh when it is embedded into the
+packet, setting its [flag bits](#mdp-message-flags) and using [SID
+abbreviation][] to omit or reduce duplicated [SID][]s, in order to conserve
+link bandwidth where possible.
+
+MDP Client Interface
+--------------------
 
 The [Serval DNA][] daemon provides an interface that allows client applications
 to send and receive individual MDP packets on the [Serval mesh network][]
 without having to construct and disassemble Overlay Mesh frames on their own.
 
-MDP API
+MDP Client API
--------
+--------------
 
-The MDP API is a [C language][] [API][] that an application can use to send and
+The *MDP Client API* is a [C language][] [API][] that an application can use to
-receive MDP packets over the [Serval mesh network][] using the
+send and receive MDP packets over the [Serval mesh network][] using the
 [interface](#mdp-interface) provided by the [Serval DNA][] daemon.
 
 -----
@@ -49,12 +247,26 @@ Available under the [Creative Commons Attribution 4.0 International licence][CC
 [Serval Project]: http://www.servalproject.org/
 [CC BY 4.0]: ../LICENSE-DOCUMENTATION.md
 [Serval mesh network]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:mesh_network
-[Serval DNA]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:servaldna:
+[Serval DNA]: ../README.md
+[Serval Mesh]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:servalmesh:
+[Mesh Extender]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:meshextender:
 [MDP]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:mdp
 [datagram]: http://en.wikipedia.org/wiki/Datagram
+[Internet protocols]: https://en.wikipedia.org/wiki/Internet_protocol_suite
+[layer 2]: https://en.wikipedia.org/wiki/Data_link_layer
+[layer 3]: https://en.wikipedia.org/wiki/Network_layer
+[layer 4]: https://en.wikipedia.org/wiki/Transport_layer
 [UDP]: http://en.wikipedia.org/wiki/User_Datagram_Protocol
-[Overlay Mesh]: ./Overlay-Mesh.md
+[MTU]: http://en.wikipedia.org/wiki/Maximum_transmission_unit
-[SID]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:sid
+[Serval ID]: ./REST-API-Keyring.md#serval-id
+[SID]: ./REST-API-Keyring.md#serval-id
 [SID abbreviation]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:sid_abbreviation
+[configured]: ./Servald-Configuration.md
+[network interfaces]: ./Servald-Configuration.md#network-interfaces
+[keyring]: ./REST-API-Keyring.md
+[encrypted]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:security_framework
+[signed]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:security_framework
+[local sockets]: https://en.wikipedia.org/wiki/Unix_domain_socket
+[pipes]: https://en.wikipedia.org/wiki/Pipeline_(Unix)
 [C language]: http://en.wikipedia.org/wiki/C_(programming_language)
 [API]:http://en.wikipedia.org/wiki/Application_programming_interface

doc/Servald-Configuration.md

@@ -1,13 +1,29 @@
 Configuring Serval DNA
 ======================
-[Serval Project][], April 2013
+[Serval Project][], March 2016
 
+Introduction
+------------
+
+The [Serval DNA][] daemon, also called **servald**, is designed to operate in a
+wide variety of environments (GNU/Linux, Android, Solaris, iOS) with different
+kinds of network links (Wi-Fi, Ethernet, packet radio, dummy), different levels
+of resources (CPU, memory, persistent storage) and for different purposes
+(development, testing, deployment).
+
+In order to adapt to all of these requirements, **servald** can be *configured*
+to adjust its behaviour in the following areas:
+
+  * [file system layout](#file-system-layout)
+  * [logging](#logging)
+  * [network interfaces](#network-interfaces)
+  * [Rhizome][]
 
 Configuration options
 ---------------------
 
-The **servald** configuration is an unordered set of LABEL=VALUE pairs called
+The [Serval DNA][] configuration is expressed as an unordered set of
-*options*.  For example:
+textual LABEL=VALUE pairs called *options*.  For example:
 
     debug.verbose=true
     interfaces.0.file=/var/tmp/serval/dummy
@@ -128,36 +144,42 @@ configuration and the file contents will once again be consistent.
 Daemon instances
 ----------------
 
-It order to support more than one daemon running on the same host, each daemon
+It order to support more than one [Serval DNA][] daemon running on the same
-can be configured to use its own *instance directory*, as follows:
+host, each daemon can be configured to use its own *instance directory*, as
+follows:
 
-  * A daemon's instance directory can be set at run time by setting the
+  * A daemon's [instance directory](#instance-directory) can be set at run time
-    `SERVALINSTANCE_PATH` environment variable prior to starting the daemon.
+    by setting the `SERVALINSTANCE_PATH` environment variable prior to starting
-    This overrides all default paths.  Once a daemon is running, the only way
+    the daemon.  This overrides the daemon's [standard file system
-    to change its instance directory is to stop it and start another daemon
+    layout](#standard-file-system-layout).  Once a daemon is running, the only
+    way to change its instance directory is to stop it and start another daemon
     with a different value for the environment variable.
 
-  * If the instance directory is not set at run time, then if **servald** was
+  * If no [instance directory](#instance-directory) is set at run time, then if
-    built with the `./configure INSTANCE_PATH=DIR` option, then the **servald**
+    **servald** was built with the `./configure INSTANCE_PATH=DIR` option, then
-    executable will use the instance directory in `DIR` by default.  The [FHS
+    the **servald** executable will use the instance directory in `DIR` by
-    paths](#fhs-paths) will never be used.
+    default, not the [standard file system layout](#standard-file-system-layout).
 
   * On an Android system, if none of the above are used, then **servald** will
-    use the instance directory `/data/data/org.servalproject/var/serval-node`
+    use the [instance directory](#instance-directory)
-    by default.  The [FHS paths](#fhs-paths) will never be used.
+    `/data/data/org.servalproject/var/serval-node`, not the [standard file
+    system layout](#standard-file-system-layout).
 
-  * If none of the above apply, then there is no *instance directory*.
+  * If none of the above apply, then the daemon uses the [standard file system
-    Instead, [FHS paths](#fhs-paths) are used.  Only one daemon can run in this
+    layout](#standard-file-system-layout).  Only one daemon can run with the
-    situation on the same host, since the single, common PID file will prevent
+    standard layout on a host, since the single, common PID file will prevent
     more than one being started.
 
-The main use for multiple instances on a single host is for testing, and this
+The main use for multiple instances on a single host is for testing, and so the
-is used extensively in the automated test suite.  Deployments other than
+[instance directory](#instance-directory) is used extensively in the [automated
-Android are unlikely to use an instance path, so the [FHS paths](#fhs-paths)
+tests][].  Environments other than Android are unlikely to use an instance
-are most likely to be used in practice.
+path, so the [standard file system layout](#standard-file-system-layout) is
+most likely to be used in most other deployments.
 
-FHS paths
+File system layout
----------
+------------------
+
+### Standard file system layout
 
 By default, **servald** locates its files such as configuration, logs, Rhizome
 storage, etc.  in accordance with the [Filesystem Heirarchy Standard][FHS] 2.3:
@@ -223,8 +245,7 @@ on the built-in defaults as overridden by configuration settings and run-time
 environment variables available to the command.  This command will work even if
 configuration is defective, so is a useful diagnostic tool.
 
-Instance directory paths
+### Instance directory
-------------------------
 
 If **servald** is started with an *instance directory*, then all configuration,
 state, and temporary files are stored in or beneath that directory, denoted
@@ -507,26 +528,43 @@ where:
  * 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 `file` options are mutually incompatible.  If both are set, it
+Exactly one of the [match](#match) and [file](#file) options must be set on an
-is an error; the interface rule is omitted from the configuration and
+interface.  If neither or both are set, it is an error; the whole interface
-`serval.conf` is treated as defective (see above).  If neither are set, it is
+rule is omitted from the configuration and `serval.conf` is treated as
-also an error.
+defective (see above).
+
+### `match`
 
 If a rule specifies a `match` option, then each PATTERN is applied to the names
 of the real system interfaces using the [fnmatch(3)][] standard library
-function.  If any PATTERN matches, then the rule's `exclude` option is checked:
+function.  If any PATTERN matches, then the rule's [exclude](#exclude) option
-if true, then the interface is not activated, otherwise a socket on that system
+is checked: if true, then the interface is not activated, otherwise a socket on
-interface is opened and the interface's `socket_type` is set to `dgram`.  (It
+that system interface is opened and the interface's
-is invalid to explicitly set `socket_type` to other than `dgram` for a match
+[socket\_type](#socket_type) is implicitly set to `dgram`.  (It is invalid to
-interface.)
+explicitly set `socket_type` to other than `dgram` for a match interface.)
 
-If a rule specifies a `file` path, then an interface is created *if the given
+### `exclude`
-file exists*.  The interface's `socket_type` determines how the file is written
-and read:
 
-  * `file` (the default) creates a “dummy” interface for closed communication
+If a rule sets its a `exclude` option to *true*, then the interface will never
-    with other **servald** daemons on the same host -- see below.  If the file
+be activated.  This can be useful for writing negative [match](#match) rules to
-    does not exist, a warning is logged and the interface is not activated.
+exclude specific interface names before a final match-all rule.
+
+### `file`
+
+If a rule specifies a `file` path, then an interface is created *only if the
+given file exists*.  The rule's [exclude](#exclude) option is ignored.  The
+interface's [socket\_type](#socket_type) determines how the file is written and
+read.
+
+### `socket_type`
+
+An interface's `socket_type` determines how the its socket file descriptor is
+written and read: descriptor is written and read:
+
+  * `file` (the default) creates a [dummy interface](#dummy-interface) for
+    closed communication with other **servald** daemons on the same host.  If
+    the dummy file does not exist, a warning is logged and the interface is not
+    activated.
 
   * `stream` reads and writes the file as though it were a [character special
     device][].  If the file does not exist, an error is logged and the
@@ -534,12 +572,17 @@ and read:
 
   * `dgram` is not valid for a file interface.
 
-The `type` option only affects the default settings the `packet_interval` and
+### `type`
-`mdp_tick_ms` options, for convenience.  In future it may also change the way
+
-the interface behaves, for example, an `ethernet` interface may automatically
+The `type` option affects the default settings of the
-assume that broadcast packets will be filtered out, so will start using MDP
+[packet\_interval](#packet_interval) and [mdp\_tick\_ms](#mdp_tick_ms) options,
-unicast protocols immediately rather than waiting to detect that broadcast
+for convenience.  In future it may also change the way the interface behaves,
-packets are not acknowledged.
+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.
+
+### `packet_interval`
 
 The `packet_interval` option controls the maximum rate at which packets are
 tramsmitted on the interface.  It sets the *average* interval, in microseconds,
@@ -548,37 +591,49 @@ transmit a packet, then packets will be sent at maximum speed with no
 intervening delay.  Otherwise, delays are inserted between packets as needed to
 keep to the average.
 
+### `mdp_tick_ms`
+
 The `mdp_tick_ms` option 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.
+[type](#type).
 
-The `encapsulation` option controls how MDP packets are written to the
+### `encapsulation`
+
+The `encapsulation` option controls how [MDP message][]s are written to the
 interface's socket:
-  * `overlay` (the default) stuffs as many MDP packets as it can into each
+
-    [UDP][] frame, to avoid wasting bandwidth on conventional [Wi-Fi][]
+  * `overlay` (the default) aggregates as many messages as possible into
-    interfaces which have a fixed packet size (the [IEEE 802.11][] [MTU][])
+    [overlay packet][]s that fit into each [UDP][] packet, in order to take
-    over the air;
+    full advantage of the bandwidth on conventional [Wi-Fi][] interfaces which
-  * `single` sends each MDP packet on its own to the socket using [SLIP][]
+    have a fixed packet size (the [IEEE 802.11][] [MTU][]) over the air;
+
+  * `single` sends each [MDP message][] on its own to the socket using [SLIP][]
     encoding, and is suited to data links with a variable packet size on the
     air (eg, a serial connection to a [packet radio][] modem).
 
-The `default_route` option, if true, causes all MDP packets with an unresolved
+### `default_route`
-recipient address (SID) to be sent to this interface instead of just dropped.
+
-This will allow the node to use [Serval Infrastructure][] to route its packets.
+The `default_route` option, if true, causes all [MDP message][]s with an
-Many interfaces may have the `default_route` set to true, but only the first
+unresolved [recipient][] address ([SID][]) to be sent to this interface instead
-one will be used as the default route.
+of just dropped.  This will allow the node to use [Serval Infrastructure][] to
+route its packets.  Many interfaces may have the `default_route` set to true,
+but only the first one will be used as the default route.
+
+### `prefer_unicast`
 
 The `prefer_unicast` option, if true, causes the interface to send to unicast
 IP addresses instead of the broadcast IP address if both have been observed to
 reach the destination.
 
-The `send_broadcasts` option, if false, prevents the interface from sending any
+### `send_broadcasts`
-broadcast packets whenever a recipient address (SID) cannot be resolved to an
+
-interface.  Normally, any MDP packet to an unresolvable recipient gets
+Normally, any [MDP message][] with an unresolvable [recipient][] gets broadcast
-broadcast on all active interfaces.
+on all active interfaces.  The `send_broadcasts` option, if *false*, prevents
+the interface from sending any broadcast packets whenever a recipient address
+(SID) cannot be resolved to an interface.
 
 Network interface “legacy” syntax
 ---------------------------------
@@ -620,8 +675,8 @@ eventually be deprecated and removed.  The “legacy” interfaces configuration
 incompatible with the modern form; an instance that uses one cannot use the
 other.
 
-Dummy network interface
+Dummy 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,
@@ -671,15 +726,23 @@ unless there is traffic explicitly sent to it).
 
 -----
 **Copyright 2013 Serval Project Inc.**  
+**Copyright 2016 Flinders University**  
 ![CC-BY-4.0](./cc-by-4.0.png)
 Available under the [Creative Commons Attribution 4.0 International licence][CC BY 4.0].
 
 
 [Serval Project]: http://www.servalproject.org/
 [CC BY 4.0]: ../LICENSE-DOCUMENTATION.md
+[Serval DNA]: ../README.md
+[SID]: ./REST-API-Keyring.md#serval-id
 [Serval Infrastructure]: ./Serval-Infrastructure.md
+[Rhizome]: ./REST-API-Rhizome.md
+[recipient]: ./Mesh-Datagram-Protocol.md#recipient
+[MDP message]: ./Mesh-Datagram-Protocol.md#mdp-message
+[overlay packet]: ./Mesh-Datagram-Protocol.md#overlay-packet
 [US-ASCII]: http://en.wikipedia.org/wiki/ASCII
 [Bourne shell]: http://en.wikipedia.org/wiki/Bourne_shell
+[FHS]: https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard
 [isspace(3)]: http://linux.die.net/man/3/isspace
 [shell wildcard]: http://www.kernel.org/doc/man-pages/online/pages/man7/glob.7.html
 [open(2)]: http://www.kernel.org/doc/man-pages/online/pages/man2/open.2.html
@@ -695,3 +758,4 @@ Available under the [Creative Commons Attribution 4.0 International licence][CC
 [packet radio]: http://en.wikipedia.org/wiki/Packet_radio
 [character special device]: http://en.wikipedia.org/wiki/Device_file#Character_devices
 [FHS]: https://en.wikipedia.org/wiki/Filesystem_Hierarchy_Standard
+[automated tests]: ./Testing.md