From 1e6caa0e6c4a5ed24c257cbd0030a83524232fe2 Mon Sep 17 00:00:00 2001 From: Andrew Bettison Date: Mon, 19 May 2014 17:29:10 +0930 Subject: [PATCH] Add Tunnelling document (TCP over MSP) --- doc/Tunnelling.md | 110 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 110 insertions(+) create mode 100644 doc/Tunnelling.md diff --git a/doc/Tunnelling.md b/doc/Tunnelling.md new file mode 100644 index 00000000..f7309288 --- /dev/null +++ b/doc/Tunnelling.md @@ -0,0 +1,110 @@ +Tunnelling through the Serval Mesh network +========================================== +[Serval Project][], May 2014 + +The [Serval Mesh network][], based on the [Mesh Datagram Protocol][MDP], +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][IP] 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][MSP] + (funded by a [grant][] from the [New America Foundation][NAF]'s [Open + Technology Institute][OTI]) + +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.** +![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]: http://creativecommons.org/licenses/by/4.0/ +[grant]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:activity:naf6 +[NAF]: http://www.newamerica.net/ +[OTI]: http://oti.newamerica.net/ +[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 service discovery]: ./Service-Discovery.md +[MDP]: ./Mesh-Datagram-Protocol.md +[MSP]: ./Mesh-Stream-Protocol.md +[UDP]: http://en.wikipedia.org/wiki/User_Datagram_Protocol +[TCP]: http://en.wikipedia.org/wiki/Transmission_Control_Protocol +[IP]: http://en.wikipedia.org/wiki/Internet_Protocol +[SID]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:sid +[MDP port]: http://developer.servalproject.org/dokuwiki/doku.php?id=content:tech:mdp_port_number +[linear network coding]: http://en.wikipedia.org/wiki/Linear_network_coding +[tunnelling]: http://en.wikipedia.org/wiki/Tunneling_protocol