c4d9468ea0
Avoid using parenthesis enclosure macros (.Pq and .Po/.Pc) with plain text. Not only this slows down the mdoc(7) processing significantly, but it also has an undesired (in this case) effect of disabling hyphenation within the entire enclosed block.
229 lines
5.4 KiB
Groff
229 lines
5.4 KiB
Groff
.\" $FreeBSD$
|
|
.\" Based on PR#2411
|
|
.\"
|
|
.Dd July 9, 2000
|
|
.Os
|
|
.Dt TAP 4
|
|
.Sh NAME
|
|
.Nm tap
|
|
.Nd Ethernet tunnel software network interface
|
|
.Sh SYNOPSIS
|
|
.Cd device tap
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Nm
|
|
interface is a software loopback mechanism that can be loosely
|
|
described as the network interface analog of the
|
|
.Xr pty 4 ,
|
|
that is,
|
|
.Nm
|
|
does for network interfaces what the
|
|
.Nm pty
|
|
driver does for terminals.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
driver, like the
|
|
.Nm pty
|
|
driver, provides two interfaces: an interface like the usual facility
|
|
it is simulating
|
|
(an Ethernet network interface in the case of
|
|
.Nm ,
|
|
or a terminal for
|
|
.Nm pty ) ,
|
|
and a character-special device
|
|
.Dq control
|
|
interface.
|
|
.Pp
|
|
The network interfaces are named
|
|
.Sy tap Ns Ar 0 ,
|
|
.Sy tap Ns Ar 1 ,
|
|
etc, as many as were made by
|
|
.Xr MAKEDEV 8 .
|
|
Each one supports the usual Ethernet network-interface
|
|
.Xr ioctl 2 Ns s ,
|
|
such as
|
|
.Dv SIOCSIFADDR
|
|
and
|
|
.Dv SIOCSIFNETMASK ,
|
|
and thus can be used with
|
|
.Xr ifconfig 8
|
|
like any other Ethernet interface. When the system chooses to transmit
|
|
an Ethernet frame on the network interface, the frame can be read from
|
|
the control device
|
|
(it appears as
|
|
.Dq input
|
|
there);
|
|
writing an Ethernet frame to the control device generates an input frame on
|
|
the network interface, as if the
|
|
(non-existent)
|
|
hardware had just received it.
|
|
.Pp
|
|
The Ethernet tunnel device, normally
|
|
.Pa /dev/tap Ns Sy N ,
|
|
is exclusive-open
|
|
(it cannot be opened if it is already open)
|
|
and is restricted to the super-user.
|
|
A
|
|
.Fn read
|
|
call will return an error
|
|
.Pq Er EHOSTDOWN
|
|
if the interface is not
|
|
.Dq ready .
|
|
Once the interface is ready,
|
|
.Fn read
|
|
will return an Ethernet frame if one is available; if not, it will
|
|
either block until one is or return
|
|
.Er EWOULDBLOCK ,
|
|
depending on whether non-blocking I/O has been enabled. If the frame
|
|
is longer than is allowed for in the buffer passed to
|
|
.Fn read ,
|
|
the extra data will be silently dropped.
|
|
.Pp
|
|
A
|
|
.Xr write 2
|
|
call passes an Ethernet frame in to be
|
|
.Dq received
|
|
on the pseudo-interface. Each
|
|
.Fn write
|
|
call supplies exactly one frame; the frame length is taken from the
|
|
amount of data provided to
|
|
.Fn write .
|
|
Writes will not block; if the frame cannot be accepted
|
|
for a transient reason
|
|
(e.g., no buffer space available),
|
|
it is silently dropped; if the reason is not transient
|
|
(e.g., frame too large),
|
|
an error is returned.
|
|
The following
|
|
.Xr ioctl 2
|
|
calls are supported
|
|
(defined in
|
|
.Aq Pa net/if_tap.h ) :
|
|
.Bl -tag -width VMIO_SIOCSETMACADDR
|
|
.It Dv TAPSDEBUG
|
|
The argument should be a pointer to an
|
|
.Va int ;
|
|
this sets the internal debugging variable to that value. What, if
|
|
anything, this variable controls is not documented here; see the source
|
|
code.
|
|
.It Dv TAPGDEBUG
|
|
The argument should be a pointer to an
|
|
.Va int ;
|
|
this stores the internal debugging variable's value into it.
|
|
.It Dv FIONBIO
|
|
Turn non-blocking I/O for reads off or on, according as the argument
|
|
.Va int Ns 's
|
|
value is or isn't zero
|
|
(Writes are always nonblocking).
|
|
.It Dv FIOASYNC
|
|
Turn asynchronous I/O for reads
|
|
(i.e., generation of
|
|
.Dv SIGIO
|
|
when data is available to be read)
|
|
off or on, according as the argument
|
|
.Va int Ns 's
|
|
value is or isn't zero.
|
|
.It Dv FIONREAD
|
|
If any frames are queued to be read, store the size of the first one into the argument
|
|
.Va int ;
|
|
otherwise, store zero.
|
|
.It Dv TIOCSPGRP
|
|
Set the process group to receive
|
|
.Dv SIGIO
|
|
signals, when asynchronous I/O is enabled, to the argument
|
|
.Va int
|
|
value.
|
|
.It Dv TIOCGPGRP
|
|
Retrieve the process group value for
|
|
.Dv SIGIO
|
|
signals into the argument
|
|
.Va int
|
|
value.
|
|
.It Dv SIOCGIFADDR
|
|
Retrieve the Media Access Control
|
|
.Pq Dv MAC
|
|
address of the
|
|
.Dq remote
|
|
side. This command is used by the VMware port and expected to be executed on
|
|
descriptor, associated with control device
|
|
(usually
|
|
.Pa /dev/vmnet Ns Sy N
|
|
or
|
|
.Pa /dev/tap Ns Sy N ) .
|
|
The
|
|
.Va buffer ,
|
|
which is passed as the argument, is expected to have enough space to store
|
|
the
|
|
.Dv MAC
|
|
address. At the open time both
|
|
.Dq local
|
|
and
|
|
.Dq remote
|
|
.Dv MAC
|
|
addresses are the same, so this command could be used to retrieve the
|
|
.Dq local
|
|
.Dv MAC
|
|
address.
|
|
.It Dv SIOCSIFADDR
|
|
Set the Media Access Control
|
|
.Pq Dv MAC
|
|
address of the
|
|
.Dq remote
|
|
side. This command is used by VMware port and expected to be executed on
|
|
a descriptor, associated with control device
|
|
(usually
|
|
.Pa /dev/vmnet Ns Sy N ) .
|
|
.El
|
|
.Pp
|
|
The control device also supports
|
|
.Xr select 2
|
|
for read; selecting for write is pointless, and always succeeds, since
|
|
writes are always non-blocking.
|
|
.Pp
|
|
On the last close of the data device, the interface is
|
|
brought down
|
|
(as if with
|
|
.Dq ifconfig tap Ns Sy N No down )
|
|
unless the devices is a VMnet device.
|
|
All queued frames are thrown away. If the interface is up when the data
|
|
device is not open, output frames are thrown away rather than
|
|
letting them pile up.
|
|
.Pp
|
|
The
|
|
.Nm
|
|
device is also can be used with the VMware port as a replacement
|
|
for the old VMnet device driver. The driver uses the minor number
|
|
to select between
|
|
.Nm
|
|
and
|
|
.Nm vmnet
|
|
devices. VMnet minor numbers begin at
|
|
.Va 0x10000
|
|
+
|
|
.Va N .
|
|
Where
|
|
.Va N
|
|
is a VMnet unit number. In this case control device is expected to be
|
|
.Pa /dev/vmnet Ns Sy N ,
|
|
and network interface will be
|
|
.Sy vmnet Ns Ar N .
|
|
Additionally, VMnet devices do not ifconfig themselves down when the
|
|
control device is closed. Everything else is the same.
|
|
.Pp
|
|
In addition to mentioned above
|
|
.Xr ioctl 2
|
|
there is one additional one for the VMware port.
|
|
.Bl -tag -width VMIO_SIOCSETMACADDR
|
|
.It Dv VMIO_SIOCSIFFLAGS
|
|
VMware
|
|
.Dv SIOCSIFFLAGS .
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr inet 4 ,
|
|
.Xr intro 4
|
|
.\" .Sh BUGS
|
|
.Sh AUTHORS
|
|
This man page has been obtained from
|
|
.Fx .
|