ExternalVendorCode/serval-dna
1
0
Fork 0
mirror of https://github.com/servalproject/serval-dna.git synced 2024-12-18 20:57:56 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Improve tech doc of MDP and servald config

Browse Source
This commit is contained in:
Andrew Bettison 2016-02-29 16:19:59 +10:30
parent 34e2e8d4bc
commit f53be7c6a6
3 changed files with 373 additions and 97 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
README.md
View File

@ -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
[MDP]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:mdp
[Serval Keyring]: ./doc/REST-API-Keyring.md
[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

268
doc/Mesh-Datagram-Protocol.md
View File

@ -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
[Serval mesh network][], with characteristics that make it particularly
The [Mesh Datagram Protocol][MDP] is a [layer 3][] network protocol developed
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
destination node or broadcast to all nodes, guaranteeing only that packet
contents will be verbatim if delivered. MDP is similar to [UDP][] in terms of
the service it provides to applications, but it uses per-hop retransmission and
adaptive link-state routing to boost packet delivery rates, which largely
immunises it from the cumulative packet loss effect typical of multi-hop
wireless networks. This means that its end-to-end, multi-hop packet delivery
rate remains usefully high despite adverse network conditions.
MDP carries [messages](#mdp-message) from [sender](#sender) to [recipient](#recipient)
[node](#node)s, or [broadcasts](#broadcast) to all nodes, guaranteeing only that
message contents will be correct if delivered, like a traditional [datagram][]
service. MDP is similar to [UDP][] in this respect, but it uses per-[link](#link)
retransmission and adaptive link-state routing to boost packet delivery
rates, which largely immunises it from the cumulative packet loss effect
typical of multi-hop wireless networks. This means that, unlike [Internet
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][]
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.
### Node
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
receive MDP packets over the [Serval mesh network][] using the
The *MDP Client API* is a [C language][] [API][] that an application can use to
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
[SID]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:sid
[MTU]: http://en.wikipedia.org/wiki/Maximum_transmission_unit
[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

194
doc/Servald-Configuration.md
View File

@ -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
*options*. For example:
The [Serval DNA][] configuration is expressed as an unordered set of
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
can be configured to use its own *instance directory*, as follows:
It order to support more than one [Serval DNA][] daemon running on the same
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
`SERVALINSTANCE_PATH` environment variable prior to starting the daemon.
This overrides all default paths. Once a daemon is running, the only way
to change its instance directory is to stop it and start another daemon
* A daemon's [instance directory](#instance-directory) can be set at run time
by setting the `SERVALINSTANCE_PATH` environment variable prior to starting
the daemon. This overrides the daemon's [standard file system
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
built with the `./configure INSTANCE_PATH=DIR` option, then the **servald**
executable will use the instance directory in `DIR` by default. The [FHS
paths](#fhs-paths) will never be used.
* If no [instance directory](#instance-directory) is set at run time, then if
**servald** was built with the `./configure INSTANCE_PATH=DIR` option, then
the **servald** executable will use the instance directory in `DIR` by
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`
by default. The [FHS paths](#fhs-paths) will never be used.
use the [instance directory](#instance-directory)
`/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*.
Instead, [FHS paths](#fhs-paths) are used. Only one daemon can run in this
situation on the same host, since the single, common PID file will prevent
* If none of the above apply, then the daemon uses the [standard file system
layout](#standard-file-system-layout). Only one daemon can run with the
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
is used extensively in the automated test suite. Deployments other than
Android are unlikely to use an instance path, so the [FHS paths](#fhs-paths)
are most likely to be used in practice.
The main use for multiple instances on a single host is for testing, and so the
[instance directory](#instance-directory) is used extensively in the [automated
tests][]. Environments other than Android are unlikely to use an instance
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
is an error; the interface rule is omitted from the configuration and
`serval.conf` is treated as defective (see above). If neither are set, it is
also an error.
Exactly one of the [match](#match) and [file](#file) options must be set on an
interface. If neither or both are set, it is an error; the whole interface
rule is omitted from the configuration and `serval.conf` is treated as
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:
if true, then the interface is not activated, otherwise a socket on that system
interface is opened and the interface's `socket_type` is set to `dgram`. (It
is invalid to explicitly set `socket_type` to other than `dgram` for a match
interface.)
function. If any PATTERN matches, then the rule's [exclude](#exclude) option
is checked: if true, then the interface is not activated, otherwise a socket on
that system interface is opened and the interface's
[socket\_type](#socket_type) is implicitly set to `dgram`. (It is invalid to
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
file exists*. The interface's `socket_type` determines how the file is written
and read:
### `exclude`
* `file` (the default) creates a “dummy” interface for closed communication
with other **servald** daemons on the same host -- see below. If the file
does not exist, a warning is logged and the interface is not activated.
If a rule sets its a `exclude` option to *true*, then the interface will never
be activated. This can be useful for writing negative [match](#match) rules to
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
`mdp_tick_ms` options, for convenience. 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.
### `type`
The `type` option affects the default settings of the
[packet\_interval](#packet_interval) and [mdp\_tick\_ms](#mdp_tick_ms) options,
for convenience. 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.
### `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][]
interfaces which have a fixed packet size (the [IEEE 802.11][] [MTU][])
over the air;
* `single` sends each MDP packet on its own to the socket using [SLIP][]
* `overlay` (the default) aggregates as many messages as possible into
[overlay packet][]s that fit into each [UDP][] packet, in order to take
full advantage of the bandwidth on conventional [Wi-Fi][] interfaces which
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
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.
Many interfaces may have the `default_route` set to true, but only the first
one will be used as the default route.
### `default_route`
The `default_route` option, if true, causes all [MDP message][]s with an
unresolved [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. 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
broadcast packets whenever a recipient address (SID) cannot be resolved to an
interface. Normally, any MDP packet to an unresolvable recipient gets
broadcast on all active interfaces.
### `send_broadcasts`
Normally, any [MDP message][] with an unresolvable [recipient][] gets broadcast
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