diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile index 19306d560e8..41fb48b9da0 100644 --- a/share/man/man4/Makefile +++ b/share/man/man4/Makefile @@ -1,4 +1,4 @@ -# $OpenBSD: Makefile,v 1.853 2024/11/05 11:12:48 miod Exp $ +# $OpenBSD: Makefile,v 1.854 2024/11/13 12:58:29 dlg Exp $ MAN= aac.4 abcrtc.4 abl.4 ac97.4 acphy.4 acrtc.4 \ acpi.4 acpiac.4 acpials.4 acpiasus.4 acpibat.4 \ @@ -95,7 +95,7 @@ MAN= aac.4 abcrtc.4 abl.4 ac97.4 acphy.4 acrtc.4 \ tascodec.4 tcic.4 tcp.4 tcpci.4 termios.4 tht.4 ti.4 tipd.4 \ tipmic.4 titmp.4 tl.4 \ tlphy.4 thmc.4 tpm.4 tpmr.4 tqphy.4 trm.4 trunk.4 tsl.4 tty.4 \ - tun.4 tap.4 twe.4 \ + tun.4 twe.4 \ txp.4 txphy.4 uaudio.4 uaq.4 uark.4 uath.4 ubcmtp.4 uberry.4 ubsa.4 \ ucc.4 ucom.4 uchcom.4 ucrcom.4 ucycom.4 ukspan.4 uslhcom.4 \ udav.4 udcf.4 udl.4 udp.4 udsbr.4 ufshci.4 \ diff --git a/share/man/man4/tap.4 b/share/man/man4/tap.4 deleted file mode 100644 index 92d3496ebe0..00000000000 --- a/share/man/man4/tap.4 +++ /dev/null @@ -1,222 +0,0 @@ -.\" $OpenBSD: tap.4,v 1.5 2021/03/23 16:26:53 claudio Exp $ -.\" -.\" Copyright (c) 2003 Marcus D. Watts All rights reserved. -.\" -.\" Redistribution and use in source and binary forms, with or without -.\" modification, are permitted provided that the following conditions -.\" are met: -.\" 1. Redistributions of source code must retain the above copyright -.\" notice, and the entire permission notice in its entirety, -.\" including the disclaimer of warranties. -.\" 2. Redistributions in binary form must reproduce the above copyright -.\" notice, this list of conditions and the following disclaimer in the -.\" documentation and/or other materials provided with the distribution. -.\" 3. The name of the author may not be used to endorse or promote -.\" products derived from this software without specific prior -.\" written permission. -.\" -.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, -.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY -.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL -.\" MARCUS D. WATTS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, -.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, -.\" BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS -.\" OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND -.\" ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR -.\" TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE -.\" USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. -.\" -.Dd $Mdocdate: March 23 2021 $ -.Dt TAP 4 -.Os -.Sh NAME -.Nm tap -.Nd Ethernet tunnel pseudo-device -.Sh SYNOPSIS -.Cd "pseudo-device tun" -.Pp -.In sys/types.h -.In net/if_tun.h -.Sh DESCRIPTION -The -.Nm -driver provides an Ethernet interface pseudo-device. -Packets sent to this interface can be read by a userland process -and processed as desired. -Packets written by the userland process are injected back into -the kernel networking subsystem. -.Pp -A -.Nm -interface can be created at runtime using the -.Ic ifconfig tap Ns Ar N Ic create -command or by opening the character special device -.Pa /dev/tapN . -.Pp -Each device has an exclusive open property: it cannot be opened -if it is already open and in use by another process. -Each read returns at most one packet; if insufficient -buffer space is provided, the packet is truncated. -Each write supplies exactly one packet. -Each packet read or written is an Ethernet packet. -The Ethernet CRC at the end of the frame is not required. -On the last close of the device, all queued packets are discarded. -If the device was created by opening -.Pa /dev/tapN , -it will be automatically destroyed. -Devices created via -.Xr ifconfig 8 -are only marked as not running and traffic will be dropped returning -.Er EHOSTDOWN . -.Pp -Writes never block. -If the protocol queue is full, the packet is dropped, a -.Dq collision -is counted, and -.Er ENOBUFS -is returned. -.Pp -In addition to the usual network interface -ioctl commands described in -.Xr netintro 4 , -the following special commands defined in -.In net/if_tun.h -are supported: -.Pp -.Bl -tag -width indent -compact -.It Dv TUNGIFINFO Fa "struct tuninfo *" -.It Dv TUNSIFINFO Fa "struct tuninfo *" -Get or set the interface characteristics. -.Bd -literal -/* iface info */ -struct tuninfo { - u_int mtu; - u_short type; - u_short flags; - u_int baudrate; -}; -.Ed -.Pp -.Va flags -sets the interface flags, and -can include one or more of -.Dv IFF_UP , -.Dv IFF_POINTOPOINT , -.Dv IFF_MULTICAST , -.Dv IFF_BROADCAST . -Flags given will be set; flags omitted will be cleared; flags not in this list -will not be changed even when given. -Flags default to -.Dv IFF_BROADCAST | IFF_MULTICAST . -It is an error to set both -.Dv IFF_POINTOPOINT -and -.Dv IFF_BROADCAST . -.\" should say what type affects... -.Va type -defaults to -.Dv IFT_ETHER . -This sets the interface media address header type. -.Pp -.It Dv TUNSIFMODE Fa int * -Set just the interface flags. -The same restrictions as for -.Dv TUNSIFINFO -apply. -.Pp -.It Dv SIOCGIFADDR Fa uint8_t Ns [ETHER_ADDR_LEN] -.It Dv SIOCSIFADDR Fa uint8_t Ns [ETHER_ADDR_LEN] -Get or set the link layer address (MAC address) of the interface. -.El -.Pp -The generic ioctls -.Dv FIONREAD , -.Dv FIONBIO , -.Dv FIOASYNC , -.Dv FIOSETOWN , -.Dv FIOGETOWN -are supported by -.Nm . -.Sh FILES -.Bl -tag -width /dev/tap* -compact -.It Pa /dev/tap* -.El -.Sh ERRORS -If open fails, -.Xr errno 2 -may be set to one of: -.Bl -tag -width Er -.It Bq Er ENXIO -Not that many devices configured. -.It Bq Er EBUSY -Device was already open. -.El -.Pp -If a -.Xr write 2 -call fails, -.Xr errno 2 -is set to one of: -.Bl -tag -width Er -.It Bq Er EMSGSIZE -The packet supplied was too small or too large. -The maximum sized packet allowed is currently 16384 bytes. -.It Bq Er ENOBUFS -There were no mbufs, or -the queue for the outgoing protocol is full. -.It Bq Er EAFNOSUPPORT -The address family specified in the tunnel header was not -recognized. -.El -.Pp -Ioctl commands may fail with: -.Bl -tag -width Er -.It Bq Er EINVAL -Attempt to set both -.Dv IFF_POINTOPOINT -and -.Dv IFF_BROADCAST -with -.Dv TUNSIFMODE . -.It Bq Er ENOTTY -Unrecognized ioctl command. -.El -.Pp -A -.Xr read 2 -call may fail because of: -.Bl -tag -width Er -.It Bq Er EHOSTDOWN -The device is not ready. -The device must have an -.Xr inet 4 -interface address assigned to it, such as via -.Dv SIOCSIFADDR . -.It Bq Er EWOULDBLOCK -Non-blocking I/O was selected and no packets were available. -.El -.Pp -An attempt to send a packet out via the interface may fail with: -.Bl -tag -width Er -.It Bq Er EHOSTDOWN -The device is not ready. -The device must have an -.Xr inet 4 -interface address assigned to it, such as via -.Dv SIOCSIFADDR . -.El -.Sh SEE ALSO -.Xr ioctl 2 , -.Xr inet 4 , -.Xr intro 4 , -.Xr netintro 4 , -.Xr hostname.if 5 , -.Xr ifconfig 8 , -.Xr netstart 8 -.Sh HISTORY -The -.Nm -driver first appeared in -.Ox 5.9 . -.Sh AUTHORS -.An Claudio Jeker Aq Mt claudio@openbsd.org diff --git a/share/man/man4/tun.4 b/share/man/man4/tun.4 index 9bae0ff4c89..89f1a9089c5 100644 --- a/share/man/man4/tun.4 +++ b/share/man/man4/tun.4 @@ -1,4 +1,4 @@ -.\" $OpenBSD: tun.4,v 1.45 2020/01/09 09:25:16 claudio Exp $ +.\" $OpenBSD: tun.4,v 1.46 2024/11/13 12:58:29 dlg Exp $ .\" .\" Copyright (c) 2003 Marcus D. Watts All rights reserved. .\" @@ -26,11 +26,12 @@ .\" TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE .\" USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: January 9 2020 $ +.Dd $Mdocdate: November 13 2024 $ .Dt TUN 4 .Os .Sh NAME -.Nm tun +.Nm tun , +.Nm tap .Nd network tunnel pseudo-device .Sh SYNOPSIS .Cd "pseudo-device tun" @@ -39,39 +40,45 @@ .In net/if_tun.h .Sh DESCRIPTION The -.Nm -driver provides a network interface pseudo-device. -Packets sent to this interface can be read by a userland process -and processed as desired. -Packets written by the userland process are injected back into -the kernel networking subsystem. +.Nm tun +pseudo-device driver provides character special devices for +communicating with the kernel network stack via the +.Nm tun +and +.Nm tap +network interfaces. +Packets sent to these interfaces can be read from the device special +file by a userland process and processed as desired. +Packets written to the device special file by the userland process +are injected back into the kernel networking subsystem. .Pp -A -.Nm -interface can be created at runtime using the -.Ic ifconfig tun Ns Ar N Ic create -command or by opening the character special device -.Pa /dev/tunN . -By default -.Nm -operates as a point-to-point interface. +.Nm tun +and +.Nm tap +interfaces can be created at runtime using the +.Ic ifconfig iface Ns Ar N Ic create +command, or by opening the character special devices +.Pa /dev/tunN +or +.Pa /dev/tapN +respectively. +.Pp +The minor number of the device special files are associated with +the unit number of the network interfaces. .Pp Each device has an exclusive open property: it cannot be opened if it is already open and in use by another process. +On the last close of the device all queued packets are discarded. +If the device was created by opening a device special file +it will be automatically destroyed. +The last close of a device special file associated with an interface +created via +.Xr ifconfig 8 +will be marked as not running and traffic sent out the will be dropped. +.Pp Each read returns at most one packet; if insufficient buffer space is provided, the packet is truncated. Each write supplies exactly one packet. -Each packet read or written is prefixed with a tunnel header consisting of -a 4-byte network byte order integer containing the address family. -On the last close of the device, all queued packets are discarded. -If the device was created by opening -.Pa /dev/tunN , -it will be automatically destroyed. -Devices created via -.Xr ifconfig 8 -are only marked as not running and traffic will be dropped returning -.Er EHOSTDOWN . -.Pp Writes never block. If the protocol queue is full, the packet is dropped, a .Dq collision @@ -79,9 +86,9 @@ is counted, and .Er ENOBUFS is returned. .Pp -In addition to the usual network interface ioctl commands described in -.Xr netintro 4 , -the following special commands defined in +The following +.Xr ioctl 2 +special commands defined in .In net/if_tun.h are supported: .Pp @@ -100,31 +107,14 @@ struct tuninfo { .Ed .Pp .Va flags -sets the interface flags, and -can include one or more of -.Dv IFF_UP , -.Dv IFF_POINTOPOINT , -.Dv IFF_MULTICAST , -.Dv IFF_BROADCAST . -Flags given will be set; flags omitted will be cleared; flags not in this list -will not be changed even when given. -Flags default to -.Dv IFF_POINTOPOINT . -It is an error to set both -.Dv IFF_POINTOPOINT and -.Dv IFF_BROADCAST . -.\" should say what type affects... .Va type -defaults to -.Dv IFT_TUNNEL . -This sets the interface media address header type. +are set by the kernel when an interface is created, +and must be set to the same values that the kernel provided. .Pp .It Dv TUNSIFMODE Fa int * -Set just the interface flags. -The same restrictions as for -.Dv TUNSIFINFO -apply. +is provided for backwards compatibiliy. +The flags set must match what the kernel initialised them to. .El .Pp The generic ioctls @@ -133,11 +123,41 @@ The generic ioctls .Dv FIOASYNC , .Dv FIOSETOWN , .Dv FIOGETOWN -are supported by -.Nm . +are also supported. +.Ss Point-to-Point Layer 3 tunnel interface (tun) +Each packet read from or written to a +.Nm tun +interface is prefixed with a tunnel header consisting of +a 4-byte network byte order integer containing the address family of +the packet. +.Nm tun +supports +.Dv AF_INET , +.Dv AF_INET6 , +and +.Dv AF_MPLS +packets. +.Ss Ethernet tunnel interface (tap) +Each packet read from or written to a +.Nm tap +interface is an Ethernet packet. +The Ethernet CRC at the end of the frame is not required. +.Pp +The device special files for +.Nm tap +interfaces support the following additional +.Xr ioctl 2 +commands: +.Pp +.Bl -tag -width indent -compact +.It Dv SIOCGIFADDR Fa uint8_t Ns [ETHER_ADDR_LEN] +.It Dv SIOCSIFADDR Fa uint8_t Ns [ETHER_ADDR_LEN] +Get or set the link layer address (MAC address) of the interface. +.El .Sh FILES .Bl -tag -width /dev/tun* -compact .It Pa /dev/tun* +.It Pa /dev/tap* .El .Sh ERRORS If open fails, @@ -146,6 +166,7 @@ may be set to one of: .Bl -tag -width Er .It Bq Er ENXIO Not that many devices configured. +.\" The associated interface existed, but is being destroyed. .It Bq Er EBUSY Device was already open. .El @@ -159,27 +180,17 @@ is set to one of: .It Bq Er EMSGSIZE The packet supplied was too small or too large. The maximum sized packet allowed is currently 16384 bytes. -.It Bq Er ENOBUFS -There were no mbufs, or -the queue for the outgoing protocol is full. -.It Bq Er EAFNOSUPPORT -The address family specified in the tunnel header was not -recognized. +.It Bq Er ENOMEM +There were no mbufs. +.\" .It Bq Er ENOBUFS +.\" The queue for the outgoing protocol is full. .El .Pp -Ioctl commands may fail with: +.Xr ioctl 2 +commands may fail with: .Bl -tag -width Er .It Bq Er EINVAL -Attempt to set both -.Dv IFF_POINTOPOINT -and -.Dv IFF_BROADCAST -with -.Dv TUNSIFMODE -or using -.Dv SIOCGIFADDR -or -.Dv SIOCSIFADDR . +Invalid parameters were specified. .It Bq Er ENOTTY Unrecognized ioctl command. .El @@ -188,25 +199,11 @@ A .Xr read 2 call may fail because of: .Bl -tag -width Er -.It Bq Er EHOSTDOWN -The device is not ready. -The device must have an -.Xr inet 4 -interface address assigned to it, such as via -.Dv SIOCSIFADDR . +.It Bq Er EIO +The associated interface has been destroyed. .It Bq Er EWOULDBLOCK Non-blocking I/O was selected and no packets were available. .El -.Pp -An attempt to send a packet out via the interface may fail with: -.Bl -tag -width Er -.It Bq Er EHOSTDOWN -The device is not ready. -The device must have an -.Xr inet 4 -interface address assigned to it, such as via -.Dv SIOCSIFADDR . -.El .Sh SEE ALSO .Xr ioctl 2 , .Xr inet 4 , @@ -215,3 +212,22 @@ interface address assigned to it, such as via .Xr hostname.if 5 , .Xr ifconfig 8 , .Xr netstart 8 +.Sh HISTORY +.Nm tun +interfaces originally supported both Layer 3 and Ethernet packets +by reconfiguring the type of interface with +.Dv TUNSIFINFO . +Ethernet packet support was split into the separate +.Nm tap +interface in +.Ox 5.9 . +.Sh AUTHORS +.Nm tun +was written by +.An Julian Onions Aq Mt Julian.Onions@nexor.co.uk +at Nottingham University. +.Pp +The +.Nm tap +interface functionality was written by +.An Claudio Jeker Aq Mt claudio@openbsd.org .