$FreeBSD: head/share/man/man4/tun.4 56187 2000-01-17 14:17:28Z asmodai $
Based on PR#2411
.Dd March 10, 1996 .Dt TUN 4 .Os .Sh NAME .Nm tun .Nd tunnel software network interface .Sh SYNOPSIS .Cd pseudo-device tun .Sh DESCRIPTION The .Nm tun interface is a software loopback mechanism that can be loosely described as the network interface analog of the .Xr pty 4 , that is, .Nm tun does for network interfaces what the .Nm pty driver does for terminals.
p The .Nm tun driver, like the .Nm pty driver, provides two interfaces: an interface like the usual facility it is simulating
o a network interface in the case of .Nm tun , or a terminal for .Nm pty
c , and a character-special device .Dq control interface.
p The network interfaces are named .Sy tun Ns Ar 0 , .Sy tun Ns Ar 1 , etc, as many as were made by .Xr MAKEDEV 8 . Each one supports the usual network-interface .Xr ioctl 2 Ns s , such as .Dv SIOCSIFADDR and .Dv SIOCSIFNETMASK , and thus can be used with .Xr ifconfig 8 like any other interface. At boot time, they are .Dv POINTOPOINT interfaces, but this can be changed; see the description of the control device, below. When the system chooses to transmit a packet on the network interface, the packet can be read from the control device
o it appears as .Dq input there
c ; writing a packet to the control device generates an input packet on the network interface, as if the
q non-existent hardware had just received it.
p The tunnel device, normally
a /dev/tun Ns Sy N , is exclusive-open
o it cannot be opened if it is already open
c and is restricted to the super-user. A .Fn read call will return an error
q Er EHOSTDOWN if the interface is not .Dq ready
o which means that the control device is open and the interface's address has been set
c . Once the interface is ready, .Fn read will return a packet if one is available; if not, it will either block until one is or return .Er EWOULDBLOCK , depending on whether non-blocking I/O has been enabled. If the packet is longer than is allowed for in the buffer passed to .Fn read , the extra data will be silently dropped.
p Packets can be optionally prepended with the destination address as presented to the network interface output routine
q Sq Li tunoutput . The destination address is in .Sq Li struct sockaddr format. The actual length of the prepended address is in the member .Sq Li sa_len . The packet data follows immediately. A .Xr write 2 call passes a packet in to be .Dq received on the pseudo-interface. Each .Fn write call supplies exactly one packet; the packet length is taken from the amount of data provided to .Fn write . Writes will not block; if the packet cannot be accepted for a transient reason
q e.g., no buffer space available , it is silently dropped; if the reason is not transient
q e.g., packet too large , an error is returned. If .Dq link-layer mode is on
q see Dv TUNSLMODE No below , the actual packet data must be preceded by a .Sq Li struct sockaddr . The driver currently only inspects the .Sq Li sa_family field. The following .Xr ioctl 2 calls are supported
q defined in Aq Pa net/if_tun.h Ns : l -tag -width TUNSIFMODE t Dv TUNSDEBUG The argument should be a pointer to an .Va int ; this sets the internal debugging variable to that value. What, if anything, this variable controls is not documented here; see the source code. t Dv TUNGDEBUG The argument should be a pointer to an .Va int ; this stores the internal debugging variable's value into it. t Dv TUNSIFMODE The argument should be a pointer to an .Va int ; its value must be .Dv IFF_POINTOPOINT or .Dv IFF_BROADCAST . The type of the corresponding .Em tun Ns Sy n interface is set to the supplied type. If the value is anything else, an .Er EINVAL error occurs. The interface must be down at the time; if it is up, an .Er EBUSY error occurs. t Dv TUNSLMODE The argument should be a pointer to an .Va int ; a non-zero value turns on .Dq link-layer mode, causing packets read from the tunnel device to be prepended with network destination address. t Dv FIONBIO Turn non-blocking I/O for reads off or on, according as the argument .Va int Ns 's value is or isn't zero
q Writes are always nonblocking . t Dv FIOASYNC Turn asynchronous I/O for reads
o i.e., generation of .Dv SIGIO when data is available to be read
c off or on, according as the argument .Va int Ns 's value is or isn't zero. t Dv FIONREAD If any packets are queued to be read, store the size of the first one into the argument .Va int ; otherwise, store zero. t Dv TIOCSPGRP Set the process group to receive .Dv SIGIO signals, when asynchronous I/O is enabled, to the argument .Va int value. t Dv TIOCGPGRP Retrieve the process group value for .Dv SIGIO signals into the argument .Va int value. .El
p The control device also supports .Xr select 2 for read; selecting for write is pointless, and always succeeds, since writes are always non-blocking.
p On the last close of the data device, by default, the interface is brought down
o as if with .Dq ifconfig tun Ns Sy n No down
c . All queued packets are thrown away.
o If the interface is up when the data device is not open output packets are always thrown away rather than letting them pile up
c . .Sh SEE ALSO .Xr inet 4 , .Xr intro 4 .Sh BUGS Currently is IP-only. .Sh AUTHORS This man page has been obtained from x Net .