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 July 17, 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, 137.Fn tunoutput . 138The destination address is in 139.Vt struct sockaddr 140format. 141The actual length of the prepended address is in the member 142.Va sa_len . 143If the 144.Dv TUNSIFHEAD 145ioctl has been set (i.e., 146.Dq multi-af 147mode), packets will be prepended with a 4-byte address 148family in network byte order. 149.Dv TUNSLMODE 150and 151.Dv TUNSIFHEAD 152are mutually exclusive. 153In any case, the packet data follows immediately. 154.Pp 155A 156.Xr write 2 157call passes a packet in to be 158.Dq received 159on the pseudo-interface. 160Each 161.Xr write 2 162call supplies exactly one packet; the packet length is taken from the 163amount of data provided to 164.Xr write 2 165(minus any supplied address family). 166Writes will not block; if the packet cannot be accepted for a 167transient reason 168(e.g., no buffer space available), 169it is silently dropped; if the reason is not transient 170(e.g., packet too large), 171an error is returned. 172.Pp 173If the 174.Dv TUNSLMODE 175ioctl has been set (i.e., 176.Dq link-layer 177mode), the actual packet data must be preceded by a 178.Vt struct sockaddr . 179The driver currently only inspects the 180.Va sa_family 181field. 182If the 183.Dv TUNSIFHEAD 184ioctl has been set (i.e., 185.Dq multi-af 186mode), the address family must be prepended, otherwise the 187packet is assumed to be of type 188.Dv AF_INET . 189.Pp 190The following 191.Xr ioctl 2 192calls are supported 193(defined in 194.In net/tun/if_tun.h ) : 195.Bl -tag -width ".Dv TUNSIFMODE" 196.It Dv TUNSDEBUG 197The argument should be a pointer to an 198.Vt int ; 199this sets the internal debugging variable to that value. 200What, if anything, this variable controls is not documented here; see 201the source code. 202.It Dv TUNGDEBUG 203The argument should be a pointer to an 204.Vt int ; 205this stores the internal debugging variable's value into it. 206.It Dv TUNSIFINFO 207The argument should be a pointer to an 208.Vt struct tuninfo 209and allows setting the MTU and the baudrate of the tunnel device. 210The type must be the same as returned by 211.Dv TUNGIFINFO 212or set to 213.Dv IFT_PPP , 214otherwise the 215.Xr ioctl 2 216call will fail. 217.Vt struct tuninfo 218is declared in 219.In net/tun/if_tun.h . 220.It Dv TUNGIFINFO 221The argument should be a pointer to an 222.Vt struct tuninfo , 223where the current MTU, type, and baudrate will be stored. 224.It Dv TUNSIFMODE 225The argument should be a pointer to an 226.Vt int ; 227its value must be either 228.Dv IFF_POINTOPOINT 229or 230.Dv IFF_BROADCAST 231and should have 232.Dv IFF_MULTICAST 233OR'd into the value if multicast support is required. 234The type of the corresponding 235.Dq Li tun Ns Ar N 236interface is set to the supplied type. 237If the value is anything else, an 238.Er EINVAL 239error is returned. 240The interface must be down at the time; if it is up, an 241.Er EBUSY 242error is returned. 243.It Dv TUNSLMODE 244The argument should be a pointer to an 245.Vt int ; 246a non-zero value turns off 247.Dq multi-af 248mode and turns on 249.Dq link-layer 250mode, causing packets read from the tunnel device to be prepended with 251the network destination address (see above). 252.It Dv TUNSIFPID 253Will set the PID owning the tunnel device to the current process's PID. 254.It Dv TUNSIFHEAD 255The argument should be a pointer to an 256.Vt int ; 257a non-zero value turns off 258.Dq link-layer 259mode, and enables 260.Dq multi-af 261mode, where every packet is preceded with a 4-byte address family. 262.It Dv TUNGIFHEAD 263The argument should be a pointer to an 264.Vt int ; 265the ioctl sets the value to one if the device is in 266.Dq multi-af 267mode, and zero otherwise. 268.It Dv FIOASYNC 269Turn asynchronous I/O for reads 270(i.e., generation of 271.Dv SIGIO 272when data is available to be read) 273off or on, according as the argument 274.Vt int Ns 's 275value is or is not zero. 276.It Dv FIONREAD 277If any packets are queued to be read, store the size of the first one 278into the argument 279.Vt int ; 280otherwise, store zero. 281.It Dv TIOCSPGRP 282Set the process group to receive 283.Dv SIGIO 284signals, when asynchronous I/O is enabled, to the argument 285.Vt int 286value. 287.It Dv TIOCGPGRP 288Retrieve the process group value for 289.Dv SIGIO 290signals into the argument 291.Vt int 292value. 293.El 294.Pp 295The control device also supports 296.Xr select 2 297for read; selecting for write is pointless, and always succeeds, since 298writes are always non-blocking. 299.Pp 300On the last close of the data device, by default, the interface is 301brought down 302(as if with 303.Nm ifconfig Ar tunN Cm down ) . 304All queued packets are thrown away. 305If the interface is up when the data device is not open 306output packets are always thrown away rather than letting 307them pile up. 308.Sh SEE ALSO 309.Xr ioctl 2 , 310.Xr devname 3 , 311.Xr inet 4 , 312.Xr tap 4 , 313.Xr ifconfig 8 314.Sh AUTHORS 315This manual page was originally obtained from 316.Nx . 317