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