TUN(4) - Device Drivers Manual #
TUN(4) - Device Drivers Manual
NAME #
tun - network tunnel pseudo-device
SYNOPSIS #
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 ifconfig tunN create command or by opening the character special device /dev/tunN. By default tun operates as a point-to-point interface.
Each device has an 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.
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
struct tuninfo *
TUNSIFINFO
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 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 toIFF_POINTOPOINT
. It is an error to set bothIFF_POINTOPOINT
andIFF_BROADCAST
. type defaults toIFT_TUNNEL
. This sets the interface media address header type.
TUNSIFMODE
int, *
Set just the interface flags. The same restrictions as for
TUNSIFINFO
apply.
The generic ioctls
FIONREAD
,
FIONBIO
,
FIOASYNC
,
FIOSETOWN
,
FIOGETOWN
are supported by
tun.
FILES #
/dev/tun*
ERRORS #
If open fails, errno(2) may be set to one of:
[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
andIFF_BROADCAST
withTUNSIFMODE
or usingSIOCGIFADDR
orSIOCSIFADDR
.
[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
.
SEE ALSO #
ioctl(2), inet(4), intro(4), netintro(4), hostname.if(5), ifconfig(8), netstart(8)
OpenBSD 7.5 - January 9, 2020