share/man/man4/tap.4

   1 .\" $FreeBSD$
   2 .\" Based on PR#2411
   3 .\"
   4 .Dd July 9, 2000
   5 .Os
   6 .Dt TAP 4
   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 (if
  45 .Nm
  46 is built into your kernel, the network interfaces cannot be removed).
  47 .Pp
  48 The
  49 .Nm
  50 interface
  51 permits opens on the special control device
  52 .Pa /dev/tap .
  53 When this device is opened,
  54 .Nm
  55 will return a handle for the lowest unused
  56 .Nm
  57 device (use
  58 .Xr devname 3
  59 to determine which).
  60 Control devices (once successfully opened) persist until
  61 .Pa if_tap.ko
  62 is unloaded in the same way that network interfaces persist (see above).
  63 .Pp
  64 Each interface supports the usual Ethernet network interface
  65 .Xr ioctl 2 Ns s ,
  66 such as
  67 .Dv SIOCSIFADDR
  68 and
  69 .Dv SIOCSIFNETMASK ,
  70 and thus can be used with
  71 .Xr ifconfig 8
  72 like any other Ethernet interface.
  73 When the system chooses to transmit
  74 an Ethernet frame on the network interface, the frame can be read from
  75 the control device
  76 (it appears as
  77 .Dq input
  78 there);
  79 writing an Ethernet frame to the control device generates an input frame on
  80 the network interface, as if the
  81 (non-existent)
  82 hardware had just received it.
  83 .Pp
  84 The Ethernet tunnel device, normally
  85 .Pa /dev/tap Ns Sy N ,
  86 is exclusive-open
  87 (it cannot be opened if it is already open)
  88 and is restricted to the super-user, unless the
  89 .Xr sysctl 8
  90 variable
  91 .Va net.link.tap.user_open
  92 is non-zero.
  93 A
  94 .Fn read
  95 call will return an error
  96 .Pq Er EHOSTDOWN
  97 if the interface is not
  98 .Dq ready .
  99 Once the interface is ready,
 100 .Fn read
 101 will return an Ethernet frame if one is available; if not, it will
 102 either block until one is or return
 103 .Er EWOULDBLOCK ,
 104 depending on whether non-blocking I/O has been enabled.
 105 If the frame
 106 is longer than is allowed for in the buffer passed to
 107 .Fn read ,
 108 the extra data will be silently dropped.
 109 .Pp
 110 A
 111 .Xr write 2
 112 call passes an Ethernet frame in to be
 113 .Dq received
 114 on the pseudo-interface.
 115 Each
 116 .Fn write
 117 call supplies exactly one frame; the frame length is taken from the
 118 amount of data provided to
 119 .Fn write .
 120 Writes will not block; if the frame cannot be accepted
 121 for a transient reason
 122 (e.g., no buffer space available),
 123 it is silently dropped; if the reason is not transient
 124 (e.g., frame too large),
 125 an error is returned.
 126 The following
 127 .Xr ioctl 2
 128 calls are supported
 129 (defined in
 130 .In net/if_tap.h ) :
 131 .Bl -tag -width VMIO_SIOCSETMACADDR
 132 .It Dv TAPSDEBUG
 133 The argument should be a pointer to an
 134 .Va int ;
 135 this sets the internal debugging variable to that value.
 136 What, if
 137 anything, this variable controls is not documented here; see the source
 138 code.
 139 .It Dv TAPGDEBUG
 140 The argument should be a pointer to an
 141 .Va int ;
 142 this stores the internal debugging variable's value into it.
 143 .It Dv FIONBIO
 144 Turn non-blocking I/O for reads off or on, according as the argument
 145 .Va int Ns 's
 146 value is or is not zero
 147 (Writes are always nonblocking).
 148 .It Dv FIOASYNC
 149 Turn asynchronous I/O for reads
 150 (i.e., generation of
 151 .Dv SIGIO
 152 when data is available to be read)
 153 off or on, according as the argument
 154 .Va int Ns 's
 155 value is or is not zero.
 156 .It Dv FIONREAD
 157 If any frames are queued to be read, store the size of the first one into the argument
 158 .Va int ;
 159 otherwise, store zero.
 160 .It Dv TIOCSPGRP
 161 Set the process group to receive
 162 .Dv SIGIO
 163 signals, when asynchronous I/O is enabled, to the argument
 164 .Va int
 165 value.
 166 .It Dv TIOCGPGRP
 167 Retrieve the process group value for
 168 .Dv SIGIO
 169 signals into the argument
 170 .Va int
 171 value.
 172 .It Dv SIOCGIFADDR
 173 Retrieve the Media Access Control
 174 .Pq Dv MAC
 175 address of the
 176 .Dq remote
 177 side.
 178 This command is used by the VMware port and expected to be executed on
 179 descriptor, associated with control device
 180 (usually
 181 .Pa /dev/vmnet Ns Sy N
 182 or
 183 .Pa /dev/tap Ns Sy N ) .
 184 The
 185 .Va buffer ,
 186 which is passed as the argument, is expected to have enough space to store
 187 the
 188 .Dv MAC
 189 address.
 190 At the open time both
 191 .Dq local
 192 and
 193 .Dq remote
 194 .Dv MAC
 195 addresses are the same, so this command could be used to retrieve the
 196 .Dq local
 197 .Dv MAC
 198 address.
 199 .It Dv SIOCSIFADDR
 200 Set the Media Access Control
 201 .Pq Dv MAC
 202 address of the
 203 .Dq remote
 204 side.
 205 This command is used by VMware port and expected to be executed on
 206 a descriptor, associated with control device
 207 (usually
 208 .Pa /dev/vmnet Ns Sy N ) .
 209 .El
 210 .Pp
 211 The control device also supports
 212 .Xr select 2
 213 for read; selecting for write is pointless, and always succeeds, since
 214 writes are always non-blocking.
 215 .Pp
 216 On the last close of the data device, the interface is
 217 brought down
 218 (as if with
 219 .Dq ifconfig tap Ns Sy N No down )
 220 unless the device is a
 221 .Em VMnet
 222 device.
 223 All queued frames are thrown away.
 224 If the interface is up when the data
 225 device is not open, output frames are thrown away rather than
 226 letting them pile up.
 227 .Pp
 228 The
 229 .Nm
 230 device can also be used with the VMware port as a replacement
 231 for the old
 232 .Em VMnet
 233 device driver.
 234 The driver uses the minor number
 235 to select between
 236 .Nm
 237 and
 238 .Nm vmnet
 239 devices.
 240 .Em VMnet
 241 minor numbers begin at
 242 .Va 0x800000
 243 +
 244 .Va N ;
 245 where
 246 .Va N
 247 is a
 248 .Em VMnet
 249 unit number.
 250 In this case the control device is expected to be
 251 .Pa /dev/vmnet Ns Sy N ,
 252 and the network interface will be
 253 .Sy vmnet Ns Ar N .
 254 Additionally,
 255 .Em VMnet
 256 devices do not
 257 .Xr ifconfig 8
 258 themselves down when the
 259 control device is closed.
 260 Everything else is the same.
 261 .Pp
 262 In addition to the above mentioned
 263 .Xr ioctl 2
 264 calls, there is an additional one for the VMware port.
 265 .Bl -tag -width VMIO_SIOCSETMACADDR
 266 .It Dv VMIO_SIOCSIFFLAGS
 267 VMware
 268 .Dv SIOCSIFFLAGS .
 269 .El
 270 .Sh SEE ALSO
 271 .Xr inet 4 ,
 272 .Xr intro 4