Download raw body.
merge tap(4) manpage into tun(4)
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?
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
+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)
+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 .
merge tap(4) manpage into tun(4)