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