1.\" $OpenBSD: tun.4,v 1.36 2007/05/31 19:19:52 jmc Exp $ 2.\" 3.\" Copyright (c) 2003 Marcus D. Watts All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, and the entire permission notice in its entirety, 10.\" including the disclaimer of warranties. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. The name of the author may not be used to endorse or promote 15.\" products derived from this software without specific prior 16.\" written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 19.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 20.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 21.\" MARCUS D. WATTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 22.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 23.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS 24.\" OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 25.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR 26.\" TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE 27.\" USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd $Mdocdate: May 31 2007 $ 30.Dt TUN 4 31.Os 32.Sh NAME 33.Nm tun 34.Nd network tunnel pseudo-device 35.Sh SYNOPSIS 36.Cd "pseudo-device tun" 37.Pp 38.Fd #include <sys/types.h> 39.Fd #include <net/if_tun.h> 40.Sh DESCRIPTION 41The 42.Nm 43driver provides a network interface pseudo-device. 44Packets sent to this interface can be read by a userland process 45and processed as desired. 46Packets written by the userland process are injected back into 47the kernel networking subsystem. 48.Pp 49A 50.Nm 51interface can be created at runtime using the 52.Ic ifconfig tun Ns Ar N Ic create 53command or by opening the character special device 54.Pa /dev/tunN . 55.Pp 56Both layer 3 and layer 2 tunneling is supported. 57Layer 3 tunneling is the default mode; to enable layer 2 tunneling mode the 58.Ar link0 59flag needs to be set with 60.Xr ifconfig 8 , 61or by setting up a 62.Xr hostname.if 5 63configuration file for 64.Xr netstart 8 . 65In layer 2 mode the 66.Nm 67interface is simulating an Ethernet network interface. 68.Pp 69Each device has the exclusive open property; it cannot be opened 70if it is already open and in use by another process. 71Each read returns at most one packet; if insufficient 72buffer space is provided, the packet is truncated. 73Each write supplies exactly one packet. 74Each packet read or written is prefixed with a tunnel header consisting of 75a 4-byte network byte order integer containing the address family in the case 76of layer 3 tunneling. 77In layer 2 mode the 4-byte tunnel header is replaced with an Ethernet header. 78On the last close of the device, all queued packets are discarded. 79If the device was created by opening 80.Pa /dev/tunN , 81it will be automatically destroyed. 82Devices created via 83.Xr ifconfig 8 84are only marked as not running and traffic will be dropped returning 85.Er EHOSTDOWN . 86.Pp 87Writes never block. 88If the protocol queue is full, the packet is dropped, a 89.Dq collision 90is counted, and 91.Er ENOBUFS 92is returned. 93.Pp 94In addition to the usual network interface 95ioctl commands described in 96.Xr netintro 4 , 97the following special commands defined in 98.Aq Pa net/if_tun.h 99are supported: 100.Pp 101.Bl -tag -width indent -compact 102.It Dv TUNGIFINFO Fa "struct tuninfo *" 103.It Dv TUNSIFINFO Fa "struct tuninfo *" 104Get or set the interface characteristics. 105.Bd -literal 106/* iface info */ 107struct tuninfo { 108 u_int mtu; 109 u_short type; 110 u_short flags; 111 u_int baudrate; 112}; 113.Ed 114.Pp 115.Va flags 116sets the interface flags, and 117can include one or more of 118.Dv IFF_UP , 119.Dv IFF_POINTOPOINT , 120.Dv IFF_MULTICAST , 121.Dv IFF_BROADCAST . 122Flags given will be set; flags omitted will be cleared; flags not in this list 123will not be changed even when given. 124Flags default to 125.Dv IFF_POINTOPOINT 126for layer 3 and to 127.Dv IFF_BROADCAST \&| IFF_MULTICAST 128for layer 2 mode. 129It is an error to set both 130.Dv IFF_POINTOPOINT 131and 132.Dv IFF_BROADCAST . 133.\" should say what type affects... 134.Va type 135defaults to 136.Dv IFT_TUNNEL 137for layer 3 and 138.Dv IFT_ETHER 139for layer 2 tunneling mode. 140This sets the interface media address header type. 141.Pp 142.It Dv TUNSIFMODE Fa int *flags 143Set just the interface flags. 144The same restrictions as for 145.Dv TUNSIFINFO 146apply. 147.Pp 148.It Dv FIONBIO Fa int *flag 149Set non-blocking I/O. 150.Pp 151.It Dv FIOASYNC Fa int *flag 152Cause signal 153.Dv SIGIO 154to be sent when a packet can be read. 155.Pp 156.It Dv TIOCSPGRP Fa int *pgrp 157.It Dv TIOCGPGRP Fa int *pgrp 158Get or set the process group to which signals might be sent 159via 160.Dv FIOASYNC . 161.Pp 162.It Dv FIONREAD Fa int *count 163Get the byte count of the next packet available to be read. 164.Pp 165.It Dv SIOCGIFADDR Fa struct ether_addr *addr 166.It Dv SIOCSIFADDR Fa struct ether_addr *addr 167Get or set the Ethernet address of the device in layer 2 mode. 168.El 169.Sh FILES 170.Bl -tag -width /dev/tun* -compact 171.It Pa /dev/tun* 172.El 173.Sh ERRORS 174If open fails, 175.Xr errno 2 176may be set to one of: 177.Bl -tag -width Er 178.It Bq Er EPERM 179Only the superuser may open the device. 180.It Bq Er ENXIO 181Not that many devices configured. 182.It Bq Er EBUSY 183Device was already open. 184.El 185.Pp 186If a 187.Xr write 2 188call fails, 189.Xr errno 2 190is set to one of: 191.Bl -tag -width Er 192.It Bq Er EMSGSIZE 193The packet supplied was too small or too large. 194The maximum sized packet allowed is currently 16384 bytes. 195.It Bq Er ENOBUFS 196There were no mbufs, or 197the queue for the outgoing protocol is full. 198.It Bq Er EAFNOSUPPORT 199The address family specified in the tunnel header was not 200recognized. 201.El 202.Pp 203Ioctl commands may fail with: 204.Bl -tag -width Er 205.It Bq Er EINVAL 206Attempt to set both 207.Dv IFF_POINTOPOINT 208and 209.Dv IFF_BROADCAST 210with 211.Dv TUNSIFMODE 212or using 213.Dv SIOCGIFADDR 214or 215.Dv SIOCSIFADDR 216in layer 3 mode. 217.It Bq Er ENOTTY 218Unrecognized ioctl command. 219.El 220.Pp 221A 222.Xr read 2 223call may fail because of: 224.Bl -tag -width Er 225.It Bq Er EHOSTDOWN 226The device is not ready. 227The device must have an 228.Xr inet 4 229interface address assigned to it, such as via 230.Dv SIOCSIFADDR . 231.It Bq Er EWOULDBLOCK 232Non-blocking I/O was selected and no packets were available. 233.El 234.Pp 235An attempt to send a packet out via the interface may fail with: 236.Bl -tag -width Er 237.It Bq Er EHOSTDOWN 238The device is not ready. 239The device must have an 240.Xr inet 4 241interface address assigned to it, such as via 242.Dv SIOCSIFADDR . 243.El 244.Sh SEE ALSO 245.Xr inet 4 , 246.Xr intro 4 , 247.Xr netintro 4 , 248.Xr hostname.if 5 , 249.Xr ifconfig 8 , 250.Xr netstart 8 251