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