1.\" $NetBSD: tun.4,v 1.21 2006/04/08 23:12:13 wiz 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.\" 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 April 8, 2006 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 off 216.Dq multi-af 217mode and turns on 218.Dq link-layer 219mode, causing packets read from the tunnel device to be prepended with 220network destination address. 221.It Dv TUNGIFHEAD 222The argument should be a pointer to an 223.Va int ; 224the ioctl sets the value to one if the device is in 225.Dq multi-af 226mode, and zero otherwise. 227.It Dv TUNSIFHEAD 228The argument should be a pointer to an 229.Va int ; 230a non-zero value turns off 231.Dq link-layer 232mode, and enables 233.Dq multi-af 234mode, where every packet is preceded with a four byte address family. 235.It Dv FIONBIO 236Turn non-blocking I/O for reads off or on, according as the argument 237.Va int Ns 's 238value is or isn't zero 239.Pq Writes are always nonblocking . 240.It Dv FIOASYNC 241Turn asynchronous I/O for reads 242.Po 243i.e., generation of 244.Dv SIGIO 245when data is available to be read 246.Pc off or on, according as the argument 247.Va int Ns 's 248value is or isn't zero. 249.It Dv FIONREAD 250If any packets are queued to be read, store the size of the first one 251into the argument 252.Va int ; 253otherwise, store zero. 254.It Dv TIOCSPGRP 255Set the process group to receive 256.Dv SIGIO 257signals, when asynchronous I/O is enabled, to the argument 258.Va int 259value. 260.It Dv TIOCGPGRP 261Retrieve the process group value for 262.Dv SIGIO 263signals into the argument 264.Va int 265value. 266.El 267.Pp 268The control device also supports 269.Xr select 2 270for read; selecting for write is pointless, and always succeeds, since 271writes are always non-blocking. 272.Pp 273On the last close of the data device, by default, the interface is 274brought down 275.Po as if with 276.Dq ifconfig tun Ns Sy n No down 277.Pc . 278All queued packets are thrown away. 279If the interface is up when the data device is not open 280output packets are always thrown away rather than letting 281them pile up. 282.Sh SEE ALSO 283.Xr inet 4 , 284.Xr intro 4 285.Sh HISTORY 286.An -split 287IPv6 support comes mostly from 288.Fx 289and was added in 290.Nx 4.0 291by 292.An Rui Paulo 293.Aq rpaulo@NetBSD.org . 294