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