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.\" $DragonFly: src/share/man/man4/tun.4,v 1.2 2003/06/17 04:36:59 dillon Exp $ 4.\" Based on PR#2411 5.\" 6.Dd March 10, 1996 7.Dt TUN 4 8.Os 9.Sh NAME 10.Nm tun 11.Nd tunnel software network interface 12.Sh SYNOPSIS 13.Cd pseudo-device tun 14.Sh DESCRIPTION 15The 16.Nm 17interface is a software loopback mechanism that can be loosely 18described as the network interface analog of the 19.Xr pty 4 , 20that is, 21.Nm 22does for network interfaces what the 23.Xr pty 4 24driver does for terminals. 25.Pp 26The 27.Nm 28driver, like the 29.Xr pty 4 30driver, provides two interfaces: an interface like the usual facility 31it is simulating 32(a network interface in the case of 33.Nm , 34or a terminal for 35.Xr pty 4 ) , 36and a character-special device 37.Dq control 38interface. 39.Pp 40The network interfaces are named 41.Dq Li tun0 , 42.Dq Li tun1 , 43etc, as many as were made by 44.Xr MAKEDEV 8 . 45Each one supports the usual network-interface 46.Xr ioctl 2 Ns s , 47such as 48.Dv SIOCSIFADDR 49and 50.Dv SIOCSIFNETMASK , 51and thus can be used with 52.Xr ifconfig 8 53like any other interface. 54At boot time, they are 55.Dv POINTOPOINT 56interfaces, but this can be changed; see the description of the control 57device, below. 58When the system chooses to transmit a packet on the 59network interface, the packet can be read from the control device 60(it appears as 61.Dq input 62there); 63writing a packet to the control device generates an input 64packet on the network interface, as if the (non\-existent) 65hardware had just received it. 66.Pp 67The tunnel device, normally 68.Pa /dev/tun Ns Ar N , 69is exclusive-open 70(it cannot be opened if it is already open) 71and is restricted to the super-user. 72A 73.Xr read 2 74call will return an error 75.Pq Er EHOSTDOWN 76if the interface is not 77.Dq ready 78(which means that the control device is open and the interface's 79address has been set). 80.Pp 81Once the interface is ready, 82.Xr read 2 83will return a packet if one is available; if not, it will either block 84until one is or return 85.Er EWOULDBLOCK , 86depending on whether non-blocking I/O has been enabled. 87If the packet is longer than is allowed for in the buffer passed to 88.Xr read 2 , 89the extra data will be silently dropped. 90.Pp 91Packets can be optionally prepended with the destination address as presented 92to the network interface output routine, 93.Fn tunoutput . 94The destination address is in 95.Vt struct sockaddr 96format. 97The actual length of the prepended address is in the member 98.Va sa_len . 99The packet data follows immediately. 100.Pp 101A 102.Xr write 2 103call passes a packet in to be 104.Dq received 105on the pseudo-interface. 106Each 107.Xr write 2 108call supplies exactly one packet; the packet length is taken from the 109amount of data provided to 110.Xr write 2 . 111Writes will not block; if the packet cannot be accepted for a 112transient reason 113(e.g., no buffer space available), 114it is silently dropped; if the reason is not transient 115(e.g., packet too large), 116an error is returned. 117If 118.Dq link-layer mode 119is on 120(see 121.Dv TUNSLMODE 122below), 123the actual packet data must be preceded by a 124.Vt struct sockaddr . 125The driver currently only inspects the 126.Va sa_family 127field. 128.Pp 129The following 130.Xr ioctl 2 131calls are supported 132(defined in 133.Aq Pa net/if_tun.h ) : 134.Bl -tag -width ".Dv TUNSIFMODE" 135.It Dv TUNSDEBUG 136The argument should be a pointer to an 137.Vt int ; 138this sets the internal debugging variable to that value. 139What, if anything, this variable controls is not documented here; see 140the source code. 141.It Dv TUNGDEBUG 142The argument should be a pointer to an 143.Vt int ; 144this stores the internal debugging variable's value into it. 145.It Dv TUNSIFINFO 146The argument should be a pointer to an 147.Vt struct tuninfo 148and allows setting the MTU, the type, and the baudrate of the tunnel 149device. 150The 151.Vt struct tuninfo 152is declared in 153.Aq Pa net/if_tun.h . 154.It Dv TUNGIFINFO 155The argument should be a pointer to an 156.Vt struct tuninfo , 157where the current MTU, type, and baudrate will be stored. 158.It Dv TUNSIFMODE 159The argument should be a pointer to an 160.Vt int ; 161its value must be either 162.Dv IFF_POINTOPOINT 163or 164.Dv IFF_BROADCAST . 165The type of the corresponding 166.Dq Li tun Ns Ar N 167interface is set to the supplied type. 168If the value is anything else, an 169.Er EINVAL 170error occurs. 171The interface must be down at the time; if it is up, an 172.Er EBUSY 173error occurs. 174.It Dv TUNSLMODE 175The argument should be a pointer to an 176.Vt int ; 177a non-zero value turns on 178.Dq link-layer 179mode, causing packets read from the tunnel device to be prepended with 180network destination address. 181.It Dv TUNSIFPID 182Will set the pid owning the tunnel device to the current process's pid. 183.It Dv TUNSIFHEAD 184The argument should be a pointer to an 185.Vt int ; 186a non-zero value turns off 187.Dq link-layer 188mode, and enables 189.Dq multi-af 190mode, where every packet is preceded with a four byte address family. 191.It Dv TUNGIFHEAD 192The argument should be a pointer to an 193.Vt int ; 194this stores one if the device is in 195.Dq multi-af 196mode, and zero otherwise in it. 197.It Dv FIONBIO 198Turn non-blocking I/O for reads off or on, according as the argument 199.Vt int Ns 's 200value is or isn't zero. 201(Writes are always non-blocking.) 202.It Dv FIOASYNC 203Turn asynchronous I/O for reads 204(i.e., generation of 205.Dv SIGIO 206when data is available to be read) 207off or on, according as the argument 208.Vt int Ns 's 209value is or isn't zero. 210.It Dv FIONREAD 211If any packets are queued to be read, store the size of the first one 212into the argument 213.Vt int ; 214otherwise, store zero. 215.It Dv TIOCSPGRP 216Set the process group to receive 217.Dv SIGIO 218signals, when asynchronous I/O is enabled, to the argument 219.Vt int 220value. 221.It Dv TIOCGPGRP 222Retrieve the process group value for 223.Dv SIGIO 224signals into the argument 225.Vt int 226value. 227.El 228.Pp 229The control device also supports 230.Xr select 2 231for read; selecting for write is pointless, and always succeeds, since 232writes are always non-blocking. 233.Pp 234On the last close of the data device, by default, the interface is 235brought down 236(as if with 237.Nm ifconfig Ar tunN Cm down ) . 238All queued packets are thrown away. 239If the interface is up when the data device is not open 240output packets are always thrown away rather than letting 241them pile up. 242.Sh SEE ALSO 243.Xr inet 4 , 244.Xr intro 4 245.Sh AUTHORS 246This manual page was originally obtained from 247.Nx . 248