NetBSD/share/man/man4/tap.4

.\" $NetBSD: tap.4,v 1.15 2020/09/27 19:36:54 roy Exp $
.\"
.\"  Copyright (c) 2004, 2005 The NetBSD Foundation.
.\"  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, this list of conditions and the following disclaimer.
.\"  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.
.\"
.\"  THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
.\"  ``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 THE FOUNDATION 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 September 27, 2020
.Dt TAP 4
.Os
.Sh NAME
.Nm tap
.Nd Ethernet tunnel software network interface
.Sh SYNOPSIS
.Cd pseudo-device tap
.Sh DESCRIPTION
The
.Nm
driver allows the creation and use of virtual Ethernet devices.
Those interfaces appear just as any real Ethernet NIC to the kernel,
but can also be accessed by userland through a character device node in order
to read frames being sent by the system or to inject frames.
.Pp
In that respect it is very similar to what
.Xr tun 4
provides, but the added Ethernet layer allows easy integration with machine
emulators or virtual Ethernet networks through the use of
.Xr bridge 4
with tunneling.
.Ss INTERFACE CREATION
Interfaces may be created in two different ways:
using the
.Xr ifconfig 8
.Cm create
command with a specified device number,
or its
.Xr ioctl 2
equivalent,
.Dv SIOCIFCREATE ,
or using the special cloning device
.Pa /dev/tap .
.Pp
The former works the same as any other cloning network interface:
the administrator can create and destroy interfaces at any time,
notably at boot time.
This is the easiest way of combining
.Nm
and
.Xr bridge 4 .
Later, userland will actually access the interfaces through the specific
device nodes
.Pa /dev/tapN .
.Pp
The latter is aimed at applications that need a virtual Ethernet device for
the duration of their execution.
A new interface is created at the opening of
.Pa /dev/tap ,
and is later destroyed when the last process using the file descriptor closes
it.
.Ss CHARACTER DEVICES
Whether the
.Nm
devices are accessed through the special cloning device
.Pa /dev/tap
or through the specific devices
.Pa /dev/tapN ,
the possible actions to control the matching interface are the same.
.Pp
When using
.Pa /dev/tap
though, as the interface is created on-the-fly, its name is not known
immediately by the application.
Therefore the
.Dv TAPGIFNAME
ioctl is provided.
It should be the first action an application using the special cloning device
will do.
It takes a pointer to a
.Ft struct ifreq
as an argument.
.Pp
Ethernet frames sent out by the kernel on a
.Nm
interface can be obtained by the controlling application with
.Xr read 2 .
It can also inject frames in the kernel with
.Xr write 2 .
There is absolutely no validation of the content of the injected frame,
it can be any data, of any length.
.Pp
One call of
.Xr write 2
will inject a single frame in the kernel, as one call of
.Xr read 2
will retrieve a single frame from the queue, to the extent of the provided
buffer.
If the buffer is not large enough, the frame will be truncated.
.Pp
.Nm
character devices support the
.Dv FIONREAD
ioctl which returns the size of the next available frame,
or 0 if there is no available frame in the queue.
.Pp
They also support non-blocking I/O through the
.Dv FIONBIO
ioctl.
In that mode,
.Er EWOULDBLOCK
is returned by
.Xr read 2
when no data is available.
.Pp
Asynchronous I/O is supported through the
.Dv FIOASYNC ,
.Dv FIOSETOWN ,
and
.Dv FIOGETOWN
ioctls.
The first will enable
.Dv SIGIO
generation, while the two other configure the process group that
will receive the signal when data is ready.
.Pp
Synchronisation may also be achieved through the use of
.Xr select 2 ,
.Xr poll 2 ,
or
.Xr kevent 2 .
.Ss ETHERNET ADDRESS
When a
.Nm
device is created, it is assigned an Ethernet address
of the form f2:0b:a4:xx:xx:xx.
This address can later be changed using
.Xr ifconfig 8
to add an active link layer address, or directly via the
.Dv SIOCALIFADDR
ioctl on a
.Dv PF_LINK
socket, as it is not available on
the ioctl handler of the character device interface.
.Ss LINK STATE
When an application has opened the
.Nm
character device the link is considered up, otherwise down.
As such, it is best to open the character device once connectivity has
been established so that Duplicate Address Detection, if applicable,
can be performed.
If connectivity is lost, the character device should be closed.
.Sh FILES
.Bl -tag -compact -width /dev/tap[0-9]*
.It Pa /dev/tap
cloning device
.It Pa /dev/tap[0-9]*
individual character device nodes
.El
.Sh SEE ALSO
.Xr bridge 4 ,
.Xr l2tp 4 ,
.Xr tun 4 ,
.Xr vether 4 ,
.Xr ifconfig 8
.Sh HISTORY
The
.Nm
driver first appeared in
.Nx 3.0 .
.Sh CAVEATS
Starting from
.Nx 10.0 ,
the
.Nm
driver can no longer be used as a
.Xr bridge 4
endpoint because it supports a link state based on if it has been opened or not.
Use the
.Xr vether 4
driver instead as it's been explicitly designed for this purpose.