share/man/man4/tap.4

   1 .\" $FreeBSD$
   2 .\" Based on PR#2411
   3 .\"
   4 .Dd January 26, 2012
   5 .Dt TAP 4
   6 .Os
   7 .Sh NAME
   8 .Nm tap
   9 .Nd Ethernet tunnel software network interface
  10 .Sh SYNOPSIS
  11 .Cd device tap
  12 .Sh DESCRIPTION
  13 The
  14 .Nm
  15 interface is a software loopback mechanism that can be loosely
  16 described as the network interface analog of the
  17 .Xr pty 4 ,
  18 that is,
  19 .Nm
  20 does for network interfaces what the
  21 .Nm pty
  22 driver does for terminals.
  23 .Pp
  24 The
  25 .Nm
  26 driver, like the
  27 .Nm pty
  28 driver, provides two interfaces: an interface like the usual facility
  29 it is simulating
  30 (an Ethernet network interface in the case of
  31 .Nm ,
  32 or a terminal for
  33 .Nm pty ) ,
  34 and a character-special device
  35 .Dq control
  36 interface.
  37 .Pp
  38 The network interfaces are named
  39 .Dq Li tap0 ,
  40 .Dq Li tap1 ,
  41 etc., one for each control device that has been opened.
  42 These Ethernet network interfaces persist until
  43 .Pa if_tap.ko
  44 module is unloaded, or until removed with "ifconfig destroy" (see below).
  45 .Pp
  46 .Nm
  47 devices are created using interface cloning.
  48 This is done using the
  49 .Dq ifconfig tap Ns Sy N No create
  50 command.
  51 This is the preferred method of creating
  52 .Nm
  53 devices.
  54 The same method allows removal of interfaces.
  55 For this, use the
  56 .Dq ifconfig tap Ns Sy N No destroy
  57 command.
  58 .Pp
  59 If the
  60 .Xr sysctl 8
  61 variable
  62 .Va net.link.tap.devfs_cloning
  63 is non-zero, the
  64 .Nm
  65 interface
  66 permits opens on the special control device
  67 .Pa /dev/tap .
  68 When this device is opened,
  69 .Nm
  70 will return a handle for the lowest unused
  71 .Nm
  72 device (use
  73 .Xr devname 3
  74 to determine which).
  75 .Pp
  76 .Bf Em
  77 Disabling the legacy devfs cloning functionality may break existing
  78 applications which use
  79 .Nm ,
  80 such as
  81 .Tn VMware
  82 and
  83 .Xr ssh 1 .
  84 It therefore defaults to being enabled until further notice.
  85 .Ef
  86 .Pp
  87 Control devices (once successfully opened) persist until
  88 .Pa if_tap.ko
  89 is unloaded or the interface is destroyed.
  90 .Pp
  91 Each interface supports the usual Ethernet network interface
  92 .Xr ioctl 2 Ns s
  93 and thus can be used with
  94 .Xr ifconfig 8
  95 like any other Ethernet interface.
  96 When the system chooses to transmit
  97 an Ethernet frame on the network interface, the frame can be read from
  98 the control device
  99 (it appears as
 100 .Dq input
 101 there);
 102 writing an Ethernet frame to the control device generates an input frame on
 103 the network interface, as if the
 104 (non-existent)
 105 hardware had just received it.
 106 .Pp
 107 The Ethernet tunnel device, normally
 108 .Pa /dev/tap Ns Sy N ,
 109 is exclusive-open
 110 (it cannot be opened if it is already open)
 111 and is restricted to the super-user, unless the
 112 .Xr sysctl 8
 113 variable
 114 .Va net.link.tap.user_open
 115 is non-zero.
 116 If the
 117 .Xr sysctl 8
 118 variable
 119 .Va net.link.tap.up_on_open
 120 is non-zero, the tunnel device will be marked
 121 .Dq up
 122 when the control device is opened.
 123 A
 124 .Fn read
 125 call will return an error
 126 .Pq Er EHOSTDOWN
 127 if the interface is not
 128 .Dq ready .
 129 Once the interface is ready,
 130 .Fn read
 131 will return an Ethernet frame if one is available; if not, it will
 132 either block until one is or return
 133 .Er EWOULDBLOCK ,
 134 depending on whether non-blocking I/O has been enabled.
 135 If the frame
 136 is longer than is allowed for in the buffer passed to
 137 .Fn read ,
 138 the extra data will be silently dropped.
 139 .Pp
 140 A
 141 .Xr write 2
 142 call passes an Ethernet frame in to be
 143 .Dq received
 144 on the pseudo-interface.
 145 Each
 146 .Fn write
 147 call supplies exactly one frame; the frame length is taken from the
 148 amount of data provided to
 149 .Fn write .
 150 Writes will not block; if the frame cannot be accepted
 151 for a transient reason
 152 (e.g., no buffer space available),
 153 it is silently dropped; if the reason is not transient
 154 (e.g., frame too large),
 155 an error is returned.
 156 The following
 157 .Xr ioctl 2
 158 calls are supported
 159 (defined in
 160 .In net/if_tap.h ) :
 161 .Bl -tag -width VMIO_SIOCSETMACADDR
 162 .It Dv TAPSIFINFO
 163 Set network interface information (line speed, MTU and type).
 164 The argument should be a pointer to a
 165 .Va struct tapinfo .
 166 .It Dv TAPGIFINFO
 167 Retrieve network interface information (line speed, MTU and type).
 168 The argument should be a pointer to a
 169 .Va struct tapinfo .
 170 .It Dv TAPSDEBUG
 171 The argument should be a pointer to an
 172 .Va int ;
 173 this sets the internal debugging variable to that value.
 174 What, if
 175 anything, this variable controls is not documented here; see the source
 176 code.
 177 .It Dv TAPGDEBUG
 178 The argument should be a pointer to an
 179 .Va int ;
 180 this stores the internal debugging variable's value into it.
 181 .It Dv TAPGIFNAME
 182 Retrieve network interface name.
 183 The argument should be a pointer to a
 184 .Va struct ifreq .
 185 The interface name will be returned in the
 186 .Va ifr_name
 187 field.
 188 .It Dv FIONBIO
 189 Turn non-blocking I/O for reads off or on, according as the argument
 190 .Va int Ns 's
 191 value is or is not zero
 192 (Writes are always nonblocking).
 193 .It Dv FIOASYNC
 194 Turn asynchronous I/O for reads
 195 (i.e., generation of
 196 .Dv SIGIO
 197 when data is available to be read)
 198 off or on, according as the argument
 199 .Va int Ns 's
 200 value is or is not zero.
 201 .It Dv FIONREAD
 202 If any frames are queued to be read, store the size of the first one into the argument
 203 .Va int ;
 204 otherwise, store zero.
 205 .It Dv TIOCSPGRP
 206 Set the process group to receive
 207 .Dv SIGIO
 208 signals, when asynchronous I/O is enabled, to the argument
 209 .Va int
 210 value.
 211 .It Dv TIOCGPGRP
 212 Retrieve the process group value for
 213 .Dv SIGIO
 214 signals into the argument
 215 .Va int
 216 value.
 217 .It Dv SIOCGIFADDR
 218 Retrieve the Media Access Control
 219 .Pq Dv MAC
 220 address of the
 221 .Dq remote
 222 side.
 223 This command is used by the VMware port and expected to be executed on
 224 descriptor, associated with control device
 225 (usually
 226 .Pa /dev/vmnet Ns Sy N
 227 or
 228 .Pa /dev/tap Ns Sy N ) .
 229 The
 230 .Va buffer ,
 231 which is passed as the argument, is expected to have enough space to store
 232 the
 233 .Dv MAC
 234 address.
 235 At the open time both
 236 .Dq local
 237 and
 238 .Dq remote
 239 .Dv MAC
 240 addresses are the same, so this command could be used to retrieve the
 241 .Dq local
 242 .Dv MAC
 243 address.
 244 .It Dv SIOCSIFADDR
 245 Set the Media Access Control
 246 .Pq Dv MAC
 247 address of the
 248 .Dq remote
 249 side.
 250 This command is used by VMware port and expected to be executed on
 251 a descriptor, associated with control device
 252 (usually
 253 .Pa /dev/vmnet Ns Sy N ) .
 254 .El
 255 .Pp
 256 The control device also supports
 257 .Xr select 2
 258 for read; selecting for write is pointless, and always succeeds, since
 259 writes are always non-blocking.
 260 .Pp
 261 On the last close of the data device, the interface is
 262 brought down
 263 (as if with
 264 .Dq ifconfig tap Ns Sy N No down )
 265 unless the device is a
 266 .Em VMnet
 267 device.
 268 All queued frames are thrown away.
 269 If the interface is up when the data
 270 device is not open, output frames are thrown away rather than
 271 letting them pile up.
 272 .Pp
 273 The
 274 .Nm
 275 device can also be used with the VMware port as a replacement
 276 for the old
 277 .Em VMnet
 278 device driver.
 279 The driver uses the minor number
 280 to select between
 281 .Nm
 282 and
 283 .Nm vmnet
 284 devices.
 285 .Em VMnet
 286 minor numbers begin at
 287 .Va 0x800000
 288 +
 289 .Va N ;
 290 where
 291 .Va N
 292 is a
 293 .Em VMnet
 294 unit number.
 295 In this case the control device is expected to be
 296 .Pa /dev/vmnet Ns Sy N ,
 297 and the network interface will be
 298 .Sy vmnet Ns Ar N .
 299 Additionally,
 300 .Em VMnet
 301 devices do not
 302 .Xr ifconfig 8
 303 themselves down when the
 304 control device is closed.
 305 Everything else is the same.
 306 .Pp
 307 In addition to the above mentioned
 308 .Xr ioctl 2
 309 calls, there is an additional one for the VMware port.
 310 .Bl -tag -width VMIO_SIOCSETMACADDR
 311 .It Dv VMIO_SIOCSIFFLAGS
 312 VMware
 313 .Dv SIOCSIFFLAGS .
 314 .El
 315 .Sh SEE ALSO
 316 .Xr inet 4 ,
 317 .Xr intro 4