1.\" $OpenBSD: tun.4,v 1.52 2024/11/18 22:33:58 dlg 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: November 18 2024 $ 30.Dt TUN 4 31.Os 32.Sh NAME 33.Nm tun , 34.Nm tap 35.Nd network tunnel pseudo-device 36.Sh SYNOPSIS 37.Cd "pseudo-device tun" 38.Pp 39.In sys/types.h 40.In net/if_tun.h 41.Sh DESCRIPTION 42The 43.Nm tun 44pseudo-device driver provides character special devices for 45communicating with the kernel network stack via the 46.Nm tun 47and 48.Nm tap 49network interfaces. 50Packets sent to these interfaces can be read from the device special 51file by a userland process and processed as desired. 52Packets written to the device special file by the userland process 53are injected back into the kernel networking subsystem. 54.Pp 55.Nm tun 56and 57.Nm tap 58interfaces can be created at runtime using the 59.Ic ifconfig iface Ns Ar N Ic create 60command, or by opening the character special devices 61.Pa /dev/tunN 62or 63.Pa /dev/tapN 64respectively. 65.Pp 66The minor number of the device special files are associated with 67the unit number of the network interfaces. 68.Pp 69Each device has an exclusive open property: it cannot be opened 70if it is already open and in use by another process. 71On the last close of the device all queued packets are discarded. 72If the device was created by opening a device special file 73it will be automatically destroyed. 74The last close of a device special file associated with an interface 75created via 76.Xr ifconfig 8 77will be marked as not running and traffic sent out the will be dropped. 78.Pp 79Each read returns at most one packet; if insufficient 80buffer space is provided, the packet is truncated. 81Each write supplies exactly one packet. 82Writes never block. 83If the protocol queue is full, the packet is dropped, a 84.Dq collision 85is counted, and 86.Er ENOBUFS 87is returned. 88.Pp 89The following 90.Xr ioctl 2 91special commands defined in 92.In net/if_tun.h 93are supported: 94.Pp 95.Bl -tag -width indent -compact 96.It Dv TUNGIFINFO Fa "struct tuninfo *" 97.It Dv TUNSIFINFO Fa "struct tuninfo *" 98Get or set the interface characteristics. 99.Bd -literal 100/* iface info */ 101struct tuninfo { 102 u_int mtu; 103 u_short type; 104 u_short flags; 105 u_int baudrate; 106}; 107.Ed 108.Pp 109.Va flags 110and 111.Va type 112are set by the kernel when an interface is created, 113and must be set to the same values that the kernel provided. 114.Pp 115.It Dv TUNSIFMODE Fa int * 116Provided for backwards compatibility. 117The flags set must match what the kernel initialised them to. 118.Pp 119.It Dv TUNSCAP Fa struct tun_capabilities * 120Enable the prepending of network packets with a 121.Vt struct tun_hdr 122offload header, 123and set which interface offload capabilities userland can 124handle on behalf of the kernel. 125.Bd -literal 126struct tun_capabilities { 127 uint32_t tun_if_capabilities; 128}; 129.Ed 130.Pp 131The 132.Fa tun_if_capabilities 133field is set with IFCAP values from 134.In net/if.h . 135It is acceptable to enable the offload header without enabling any 136interface offload capabilities. 137.Pp 138The prepending of network packets with a 139.Vt struct tun_hdr 140offload header is disabled, 141and the interface offload capabilities are reset when the device 142special file is closed. 143.Pp 144.It Dv TUNGCAP Fa struct tun_capabilities * 145Get which interface offload capabilities are currently enabled. 146If the interface has not been configured with 147.Dv TUNSCAP 148this command will fail with 149.Er ENODEV . 150.Pp 151.It Dv TUNDCAP 152Disable the prepending of network packets with the 153.Vt struct tun_hdr 154offload header, 155and clear interface offload capabilities. 156.El 157.Pp 158The generic ioctls 159.Dv FIONREAD , 160.Dv FIONBIO , 161.Dv FIOASYNC , 162.Dv FIOSETOWN , 163.Dv FIOGETOWN 164are also supported. 165.Ss Point-to-Point Layer 3 tunnel interface (tun) 166Each packet read from or written to a 167.Nm tun 168interface is prefixed with a tunnel header consisting of 169a 4-byte network byte order integer containing the address family of 170the packet. 171.Nm tun 172supports 173.Dv AF_INET , 174.Dv AF_INET6 , 175and 176.Dv AF_MPLS 177packets. 178.Ss Ethernet tunnel interface (tap) 179Each packet read from or written to a 180.Nm tap 181interface is an Ethernet packet. 182The Ethernet CRC at the end of the frame is not required. 183.Pp 184The device special files for 185.Nm tap 186interfaces support the following additional 187.Xr ioctl 2 188commands: 189.Pp 190.Bl -tag -width indent -compact 191.It Dv SIOCGIFADDR Fa uint8_t Ns [ETHER_ADDR_LEN] 192.It Dv SIOCSIFADDR Fa uint8_t Ns [ETHER_ADDR_LEN] 193Get or set the link layer address (MAC address) of the interface. 194.El 195.Ss Network offload support 196When network offload support has been enabled with the 197.Dv TUNSCAP 198.Xr ioctl 2 199command, 200.Va struct tun_hdr 201is prepended to packets read from and written to the device special 202file. 203.Pp 204The kernel will populate the offload header for reads from the 205device special file depending on which interface offload capabilities 206are enabled. 207A program may use any offload feature when writing to the device 208special file regardless of which interface offload capabilities are 209enabled. 210The offload header can be read from one device special file and 211written directly to another without interpretation or modification. 212.Bd -literal 213struct tun_hdr { 214 uint16_t th_flags; 215 uint16_t th_pad; 216 uint16_t th_vtag; 217 uint16_t th_mss; 218}; 219.Ed 220.Pp 221The fields in the 222.Va struct tun_hdr 223are in host native byte order. 224.Pp 225The following flags can be set in 226.Fa th_flags 227to specify which offloads are requested for the current packet: 228.Pp 229.Bl -tag -width "TUN_H_ICMP_CSUM" -compact 230.It Dv TUN_H_VTAG 231.Fa th_vtag 232is set. 233.It Dv TUN_H_TCP_MSS 234TCP segmentation offload is requested for the current packet. 235The maximum segment size is specified in 236.Fa th_mss . 237.It Dv TUN_H_IPV4_CSUM 238IPv4 header checksum calculation requested. 239.It Dv TUN_H_TCP_CSUM 240TCP checksum calculation requested. 241.It Dv TUN_H_UDP_CSUM 242UDP checksum calculation requested. 243.It Dv TUN_H_ICMP_CSUM 244ICMP checksum calculation requested. 245.El 246.Pp 247Only one of 248.Dv TUN_H_TCP_CSUM , 249.Dv TUN_H_UDP_CSUM , 250and 251.Dv TUN_H_ICMP_CSUM 252can be specified at a time. 253.Dv TUN_H_VTAG 254can only be used with 255.Nm tap 256interfaces. 257.Pp 258.Fa th_pad 259should be set to 0 when writing to the device special file, and 260ignored when reading from the device special file. 261.Sh FILES 262.Bl -tag -width /dev/tun* -compact 263.It Pa /dev/tun* 264.It Pa /dev/tap* 265.El 266.Sh ERRORS 267If open fails, 268.Xr errno 2 269may be set to one of: 270.Bl -tag -width Er 271.It Bq Er ENXIO 272Not that many devices configured. 273.\" The associated interface existed, but is being destroyed. 274.It Bq Er EBUSY 275Device was already open. 276.El 277.Pp 278If a 279.Xr write 2 280call fails, 281.Xr errno 2 282is set to one of: 283.Bl -tag -width Er 284.It Bq Er EMSGSIZE 285The packet supplied was too small or too large. 286The maximum sized packet allowed is currently 16384 bytes. 287.It Bq Er ENOMEM 288There were no mbufs. 289.\" .It Bq Er ENOBUFS 290.\" The queue for the outgoing protocol is full. 291.El 292.Pp 293.Xr ioctl 2 294commands may fail with: 295.Bl -tag -width Er 296.It Bq Er EINVAL 297Invalid parameters were specified. 298.It Bq Er ENOTTY 299Unrecognized ioctl command. 300.El 301.Pp 302A 303.Xr read 2 304call may fail because of: 305.Bl -tag -width Er 306.It Bq Er EIO 307The associated interface has been destroyed. 308.It Bq Er EWOULDBLOCK 309Non-blocking I/O was selected and no packets were available. 310.El 311.Sh SEE ALSO 312.Xr ioctl 2 , 313.Xr inet 4 , 314.Xr intro 4 , 315.Xr netintro 4 , 316.Xr hostname.if 5 , 317.Xr ifconfig 8 , 318.Xr netstart 8 319.Sh HISTORY 320.Nm tun 321interfaces originally supported both Layer 3 and Ethernet packets 322by reconfiguring the type of interface with 323.Dv TUNSIFINFO . 324Ethernet packet support was split into the separate 325.Nm tap 326interface in 327.Ox 5.9 . 328.Sh AUTHORS 329.Nm tun 330was written by 331.An Julian Onions Aq Mt Julian.Onions@nexor.co.uk 332at Nottingham University. 333.Pp 334The 335.Nm tap 336interface functionality was written by 337.An Claudio Jeker Aq Mt claudio@openbsd.org . 338