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