1.\" $NetBSD: tun.4,v 1.14 2003/03/09 23:29:52 jdolecek 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 March 10, 1996 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 Op Ar count 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. This can 76be done by using the 77.Xr ifconfig 8 78.Sq create 79command, or via the 80.Dv SIOCIFCREATE 81ioctl. Note that an 82.Fn open 83call on 84.Pa /dev/tun Ns Sy N , 85will indicate that the device is not configured 86.Pq Er ENXIO 87unless the corresponding network interface has been created. 88.Pp 89The network interfaces are named 90.Sy tun Ns Ar 0 , 91.Sy tun Ns Ar 1 , 92etc, as many in all as the 93.Ar count 94figure given on the 95.Sy pseudo-device 96line. Each one supports the usual network-interface 97.Xr ioctl 2 Ns s , 98such as 99.Dv SIOCSIFADDR 100and 101.Dv SIOCSIFNETMASK , 102and thus can be used with 103.Xr ifconfig 8 104like any other interface. At boot time, they are 105.Dv POINTOPOINT 106interfaces, but this can be changed; see the description of the control 107device, below. When the system chooses to transmit a packet on the 108network interface, the packet can be read from the control device 109.Po 110it appears there as 111.Dq output 112.Pc ; 113writing a packet to the control device generates an input 114packet on the network interface, as if the 115.Pq non-existent 116hardware had just received it. 117.Pp 118The tunnel device, normally 119.Pa /dev/tun Ns Sy N , 120is exclusive-open 121.Po 122it cannot be opened if it is already open 123.Pc 124and is restricted to the super-user 125.Po 126regardless of file system permissions 127.Pc . A 128.Fn read 129call will return an error 130.Pq Er EHOSTDOWN 131if the interface is not 132.Dq ready 133(which means that the interface 134address has not been set). 135Once the interface is ready, 136.Fn read 137will return a packet if one is available; if not, it will either block 138until one is or return 139.Er EAGAIN , 140depending on whether non-blocking I/O has been enabled. If the packet 141is longer than is allowed for in the buffer passed to 142.Fn read , 143the extra data will be silently dropped. 144.Pp 145Packets can be optionally prepended with the destination address as presented 146to the network interface output routine 147.Pq Sq Li tunoutput . 148The destination address is in 149.Sq Li struct sockaddr 150format. The 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. Each 158.Fn write 159call supplies exactly one packet; the packet length is taken from the 160amount of data provided to 161.Fn write . 162Writes will not block; if the packet cannot be accepted for a 163transient reason 164.Pq e.g., no buffer space available , 165it is silently dropped; if the reason is not transient 166.Pq e.g., packet too large , 167an error is returned. 168If 169.Dq link-layer mode 170is on 171.Pq see Dv TUNSLMODE No below , 172the actual packet data must be preceded by a 173.Sq Li struct sockaddr . 174The driver currently only inspects the 175.Sq Li sa_family 176field. 177The following 178.Xr ioctl 2 179calls are supported 180.Pq defined in Aq Pa net/if_tun.h : 181.Bl -tag -width TUNSIFMODE 182.It Dv TUNSDEBUG 183The argument should be a pointer to an 184.Va int ; 185this sets the internal debugging variable to that value. What, if 186anything, this variable controls is not documented here; see the source 187code. 188.It Dv TUNGDEBUG 189The argument should be a pointer to an 190.Va int ; 191this stores the internal debugging variable's value into it. 192.It Dv TUNSIFMODE 193The argument should be a pointer to an 194.Va int ; 195its value must be either 196.Dv IFF_POINTOPOINT 197or 198.Dv IFF_BROADCAST 199(optionally 200.Dv IFF_MULTICAST 201may be or'ed into the value). The type of the corresponding 202.Em tun Ns Sy n 203interface is set to the supplied type. If the value is anything else, 204an 205.Er EINVAL 206error occurs. The interface must be down at the time; if it is up, an 207.Er EBUSY 208error occurs. 209.It Dv TUNSLMODE 210The argument should be a pointer to an 211.Va int ; 212a non-zero value turns on 213.Dq link-layer 214mode, causing packets read from the tunnel device to be prepended with 215network destination address. 216.It Dv FIONBIO 217Turn non-blocking I/O for reads off or on, according as the argument 218.Va int Ns 's 219value is or isn't zero 220.Pq Writes are always nonblocking . 221.It Dv FIOASYNC 222Turn asynchronous I/O for reads 223.Po 224i.e., generation of 225.Dv SIGIO 226when data is available to be read 227.Pc off or on, according as the argument 228.Va int Ns 's 229value is or isn't zero. 230.It Dv FIONREAD 231If any packets are queued to be read, store the size of the first one 232into the argument 233.Va int ; 234otherwise, store zero. 235.It Dv TIOCSPGRP 236Set the process group to receive 237.Dv SIGIO 238signals, when asynchronous I/O is enabled, to the argument 239.Va int 240value. 241.It Dv TIOCGPGRP 242Retrieve the process group value for 243.Dv SIGIO 244signals into the argument 245.Va int 246value. 247.El 248.Pp 249The control device also supports 250.Xr select 2 251for read; selecting for write is pointless, and always succeeds, since 252writes are always non-blocking. 253.Pp 254On the last close of the data device, by default, the interface is 255brought down 256.Po as if with 257.Dq ifconfig tun Ns Sy n No down 258.Pc . 259All queued packets are thrown away. 260If the interface is up when the data device is not open 261output packets are always thrown away rather than letting 262them pile up. 263.Sh SEE ALSO 264.Xr inet 4 , 265.Xr intro 4 266.Sh BUGS 267Currently is IPv4-only. 268