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