share/man/man4/tap.4

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