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