merge tap(4) into tun(4). it's the one driver providing both interfaces.

ok and tweaks from claudio@ and jmc@

3 files changed, 106 insertions, 312 deletions

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.
-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 ,
+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.
-Devices created via
+The last close of a device special file associated with an interface
+created via
 .Xr ifconfig 8
-are only marked as not running and traffic will be dropped returning
-.Er EHOSTDOWN .
+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.
 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 .