NAME

       tap — Ethernet tunnel software network interface

SYNOPSIS

       device tap

DESCRIPTION

       The tap interface is a software loopback mechanism that can be loosely described as the network interface
       analog of the pty(4), that is, tap does for network interfaces what the pty driver does for terminals.

       The  tap driver, like the pty driver, provides two interfaces: an interface like the usual facility it is
       simulating (an Ethernet network interface in the case of tap, or a terminal for pty),  and  a  character-
       special device “control” interface.

       The  network interfaces are named “tap0”, “tap1”, etc., one for each control device that has been opened.
       These Ethernet network interfaces persist until if_tap.ko module  is  unloaded,  or  until  removed  with
       "ifconfig destroy" (see below).

       tap  devices are created using interface cloning.  This is done using the “ifconfig tapN create” command.
       This is the preferred method of creating tap devices.  The same method allows removal of interfaces.  For
       this, use the “ifconfig tapN destroy” command.

       If the sysctl(8) variable net.link.tap.devfs_cloning is non-zero, the tap interface permits opens on  the
       special  control  device  /dev/tap.   When this device is opened, tap will return a handle for the lowest
       unused tap device (use devname(3) to determine which).

       Disabling the legacy devfs cloning functionality may break existing applications which use tap,  such  as
       VMware and ssh(1).  It therefore defaults to being enabled until further notice.

       Control  devices  (once  successfully  opened)  persist  until  if_tap.ko is unloaded or the interface is
       destroyed.

       Each interface supports  the  usual  Ethernet  network  interface  ioctl(2)s,  such  as  SIOCSIFADDR  and
       SIOCSIFNETMASK, and thus can be used with 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 “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.

       The  Ethernet  tunnel device, normally /dev/tapN, is exclusive-open (it cannot be opened if it is already
       open) and is restricted to the super-user, unless the sysctl(8) variable net.link.tap.user_open  is  non-
       zero.   If  the  sysctl(8) variable net.link.tap.up_on_open is non-zero, the tunnel device will be marked
       “up” when the control device is opened.  A read() call will return an error (EHOSTDOWN) if the  interface
       is  not  “ready”.  Once the interface is ready, read() will return an Ethernet frame if one is available;
       if not, it will either block until one is or return 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 read(), the extra
       data will be silently dropped.

       A write(2) call passes an Ethernet frame in to be “received” on the pseudo-interface.  Each write()  call
       supplies  exactly  one  frame;  the  frame  length  is taken from the amount of data provided to 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 ioctl(2) calls are supported (defined in <net/if_tap.h>):

       TAPSIFINFO           Set network interface information (line speed, MTU and type).  The  argument  should
                            be a pointer to a struct tapinfo.

       TAPGIFINFO           Retrieve  network  interface  information  (line speed, MTU and type).  The argument
                            should be a pointer to a struct tapinfo.

       TAPSDEBUG            The argument should be a pointer  to  an  int;  this  sets  the  internal  debugging
                            variable to that value.  What, if anything, this variable controls is not documented
                            here; see the source code.

       TAPGDEBUG            The  argument  should  be  a  pointer  to an int; this stores the internal debugging
                            variable's value into it.

       TAPGIFNAME           Retrieve network interface name.  The argument should  be  a  pointer  to  a  struct
                            ifreq.  The interface name will be returned in the ifr_name field.

       FIONBIO              Turn  non-blocking I/O for reads off or on, according as the argument int's value is
                            or is not zero (Writes are always nonblocking).

       FIOASYNC             Turn asynchronous I/O for reads (i.e., generation of SIGIO when data is available to
                            be read) off or on, according as the argument int's value is or is not zero.

       FIONREAD             If any frames are queued to be read, store the  size  of  the  first  one  into  the
                            argument int; otherwise, store zero.

       TIOCSPGRP            Set the process group to receive SIGIO signals, when asynchronous I/O is enabled, to
                            the argument int value.

       TIOCGPGRP            Retrieve the process group value for SIGIO signals into the argument int value.

       SIOCGIFADDR          Retrieve  the Media Access Control (MAC) address of the “remote” side.  This command
                            is used by the VMware port and expected to be  executed  on  descriptor,  associated
                            with control device (usually /dev/vmnetN or /dev/tapN).  The buffer, which is passed
                            as  the argument, is expected to have enough space to store the MAC address.  At the
                            open time both “local” and “remote” MAC addresses are  the  same,  so  this  command
                            could be used to retrieve the “local” MAC address.

       SIOCSIFADDR          Set  the  Media  Access Control (MAC) address of the “remote” side.  This command is
                            used by VMware port and expected to be executed on  a  descriptor,  associated  with
                            control device (usually /dev/vmnetN).

       The  control  device  also  supports  select(2)  for  read;  selecting for write is pointless, and always
       succeeds, since writes are always non-blocking.

       On the last close of the data device, the interface is brought down (as if  with  “ifconfig  tapN  down”)
       unless the device 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.

       The  tap  device  can also be used with the VMware port as a replacement for the old VMnet device driver.
       The driver uses the minor number to select between tap and vmnet devices.  VMnet minor numbers  begin  at
       0x800000  +  N;  where  N  is  a  VMnet  unit  number.  In this case the control device is expected to be
       /dev/vmnetN, and the network interface will be vmnetN.  Additionally, VMnet devices  do  not  ifconfig(8)
       themselves down when the control device is closed.  Everything else is the same.

       In addition to the above mentioned ioctl(2) calls, there is an additional one for the VMware port.

       VMIO_SIOCSIFFLAGS    VMware SIOCSIFFLAGS.

SEE ALSO

       inet(4), intro(4)

Debian                                          September 8, 2008                                         TAP(4)