Magic Tunnel Daemon

This Google Summer of Code 2007 projects aims to develop a tunelling daemon. It will be worked on by Matus Harvan, while being mentored by Max Laier and Brooks Davis.

Note that this project originally started under the name Super Tunnel Daemon. This was later changed to Magic Tunnel Daemon, short mtund.




A snapshot of the code can be obtained from Note that you should also apply the kernel patches to use all features.

The source code is also available in the perforce repository. Use this for a more recent version.

Original Proposal


IP can easily be tunneled over a plethora of network protocols at various layers, such as IP, ICMP, UDP, TCP, DNS, HTTP, SSH to name a few. While a direct connection may not always be possible due to a firewall, the IP packets could be encapsulated as payload in other protocols, which would get through. However, each such encapsulation requires the setup of a different program and the user has to manually probe different encapsulations to find out which of them works in a given environment.

The aim of this project is to implement the Super Tunnel Daemon, a tunneling daemon using plugins for different encapsulations and automagically selecting the best encapsulation in each environment. Should the environment change, the user would not notice the transition to a different encapsulation except for a small delay. Connections estabilished within the tunnel would seamlessly be migrated to a different encapsulation. In this way, mobility would be supported as well, even to the extent of changing between different physical network interfaces, e.g. disabling the wireless interface and plugging in an ethernet cable. New encapsulations could easily be added in the future using the plugin interface.

Benefits to the FreeBSD Community


Project Details

The daemon and plugins would be written in plain C. A tun(4) interface, for which the daemon would be responsible, would serve as the tunnel endpoint. Plugins would be loaded using dlopen(3) and register their file descriptors with the daemon. The daemon would use select(2) to watch file descriptors for activity, read from the tun device, call the necessary plugin read functions and move data between the tun device and the plugins. From the return value of the send/receive functions the daemon would notice a malfunctioning encapsulation and failover to another one. Each plugin would have to implement functions for initializing and uninitializing the encapsulation as well as sending and receiving data.

To check whether this approach could work, I have implemented the daemon with minimal features. It is available at

It handles the tun device, loads encapsulation plugins, probes for a working encapsulation, successfully tunnels IP traffic and does failover between encapsulations. There are two encapsulation plugins, a TCP and a UDP one. Afer adding blocking rules to the firewall, the daemon successfully does a failover to another encapsulation. Detecting encapsulation malfunction works for TCP, but not yet for UDP. Exchanging some keep-alive traffic might be needed for unreliable protocols such as UDP and ICMP. Functions that a plugin has to implement are in plugin.h, functions available to the plugins from the daemon are in tunneld.h and an overview can be found in the README file. Note that the interfaces are just an initial version and may be changed later if needed.

The ICMP encapsulation could easily be done in C. The plain-text protocol encapsulations such as DNS and HTTP could also be written in C, but might require more protocol features to be implemented to allow HTTP traffic to pass through intermediate proxies and DNS traffic via other DNS servers. In such a scenario, the client would have to regularly poll the server and for DNS a proper DNS zone delegation may be needed. For the ssh plugin, forking an ssh(1) or autossh(1) process and talking to it via a pipe might be a viable option.

Authentication and encryption would likely not be addressed. However, one can always set up IPSec on top of the tun interface.

By using the tun interface as the only kernel-specific feature, the daemon and the plugins would essentially live in the user space, increasing portability. While this may not seem as an advantage to the FreeBSD community, the project would benefit a much broader community and possibly encourage more people to contribute new plugins in the future.

Project Schedule

The project can be divided into several parts, for which I would estimate the time needed to completion as follows

The rest of the time would be used for dealing with unforeseen problems and for the writeup. Should things be completed faster, more plugins could be written or authentication/encryption could be looked into.

mtund (last edited 2008-06-17 21:37:29 by localhost)