NetBSD/share/man/man4/tap.4

.\" $NetBSD: tap.4,v 1.5 2006/01/09 20:38:31 cube Exp $
.\"
.\"  Copyright (c) 2004, 2005 The NetBSD Foundation.
.\"  All rights reserved.
.\"
.\"  This code is derived from software contributed to the NetBSD Foundation
.\"   by Quentin Garnier.
.\"
.\"  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.
.\"  3. All advertising materials mentioning features or use of this software
.\"     must display the following acknowledgement:
.\"         This product includes software developed by the NetBSD
.\"         Foundation, Inc. and its contributors.
.\"  4. Neither the name of The NetBSD Foundation nor the names of its
.\"     contributors may be used to endorse or promote products derived
.\"     from this software without specific prior written permission.
.\"
.\"  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 January 10, 2005
.Dt TAP 4
.Os
.Sh NAME
.Nm tap
.Nd virtual Ethernet device
.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 in two ways:
through a sysctl node, or an ioctl call.
.Pp
The sysctl node is net.link.tap.\*[Lt]iface\*[Gt].
Any string of six colon-separated hexadecimal numbers will be accepted.
Reading that node will provide a string representation of the current
Ethernet address.
.Pp
The address can also be changed with the
.Dv SIOCSIFPHYADDR
ioctl, which is used the same way as with
.Xr gif 4 .
The difference is in the family of the address which is passed inside the
.Ft struct ifreqalias
argument, which should be set to
.Dv AF_LINK .
This ioctl call should be made on a socket, as it is not available on
the ioctl handler of the character device interface.
.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 gif 4 ,
.Xr tun 4 ,
.Xr ifconfig 8
.Sh HISTORY
The
.Nm
driver first appeared in
.Nx 3.0 .