This is automatically generated documentation. Edit after the "COMMENTS" heading; changes to the main body will be lost.

KernelTun Element Documentation


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



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:

Integer. The maximum number of packets to emit per scheduling. Default is 1.
Integer. The number of bytes left empty before output packet data to leave room for additional encapsulation headers. Default is 28.
Integer. The interface's MTU, not including any link headers. KernelTun will refuse to send packets larger than the MTU. Default is 1500; not all operating systems allow MTU to be set.
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.
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.
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"). On Linux and most BSDs, packets sent to ADDR will be processed by the host kernel stack; on Mac OS X there is no special handling for ADDR. Packets sent to any (other) address in ADDR/MASK will be sent to KernelTun. Say you run this configuration:

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

On Linux and most BSDs, if you then "ping", your own kernel will respond: Click will never see the packets, so it won't print anything. But if you "ping", 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

Generated by 'click-elem2man' from '../elements/userlevel/kerneltun.hh:10' on 12/Jul/2011.


elements/kerneltun.txt · Last modified: 2011/07/12 11:29 (external edit)
Recent changes RSS feed Driven by DokuWiki