share/man/man4/tap.4

   1 .\" $FreeBSD: src/share/man/man4/tap.4,v 1.1.2.7 2002/04/16 23:59:28 trhodes Exp $
   2 .\" $DragonFly: src/share/man/man4/tap.4,v 1.6 2006/10/14 23:46:23 swildner Exp $
   3 .\" Based on PR#2411
   4 .\"
   5 .Dd August 6, 2009
   6 .Os
   7 .Dt TAP 4
   8 .Sh NAME
   9 .Nm tap
  10 .Nd Ethernet tunnel software network interface
  11 .Sh SYNOPSIS
  12 .Cd pseudo-device tap
  13 .Sh DESCRIPTION
  14 The
  15 .Nm
  16 interface is a software loopback mechanism that can be loosely
  17 described as the network interface analog of the
  18 .Xr pty 4 ,
  19 that is,
  20 .Nm
  21 does for network interfaces what the
  22 .Nm pty
  23 driver does for terminals.
  24 .Pp
  25 The
  26 .Nm
  27 driver, like the
  28 .Nm pty
  29 driver, provides two interfaces: an interface like the usual facility
  30 it is simulating
  31 (an Ethernet network interface in the case of
  32 .Nm ,
  33 or a terminal for
  34 .Nm pty ) ,
  35 and a character-special device
  36 .Dq control
  37 interface.
  38 .Pp
  39 The network interfaces are named
  40 .Sy tap Ns Ar 0 ,
  41 .Sy tap Ns Ar 1 ,
  42 etc, and each one supports the usual Ethernet network-interface
  43 .Xr ioctl 2 Ns s ,
  44 such as
  45 .Dv SIOCSIFADDR
  46 and
  47 .Dv SIOCSIFNETMASK ,
  48 and thus can be used with
  49 .Xr ifconfig 8
  50 like any other Ethernet interface. When the system chooses to transmit
  51 an Ethernet frame on the network interface, the frame can be read from
  52 the control device
  53 (it appears as
  54 .Dq input
  55 there);
  56 writing an Ethernet frame to the control device generates an input frame on
  57 the network interface, as if the
  58 (non-existent)
  59 hardware had just received it.
  60 .Pp
  61 The Ethernet tunnel device, normally
  62 .Pa /dev/tap Ns Sy N ,
  63 is exclusive-open
  64 (it cannot be opened if it is already open)
  65 and is restricted to the super-user.
  66 A
  67 .Fn read
  68 call will return an error
  69 .Pq Er EHOSTDOWN
  70 if the interface is not
  71 .Dq ready .
  72 Once the interface is ready,
  73 .Fn read
  74 will return an Ethernet frame if one is available; if not, it will
  75 either block until one is or return
  76 .Er EWOULDBLOCK ,
  77 depending on whether non-blocking I/O has been enabled. If the frame
  78 is longer than is allowed for in the buffer passed to
  79 .Fn read ,
  80 the extra data will be silently dropped.
  81 .Pp
  82 A
  83 .Xr write 2
  84 call passes an Ethernet frame in to be
  85 .Dq received
  86 on the pseudo-interface.  Each
  87 .Fn write
  88 call supplies exactly one frame; the frame length is taken from the
  89 amount of data provided to
  90 .Fn write .
  91 Writes will not block; if the frame cannot be accepted
  92 for a transient reason
  93 (e.g., no buffer space available),
  94 it is silently dropped; if the reason is not transient
  95 (e.g., frame too large),
  96 an error is returned.
  97 The following
  98 .Xr ioctl 2
  99 calls are supported
 100 (defined in
 101 .In net/tap/if_tap.h ) :
 102 .Bl -tag -width ".Dv VMIO_SIOCSETMACADDR"
 103 .It Dv TAPSDEBUG
 104 The argument should be a pointer to an
 105 .Va int ;
 106 this sets the internal debugging variable to that value.  What, if
 107 anything, this variable controls is not documented here; see the source
 108 code.
 109 .It Dv TAPGDEBUG
 110 The argument should be a pointer to an
 111 .Va int ;
 112 this stores the internal debugging variable's value into it.
 113 .It Dv FIONBIO
 114 Turn non-blocking I/O for reads off or on, according as the argument
 115 .Va int Ns 's
 116 value is or isn't zero
 117 (Writes are always nonblocking).
 118 .It Dv FIOASYNC
 119 Turn asynchronous I/O for reads
 120 (i.e., generation of
 121 .Dv SIGIO
 122 when data is available to be read)
 123 off or on, according as the argument
 124 .Va int Ns 's
 125 value is or isn't zero.
 126 .It Dv FIONREAD
 127 If any frames are queued to be read, store the size of the first one into the argument
 128 .Va int ;
 129 otherwise, store zero.
 130 .It Dv TIOCSPGRP
 131 Set the process group to receive
 132 .Dv SIGIO
 133 signals, when asynchronous I/O is enabled, to the argument
 134 .Va int
 135 value.
 136 .It Dv TIOCGPGRP
 137 Retrieve the process group value for
 138 .Dv SIGIO
 139 signals into the argument
 140 .Va int
 141 value.
 142 .It Dv SIOCGIFADDR
 143 Retrieve the Media Access Control
 144 .Pq Dv MAC
 145 address of the
 146 .Dq remote
 147 side. This command is used by the VMware port and expected to be executed on
 148 descriptor, associated with control device
 149 (usually
 150 .Pa /dev/vmnet Ns Sy N
 151 or
 152 .Pa /dev/tap Ns Sy N ) .
 153 The
 154 .Va buffer ,
 155 which is passed as the argument, is expected to have enough space to store
 156 the
 157 .Dv MAC
 158 address. At the open time both
 159 .Dq local
 160 and
 161 .Dq remote
 162 .Dv MAC
 163 addresses are the same, so this command could be used to retrieve the
 164 .Dq local
 165 .Dv MAC
 166 address.
 167 .It Dv SIOCSIFADDR
 168 Set the Media Access Control
 169 .Pq Dv MAC
 170 address of the
 171 .Dq remote
 172 side. This command is used by VMware port and expected to be executed on
 173 a descriptor, associated with control device
 174 (usually
 175 .Pa /dev/vmnet Ns Sy N ) .
 176 .El
 177 .Pp
 178 The control device also supports
 179 .Xr select 2
 180 for read; selecting for write is pointless, and always succeeds, since
 181 writes are always non-blocking.
 182 .Pp
 183 On the last close of the data device, the interface is
 184 brought down
 185 (as if with
 186 .Dq ifconfig tap Ns Sy N No down )
 187 unless the devices is a
 188 .Em VMnet
 189 device.
 190 All queued frames are thrown away. If the interface is up when the data
 191 device is not open, output frames are thrown away rather than
 192 letting them pile up.
 193 .Pp
 194 The
 195 .Nm
 196 device is also can be used with the
 197 .Em VMware
 198 port as a replacement
 199 for the old
 200 .Em VMnet
 201 device driver. The driver uses the minor number
 202 to select between
 203 .Nm
 204 and
 205 .Nm vmnet
 206 devices.
 207 .Em VMnet
 208 minor numbers begin at
 209 .Va 0x10000
 210 +
 211 .Va N ;
 212 where
 213 .Va N
 214 is a
 215 .Em VMnet
 216 unit number. In this case control device is expected to be
 217 .Pa /dev/vmnet Ns Sy N ,
 218 and network interface will be
 219 .Sy vmnet Ns Ar N .
 220 Additionally,
 221 .Em VMnet
 222 devices do not
 223 .Xr ifconfig 8
 224 themselves down when the
 225 control device is closed. Everything else is the same.
 226 .Pp
 227 In addition to the above mentioned,
 228 .Xr ioctl 2
 229 calls, there is one additional one for the VMware port.
 230 .Bl -tag -width ".Dv VMIO_SIOCSETMACADDR"
 231 .It Dv VMIO_SIOCSIFFLAGS
 232 VMware
 233 .Dv SIOCSIFFLAGS .
 234 .El
 235 .Sh SEE ALSO
 236 .Xr inet 4 ,
 237 .Xr intro 4