share/man/man4/tap.4

   1 .\" $NetBSD: tap.4,v 1.10 2009/03/12 11:34:54 plunky Exp $
   2 .\"
   3 .\"  Copyright (c) 2004, 2005 The NetBSD Foundation.
   4 .\"  All rights reserved.
   5 .\"
   6 .\"  Redistribution and use in source and binary forms, with or without
   7 .\"  modification, are permitted provided that the following conditions
   8 .\"  are met:
   9 .\"  1. Redistributions of source code must retain the above copyright
  10 .\"     notice, this list of conditions and the following disclaimer.
  11 .\"  2. Redistributions in binary form must reproduce the above copyright
  12 .\"     notice, this list of conditions and the following disclaimer in the
  13 .\"     documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\"  THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  16 .\"  ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  17 .\"  TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  18 .\"  PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  19 .\"  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  20 .\"  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  21 .\"  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  22 .\"  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  23 .\"  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  24 .\"  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  25 .\"  POSSIBILITY OF SUCH DAMAGE.
  26 .\"
  27 .Dd March 10, 2009
  28 .Dt TAP 4
  29 .Os
  30 .Sh NAME
  31 .Nm tap
  32 .Nd virtual Ethernet device
  33 .Sh SYNOPSIS
  34 .Cd pseudo-device tap
  35 .Sh DESCRIPTION
  36 The
  37 .Nm
  38 driver allows the creation and use of virtual Ethernet devices.
  39 Those interfaces appear just as any real Ethernet NIC to the kernel,
  40 but can also be accessed by userland through a character device node in order
  41 to read frames being sent by the system or to inject frames.
  42 .Pp
  43 In that respect it is very similar to what
  44 .Xr tun 4
  45 provides, but the added Ethernet layer allows easy integration with machine
  46 emulators or virtual Ethernet networks through the use of
  47 .Xr bridge 4
  48 with tunneling.
  49 .Ss INTERFACE CREATION
  50 Interfaces may be created in two different ways:
  51 using the
  52 .Xr ifconfig 8
  53 .Cm create
  54 command with a specified device number,
  55 or its
  56 .Xr ioctl 2
  57 equivalent,
  58 .Dv SIOCIFCREATE ,
  59 or using the special cloning device
  60 .Pa /dev/tap .
  61 .Pp
  62 The former works the same as any other cloning network interface:
  63 the administrator can create and destroy interfaces at any time,
  64 notably at boot time.
  65 This is the easiest way of combining
  66 .Nm
  67 and
  68 .Xr bridge 4 .
  69 Later, userland will actually access the interfaces through the specific
  70 device nodes
  71 .Pa /dev/tapN .
  72 .Pp
  73 The latter is aimed at applications that need a virtual Ethernet device for
  74 the duration of their execution.
  75 A new interface is created at the opening of
  76 .Pa /dev/tap ,
  77 and is later destroyed when the last process using the file descriptor closes
  78 it.
  79 .Ss CHARACTER DEVICES
  80 Whether the
  81 .Nm
  82 devices are accessed through the special cloning device
  83 .Pa /dev/tap
  84 or through the specific devices
  85 .Pa /dev/tapN ,
  86 the possible actions to control the matching interface are the same.
  87 .Pp
  88 When using
  89 .Pa /dev/tap
  90 though, as the interface is created on-the-fly, its name is not known
  91 immediately by the application.
  92 Therefore the
  93 .Dv TAPGIFNAME
  94 ioctl is provided.
  95 It should be the first action an application using the special cloning device
  96 will do.
  97 It takes a pointer to a
  98 .Ft struct ifreq
  99 as an argument.
 100 .Pp
 101 Ethernet frames sent out by the kernel on a
 102 .Nm
 103 interface can be obtained by the controlling application with
 104 .Xr read 2 .
 105 It can also inject frames in the kernel with
 106 .Xr write 2 .
 107 There is absolutely no validation of the content of the injected frame,
 108 it can be any data, of any length.
 109 .Pp
 110 One call of
 111 .Xr write 2
 112 will inject a single frame in the kernel, as one call of
 113 .Xr read 2
 114 will retrieve a single frame from the queue, to the extent of the provided
 115 buffer.
 116 If the buffer is not large enough, the frame will be truncated.
 117 .Pp
 118 .Nm
 119 character devices support the
 120 .Dv FIONREAD
 121 ioctl which returns the size of the next available frame,
 122 or 0 if there is no available frame in the queue.
 123 .Pp
 124 They also support non-blocking I/O through the
 125 .Dv FIONBIO
 126 ioctl.
 127 In that mode,
 128 .Er EWOULDBLOCK
 129 is returned by
 130 .Xr read 2
 131 when no data is available.
 132 .Pp
 133 Asynchronous I/O is supported through the
 134 .Dv FIOASYNC ,
 135 .Dv FIOSETOWN ,
 136 and
 137 .Dv FIOGETOWN
 138 ioctls.
 139 The first will enable
 140 .Dv SIGIO
 141 generation, while the two other configure the process group that
 142 will receive the signal when data is ready.
 143 .Pp
 144 Synchronisation may also be achieved through the use of
 145 .Xr select 2 ,
 146 .Xr poll 2 ,
 147 or
 148 .Xr kevent 2 .
 149 .Ss ETHERNET ADDRESS
 150 When a
 151 .Nm
 152 device is created, it is assigned an Ethernet address
 153 of the form f2:0b:a4:xx:xx:xx.
 154 This address can later be changed using
 155 .Xr ifconfig 8
 156 to add an active link layer address, or directly via the
 157 .Dv SIOCALIFADDR
 158 ioctl on a
 159 .Dv PF_LINK
 160 socket, as it is not available on
 161 the ioctl handler of the character device interface.
 162 .Sh FILES
 163 .Bl -tag -compact -width /dev/tap[0-9]*
 164 .It Pa /dev/tap
 165 cloning device
 166 .It Pa /dev/tap[0-9]*
 167 individual character device nodes
 168 .El
 169 .Sh SEE ALSO
 170 .Xr bridge 4 ,
 171 .Xr etherip 4 ,
 172 .Xr tun 4 ,
 173 .Xr ifconfig 8
 174 .Sh HISTORY
 175 The
 176 .Nm
 177 driver first appeared in
 178 .Nx 3.0 .