diff options
Diffstat (limited to 'share/man/man4/tun.4')
-rw-r--r-- | share/man/man4/tun.4 | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/share/man/man4/tun.4 b/share/man/man4/tun.4 new file mode 100644 index 000000000000..b5139a7cdf0d --- /dev/null +++ b/share/man/man4/tun.4 @@ -0,0 +1,313 @@ +.\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $ +.\" $FreeBSD$ +.\" Based on PR#2411 +.\" +.Dd February 4, 2007 +.Dt TUN 4 +.Os +.Sh NAME +.Nm tun +.Nd tunnel software network interface +.Sh SYNOPSIS +.Cd device tun +.Sh DESCRIPTION +The +.Nm +interface is a software loopback mechanism that can be loosely +described as the network interface analog of the +.Xr pty 4 , +that is, +.Nm +does for network interfaces what the +.Xr pty 4 +driver does for terminals. +.Pp +The +.Nm +driver, like the +.Xr pty 4 +driver, provides two interfaces: an interface like the usual facility +it is simulating +(a network interface in the case of +.Nm , +or a terminal for +.Xr pty 4 ) , +and a character-special device +.Dq control +interface. +.Pp +The network interfaces are named +.Dq Li tun0 , +.Dq Li tun1 , +etc., one for each control device that has been opened. +These network interfaces persist until the +.Pa if_tun.ko +module is unloaded, or until removed with the +.Xr ifconfig 8 +command. +.Pp +.Nm +devices are created using interface cloning. +This is done using the +.Dq ifconfig tun Ns Sy N No create +command. +This is the preferred method of creating +.Nm +devices. +The same method allows removal of interfaces. +For this, use the +.Dq ifconfig tun Ns Sy N No destroy +command. +.Pp +If the +.Xr sysctl 8 +variable +.Va net.link.tun.devfs_cloning +is non-zero, the +.Nm +interface +permits opens on the special control device +.Pa /dev/tun . +When this device is opened, +.Nm +will return a handle for the lowest unused +.Nm +device (use +.Xr devname 3 +to determine which). +.Pp +.Bf Em +Disabling the legacy devfs cloning functionality may break existing +applications which use +.Nm , +such as +.Xr ppp 8 +and +.Xr ssh 1 . +It therefore defaults to being enabled until further notice. +.Ef +.Pp +Control devices (once successfully opened) persist until +.Pa if_tun.ko +is unloaded in the same way that network interfaces persist (see above). +.Pp +Each interface supports the usual network-interface +.Xr ioctl 2 Ns s , +such as +.Dv SIOCAIFADDR +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 +(it appears as +.Dq input +there); +writing a packet to the control device generates an input +packet on the network interface, as if the (non-existent) +hardware had just received it. +.Pp +The tunnel device +.Pq Pa /dev/tun Ns Ar N +is exclusive-open +(it cannot be opened if it is already open). +A +.Xr read 2 +call will return an error +.Pq Er EHOSTDOWN +if the interface is not +.Dq ready +(which means that the control device is open and the interface's +address has been set). +.Pp +Once the interface is ready, +.Xr read 2 +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 +.Xr read 2 , +the extra data will be silently dropped. +.Pp +If the +.Dv TUNSLMODE +ioctl has been set, packets read from the control device will be prepended +with the destination address as presented to the network interface output +routine, +.Fn tunoutput . +The destination address is in +.Vt struct sockaddr +format. +The actual length of the prepended address is in the member +.Va sa_len . +If the +.Dv TUNSIFHEAD +ioctl has been set, packets will be prepended with a four byte address +family in network byte order. +.Dv TUNSLMODE +and +.Dv TUNSIFHEAD +are mutually exclusive. +In any case, the packet data follows immediately. +.Pp +A +.Xr write 2 +call passes a packet in to be +.Dq received +on the pseudo-interface. +If the +.Dv TUNSIFHEAD +ioctl has been set, the address family must be prepended, otherwise the +packet is assumed to be of type +.Dv AF_INET . +Each +.Xr write 2 +call supplies exactly one packet; the packet length is taken from the +amount of data provided to +.Xr write 2 +(minus any supplied address family). +Writes will not block; if the packet cannot be accepted for a +transient reason +(e.g., no buffer space available), +it is silently dropped; if the reason is not transient +(e.g., packet too large), +an error is returned. +.Pp +The following +.Xr ioctl 2 +calls are supported +(defined in +.In net/if_tun.h ) : +.Bl -tag -width ".Dv TUNSIFMODE" +.It Dv TUNSDEBUG +The argument should be a pointer to an +.Vt int ; +this sets the internal debugging variable to that value. +What, if anything, this variable controls is not documented here; see +the source code. +.It Dv TUNGDEBUG +The argument should be a pointer to an +.Vt int ; +this stores the internal debugging variable's value into it. +.It Dv TUNSIFINFO +The argument should be a pointer to an +.Vt struct tuninfo +and allows setting the MTU, the type, and the baudrate of the tunnel +device. +The +.Vt struct tuninfo +is declared in +.In net/if_tun.h . +.Pp +The use of this ioctl is restricted to the super-user. +.It Dv TUNGIFINFO +The argument should be a pointer to an +.Vt struct tuninfo , +where the current MTU, type, and baudrate will be stored. +.It Dv TUNSIFMODE +The argument should be a pointer to an +.Vt int ; +its value must be either +.Dv IFF_POINTOPOINT +or +.Dv IFF_BROADCAST +and should have +.Dv IFF_MULTICAST +OR'd into the value if multicast support is required. +The type of the corresponding +.Dq Li tun Ns Ar N +interface is set to the supplied type. +If the value is outside the above range, an +.Er EINVAL +error is returned. +The interface must be down at the time; if it is up, an +.Er EBUSY +error is returned. +.It Dv TUNSLMODE +The argument should be a pointer to an +.Vt int ; +a non-zero value turns off +.Dq multi-af +mode and turns on +.Dq link-layer +mode, causing packets read from the tunnel device to be prepended with +the network destination address (see above). +.It Dv TUNSIFPID +Will set the pid owning the tunnel device to the current process's pid. +.It Dv TUNSIFHEAD +The argument should be a pointer to an +.Vt int ; +a non-zero value turns off +.Dq link-layer +mode, and enables +.Dq multi-af +mode, where every packet is preceded with a four byte address family. +.It Dv TUNGIFHEAD +The argument should be a pointer to an +.Vt int ; +the ioctl sets the value to one if the device is in +.Dq multi-af +mode, and zero otherwise. +.It Dv FIONBIO +Turn non-blocking I/O for reads off or on, according as the argument +.Vt int Ns 's +value is or is not zero. +(Writes are always non-blocking.) +.It Dv FIOASYNC +Turn asynchronous I/O for reads +(i.e., generation of +.Dv SIGIO +when data is available to be read) +off or on, according as the argument +.Vt int Ns 's +value is or is not zero. +.It Dv FIONREAD +If any packets are queued to be read, store the size of the first one +into the argument +.Vt int ; +otherwise, store zero. +.It Dv TIOCSPGRP +Set the process group to receive +.Dv SIGIO +signals, when asynchronous I/O is enabled, to the argument +.Vt int +value. +.It Dv TIOCGPGRP +Retrieve the process group value for +.Dv SIGIO +signals into the argument +.Vt int +value. +.El +.Pp +The control device also supports +.Xr select 2 +for read; selecting for write is pointless, and always succeeds, since +writes are always non-blocking. +.Pp +On the last close of the data device, by default, the interface is +brought down +(as if with +.Nm ifconfig Ar tunN Cm down ) . +All queued packets are thrown away. +If the interface is up when the data device is not open +output packets are always thrown away rather than letting +them pile up. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr read 2 , +.Xr select 2 , +.Xr write 2 , +.Xr devname 3 , +.Xr inet 4 , +.Xr intro 4 , +.Xr pty 4 , +.Xr ifconfig 8 +.Sh AUTHORS +This manual page was originally obtained from +.Nx . |