serval-dna/doc/Tunnelling.md

Tunnelling through the Serval Mesh network

Serval Project, May 2014

The Serval Mesh network, based on the Mesh Datagram Protocol, provides better packet delivery rates than conventional UDP over a multi-hop wireless network by employing per-hop retransmission (and, in future, linear network coding) to reduce the per-hop packet loss rate. This significantly reduces the cumulative multi-hop packet loss rate. For this reason, it is useful to carry Internet Protocol traffic over the Serval Mesh wireless network using a technique called tunnelling.

At present, only one tunnelling service is available for the Serval Mesh:

• tunnelling of TCP byte streams over the Mesh Stream Protocol (funded by a grant from the New America Foundation's Open Technology Institute)

Tunnelling TCP over MSP

An MSP tunnel can carry many TCP streams simultaneously. The tunnel is set up by running a process on each of the two end-point nodes:

• the “server” node's process acts as an MSP listener

• the “client” node's process connects to the server's MSP listener once for each TCP stream that is to be tunnelled.

While an MSP tunnel is running, the client can initiate new TCP connections to the server, but not vice versa. The tunnel creates one MSP stream per TCP stream. Each MSP stream carries data in both directions.

When either process terminates, the tunnel is broken and all of its connections immediately break.

Server end - msp listen

$ servald msp listen [--once] --forward=TCPPORT [--service=NAME] MDPPORT

The msp listen command acts as a server process which connects to the Serval DNA daemon, binds to the MDP port number given by MDPPORT, creates an MSP listening socket on that port, and waits for connections from remote MSP clients to that socket. Whenever a connection is received, it:

• connects to the TCP port TCPPORT on the local host (loopback interface), then:
• writes all inbound MSP messages to the TCP stream in byte order, and
• reads bytes from the local TCP stream and sends them as MSP messages
• until either the local TCP stream is broken or the MSP connection is closed, whereupon it:
• closes the TCP stream and the MSP connection.

If the --once option is given then the server process only accepts a single MSP connection and exits as soon as the connection is closed.

If the --service=NAME option is given, then the server process also binds to the standard Serval service discovery MDP port and responds to any matching query with the response NAME.mdp.port=MDPPORT.

If the --forward option is omitted, then instead of connecting to a TCP port, accepts only a single connection (the --once option is implied, and need not be given explicitly) and forwards the MSP data to and from standard output and input.

Client end - msp connect

$ servald msp connect [--once] --forward=TCPPORT SID MDPPORT

The msp connect command listens on TCP port TCPPORT of the localhost (loopback interface) for a TCP connection from a local process. Whenever a connection is received, it:

• makes an MSP connection to the given SID and MDP port number, then:
• reads bytes from the local TCP stream and sends them as MSP messages, and
• writes all inbound MSP messages to the local TCP stream in byte order
• until either the TCP stream is broken or the MSP connection is closed, whereupon it:
• closes the TCP stream and the MSP connection.

If the --once option is given then the server process only accepts a single TCP connection and exits as soon as the connection is closed.

If the --forward option is omitted, then instead of listening on a TCP port, makes the MSP connection immediately and forwards the MSP data to and from standard output and input.

---

Copyright 2014 Serval Project Inc.
Available under the Creative Commons Attribution 4.0 International licence.