Route REST API ============== [Serval Project][], September 2016 Introduction ------------ Every [Serval DNA][] daemon running on a node in the [Serval mesh network][] maintains its own dynamic *routing table*, which it uses to choose the [network interface][] on which to send each outgoing [MDP message][]. The mesh routing algorithm updates the routing table whenever Serval DNA receives an [overlay packet][] and whenever system time advances. For more details, see [Mesh Datagram Protocol][]. The [Serval DNA][] daemon gives applications access to its routing table via the **Route REST API** described in this document. Applications can use this information to: * discover the current [network neighbours](#neighbour) * discover all currently (and recently) [reachable nodes](#reachable) * estimate the quality of service to any given [reachable node](#reachable) Basic concepts -------------- ### Routing table Every [node](#node) in the [Serval mesh network][] maintains its own *routing table*, which identifies a single [path](#path) to every [reachable](#reachable) [node](#node). The mesh routing algorithm chooses the best path based on routing information received from other nodes along the path. Whenever a [node](#node) receives an [overlay packet][], it knows that, at the time the packet was received, there existed a direct incoming [link](#link) from the [transmitting node][transmitter]. It updates its routing table to mark the transmitter's [primary SID](#primary-sid) as a [neighbour](#neighbour). Whenever a [node](#node) receives nothing from a given neighbour for longer than a [configured][] time interval, it presumes that the [link](#link) is broken. It updates its routing table to mark the neighbour's [primary SID](#primary-sid) as no longer a neighbour. ### Tick Every daemon ensures that all of its nearby nodes remain aware of its presence by sending regular [overlay packet][]s to every [neighbour](#neighbour). Every [overlay packet][] contains its own [primary SID](#primary-sid) as the sender address. Every [network interface][] has a [configured][] *tick interval*, which is the maximum time period that may elapse between messages sent to any neighbour on that interface. If no message has been sent to a given neighbour for a whole tick interval, then the daemon sends an empty [overlay packet][], called a *tick packet*, to the neighbour. As a result, while an interface is quiescent (no traffic), depending on whether the [link](#link) to each neighbour is *broadcast* or *unicast*, at every tick the daemon will send either a single broadcast Wi-Fi packet, or several unicast Wi-Fi packets, or a mixture. ### Node A *node* in the [Serval mesh network][] is any device with its own link-layer address (eg, a UDP/IP address or a Wi-Fi MAC address) that is running a [Serval DNA][] daemon configured to use that network interface. ### Neighbour A [node's](#node) *neighbour* in the [Serval mesh network][] is any node from which its [Serval DNA][] daemon directly receives [overlay packet][]s through a [network interface][]. Note that a neighbour is not necessarily [reachable](#reachable), because wireless links are not always symmetrical; even though station A receives from station B, it does not necessarily mean that B can receive from A, because of factors like different transmitter power and antenna gain. ### Link A *link* is a one-way connection from a [node](#node) to one of its [neighbour nodes](#neighbour). Links are represented in the routing table by the [primary SID](#primary-sid) of their receiving end. A link may be either *broadcast* or *unicast*, which is chosen by the receiver [node](#node) during link negotiation. Each link is characterised by a metric that represents the dynamic link quality (eg, the proportion of recent packets successfully received). Every [node](#node) dynamically computes the quality of all its incoming links by counting the gaps in the sequence numbers on received [overlay packet][]s. It continuously informs each [neighbour node](#neighbour) of the measured quality of its incoming link by periodically sending a [routing message](#routing-message) to each neighbour at a [configured][] time interval. ### Primary SID Every [node](#node) identifies itself by its *primary SID*, which is usually the [SID][] of the first identity that was [unlocked][] since the daemon was started. ### Secondary SID A [node](#node) may have more than one [SID][], ie more than one [unlocked][] identity. All its SIDs except the [primary SID](#primary-sid) are called *secondary*. A [node](#node) announces all of its secondary SIDs by representing them in its [routing messages](#routing-message) as [reachable](#reachable) [neighbours](#neighbour) on a private network interface (ie, not available to other nodes) with a 100% link quality. ### Routing message Every [node](#node) in the [Serval mesh network][] informs other nodes of the presence and quality of all of its incoming and outgoing [links](#link) by sending *routing messages*. A routing message is a one-hop message that goes to all [neighbouring](#neighbour) nodes but no further: * whenever a node detects the presence (received packet) or absence (timeout) of an incoming link, or revises the measured quality of an incoming link, it sends a routing message with the single link's state/quality to the single [neighbour](#neighbour) at the transmitting end of the link; * whenever a node receives a routing message from one of its neighbours, it incorporates the new link state (up/down) and quality information into its own routing table, re-evaluates its [paths](#path), and, shortly afterwards, sends a routing message containing the state/quality information of all its outgoing and incoming links to all of its [neighbours](#neighbour). Routing messages are not forwarded directly, but the information they carry propagates beyond the node's immediate neighbours because each neighbour, upon receiving a routing message, updates its own [routing table](#routing-table) and sends out its own routing messages that arise as a result of the update. ### Path A *path* is a one-way route from a *sender* [node](#node) to a *recipient* [node](#node), expressed as a sequence of non-repeating [links](#link). The first link in a path always leads to a [reachable](#reachable) [neighbour node](#neighbour). The routing algorithm constructs paths by choosing links whose existence and quality has been revealed by a recently-received *routing message* from a neighbour. ### Reachable A [node](#node) in the [Serval mesh network][] considers another node to be *reachable* if its own [routing table](#routing-table) contains a [path](#path) to the second node. REST Requests ------------- ### GET /restful/route/all.json Returns a list of all currently known identities, in [JSON table][] format. The table columns are: | heading | type | content | |:--------------------- |:---------------- |:------------------------------------------------------------------------------ | | `sid` | string | the [SID][] of the identity, as 64 uppercase hex digits | | `did` | string or `null` | the [DID][] of the identity if known (eg, for a local [keyring][] identity) | | `name` | string or `null` | the [Name][] of the identity if known (eg, for a local [keyring][] identity) | | `is_self` | boolean | true if the identity is a self-identity, ie, in the local [keyring][] | | `reachable_broadcast` | boolean | true if the identity is [reachable](#reachable) by broadcast [link](#link) | | `reachable_unicast` | boolean | true if the identity is [reachable](#reachable) by unicast [link](#link) | | `reachable_indirect` | boolean | true if the identity is [reachable](#reachable) only via another [node](#node) | | `interface` | string or `null` | the name of the local network interface on which the identity is reachable | | `hop_count` | integer | the number of hops to reach the identity | | `first_hop` | string or `null` | if `hop_count > 1`, then the [SID][] of the first identity in the route | | `penultimate_hop` | string or `null` | if `hop_count > 2`, then the [SID][] of the penultimate identity in the route | ----- **Copyright 2015 Serval Project Inc.** **Copyright 2016-2018 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 Mesh network]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:mesh_network [Serval DNA]: ../README.md [REST-API]: ./REST-API.md [keyring]: ./REST-API-Keyring.md [SID]: ./REST-API-Keyring.md#serval-id [DID]: ./REST-API-Keyring.md#did [Name]: ./REST-API-Keyring.md#name [unlocked]: ./REST-API-Keyring.md#identity-unlocking [overlay packet]: ./Mesh-Datagram-Protocol.md#overlay-packet [sender]: ./Mesh-Datagram-Protocol.md#sender [transmitter]: ./Mesh-Datagram-Protocol.md#transmitter [MDP message]: ./Mesh-Datagram-Protocol.md#mdp-message [broadcast]: ./Mesh-Datagram-Protocol.md#broadcast [Mesh Datagram Protocol]: ./Mesh-Datagram-Protocol.md [JSON table]: ./REST-API.md#json-table [configured]: ./Servald-Configuration.md [network interface]: ./Servald-Configuration.md#network-interfaces [200]: ./REST-API.md#200-ok [201]: ./REST-API.md#201-created [202]: ./REST-API.md#202-accepted [400]: ./REST-API.md#400-bad-request [404]: ./REST-API.md#404-not-found [419]: ./REST-API.md#419-authentication-timeout [422]: ./REST-API.md#422-unprocessable-entity [423]: ./REST-API.md#423-locked [500]: ./REST-API.md#500-server-error