1.\" $NetBSD: tun.4,v 1.17 2004/12/05 13:28:54 wiz Exp $ 2.\" 3.\" Copyright (c) 1996-2003 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by der Mouse. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 29.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.Dd November 22, 2004 38.Dt TUN 4 39.Os 40.Sh NAME 41.Nm tun 42.Nd tunnel software network interface 43.Sh SYNOPSIS 44.Cd pseudo-device tun 45.Sh DESCRIPTION 46The 47.Nm tun 48interface is a software loopback mechanism that can be loosely 49described as the network interface analog of the 50.Xr pty 4 , 51that is, 52.Nm tun 53does for network interfaces what the 54.Nm pty 55driver does for terminals. 56.Pp 57The 58.Nm tun 59driver, like the 60.Nm pty 61driver, provides two interfaces: an interface like the usual facility 62it is simulating 63.Po 64a network interface in the case of 65.Nm tun , 66or a terminal for 67.Nm pty 68.Pc , 69and a character-special device 70.Dq control 71interface. 72.Pp 73To use a 74.Nm tun 75device, the administrator must first create the interface. 76This can be done by using the 77.Xr ifconfig 8 78.Cm create 79command, or via the 80.Dv SIOCIFCREATE 81ioctl. 82An 83.Fn open 84call on 85.Pa /dev/tun Ns Sy N , 86will also create a network interface with the same unit number of 87that device if it doesn't exists yet. 88.Pp 89The network interfaces should be named 90.Sy tun Ns Ar 0 , 91.Sy tun Ns Ar 1 , 92etc. 93Each interface supports the usual network-interface 94.Xr ioctl 2 Ns s , 95such as 96.Dv SIOCSIFADDR 97and 98.Dv SIOCSIFNETMASK , 99and thus can be used with 100.Xr ifconfig 8 101like any other interface. 102At boot time, they are 103.Dv POINTOPOINT 104interfaces, but this can be changed; see the description of the control 105device, below. 106When the system chooses to transmit a packet on the 107network interface, the packet can be read from the control device 108.Po 109it appears there as 110.Dq output 111.Pc ; 112writing a packet to the control device generates an input 113packet on the network interface, as if the 114.Pq non-existent 115hardware had just received it. 116.Pp 117The tunnel device, normally 118.Pa /dev/tun Ns Sy N , 119is exclusive-open 120.Po 121it cannot be opened if it is already open 122.Pc 123and is restricted to the super-user 124.Pq regardless of file system permissions . 125A 126.Fn read 127call will return an error 128.Pq Er EHOSTDOWN 129if the interface is not 130.Dq ready 131(which means that the interface 132address has not been set). 133Once the interface is ready, 134.Fn read 135will return a packet if one is available; if not, it will either block 136until one is or return 137.Er EAGAIN , 138depending on whether non-blocking I/O has been enabled. 139If the packet 140is longer than is allowed for in the buffer passed to 141.Fn read , 142the extra data will be silently dropped. 143.Pp 144Packets can be optionally prepended with the destination address as presented 145to the network interface output routine 146.Pq Sq Li tunoutput . 147The destination address is in 148.Sq Li struct sockaddr 149format. 150The actual length of the prepended address is in the member 151.Sq Li sa_len . 152The packet data follows immediately. 153A 154.Xr write 2 155call passes a packet in to be 156.Dq received 157on the pseudo-interface. 158Each 159.Fn write 160call supplies exactly one packet; the packet length is taken from the 161amount of data provided to 162.Fn write . 163Writes will not block; if the packet cannot be accepted for a 164transient reason 165.Pq e.g., no buffer space available , 166it is silently dropped; if the reason is not transient 167.Pq e.g., packet too large , 168an error is returned. 169If 170.Dq link-layer mode 171is on 172.Pq see Dv TUNSLMODE No below , 173the actual packet data must be preceded by a 174.Sq Li struct sockaddr . 175The driver currently only inspects the 176.Sq Li sa_family 177field. 178The following 179.Xr ioctl 2 180calls are supported 181.Pq defined in Aq Pa net/if_tun.h : 182.Bl -tag -width TUNSIFMODE 183.It Dv TUNSDEBUG 184The argument should be a pointer to an 185.Va int ; 186this sets the internal debugging variable to that value. 187What, if anything, this variable controls is not documented here; 188see the source code. 189.It Dv TUNGDEBUG 190The argument should be a pointer to an 191.Va int ; 192this stores the internal debugging variable's value into it. 193.It Dv TUNSIFMODE 194The argument should be a pointer to an 195.Va int ; 196its value must be either 197.Dv IFF_POINTOPOINT 198or 199.Dv IFF_BROADCAST 200(optionally 201.Dv IFF_MULTICAST 202may be or'ed into the value). 203The type of the corresponding 204.Em tun Ns Sy n 205interface is set to the supplied type. 206If the value is anything else, an 207.Er EINVAL 208error occurs. 209The interface must be down at the time; if it is up, an 210.Er EBUSY 211error occurs. 212.It Dv TUNSLMODE 213The argument should be a pointer to an 214.Va int ; 215a non-zero value turns on 216.Dq link-layer 217mode, causing packets read from the tunnel device to be prepended with 218network destination address. 219.It Dv FIONBIO 220Turn non-blocking I/O for reads off or on, according as the argument 221.Va int Ns 's 222value is or isn't zero 223.Pq Writes are always nonblocking . 224.It Dv FIOASYNC 225Turn asynchronous I/O for reads 226.Po 227i.e., generation of 228.Dv SIGIO 229when data is available to be read 230.Pc off or on, according as the argument 231.Va int Ns 's 232value is or isn't zero. 233.It Dv FIONREAD 234If any packets are queued to be read, store the size of the first one 235into the argument 236.Va int ; 237otherwise, store zero. 238.It Dv TIOCSPGRP 239Set the process group to receive 240.Dv SIGIO 241signals, when asynchronous I/O is enabled, to the argument 242.Va int 243value. 244.It Dv TIOCGPGRP 245Retrieve the process group value for 246.Dv SIGIO 247signals into the argument 248.Va int 249value. 250.El 251.Pp 252The control device also supports 253.Xr select 2 254for read; selecting for write is pointless, and always succeeds, since 255writes are always non-blocking. 256.Pp 257On the last close of the data device, by default, the interface is 258brought down 259.Po as if with 260.Dq ifconfig tun Ns Sy n No down 261.Pc . 262All queued packets are thrown away. 263If the interface is up when the data device is not open 264output packets are always thrown away rather than letting 265them pile up. 266.Sh SEE ALSO 267.Xr inet 4 , 268.Xr intro 4 269.Sh BUGS 270Currently is IPv4-only. 271