share/man/man4/tap.4

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