KernelTun Element Documentation

KernelTun -- Click element; interface to /dev/tun or ethertap (user-level)

KernelTun(ADDR/MASK [, GATEWAY, keywords HEADROOM, ETHER, MTU, IGNORE_QUEUE_OVERFLOWS])

Ports: at most 1 input, 1-2 outputs
Drivers: userlevel
Package: userlevel (core)

Reads IP packets from and writes IP packets to a /dev/net/tun, /dev/tun*, or /dev/tap* device. This allows a user-level Click to hand packets to the ordinary kernel IP processing code. KernelTun will also install a routing table entry so that the kernel can pass packets to the KernelTun device. KernelTun produces and expects IP packets. If, for some reason, the kernel passes up a non-IP packet (or an invalid IP packet), KernelTun will emit that packet on its second output, or drop it if there is no second output. KernelTun allocates a /dev/net/tun, /dev/tun*, or /dev/tap* device (this might fail) and runs ifconfig to set the interface's local (i.e., kernel) address to ADDR and the netmask to MASK. If a nonzero GATEWAY IP address (which must be on the same network as the tun) is specified, then KernelTun tries to set up a default route through that host. When cleaning up, KernelTun attempts to bring down the device via ifconfig. Keyword arguments are:

HEADROOM

Integer. The number of bytes left empty before the packet data to leave room for additional encapsulation headers. Default is 28.

MTU

Integer. The interface's MTU. KernelTun will refuse to send packets larger than the MTU. Default is 1500; not all operating systems allow MTU to be set.

ETHER

Ethernet address. Specifies the tunnel device's Ethernet address. Default is 00:01:02:03:04:05. On FreeBSD, any ETHER argument is silently ignored.

IGNORE_QUEUE_OVERFLOWS

Boolean. If true, don't print more than one error message when there are queue overflows error when sending/receiving packets to/from the tun device (e.g. there was an ENOBUFS error). Default is false.

DEVNAME

String. If specified, try to alloc a tun device with name DEVNAME. Otherwise, we'll just take the first virtual device we find. This option only works with the Linux Universal TUN/TAP driver.

Make sure that your kernel has tun support enabled before running KernelTun. Initialization errors like "no such device" or "no such file or directory" may indicate that your kernel isn't set up, or that some required kernel module hasn't been loaded (on Linux, the relevant module is "tun"). Packets sent to ADDR will be processed by the host kernel stack; packets sent to any other address in ADDR/MASK will be sent to KernelTun. Say you run this configuration:

    tun :: KernelTun(1.0.0.1/8);
    tun -> IPClassifier(icmp type echo) -> ICMPPingResponder
        -> IPPrint -> tun;

If you then "ping 1.0.0.1", your own kernel will respond. Click will never see the packets, so it won't print anything. But if you "ping 1.0.0.2", the pings are sent to Click. You should see printouts from Click, and ping should print Click's responses. This element differs from KernelTap in that it produces and expects IP packets, not IP-in-Ethernet packets.

FromDevice.u, ToDevice.u, KernelTap, ifconfig(8)

Generated by 'click-elem2man' from '../elements/userlevel/kerneltun.hh' on 18/Sep/2007.