lwip-tap
lwip-tap is an application of "lwIP - A Lightweight TCP/IP Stack" which is
a small, user-space implementation of the TCP/IP protocol stack.
Using lwip-tap, you can easily plug an instance of lwIP to Linux Bridge or
Open vSwitch through TAP devices. lwip-tap supports multiple network
interfaces, so that it also works as a router. A wide range of different
network topologies can be built flexibly.
1. System Requirement
As of now, lwip-tap has been developed only in Linux, more precisely Arch
Linux with latest updates. The original tapif driver available in the
lwip-contrib, however, includes code chunks for other environments as well.
Although lwip-tap is fully supported only in Linux right now, it should
work on any environment that supports TAP/TUN-like devices if the tapif
driver is updated.
2. Build
Clone the git repository from GitHub and initialize submodules,
$ git clone git://github.com/takayuki/lwip-tap.git
$ cd lwip-tap
$ git submodule init
$ git submodule update
GNU make is required to build lwip-tap. A compile-time option to enable
debugging facilities lwIP provides is available. See "8. Debugging" below.
$ ./configure
$ make
Makefile currently does not have install targets. lwip-tap works in-place
in the source directory. Copy it to anywhere if you like.
3. Example: Running lwip-tap with a transient TAP device
The quickest, but less flexible way to run lwip-tap is, having it create
a transient TAP device for you,
# lwip-tap -i addr=172.16.0.2,netmask=255.255.255.0,gw=172.16.0.1
In this example, lwip-tap (1) creates a transient TAP device, (2) assign
172.16.0.1 to the tap, (3) adds a route 172.16.0.1/255.255.255.0 to the tap,
(4) links an instance of lwIP to the tap, and (5) assign 172.16.0.2 to the
interface of the lwIP. To check if the lwIP is working,
# ping 172.16.0.2
4. Example: Attach lwip-tap to a persistent TAP device
For more flexible network settings, all the steps mentioned above can be
made separately using persistent TAP devices,
# ip tuntap add dev tap0 mode tap
# ip link set dev tap0 up
# ip addr add 172.16.0.1/24 dev tap0
# lwip-tap -i name=tap0,addr=172.16.0.2,netmask=255.255.255.0,gw=172.16.0.1
# ping 172.16.0.2
5. Example: Use DHCP with a persistent TAP device
If you omit an address to an instance, lwip-tap automatically uses DHCP.
# lwip-tap -i name=tap0
6. Example: Run lwip-tap with Open vSwitch
Add br0 (172.16.0.1),
# ovs-vsctl add-br br0
# ip link set dev br0 up
# ip addr add 172.16.0.1/24 dev br0
Add tap0 to br0,
# ip tuntap add dev tap0 mode tap
# ip link set dev tap0 up
# ovs-vsctl add-port br0 tap0
Run a lwip-tap on tap0 (172.16.0.2),
# lwip-tap -i name=tap0,addr=172.16.0.2,netmask=255.255.255.0,gw=172.16.0.1
# ping 172.16.0.2
7. Example: Run lwip-tap as a router
Add br0 (172.16.0.1),
# ovs-vsctl add-br br0
# ip link set dev br0 up
# ip addr add 172.16.0.1/24 dev br0
# ip route add 172.16.1.0/24 via 172.16.0.2
Add br1 (without IP address),
# ovs-vsctl add-br br1
# ip link set dev br1 up
Add tap0 to br0,
# ip tuntap add dev tap0 mode tap
# ip link set dev tap0 up
# ovs-vsctl add-port br0 tap0
Add tap1 and tap2 to br1,
# ip tuntap add dev tap1 mode tap
# ip link set dev tap1 up
# ovs-vsctl add-port br1 tap1
# ip tuntap add dev tap2 mode tap
# ip link set dev tap2 up
# ovs-vsctl add-port br1 tap2
Run one lwip-tap on tap2 (172.16.1.2),
# lwip-tap \
-i name=tap2,addr=172.16.1.2,netmask=255.255.255.0,gw=172.16.1.1
Run another lwip-tap on tap0 (172.16.0.2) and tap1 (172.16.1.1), which is
a router between 172.16.0.2/24 and 172.16.1.1/24,
# lwip-tap \
-i name=tap0,addr=172.16.0.2,netmask=255.255.255.0,gw=172.16.0.1 \
-i name=tap1,addr=172.16.1.1,netmask=255.255.255.0
# ping 172.16.0.2
# ping 172.16.1.1
# ping 172.16.1.2
8. Build-in Applications
lwip-tap has currently three built-in applications which has been integrated
from lwip-contrib for debugging purposes. All applications are disabled by
default. Use command-line options to enable those services.
- echo (port 7) in TCP/UDP (-E)
- chargen (port 19) in TCP (-C)
- http (port 80) in TCP (-H)
9. Debugging
lwIP has a compile-time option for debugging which is disable by default.
To enable it, you need to rebuild lwip-tap giving an option to configure,
$ configure --enable-debug
$ make
which compiles all object files with LWIP_DEBUG set to 1 and adds another
option -d to lwip-tap.