Skip to content


Folders and files

Last commit message
Last commit date

Latest commit



31 Commits

Repository files navigation


experiments on digging tunnels

Why tunneldigger? See .

tested on ubuntu 16.04 LTS

Fast Mode (Vagrant)

This will get you up and running quickly. It's more for folks setting up the lab for workshop purposes, and you'll learn a bit less if you skip the setup that this saves you from.

Anyway, if you have Vagrant installed, you should be able to run the following:

git clone
cd tunneldigger-lab
vagrant up && vagrant ssh -c /vagrant/

The various tmux panes will highlight changes to the system's network as they occur. You can stop the current client session by pressing Ctrl+C, and experiment with other commands to see how they change things.

To learn how to configure a tunneldigger client yourself, read on!


sudo apt update
sudo apt install cmake libnl-3-dev libnl-genl-3-dev build-essential pkg-config
sudo apt install linux-image-extra-$(uname -r)


kernel modules

You have to load some kernel modules (l2tp_*).

sudo modprobe l2tp_netlink
sudo modprobe l2tp_eth
sudo modprobe l2tp_core

Verify that the modules were loaded by running sudo lsmod | grep l2tp, result should be something like:

$ sudo lsmod | grep l2tp
l2tp_eth               16384  0
l2tp_ppp               24576  0
l2tp_netlink           20480  2 l2tp_eth,l2tp_ppp
l2tp_core              32768  3 l2tp_eth,l2tp_ppp,l2tp_netlink
ip6_udp_tunnel         16384  1 l2tp_core
udp_tunnel             16384  1 l2tp_core
pppox                  16384  2 l2tp_ppp,pppoe

If you'd like to automatically load the kernel modules on reboot, the system should be configured to load these modules at boot which is usually done by listing the modules in /etc/modules. For more information see the Tunneldigger docs.


First clone and build the tunneldigger client

git clone

The version that is used in firmware can be found in the nodewatcher Makefile. At time of writing, sudomesh/tunneldigger was used, a fork of wlanslovenija. The sudomesh fork does not run on ubuntu because of some library depedencies.


cd tunneldigger/client
cmake .

cmake may provide an output like:

-- Checking for module 'libasyncns'
--   No package 'libasyncns' found
-- Configuring done
-- Generating done
-- Build files have been written to: /home/user/tunneldigger/client

Do not worry about this missing package. The libasyncns source is included in the tunneldigger repository, so it does not need to be installed globally. Now you can run make,


which should produce and output like:

Scanning dependencies of target tunneldigger
[ 33%] Building C object CMakeFiles/tunneldigger.dir/l2tp_client.c.o
[ 66%] Building C object CMakeFiles/tunneldigger.dir/libasyncns/asyncns.c.o
[100%] Linking C executable tunneldigger
[100%] Built target tunneldigger

and the file [tunneldigger-lib]/tunneldigger/client/tunneldigger should exist.

digging a tunnel

Before digging a tunnel, check interfaces using ip addr, there should be no l2tp interface yet. Check udp ports using netstat -u, this should be empty. Check syslog using cat /var/log/syslog | grep td-client, this should not contain any recent entries.

First, generate a uuid using uuidgen on the commandline: the output should be a valid uuid .

Now run

sudo $PWD/tunneldigger/client/tunneldigger -f -b -u [uuid] -i l2tp0 -s $PWD/


  1. is the end of the tunnel you are attempting to dig also known as the "broker"
  2. [uuid] is the uuid you just generated with uuidgen
  3. l2tp0 is the interface that will be created for the tunnel
  4. is the shell script (aka "hook") that is called by the tunnel digger on creating/destroying a session.

On starting, you should see something like:

td-client: Performing broker selection...
td-client: Broker usage of [ip tunnel digger broker]:8942: 127
td-client: Selected [ip tunnel digger broker]:8942 as the best broker.
td-client: Tunnel successfully established.
td-client: Setting MTU to 1446

Now, open another terminal and check the status of the tunnel by:

  1. inspecting the for recent entries of new sessions. Expected entries are like
Mon Dec 18 21:29:28 PST 2017 [td-hook] session.up l2tp0
Mon Dec 18 21:30:10 PST 2017 [td-hook] session.down l2tp0
  1. run ip addr and verify that an interface l2tp0 now exists.
  2. also, open udp ports netstat -u and verify you see something like this:
Active Internet connections (w/o servers)
Proto Recv-Q Send-Q Local Address           Foreign Address         State      
udp        0      0 xxxx:42862         xxxx:8942 ESTABLISHED
  1. verify syslog entries using cat /var/log/syslog | grep td-client - expecting something like:
Dec 17 13:24:06 xx td-client: Performing broker selection...
Dec 17 13:24:08 xx td-client: Broker usage of 1471
Dec 17 13:24:08 xx td-client: Selected as the best broker.
Dec 17 13:24:12 xx td-client: Tunnel successfully established.
Dec 17 13:24:21 xx td-client: Setting MTU to 1446
  1. the tunnel can be closed using CRTL-C in the original, or can be run in the background like any shell command.

Setting up a broker

It is also possible to set up your own broker within the client machine or on a hosted server (such as on digitalocean). You can follow instructions published in the Tunneldigger docs. Perhaps easiest way to setup a broker is to follow instructions and/or inspect scripts published at sudomesh/exitnode.


No releases published


No packages published