share/man/man4/tap.4

   1 .\" $FreeBSD$
   2 .\" Based on PR#2411
   3 .\"
   4 .Dd September 8, 2008
   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 such as
  94 .Dv SIOCSIFADDR
  95 and
  96 .Dv SIOCSIFNETMASK ,
  97 and thus can be used with
  98 .Xr ifconfig 8
  99 like any other Ethernet interface.
 100 When the system chooses to transmit
 101 an Ethernet frame on the network interface, the frame can be read from
 102 the control device
 103 (it appears as
 104 .Dq input
 105 there);
 106 writing an Ethernet frame to the control device generates an input frame on
 107 the network interface, as if the
 108 (non-existent)
 109 hardware had just received it.
 110 .Pp
 111 The Ethernet tunnel device, normally
 112 .Pa /dev/tap Ns Sy N ,
 113 is exclusive-open
 114 (it cannot be opened if it is already open)
 115 and is restricted to the super-user, unless the
 116 .Xr sysctl 8
 117 variable
 118 .Va net.link.tap.user_open
 119 is non-zero.
 120 If the
 121 .Xr sysctl 8
 122 variable
 123 .Va net.link.tap.up_on_open
 124 is non-zero, the tunnel device will be marked
 125 .Dq up
 126 when the control device is opened.
 127 A
 128 .Fn read
 129 call will return an error
 130 .Pq Er EHOSTDOWN
 131 if the interface is not
 132 .Dq ready .
 133 Once the interface is ready,
 134 .Fn read
 135 will return an Ethernet frame if one is available; if not, it will
 136 either block until one is or return
 137 .Er EWOULDBLOCK ,
 138 depending on whether non-blocking I/O has been enabled.
 139 If the frame
 140 is longer than is allowed for in the buffer passed to
 141 .Fn read ,
 142 the extra data will be silently dropped.
 143 .Pp
 144 A
 145 .Xr write 2
 146 call passes an Ethernet frame in to be
 147 .Dq received
 148 on the pseudo-interface.
 149 Each
 150 .Fn write
 151 call supplies exactly one frame; the frame length is taken from the
 152 amount of data provided to
 153 .Fn write .
 154 Writes will not block; if the frame cannot be accepted
 155 for a transient reason
 156 (e.g., no buffer space available),
 157 it is silently dropped; if the reason is not transient
 158 (e.g., frame too large),
 159 an error is returned.
 160 The following
 161 .Xr ioctl 2
 162 calls are supported
 163 (defined in
 164 .In net/if_tap.h ) :
 165 .Bl -tag -width VMIO_SIOCSETMACADDR
 166 .It Dv TAPSIFINFO
 167 Set network interface information (line speed, MTU and type).
 168 The argument should be a pointer to a
 169 .Va struct tapinfo .
 170 .It Dv TAPGIFINFO
 171 Retrieve network interface information (line speed, MTU and type).
 172 The argument should be a pointer to a
 173 .Va struct tapinfo .
 174 .It Dv TAPSDEBUG
 175 The argument should be a pointer to an
 176 .Va int ;
 177 this sets the internal debugging variable to that value.
 178 What, if
 179 anything, this variable controls is not documented here; see the source
 180 code.
 181 .It Dv TAPGDEBUG
 182 The argument should be a pointer to an
 183 .Va int ;
 184 this stores the internal debugging variable's value into it.
 185 .It Dv TAPGIFNAME
 186 Retrieve network interface name.
 187 The argument should be a pointer to a
 188 .Va struct ifreq .
 189 The interface name will be returned in the
 190 .Va ifr_name
 191 field.
 192 .It Dv FIONBIO
 193 Turn non-blocking I/O for reads off or on, according as the argument
 194 .Va int Ns 's
 195 value is or is not zero
 196 (Writes are always nonblocking).
 197 .It Dv FIOASYNC
 198 Turn asynchronous I/O for reads
 199 (i.e., generation of
 200 .Dv SIGIO
 201 when data is available to be read)
 202 off or on, according as the argument
 203 .Va int Ns 's
 204 value is or is not zero.
 205 .It Dv FIONREAD
 206 If any frames are queued to be read, store the size of the first one into the argument
 207 .Va int ;
 208 otherwise, store zero.
 209 .It Dv TIOCSPGRP
 210 Set the process group to receive
 211 .Dv SIGIO
 212 signals, when asynchronous I/O is enabled, to the argument
 213 .Va int
 214 value.
 215 .It Dv TIOCGPGRP
 216 Retrieve the process group value for
 217 .Dv SIGIO
 218 signals into the argument
 219 .Va int
 220 value.
 221 .It Dv SIOCGIFADDR
 222 Retrieve the Media Access Control
 223 .Pq Dv MAC
 224 address of the
 225 .Dq remote
 226 side.
 227 This command is used by the VMware port and expected to be executed on
 228 descriptor, associated with control device
 229 (usually
 230 .Pa /dev/vmnet Ns Sy N
 231 or
 232 .Pa /dev/tap Ns Sy N ) .
 233 The
 234 .Va buffer ,
 235 which is passed as the argument, is expected to have enough space to store
 236 the
 237 .Dv MAC
 238 address.
 239 At the open time both
 240 .Dq local
 241 and
 242 .Dq remote
 243 .Dv MAC
 244 addresses are the same, so this command could be used to retrieve the
 245 .Dq local
 246 .Dv MAC
 247 address.
 248 .It Dv SIOCSIFADDR
 249 Set the Media Access Control
 250 .Pq Dv MAC
 251 address of the
 252 .Dq remote
 253 side.
 254 This command is used by VMware port and expected to be executed on
 255 a descriptor, associated with control device
 256 (usually
 257 .Pa /dev/vmnet Ns Sy N ) .
 258 .El
 259 .Pp
 260 The control device also supports
 261 .Xr select 2
 262 for read; selecting for write is pointless, and always succeeds, since
 263 writes are always non-blocking.
 264 .Pp
 265 On the last close of the data device, the interface is
 266 brought down
 267 (as if with
 268 .Dq ifconfig tap Ns Sy N No down )
 269 unless the device is a
 270 .Em VMnet
 271 device.
 272 All queued frames are thrown away.
 273 If the interface is up when the data
 274 device is not open, output frames are thrown away rather than
 275 letting them pile up.
 276 .Pp
 277 The
 278 .Nm
 279 device can also be used with the VMware port as a replacement
 280 for the old
 281 .Em VMnet
 282 device driver.
 283 The driver uses the minor number
 284 to select between
 285 .Nm
 286 and
 287 .Nm vmnet
 288 devices.
 289 .Em VMnet
 290 minor numbers begin at
 291 .Va 0x800000
 292 +
 293 .Va N ;
 294 where
 295 .Va N
 296 is a
 297 .Em VMnet
 298 unit number.
 299 In this case the control device is expected to be
 300 .Pa /dev/vmnet Ns Sy N ,
 301 and the network interface will be
 302 .Sy vmnet Ns Ar N .
 303 Additionally,
 304 .Em VMnet
 305 devices do not
 306 .Xr ifconfig 8
 307 themselves down when the
 308 control device is closed.
 309 Everything else is the same.
 310 .Pp
 311 In addition to the above mentioned
 312 .Xr ioctl 2
 313 calls, there is an additional one for the VMware port.
 314 .Bl -tag -width VMIO_SIOCSETMACADDR
 315 .It Dv VMIO_SIOCSIFFLAGS
 316 VMware
 317 .Dv SIOCSIFFLAGS .
 318 .El
 319 .Sh SEE ALSO
 320 .Xr inet 4 ,
 321 .Xr intro 4