NAME
tap
—
Ethernet tunnel
pseudo-device
SYNOPSIS
pseudo-device tun
#include <sys/types.h>
#include <net/if_tun.h>
DESCRIPTION
The tap
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.
A tap
interface can be created at runtime
using the ifconfig tap
N
create
command or by opening the character special
device /dev/tapN.
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
/dev/tapN, it will be automatically destroyed.
Devices created via
ifconfig(8) are only marked as not running and traffic will be
dropped returning EHOSTDOWN
.
Writes never block. If the protocol queue is full, the packet is
dropped, a “collision” is counted, and
ENOBUFS
is returned.
In addition to the usual network interface ioctl commands
described in
netintro(4), the following special commands defined in
<net/if_tun.h>
are
supported:
TUNGIFINFO
struct tuninfo *TUNSIFINFO
struct tuninfo *- Get or set the interface characteristics.
/* iface info */ struct tuninfo { u_int mtu; u_short type; u_short flags; u_int baudrate; };
flags sets the interface flags, and can include one or more of
IFF_UP
,IFF_POINTOPOINT
,IFF_MULTICAST
,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 toIFF_BROADCAST
|IFF_MULTICAST
. It is an error to set bothIFF_POINTOPOINT
andIFF_BROADCAST
. type defaults toIFT_ETHER
. This sets the interface media address header type. TUNSIFMODE
int *flags- Set just the interface flags. The same restrictions as for
TUNSIFINFO
apply. FIONBIO
int *flag- Set non-blocking I/O.
FIOASYNC
int *flag- Cause signal
SIGIO
to be sent when a packet can be read. TIOCSPGRP
int *pgrpTIOCGPGRP
int *pgrp- Get or set the process group to which signals might be sent via
FIOASYNC
. FIONREAD
int *count- Get the byte count of the next packet available to be read.
SIOCGIFADDR
struct ether_addr *addrSIOCSIFADDR
struct ether_addr *addr- Get or set the Ethernet address of the device.
FILES
- /dev/tap*
ERRORS
If open fails, errno(2) may be set to one of:
- [
ENXIO
] - Not that many devices configured.
- [
EBUSY
] - Device was already open.
If a write(2) call fails, errno(2) is set to one of:
- [
EMSGSIZE
] - The packet supplied was too small or too large. The maximum sized packet allowed is currently 16384 bytes.
- [
ENOBUFS
] - There were no mbufs, or the queue for the outgoing protocol is full.
- [
EAFNOSUPPORT
] - The address family specified in the tunnel header was not recognized.
Ioctl commands may fail with:
- [
EINVAL
] - Attempt to set both
IFF_POINTOPOINT
andIFF_BROADCAST
withTUNSIFMODE
. - [
ENOTTY
] - Unrecognized ioctl command.
A read(2) call may fail because of:
- [
EHOSTDOWN
] - The device is not ready. The device must have an
inet(4) interface address assigned to it, such as via
SIOCSIFADDR
. - [
EWOULDBLOCK
] - Non-blocking I/O was selected and no packets were available.
An attempt to send a packet out via the interface may fail with:
- [
EHOSTDOWN
] - The device is not ready. The device must have an
inet(4) interface address assigned to it, such as via
SIOCSIFADDR
.
SEE ALSO
inet(4), intro(4), netintro(4), hostname.if(5), ifconfig(8), netstart(8)
HISTORY
The tap
driver first appeared in
OpenBSD 5.9.
AUTHORS
Claudio Jeker <claudio@openbsd.org>