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 April 29, 2019 6.Dt TUN 4 7.Os 8.Sh NAME 9.Nm tun 10.Nd tunnel software network interface 11.Sh SYNOPSIS 12.Cd device tuntap 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_tuntap.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_tuntap.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 and the baudrate of the tunnel 212device. 213The type must be the same as returned by 214.Dv TUNGIFINFO 215or set to 216.Dv IFT_PPP 217else the 218.Xr ioctl 2 219call will fail. 220The 221.Vt struct tuninfo 222is declared in 223.In net/if_tun.h . 224.Pp 225The use of this ioctl is restricted to the super-user. 226.It Dv TUNGIFINFO 227The argument should be a pointer to an 228.Vt struct tuninfo , 229where the current MTU, type, and baudrate will be stored. 230.It Dv TUNSIFMODE 231The argument should be a pointer to an 232.Vt int ; 233its value must be either 234.Dv IFF_POINTOPOINT 235or 236.Dv IFF_BROADCAST 237and should have 238.Dv IFF_MULTICAST 239OR'd into the value if multicast support is required. 240The type of the corresponding 241.Dq Li tun Ns Ar N 242interface is set to the supplied type. 243If the value is outside the above range, an 244.Er EINVAL 245error is returned. 246The interface must be down at the time; if it is up, an 247.Er EBUSY 248error is returned. 249.It Dv TUNSLMODE 250The argument should be a pointer to an 251.Vt int ; 252a non-zero value turns off 253.Dq multi-af 254mode and turns on 255.Dq link-layer 256mode, causing packets read from the tunnel device to be prepended with 257the network destination address (see above). 258.It Dv TUNSIFPID 259Will set the pid owning the tunnel device to the current process's pid. 260.It Dv TUNSIFHEAD 261The argument should be a pointer to an 262.Vt int ; 263a non-zero value turns off 264.Dq link-layer 265mode, and enables 266.Dq multi-af 267mode, where every packet is preceded with a four byte address family. 268.It Dv TUNGIFHEAD 269The argument should be a pointer to an 270.Vt int ; 271the ioctl sets the value to one if the device is in 272.Dq multi-af 273mode, and zero otherwise. 274.It Dv FIONBIO 275Turn non-blocking I/O for reads off or on, according as the argument 276.Vt int Ns 's 277value is or is not zero. 278(Writes are always non-blocking.) 279.It Dv FIOASYNC 280Turn asynchronous I/O for reads 281(i.e., generation of 282.Dv SIGIO 283when data is available to be read) 284off or on, according as the argument 285.Vt int Ns 's 286value is or is not zero. 287.It Dv FIONREAD 288If any packets are queued to be read, store the size of the first one 289into the argument 290.Vt int ; 291otherwise, store zero. 292.It Dv TIOCSPGRP 293Set the process group to receive 294.Dv SIGIO 295signals, when asynchronous I/O is enabled, to the argument 296.Vt int 297value. 298.It Dv TIOCGPGRP 299Retrieve the process group value for 300.Dv SIGIO 301signals into the argument 302.Vt int 303value. 304.El 305.Pp 306The control device also supports 307.Xr select 2 308for read; selecting for write is pointless, and always succeeds, since 309writes are always non-blocking. 310.Pp 311On the last close of the data device, by default, the interface is 312brought down 313(as if with 314.Nm ifconfig Ar tunN Cm down ) . 315All queued packets are thrown away. 316If the interface is up when the data device is not open 317output packets are always thrown away rather than letting 318them pile up. 319.Sh SEE ALSO 320.Xr ioctl 2 , 321.Xr read 2 , 322.Xr select 2 , 323.Xr write 2 , 324.Xr devname 3 , 325.Xr inet 4 , 326.Xr intro 4 , 327.Xr pty 4 , 328.Xr tap 4 , 329.Xr ifconfig 8 330.Sh AUTHORS 331This manual page was originally obtained from 332.Nx . 333