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