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: January 9 2020 $ .Dt TAP 4 .Os .Sh NAME .Nm tap .Nd Ethernet tunnel pseudo-device .Sh SYNOPSIS .Cd "pseudo-device tun"
p n sys/types.h n 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.
p A .Nm interface can be created at runtime using the c ifconfig tap Ns Ar N Ic create command or by opening the character special device
p 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
a /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 .
p Writes never block. If the protocol queue is full, the packet is dropped, a .Dq collision is counted, and .Er ENOBUFS is returned.
p In addition to the usual network interface ioctl commands described in .Xr netintro 4 , the following special commands defined in n net/if_tun.h are supported:
p l -tag -width indent -compact t Dv TUNGIFINFO Fa "struct tuninfo *" t Dv TUNSIFINFO Fa "struct tuninfo *" Get or set the interface characteristics. d -literal /* iface info */ struct tuninfo { u_int mtu; u_short type; u_short flags; u_int baudrate; }; .Ed
p
.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.
p t Dv TUNSIFMODE Fa int * Set just the interface flags. The same restrictions as for .Dv TUNSIFINFO apply.
p t Dv SIOCGIFADDR Fa uint8_t Ns [ETHER_ADDR_LEN] t Dv SIOCSIFADDR Fa uint8_t Ns [ETHER_ADDR_LEN] Get or set the link layer address (MAC address) of the interface. .El
p The generic ioctls .Dv FIONREAD , .Dv FIONBIO , .Dv FIOASYNC , .Dv FIOSETOWN , .Dv FIOGETOWN are supported by .Nm . .Sh FILES l -tag -width /dev/tap* -compact t Pa /dev/tap* .El .Sh ERRORS If open fails, .Xr errno 2 may be set to one of: l -tag -width Er t Bq Er ENXIO Not that many devices configured. t Bq Er EBUSY Device was already open. .El
p If a .Xr write 2 call fails, .Xr errno 2 is set to one of: l -tag -width Er t Bq Er EMSGSIZE The packet supplied was too small or too large. The maximum sized packet allowed is currently 16384 bytes. t Bq Er ENOBUFS There were no mbufs, or the queue for the outgoing protocol is full. t Bq Er EAFNOSUPPORT The address family specified in the tunnel header was not recognized. .El
p Ioctl commands may fail with: l -tag -width Er t Bq Er EINVAL Attempt to set both .Dv IFF_POINTOPOINT and .Dv IFF_BROADCAST with .Dv TUNSIFMODE . t Bq Er ENOTTY Unrecognized ioctl command. .El
p A .Xr read 2 call may fail because of: l -tag -width Er t 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 . t Bq Er EWOULDBLOCK Non-blocking I/O was selected and no packets were available. .El
p An attempt to send a packet out via the interface may fail with: l -tag -width Er t 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