1.\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $ 2.\" $FreeBSD: src/share/man/man4/tun.4,v 1.9.2.4 2001/08/17 13:08:39 ru Exp $ 3.\" $DragonFly: src/share/man/man4/tun.4,v 1.3 2006/05/26 19:39:39 swildner Exp $ 4.\" Based on PR#2411 5.\" 6.Dd August 6, 2009 7.Dt TUN 4 8.Os 9.Sh NAME 10.Nm tun 11.Nd tunnel software network interface 12.Sh SYNOPSIS 13.Cd pseudo-device tun 14.Sh DESCRIPTION 15The 16.Nm 17interface is a software loopback mechanism that can be loosely 18described as the network interface analog of the 19.Xr pty 4 , 20that is, 21.Nm 22does for network interfaces what the 23.Xr pty 4 24driver does for terminals. 25.Pp 26The 27.Nm 28driver, like the 29.Xr pty 4 30driver, provides two interfaces: an interface like the usual facility 31it is simulating 32(a network interface in the case of 33.Nm , 34or a terminal for 35.Xr pty 4 ) , 36and a character-special device 37.Dq control 38interface. 39.Pp 40The network interfaces are named 41.Dq Li tun0 , 42.Dq Li tun1 , 43etc, and each one supports the usual network-interface 44.Xr ioctl 2 Ns s , 45such as 46.Dv SIOCSIFADDR 47and 48.Dv SIOCSIFNETMASK , 49and thus can be used with 50.Xr ifconfig 8 51like any other interface. 52At boot time, they are 53.Dv POINTOPOINT 54interfaces, but this can be changed; see the description of the control 55device, below. 56When the system chooses to transmit a packet on the 57network interface, the packet can be read from the control device 58(it appears as 59.Dq input 60there); 61writing a packet to the control device generates an input 62packet on the network interface, as if the (non\-existent) 63hardware had just received it. 64.Pp 65The tunnel device, normally 66.Pa /dev/tun Ns Ar N , 67is exclusive-open 68(it cannot be opened if it is already open) 69and is restricted to the super-user. 70A 71.Xr read 2 72call will return an error 73.Pq Er EHOSTDOWN 74if the interface is not 75.Dq ready 76(which means that the control device is open and the interface's 77address has been set). 78.Pp 79Once the interface is ready, 80.Xr read 2 81will return a packet if one is available; if not, it will either block 82until one is or return 83.Er EWOULDBLOCK , 84depending on whether non-blocking I/O has been enabled. 85If the packet is longer than is allowed for in the buffer passed to 86.Xr read 2 , 87the extra data will be silently dropped. 88.Pp 89Packets can be optionally prepended with the destination address as presented 90to the network interface output routine, 91.Fn tunoutput . 92The destination address is in 93.Vt struct sockaddr 94format. 95The actual length of the prepended address is in the member 96.Va sa_len . 97The packet data follows immediately. 98.Pp 99A 100.Xr write 2 101call passes a packet in to be 102.Dq received 103on the pseudo-interface. 104Each 105.Xr write 2 106call supplies exactly one packet; the packet length is taken from the 107amount of data provided to 108.Xr write 2 . 109Writes will not block; if the packet cannot be accepted for a 110transient reason 111(e.g., no buffer space available), 112it is silently dropped; if the reason is not transient 113(e.g., packet too large), 114an error is returned. 115If 116.Dq link-layer mode 117is on 118(see 119.Dv TUNSLMODE 120below), 121the actual packet data must be preceded by a 122.Vt struct sockaddr . 123The driver currently only inspects the 124.Va sa_family 125field. 126.Pp 127The following 128.Xr ioctl 2 129calls are supported 130(defined in 131.In net/tun/if_tun.h ) : 132.Bl -tag -width ".Dv TUNSIFMODE" 133.It Dv TUNSDEBUG 134The argument should be a pointer to an 135.Vt int ; 136this sets the internal debugging variable to that value. 137What, if anything, this variable controls is not documented here; see 138the source code. 139.It Dv TUNGDEBUG 140The argument should be a pointer to an 141.Vt int ; 142this stores the internal debugging variable's value into it. 143.It Dv TUNSIFINFO 144The argument should be a pointer to an 145.Vt struct tuninfo 146and allows setting the MTU, the type, and the baudrate of the tunnel 147device. 148The 149.Vt struct tuninfo 150is declared in 151.In net/tun/if_tun.h . 152.It Dv TUNGIFINFO 153The argument should be a pointer to an 154.Vt struct tuninfo , 155where the current MTU, type, and baudrate will be stored. 156.It Dv TUNSIFMODE 157The argument should be a pointer to an 158.Vt int ; 159its value must be either 160.Dv IFF_POINTOPOINT 161or 162.Dv IFF_BROADCAST . 163The type of the corresponding 164.Dq Li tun Ns Ar N 165interface is set to the supplied type. 166If the value is anything else, an 167.Er EINVAL 168error occurs. 169The interface must be down at the time; if it is up, an 170.Er EBUSY 171error occurs. 172.It Dv TUNSLMODE 173The argument should be a pointer to an 174.Vt int ; 175a non-zero value turns on 176.Dq link-layer 177mode, causing packets read from the tunnel device to be prepended with 178network destination address. 179.It Dv TUNSIFPID 180Will set the pid owning the tunnel device to the current process's pid. 181.It Dv TUNSIFHEAD 182The argument should be a pointer to an 183.Vt int ; 184a non-zero value turns off 185.Dq link-layer 186mode, and enables 187.Dq multi-af 188mode, where every packet is preceded with a four byte address family. 189.It Dv TUNGIFHEAD 190The argument should be a pointer to an 191.Vt int ; 192this stores one if the device is in 193.Dq multi-af 194mode, and zero otherwise in it. 195.It Dv FIONBIO 196Turn non-blocking I/O for reads off or on, according as the argument 197.Vt int Ns 's 198value is or isn't zero. 199(Writes are always non-blocking.) 200.It Dv FIOASYNC 201Turn asynchronous I/O for reads 202(i.e., generation of 203.Dv SIGIO 204when data is available to be read) 205off or on, according as the argument 206.Vt int Ns 's 207value is or isn't zero. 208.It Dv FIONREAD 209If any packets are queued to be read, store the size of the first one 210into the argument 211.Vt int ; 212otherwise, store zero. 213.It Dv TIOCSPGRP 214Set the process group to receive 215.Dv SIGIO 216signals, when asynchronous I/O is enabled, to the argument 217.Vt int 218value. 219.It Dv TIOCGPGRP 220Retrieve the process group value for 221.Dv SIGIO 222signals into the argument 223.Vt int 224value. 225.El 226.Pp 227The control device also supports 228.Xr select 2 229for read; selecting for write is pointless, and always succeeds, since 230writes are always non-blocking. 231.Pp 232On the last close of the data device, by default, the interface is 233brought down 234(as if with 235.Nm ifconfig Ar tunN Cm down ) . 236All queued packets are thrown away. 237If the interface is up when the data device is not open 238output packets are always thrown away rather than letting 239them pile up. 240.Sh SEE ALSO 241.Xr inet 4 , 242.Xr intro 4 243.Sh AUTHORS 244This manual page was originally obtained from 245.Nx . 246