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 tun
N
create
command or by opening the character special
device /dev/tunN.
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 *flags- Set just the interface flags. The same restrictions as for
TUNSIFINFO
apply. FIONBIO
int *flag- Set non-blocking I/O.
FIOASYNC
int *flag- Cause signal
SIGIO
to be sent when a packet can be read. TIOCSPGRP
int *pgrpTIOCGPGRP
int *pgrp- Get or set the process group to which signals might be sent via
FIOASYNC
. FIONREAD
int *count- Get the byte count of the next packet available to be read.
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
inet(4), intro(4), netintro(4), hostname.if(5), ifconfig(8), netstart(8)