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