mischief/openbsd-src
1
0
Fork 0
mirror of https://github.com/openbsd/src.git synced 2024-12-22 07:27:59 -08:00
Code

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

Browse Source 
ok and tweaks from claudio@ and jmc@
This commit is contained in:
dlg 2024-11-13 12:58:29 +00:00
parent 30a085025d
commit 5dfc6dfff9
3 changed files with 106 additions and 312 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
share/man/man4/Makefile
View File

@ -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 \

222
share/man/man4/tap.4
View File

@ -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

192
share/man/man4/tun.4
View File

@ -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 .