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 November 30, 2014 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. 38A client program transfers IP (by default) packets to or from the 39.Nm 40.Dq control 41interface. 42The 43.Xr tap 4 44interface provides similar functionality at the Ethernet layer: 45a client will transfer Ethernet frames to or from a 46.Xr tap 4 47.Dq control 48interface. 49.Pp 50The network interfaces are named 51.Dq Li tun0 , 52.Dq Li tun1 , 53etc., one for each control device that has been opened. 54These network interfaces persist until the 55.Pa if_tun.ko 56module is unloaded, or until removed with the 57.Xr ifconfig 8 58command. 59.Pp 60.Nm 61devices are created using interface cloning. 62This is done using the 63.Dq ifconfig tun Ns Sy N No create 64command. 65This is the preferred method of creating 66.Nm 67devices. 68The same method allows removal of interfaces. 69For this, use the 70.Dq ifconfig tun Ns Sy N No destroy 71command. 72.Pp 73If the 74.Xr sysctl 8 75variable 76.Va net.link.tun.devfs_cloning 77is non-zero, the 78.Nm 79interface 80permits opens on the special control device 81.Pa /dev/tun . 82When this device is opened, 83.Nm 84will return a handle for the lowest unused 85.Nm 86device (use 87.Xr devname 3 88to determine which). 89.Pp 90.Bf Em 91Disabling the legacy devfs cloning functionality may break existing 92applications which use 93.Nm , 94such as 95.Xr ppp 8 96and 97.Xr ssh 1 . 98It therefore defaults to being enabled until further notice. 99.Ef 100.Pp 101Control devices (once successfully opened) persist until 102.Pa if_tun.ko 103is unloaded in the same way that network interfaces persist (see above). 104.Pp 105Each interface supports the usual network-interface 106.Xr ioctl 2 Ns s , 107such as 108.Dv SIOCAIFADDR 109and thus can be used with 110.Xr ifconfig 8 111like any other interface. 112At boot time, they are 113.Dv POINTOPOINT 114interfaces, but this can be changed; see the description of the control 115device, below. 116When the system chooses to transmit a packet on the 117network interface, the packet can be read from the control device 118(it appears as 119.Dq input 120there); 121writing a packet to the control device generates an input 122packet on the network interface, as if the (non-existent) 123hardware had just received it. 124.Pp 125The tunnel device 126.Pq Pa /dev/tun Ns Ar N 127is exclusive-open 128(it cannot be opened if it is already open). 129A 130.Xr read 2 131call will return an error 132.Pq Er EHOSTDOWN 133if the interface is not 134.Dq ready 135(which means that the control device is open and the interface's 136address has been set). 137.Pp 138Once the interface is ready, 139.Xr read 2 140will return a packet if one is available; if not, it will either block 141until one is or return 142.Er EWOULDBLOCK , 143depending on whether non-blocking I/O has been enabled. 144If the packet is longer than is allowed for in the buffer passed to 145.Xr read 2 , 146the extra data will be silently dropped. 147.Pp 148If the 149.Dv TUNSLMODE 150ioctl has been set, packets read from the control device will be prepended 151with the destination address as presented to the network interface output 152routine, 153.Fn tunoutput . 154The destination address is in 155.Vt struct sockaddr 156format. 157The actual length of the prepended address is in the member 158.Va sa_len . 159If the 160.Dv TUNSIFHEAD 161ioctl has been set, packets will be prepended with a four byte address 162family in network byte order. 163.Dv TUNSLMODE 164and 165.Dv TUNSIFHEAD 166are mutually exclusive. 167In any case, the packet data follows immediately. 168.Pp 169A 170.Xr write 2 171call passes a packet in to be 172.Dq received 173on the pseudo-interface. 174If the 175.Dv TUNSIFHEAD 176ioctl has been set, the address family must be prepended, otherwise the 177packet is assumed to be of type 178.Dv AF_INET . 179Each 180.Xr write 2 181call supplies exactly one packet; the packet length is taken from the 182amount of data provided to 183.Xr write 2 184(minus any supplied address family). 185Writes will not block; if the packet cannot be accepted for a 186transient reason 187(e.g., no buffer space available), 188it is silently dropped; if the reason is not transient 189(e.g., packet too large), 190an error is returned. 191.Pp 192The following 193.Xr ioctl 2 194calls are supported 195(defined in 196.In net/if_tun.h ) : 197.Bl -tag -width ".Dv TUNSIFMODE" 198.It Dv TUNSDEBUG 199The argument should be a pointer to an 200.Vt int ; 201this sets the internal debugging variable to that value. 202What, if anything, this variable controls is not documented here; see 203the source code. 204.It Dv TUNGDEBUG 205The argument should be a pointer to an 206.Vt int ; 207this stores the internal debugging variable's value into it. 208.It Dv TUNSIFINFO 209The argument should be a pointer to an 210.Vt struct tuninfo 211and allows setting the MTU, the type, and the baudrate of the tunnel 212device. 213The 214.Vt struct tuninfo 215is declared in 216.In net/if_tun.h . 217.Pp 218The use of this ioctl is restricted to the super-user. 219.It Dv TUNGIFINFO 220The argument should be a pointer to an 221.Vt struct tuninfo , 222where the current MTU, type, and baudrate will be stored. 223.It Dv TUNSIFMODE 224The argument should be a pointer to an 225.Vt int ; 226its value must be either 227.Dv IFF_POINTOPOINT 228or 229.Dv IFF_BROADCAST 230and should have 231.Dv IFF_MULTICAST 232OR'd into the value if multicast support is required. 233The type of the corresponding 234.Dq Li tun Ns Ar N 235interface is set to the supplied type. 236If the value is outside the above range, an 237.Er EINVAL 238error is returned. 239The interface must be down at the time; if it is up, an 240.Er EBUSY 241error is returned. 242.It Dv TUNSLMODE 243The argument should be a pointer to an 244.Vt int ; 245a non-zero value turns off 246.Dq multi-af 247mode and turns on 248.Dq link-layer 249mode, causing packets read from the tunnel device to be prepended with 250the network destination address (see above). 251.It Dv TUNSIFPID 252Will set the pid owning the tunnel device to the current process's pid. 253.It Dv TUNSIFHEAD 254The argument should be a pointer to an 255.Vt int ; 256a non-zero value turns off 257.Dq link-layer 258mode, and enables 259.Dq multi-af 260mode, where every packet is preceded with a four byte address family. 261.It Dv TUNGIFHEAD 262The argument should be a pointer to an 263.Vt int ; 264the ioctl sets the value to one if the device is in 265.Dq multi-af 266mode, and zero otherwise. 267.It Dv FIONBIO 268Turn non-blocking I/O for reads off or on, according as the argument 269.Vt int Ns 's 270value is or is not zero. 271(Writes are always non-blocking.) 272.It Dv FIOASYNC 273Turn asynchronous I/O for reads 274(i.e., generation of 275.Dv SIGIO 276when data is available to be read) 277off or on, according as the argument 278.Vt int Ns 's 279value is or is not zero. 280.It Dv FIONREAD 281If any packets are queued to be read, store the size of the first one 282into the argument 283.Vt int ; 284otherwise, store zero. 285.It Dv TIOCSPGRP 286Set the process group to receive 287.Dv SIGIO 288signals, when asynchronous I/O is enabled, to the argument 289.Vt int 290value. 291.It Dv TIOCGPGRP 292Retrieve the process group value for 293.Dv SIGIO 294signals into the argument 295.Vt int 296value. 297.El 298.Pp 299The control device also supports 300.Xr select 2 301for read; selecting for write is pointless, and always succeeds, since 302writes are always non-blocking. 303.Pp 304On the last close of the data device, by default, the interface is 305brought down 306(as if with 307.Nm ifconfig Ar tunN Cm down ) . 308All queued packets are thrown away. 309If the interface is up when the data device is not open 310output packets are always thrown away rather than letting 311them pile up. 312.Sh SEE ALSO 313.Xr ioctl 2 , 314.Xr read 2 , 315.Xr select 2 , 316.Xr write 2 , 317.Xr devname 3 , 318.Xr inet 4 , 319.Xr intro 4 , 320.Xr pty 4 , 321.Xr tap 4 , 322.Xr ifconfig 8 323.Sh AUTHORS 324This manual page was originally obtained from 325.Nx . 326