1.\" $OpenBSD: tun.4,v 1.40 2014/01/21 03:15:46 schwarze 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: January 21 2014 $ 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. 58To enable layer 2 tunneling mode, 59where the 60.Nm 61interface simulates an Ethernet network interface, 62the 63.Ar link0 64flag needs to be set with 65.Xr ifconfig 8 66or by setting up a 67.Xr hostname.if 5 68configuration file for 69.Xr netstart 8 . 70Note that setting or unsetting the 71.Ar link0 72flag causes 73.Nm 74to lose any configuration settings, 75and that it is not advisable to use the flag with any other parameters. 76.Pp 77Each device has the exclusive open property; it cannot be opened 78if it is already open and in use by another process. 79Each read returns at most one packet; if insufficient 80buffer space is provided, the packet is truncated. 81Each write supplies exactly one packet. 82Each packet read or written is prefixed with a tunnel header consisting of 83a 4-byte network byte order integer containing the address family in the case 84of layer 3 tunneling. 85In layer 2 mode the 4-byte tunnel header is replaced with an Ethernet header. 86On the last close of the device, all queued packets are discarded. 87If the device was created by opening 88.Pa /dev/tunN , 89it will be automatically destroyed. 90Devices created via 91.Xr ifconfig 8 92are only marked as not running and traffic will be dropped returning 93.Er EHOSTDOWN . 94.Pp 95Writes never block. 96If the protocol queue is full, the packet is dropped, a 97.Dq collision 98is counted, and 99.Er ENOBUFS 100is returned. 101.Pp 102In addition to the usual network interface 103ioctl commands described in 104.Xr netintro 4 , 105the following special commands defined in 106.In net/if_tun.h 107are supported: 108.Pp 109.Bl -tag -width indent -compact 110.It Dv TUNGIFINFO Fa "struct tuninfo *" 111.It Dv TUNSIFINFO Fa "struct tuninfo *" 112Get or set the interface characteristics. 113.Bd -literal 114/* iface info */ 115struct tuninfo { 116 u_int mtu; 117 u_short type; 118 u_short flags; 119 u_int baudrate; 120}; 121.Ed 122.Pp 123.Va flags 124sets the interface flags, and 125can include one or more of 126.Dv IFF_UP , 127.Dv IFF_POINTOPOINT , 128.Dv IFF_MULTICAST , 129.Dv IFF_BROADCAST . 130Flags given will be set; flags omitted will be cleared; flags not in this list 131will not be changed even when given. 132Flags default to 133.Dv IFF_POINTOPOINT 134for layer 3 and to 135.Dv IFF_BROADCAST | IFF_MULTICAST 136for layer 2 mode. 137It is an error to set both 138.Dv IFF_POINTOPOINT 139and 140.Dv IFF_BROADCAST . 141.\" should say what type affects... 142.Va type 143defaults to 144.Dv IFT_TUNNEL 145for layer 3 and 146.Dv IFT_ETHER 147for layer 2 tunneling mode. 148This sets the interface media address header type. 149.Pp 150.It Dv TUNSIFMODE Fa int *flags 151Set just the interface flags. 152The same restrictions as for 153.Dv TUNSIFINFO 154apply. 155.Pp 156.It Dv FIONBIO Fa int *flag 157Set non-blocking I/O. 158.Pp 159.It Dv FIOASYNC Fa int *flag 160Cause signal 161.Dv SIGIO 162to be sent when a packet can be read. 163.Pp 164.It Dv TIOCSPGRP Fa int *pgrp 165.It Dv TIOCGPGRP Fa int *pgrp 166Get or set the process group to which signals might be sent 167via 168.Dv FIOASYNC . 169.Pp 170.It Dv FIONREAD Fa int *count 171Get the byte count of the next packet available to be read. 172.Pp 173.It Dv SIOCGIFADDR Fa struct ether_addr *addr 174.It Dv SIOCSIFADDR Fa struct ether_addr *addr 175Get or set the Ethernet address of the device in layer 2 mode. 176.El 177.Sh FILES 178.Bl -tag -width /dev/tun* -compact 179.It Pa /dev/tun* 180.El 181.Sh ERRORS 182If open fails, 183.Xr errno 2 184may be set to one of: 185.Bl -tag -width Er 186.It Bq Er ENXIO 187Not that many devices configured. 188.It Bq Er EBUSY 189Device was already open. 190.El 191.Pp 192If a 193.Xr write 2 194call fails, 195.Xr errno 2 196is set to one of: 197.Bl -tag -width Er 198.It Bq Er EMSGSIZE 199The packet supplied was too small or too large. 200The maximum sized packet allowed is currently 16384 bytes. 201.It Bq Er ENOBUFS 202There were no mbufs, or 203the queue for the outgoing protocol is full. 204.It Bq Er EAFNOSUPPORT 205The address family specified in the tunnel header was not 206recognized. 207.El 208.Pp 209Ioctl commands may fail with: 210.Bl -tag -width Er 211.It Bq Er EINVAL 212Attempt to set both 213.Dv IFF_POINTOPOINT 214and 215.Dv IFF_BROADCAST 216with 217.Dv TUNSIFMODE 218or using 219.Dv SIOCGIFADDR 220or 221.Dv SIOCSIFADDR 222in layer 3 mode. 223.It Bq Er ENOTTY 224Unrecognized ioctl command. 225.El 226.Pp 227A 228.Xr read 2 229call may fail because of: 230.Bl -tag -width Er 231.It Bq Er EHOSTDOWN 232The device is not ready. 233The device must have an 234.Xr inet 4 235interface address assigned to it, such as via 236.Dv SIOCSIFADDR . 237.It Bq Er EWOULDBLOCK 238Non-blocking I/O was selected and no packets were available. 239.El 240.Pp 241An attempt to send a packet out via the interface may fail with: 242.Bl -tag -width Er 243.It Bq Er EHOSTDOWN 244The device is not ready. 245The device must have an 246.Xr inet 4 247interface address assigned to it, such as via 248.Dv SIOCSIFADDR . 249.El 250.Sh SEE ALSO 251.Xr inet 4 , 252.Xr intro 4 , 253.Xr netintro 4 , 254.Xr hostname.if 5 , 255.Xr ifconfig 8 , 256.Xr netstart 8 257