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