TUN

TUN(4)

AerieBSD 1.0 Refernce Manual

TUN(4)

NAME

tun — network tunnel pseudo-device

SYNOPSIS

.Cd "pseudo-device tun"

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

DESCRIPTION

The tun driver provides a network interface pseudo-device. Packets sent to this interface can be read by a userland process and processed as desired. Packets written by the userland process are injected back into the kernel networking subsystem.

A tun interface can be created at runtime using the ifconfigtun command or by opening the character special device /dev/tunN.

Both layer 3 and layer 2 tunneling is supported. Layer 3 tunneling is the default mode; to enable layer 2 tunneling mode the link0 flag needs to be set with ifconfig(8), or by setting up a hostname.if(5) configuration file for netstart(8). In layer 2 mode the tun interface is simulating an Ethernet network interface.

Each device has the exclusive open property; it cannot be opened if it is already open and in use by another process. Each read returns at most one packet; if insufficient buffer space is provided, the packet is truncated. Each write supplies exactly one packet. Each packet read or written is prefixed with a tunnel header consisting of a 4-byte network byte order integer containing the address family in the case of layer 3 tunneling. In layer 2 mode the 4-byte tunnel header is replaced with an Ethernet header. On the last close of the device, all queued packets are discarded. If the device was created by opening /dev/tunN, it will be automatically destroyed. Devices created via ifconfig(8) are only marked as not running and traffic will be dropped returning EHOSTDOWN.

Writes never block. If the protocol queue is full, the packet is dropped, a “collision” is counted, and ENOBUFS is returned.

In addition to the usual network interface ioctl commands described in netintro(4), the following special commands defined in ‹net/if_tun.h› are supported:

TUNGIFINFO"structtuninfo *"

TUNSIFINFO"structtuninfo *"

Get or set the interface characteristics.

/* iface info */
struct tuninfo {
        u_int   mtu;
        u_short type;
        u_short flags;
        u_int   baudrate;
};

flags sets the interface flags, and can include one or more of IFF_UP, IFF_POINTOPOINT, IFF_MULTICAST, IFF_BROADCAST. Flags given will be set; flags omitted will be cleared; flags not in this list will not be changed even when given. Flags default to IFF_POINTOPOINT for layer 3 and to IFF_BROADCAST\&| IFF_MULTICAST for layer 2 mode. It is an error to set both IFF_POINTOPOINT and IFF_BROADCAST. type defaults to IFT_TUNNEL for layer 3 and IFT_ETHER for layer 2 tunneling mode. This sets the interface media address header type.

TUNSIFMODEint*flags

Set just the interface flags. The same restrictions as for TUNSIFINFO apply.

FIONBIOint*flag

Set non-blocking I/O.

FIOASYNCint*flag

Cause signal SIGIO to be sent when a packet can be read.

TIOCSPGRPint*pgrp

TIOCGPGRPint*pgrp

Get or set the process group to which signals might be sent via FIOASYNC.

FIONREADint*count

Get the byte count of the next packet available to be read.

SIOCGIFADDRstructether_addr *addr

SIOCSIFADDRstructether_addr *addr

Get or set the Ethernet address of the device in layer 2 mode.

FILES

/dev/tun*

ERRORS

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

[EPERM]: Only the superuser may open the device.
[ENXIO]: Not that many devices configured.
[EBUSY]: Device was already open.

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

[EMSGSIZE]: The packet supplied was too small or too large. The maximum sized packet allowed is currently 16384 bytes.
[ENOBUFS]: There were no mbufs, or the queue for the outgoing protocol is full.
[EAFNOSUPPORT]: The address family specified in the tunnel header was not recognized.

Ioctl commands may fail with:

[EINVAL]: Attempt to set both IFF_POINTOPOINT and IFF_BROADCAST with TUNSIFMODE or using SIOCGIFADDR or SIOCSIFADDR in layer 3 mode.
[ENOTTY]: Unrecognized ioctl command.

A read(2) call may fail because of:

[EHOSTDOWN]: The device is not ready. The device must have an inet(4) interface address assigned to it, such as via SIOCSIFADDR.
[EWOULDBLOCK]: Non-blocking I/O was selected and no packets were available.

An attempt to send a packet out via the interface may fail with:

[EHOSTDOWN]: The device is not ready. The device must have an inet(4) interface address assigned to it, such as via SIOCSIFADDR.

NAME

SYNOPSIS

DESCRIPTION

FILES

ERRORS

SEE ALSO