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