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 June 5, 2001 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 SIOCSIFADDR 69and 70.Dv SIOCSIFNETMASK , 71and thus can be used with 72.Xr ifconfig 8 73like any other interface. 74At boot time, they are 75.Dv POINTOPOINT 76interfaces, but this can be changed; see the description of the control 77device, below. 78When the system chooses to transmit a packet on the 79network interface, the packet can be read from the control device 80(it appears as 81.Dq input 82there); 83writing a packet to the control device generates an input 84packet on the network interface, as if the (non-existent) 85hardware had just received it. 86.Pp 87The tunnel device 88.Pq Pa /dev/tun Ns Ar N 89is exclusive-open 90(it cannot be opened if it is already open). 91A 92.Xr read 2 93call will return an error 94.Pq Er EHOSTDOWN 95if the interface is not 96.Dq ready 97(which means that the control device is open and the interface's 98address has been set). 99.Pp 100Once the interface is ready, 101.Xr read 2 102will return a packet if one is available; if not, it will either block 103until one is or return 104.Er EWOULDBLOCK , 105depending on whether non-blocking I/O has been enabled. 106If the packet is longer than is allowed for in the buffer passed to 107.Xr read 2 , 108the extra data will be silently dropped. 109.Pp 110If the 111.Dv TUNSLMODE 112ioctl has been set, packets read from the control device will be prepended 113with the destination address as presented to the network interface output 114routine, 115.Fn tunoutput . 116The destination address is in 117.Vt struct sockaddr 118format. 119The actual length of the prepended address is in the member 120.Va sa_len . 121If the 122.Dv TUNSIFHEAD 123ioctl has been set, packets will be prepended with a four byte address 124family in network byte order. 125.Dv TUNSLMODE 126and 127.Dv TUNSIFHEAD 128are mutually exclusive. 129In any case, the packet data follows immediately. 130.Pp 131A 132.Xr write 2 133call passes a packet in to be 134.Dq received 135on the pseudo-interface. 136If the 137.Dv TUNSIFHEAD 138ioctl has been set, the address family must be prepended, otherwise the 139packet is assumed to be of type 140.Dv AF_INET . 141Each 142.Xr write 2 143call supplies exactly one packet; the packet length is taken from the 144amount of data provided to 145.Xr write 2 146(minus any supplied address family). 147Writes will not block; if the packet cannot be accepted for a 148transient reason 149(e.g., no buffer space available), 150it is silently dropped; if the reason is not transient 151(e.g., packet too large), 152an error is returned. 153.Pp 154The following 155.Xr ioctl 2 156calls are supported 157(defined in 158.In net/if_tun.h ) : 159.Bl -tag -width ".Dv TUNSIFMODE" 160.It Dv TUNSDEBUG 161The argument should be a pointer to an 162.Vt int ; 163this sets the internal debugging variable to that value. 164What, if anything, this variable controls is not documented here; see 165the source code. 166.It Dv TUNGDEBUG 167The argument should be a pointer to an 168.Vt int ; 169this stores the internal debugging variable's value into it. 170.It Dv TUNSIFINFO 171The argument should be a pointer to an 172.Vt struct tuninfo 173and allows setting the MTU, the type, and the baudrate of the tunnel 174device. 175The 176.Vt struct tuninfo 177is declared in 178.In net/if_tun.h . 179.Pp 180The use of this ioctl is restricted to the super-user. 181.It Dv TUNGIFINFO 182The argument should be a pointer to an 183.Vt struct tuninfo , 184where the current MTU, type, and baudrate will be stored. 185.It Dv TUNSIFMODE 186The argument should be a pointer to an 187.Vt int ; 188its value must be either 189.Dv IFF_POINTOPOINT 190or 191.Dv IFF_BROADCAST 192and should have 193.Dv IFF_MULTICAST 194OR'd into the value if multicast support is required. 195The type of the corresponding 196.Dq Li tun Ns Ar N 197interface is set to the supplied type. 198If the value is outside the above range, an 199.Er EINVAL 200error is returned. 201The interface must be down at the time; if it is up, an 202.Er EBUSY 203error is returned. 204.It Dv TUNSLMODE 205The argument should be a pointer to an 206.Vt int ; 207a non-zero value turns off 208.Dq multi-af 209mode and turns on 210.Dq link-layer 211mode, causing packets read from the tunnel device to be prepended with 212the network destination address (see above). 213.It Dv TUNSIFPID 214Will set the pid owning the tunnel device to the current process's pid. 215.It Dv TUNSIFHEAD 216The argument should be a pointer to an 217.Vt int ; 218a non-zero value turns off 219.Dq link-layer 220mode, and enables 221.Dq multi-af 222mode, where every packet is preceded with a four byte address family. 223.It Dv TUNGIFHEAD 224The argument should be a pointer to an 225.Vt int ; 226the ioctl sets the value to one if the device is in 227.Dq multi-af 228mode, and zero otherwise. 229.It Dv FIONBIO 230Turn non-blocking I/O for reads off or on, according as the argument 231.Vt int Ns 's 232value is or is not zero. 233(Writes are always non-blocking.) 234.It Dv FIOASYNC 235Turn asynchronous I/O for reads 236(i.e., generation of 237.Dv SIGIO 238when data is available to be read) 239off or on, according as the argument 240.Vt int Ns 's 241value is or is not zero. 242.It Dv FIONREAD 243If any packets are queued to be read, store the size of the first one 244into the argument 245.Vt int ; 246otherwise, store zero. 247.It Dv TIOCSPGRP 248Set the process group to receive 249.Dv SIGIO 250signals, when asynchronous I/O is enabled, to the argument 251.Vt int 252value. 253.It Dv TIOCGPGRP 254Retrieve the process group value for 255.Dv SIGIO 256signals into the argument 257.Vt int 258value. 259.El 260.Pp 261The control device also supports 262.Xr select 2 263for read; selecting for write is pointless, and always succeeds, since 264writes are always non-blocking. 265.Pp 266On the last close of the data device, by default, the interface is 267brought down 268(as if with 269.Nm ifconfig Ar tunN Cm down ) . 270All queued packets are thrown away. 271If the interface is up when the data device is not open 272output packets are always thrown away rather than letting 273them pile up. 274.Sh SEE ALSO 275.Xr ioctl 2 , 276.Xr read 2 , 277.Xr select 2 , 278.Xr write 2 , 279.Xr devname 3 , 280.Xr inet 4 , 281.Xr intro 4 , 282.Xr pty 4 , 283.Xr ifconfig 8 284.Sh AUTHORS 285This manual page was originally obtained from 286.Nx . 287