README.md

April 9, 2026 · View on GitHub

tunctl is an Erlang API for creating and using TUN/TAP interfaces.

PRIVILEGES

Linux

For IPv4 addresses, beam needs to have privileges to configure interfaces.

To add cap_net_admin capabilities:

 sudo setcap cap_net_admin=ep /path/to/bin/beam.smp

To check the privileges:

 getcap /path/to/bin/beam.smp

To remove the privileges:

 sudo setcap -r cap_net_admin=ep /path/to/bin/beam.smp

Currently, IPv6 addresses are configured by calling ifconfig using sudo (see below).

Mac OS X

Requires the tun/tap driver from:

http://tuntaposx.sourceforge.net/

Allow the user running tunctl to call ifconfig using sudo:

sudo visudo
youruser ALL=NOPASSWD: /sbin/ifconfig tap*
youruser ALL=NOPASSWD: /sbin/ifconfig tun*

FreeBSD

tunctl uses the FreeBSD tuntap legacy interface.

Ensure the tap device kernel module is loaded:
```
 $ kldstat
 $ kldload if_tap
```
If you want the tap driver loaded on boot, add to /boot/loader.conf:
```
 if_tap_load="YES"
```

Check cloning is enabled:

 $ sysctl net.link.tun.devfs_cloning
 net.link.tun.devfs_cloning: 1

 $ sysctl net.link.tap.devfs_cloning
 net.link.tap.devfs_cloning: 1

Allow the user running tunctl to call ifconfig using sudo:

 sudo visudo
 youruser ALL=NOPASSWD: /sbin/ifconfig tap*
 youruser ALL=NOPASSWD: /sbin/ifconfig tun*

EXAMPLES

"Passive" mode

  1> {ok, Ref} = tuncer:create().
  {ok,<0.34.0>}

  2> tuncer:devname(Ref).
  <<"tap0">>

  3> tuncer:up(Ref, "192.168.123.4").
  ok

  4> FD = tuncer:getfd(Ref).
  9

  5> {ok, Buf} = tuncer:read(FD, 1500).
  {ok,<<1,0,94,0,0,22,190,138,20,22,76,120,8,0,70,192,0,40,
        0,0,64,0,1,2,200,76,192,...>>}

  6> tuncer:destroy(Ref).
  ok

Active mode

  1> {ok, Ref} = tuncer:create(<<>>, [tap, no_pi, {active, true}]).
  {ok,<0.34.0>}

  2> tuncer:devname(Ref).
  <<"tap0">>

  3> tuncer:up(Ref, "192.168.123.4").
  ok

  4> flush().
  Shell got {tuntap,<0.47.0>,
                    <<51,51,0,0,0,22,250,6,27,10,131,177,134,221,96,0,0,0,0,36,
                      0,1,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,255,2,0,0,0,0,0,0,0,0,
                      0,0,0,0,0,22,58,0,5,2,0,0,1,0,143,0,235,206,0,0,0,1,4,0,0,
                      0,255,2,0,0,0,0,0,0,0,0,0,1,255,10,131,177>>}
  Shell got {tuntap,<0.47.0>,
                    <<51,51,255,10,131,177,250,6,27,10,131,177,134,221,96,0,0,0,
                      0,24,58,255,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,0,255,2,0,0,0,0,
                      0,0,0,0,0,1,255,10,131,177,135,0,98,169,0,0,0,0,254,128,0,
                      0,0,0,0,0,248,6,27,255,254,10,131,177>>}

  5> tuncer:destroy(Ref).
  ok

vpwn

vpwn will set up a point to point tunnel over the Erlang distribution protocol.

Compile vpwn on the source and destination nodes:

erlc -I deps -o ebin examples/*.erl

Run Erlang on the destination node:

erl -pa deps/*/ebin ebin -setcookie OMNOMNOM -name node

And on the source node:

erl -pa deps/*/ebin ebin -setcookie OMNOMNOM -name node

Then start up the tunnel (replace the host name):

vpwn:start('node@vpn.example.com', "10.10.10.1", "10.10.10.2").

Then connect over the tunnel to the second node:

ping 10.10.10.2
ssh 10.10.10.2

Bridging

br is an example of a simple bridge that floods frames to all the switch ports. br uses a tap device plugged into a Linux bridge as an uplink port and 1 or more tap devices as the switch ports.

This example uses the tap devices as interfaces for Linux containers (LXC).

Create a bridge and attach the physical ethernet interface

# /etc/network/interfaces
iface br0 inet dhcp
    bridge_ports eth0
    bridge_stp off
    bridge_fd 0
    bridge_maxwait 0

Start the bridge:
- erlbr0 is the name of the tap device connected to the bridge
- erl0, erl1, erl2 are the tap devices used by the containers

br:start(["erlbr0", "erl0", "erl1", "erl2"]).

In another shell, as root, bring up the uplink and attach it to the bridge:

# ifconfig erlbr0 up
# brctl addif br0 erlbr0
# brctl show br0
bridge name     bridge id               STP enabled     interfaces
br0             8000.4aec6d3a44d1       no              erlbr0

Move the switch port interface into the container. The interface name inside the container will be known as "erl0".

lxc.network.type=phys
lxc.network.link=erl0
lxc.network.flags=up