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 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.Po 32a network interface in the case of 33.Nm , 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. 76A 77.Fn read 78call will return an error 79.Pq Er EHOSTDOWN 80if the interface is not 81.Dq ready 82.Po 83which means that the control device is open and the interface's 84address has been set 85.Pc . 86Once the interface is ready, 87.Fn read 88will return a packet if one is available; if not, it will either block 89until one is or return 90.Er EWOULDBLOCK , 91depending on whether non-blocking I/O has been enabled. If the packet 92is longer than is allowed for in the buffer passed to 93.Fn read , 94the extra data will be silently dropped. 95.Pp 96Packets can be optionally prepended with the destination address as presented 97to the network interface output routine 98.Pq Sq Li tunoutput . 99The destination address is in 100.Sq Li struct sockaddr 101format. 102The 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 TUNSIFINFO 145The argument should be a pointer to an 146.Va struct tuninfo 147and allows setting the MTU, the type, and the baudrate of the tunnel 148device. 149The 150.Va struct tuninfo 151is declared in 152.Aq Pa net/if_tun.h . 153.It Dv TUNGIFINFO 154The argument should be a pointer to an 155.Va struct tuninfo , 156where the current MTU, type, and baudrate will be stored. 157.It Dv TUNSIFMODE 158The argument should be a pointer to an 159.Va int ; 160its value must be either 161.Dv IFF_POINTOPOINT 162or 163.Dv IFF_BROADCAST . 164The type of the corresponding 165.Em tun Ns Sy n 166interface is set to the supplied type. If the value is anything else, 167an 168.Er EINVAL 169error occurs. The interface must be down at the time; if it is up, an 170.Er EBUSY 171error occurs. 172.It Dv TUNSLMODE 173The argument should be a pointer to an 174.Va int ; 175a non-zero value turns on 176.Dq link-layer 177mode, causing packets read from the tunnel device to be prepended with 178network destination address. 179.It Dv TUNSIFPID 180Will set the pid owning the tunnel device to the current process's pid. 181.It Dv TUNSIFHEAD 182The argument should be a pointer to an 183.Va int ; 184a non-zero value turns off 185.Dq link-layer 186mode, and enables multi-af mode, where every packet is preceded with a 187four byte address family. 188.It Dv TUNGIFHEAD 189The argument should be a pointer to an 190.Va int ; 191this stores one if the device is in multi-af mode, and zero otherwise 192in it. 193.It Dv FIONBIO 194Turn non-blocking I/O for reads off or on, according as the argument 195.Va int Ns 's 196value is or isn't zero 197.Pq Writes are always nonblocking . 198.It Dv FIOASYNC 199Turn asynchronous I/O for reads 200.Po 201i.e., generation of 202.Dv SIGIO 203when data is available to be read 204.Pc off or on, according as the argument 205.Va int Ns 's 206value is or isn't zero. 207.It Dv FIONREAD 208If any packets are queued to be read, store the size of the first one 209into the argument 210.Va int ; 211otherwise, store zero. 212.It Dv TIOCSPGRP 213Set the process group to receive 214.Dv SIGIO 215signals, when asynchronous I/O is enabled, to the argument 216.Va int 217value. 218.It Dv TIOCGPGRP 219Retrieve the process group value for 220.Dv SIGIO 221signals into the argument 222.Va int 223value. 224.El 225.Pp 226The control device also supports 227.Xr select 2 228for read; selecting for write is pointless, and always succeeds, since 229writes are always non-blocking. 230.Pp 231On the last close of the data device, by default, the interface is 232brought down 233.Po as if with 234.Dq ifconfig tun Ns Sy n No down 235.Pc . 236All queued packets are thrown away. 237If the interface is up when the data device is not open 238output packets are always thrown away rather than letting 239them pile up. 240.Sh SEE ALSO 241.Xr inet 4 , 242.Xr intro 4 243.Sh AUTHORS 244This man page has been obtained from 245.Bx Net . 246