From: Claudio Jeker <cjeker@diehard.n-r-g.com>
Subject: Re: merge tap(4) manpage into tun(4)
To: David Gwynne <david@gwynne.id.au>
Cc: tech@openbsd.org
Date: Wed, 13 Nov 2024 11:48:22 +0100

On Wed, Nov 13, 2024 at 08:36:55PM +1000, David Gwynne wrote:
> it's one driver that provides two interfaces.
> 
> there's upcoming changes to if_tun.c that i would like to document, but
> only once.
> 
> ok?

Minor bits below. Apart from that OK claudio@
 
> Index: Makefile
> ===================================================================
> RCS file: /cvs/src/share/man/man4/Makefile,v
> diff -u -p -r1.853 Makefile
> --- Makefile	5 Nov 2024 11:12:48 -0000	1.853
> +++ Makefile	13 Nov 2024 09:42:20 -0000
> @@ -95,7 +95,7 @@ MAN=	aac.4 abcrtc.4 abl.4 ac97.4 acphy.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 \
> Index: tap.4
> ===================================================================
> RCS file: tap.4
> diff -N tap.4
> --- tap.4	23 Mar 2021 16:26:53 -0000	1.5
> +++ /dev/null	1 Jan 1970 00:00:00 -0000
> @@ -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
> Index: tun.4
> ===================================================================
> RCS file: /cvs/src/share/man/man4/tun.4,v
> diff -u -p -r1.45 tun.4
> --- tun.4	9 Jan 2020 09:25:16 -0000	1.45
> +++ tun.4	13 Nov 2024 09:42:20 -0000
> @@ -30,7 +30,8 @@
>  .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

I dislike the iface here but not sure how to make it better.
Should that actually be
.Ic ifconfig Ar 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 (tap)
                                                ^^^ that must be 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 a
>  .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 seperate
> +.Nm tap
> +interfaces 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 .
> 

-- 
:wq Claudio