OpenBSD manual page server

Manual Page Search Parameters
TUN(4) Device Drivers Manual TUN(4)

tun, tap — network tunnel pseudo-device

pseudo-device tun


#include <sys/types.h>
#include <net/if_tun.h>

The tun pseudo-device driver provides character special devices for communicating with the kernel network stack via the tun and tap network interfaces. Packets sent to these interfaces can be read from the device special file by a userland process and processed as desired. Packets written to the device special file by the userland process are injected back into the kernel networking subsystem.

tun and tap interfaces can be created at runtime using the ifconfig ifaceN create command, or by opening the character special devices /dev/tunN or /dev/tapN respectively.

The minor number of the device special files are associated with the unit number of the network interfaces.

Each device has an exclusive open property: it cannot be opened if it is already open and in use by another process. On the last close of the device all queued packets are discarded. If the device was created by opening a device special file it will be automatically destroyed. The last close of a device special file associated with an interface created via ifconfig(8) will be marked as not running and traffic sent out the will be dropped.

Each read returns at most one packet; if insufficient buffer space is provided, the packet is truncated. Each write supplies exactly one packet. Writes never block. If the protocol queue is full, the packet is dropped, a “collision” is counted, and ENOBUFS is returned.

The following ioctl(2) special commands defined in <net/if_tun.h> are supported:

struct tuninfo *
 
struct tuninfo *
Get or set the interface characteristics. 
/* iface info */
struct tuninfo {
        u_int   mtu;
        u_short type;
        u_short flags;
        u_int   baudrate;
};

flags and type are set by the kernel when an interface is created, and must be set to the same values that the kernel provided.

int *
is provided for backwards compatibiliy. The flags set must match what the kernel initialised them to.

The generic ioctls FIONREAD, FIONBIO, FIOASYNC, FIOSETOWN, FIOGETOWN are also supported.

Each packet read from or written to a tun interface is prefixed with a tunnel header consisting of a 4-byte network byte order integer containing the address family of the packet. tun supports AF_INET, AF_INET6, and AF_MPLS packets.

Each packet read from or written to a tap interface is an Ethernet packet. The Ethernet CRC at the end of the frame is not required.

The device special files for tap interfaces support the following additional ioctl(2) commands:

uint8_t[ETHER_ADDR_LEN]
 
uint8_t[ETHER_ADDR_LEN]
Get or set the link layer address (MAC address) of the interface.

/dev/tun*
 
/dev/tap*
 

If open fails, errno(2) may be set to one of:

[]
Not that many devices configured.
[]
Device was already open.

If a write(2) call fails, errno(2) is set to one of:

[]
The packet supplied was too small or too large. The maximum sized packet allowed is currently 16384 bytes.
[]
There were no mbufs.

ioctl(2) commands may fail with:

[]
Invalid parameters were specified.
[]
Unrecognized ioctl command.

A read(2) call may fail because of:

[]
The associated interface has been destroyed.
[]
Non-blocking I/O was selected and no packets were available.

ioctl(2), inet(4), intro(4), netintro(4), hostname.if(5), ifconfig(8), netstart(8)

tun interfaces originally supported both Layer 3 and Ethernet packets by reconfiguring the type of interface with TUNSIFINFO. Ethernet packet support was split into the separate tap interface in OpenBSD 5.9.

tun was written by Julian Onions <Julian.Onions@nexor.co.uk> at Nottingham University.

The tap interface functionality was written by
Claudio Jeker <claudio@openbsd.org>.

November 13, 2024 OpenBSD-current