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.
  89 A
  90 .Fn read
  91 call will return an error
  92 .Pq Er EHOSTDOWN
  93 if the interface is not
  94 .Dq ready .
  95 Once the interface is ready,
  96 .Fn read
  97 will return an Ethernet frame if one is available; if not, it will
  98 either block until one is or return
  99 .Er EWOULDBLOCK ,
 100 depending on whether non-blocking I/O has been enabled.
 101 If the frame
 102 is longer than is allowed for in the buffer passed to
 103 .Fn read ,
 104 the extra data will be silently dropped.
 105 .Pp
 106 A
 107 .Xr write 2
 108 call passes an Ethernet frame in to be
 109 .Dq received
 110 on the pseudo-interface.
 111 Each
 112 .Fn write
 113 call supplies exactly one frame; the frame length is taken from the
 114 amount of data provided to
 115 .Fn write .
 116 Writes will not block; if the frame cannot be accepted
 117 for a transient reason
 118 (e.g., no buffer space available),
 119 it is silently dropped; if the reason is not transient
 120 (e.g., frame too large),
 121 an error is returned.
 122 The following
 123 .Xr ioctl 2
 124 calls are supported
 125 (defined in
 126 .In net/if_tap.h ) :
 127 .Bl -tag -width VMIO_SIOCSETMACADDR
 128 .It Dv TAPSDEBUG
 129 The argument should be a pointer to an
 130 .Va int ;
 131 this sets the internal debugging variable to that value.
 132 What, if
 133 anything, this variable controls is not documented here; see the source
 134 code.
 135 .It Dv TAPGDEBUG
 136 The argument should be a pointer to an
 137 .Va int ;
 138 this stores the internal debugging variable's value into it.
 139 .It Dv FIONBIO
 140 Turn non-blocking I/O for reads off or on, according as the argument
 141 .Va int Ns 's
 142 value is or isn't zero
 143 (Writes are always nonblocking).
 144 .It Dv FIOASYNC
 145 Turn asynchronous I/O for reads
 146 (i.e., generation of
 147 .Dv SIGIO
 148 when data is available to be read)
 149 off or on, according as the argument
 150 .Va int Ns 's
 151 value is or isn't zero.
 152 .It Dv FIONREAD
 153 If any frames are queued to be read, store the size of the first one into the argument
 154 .Va int ;
 155 otherwise, store zero.
 156 .It Dv TIOCSPGRP
 157 Set the process group to receive
 158 .Dv SIGIO
 159 signals, when asynchronous I/O is enabled, to the argument
 160 .Va int
 161 value.
 162 .It Dv TIOCGPGRP
 163 Retrieve the process group value for
 164 .Dv SIGIO
 165 signals into the argument
 166 .Va int
 167 value.
 168 .It Dv SIOCGIFADDR
 169 Retrieve the Media Access Control
 170 .Pq Dv MAC
 171 address of the
 172 .Dq remote
 173 side.
 174 This command is used by the VMware port and expected to be executed on
 175 descriptor, associated with control device
 176 (usually
 177 .Pa /dev/vmnet Ns Sy N
 178 or
 179 .Pa /dev/tap Ns Sy N ) .
 180 The
 181 .Va buffer ,
 182 which is passed as the argument, is expected to have enough space to store
 183 the
 184 .Dv MAC
 185 address.
 186 At the open time both
 187 .Dq local
 188 and
 189 .Dq remote
 190 .Dv MAC
 191 addresses are the same, so this command could be used to retrieve the
 192 .Dq local
 193 .Dv MAC
 194 address.
 195 .It Dv SIOCSIFADDR
 196 Set the Media Access Control
 197 .Pq Dv MAC
 198 address of the
 199 .Dq remote
 200 side.
 201 This command is used by VMware port and expected to be executed on
 202 a descriptor, associated with control device
 203 (usually
 204 .Pa /dev/vmnet Ns Sy N ) .
 205 .El
 206 .Pp
 207 The control device also supports
 208 .Xr select 2
 209 for read; selecting for write is pointless, and always succeeds, since
 210 writes are always non-blocking.
 211 .Pp
 212 On the last close of the data device, the interface is
 213 brought down
 214 (as if with
 215 .Dq ifconfig tap Ns Sy N No down )
 216 unless the device is a
 217 .Em VMnet
 218 device.
 219 All queued frames are thrown away.
 220 If the interface is up when the data
 221 device is not open, output frames are thrown away rather than
 222 letting them pile up.
 223 .Pp
 224 The
 225 .Nm
 226 device can also be used with the VMware port as a replacement
 227 for the old
 228 .Em VMnet
 229 device driver.
 230 The driver uses the minor number
 231 to select between
 232 .Nm
 233 and
 234 .Nm vmnet
 235 devices.
 236 .Em VMnet
 237 minor numbers begin at
 238 .Va 0x800000
 239 +
 240 .Va N ;
 241 where
 242 .Va N
 243 is a
 244 .Em VMnet
 245 unit number.
 246 In this case the control device is expected to be
 247 .Pa /dev/vmnet Ns Sy N ,
 248 and the network interface will be
 249 .Sy vmnet Ns Ar N .
 250 Additionally,
 251 .Em VMnet
 252 devices do not
 253 .Xr ifconfig 8
 254 themselves down when the
 255 control device is closed.
 256 Everything else is the same.
 257 .Pp
 258 In addition to the above mentioned
 259 .Xr ioctl 2
 260 calls, there is an additional one for the VMware port.
 261 .Bl -tag -width VMIO_SIOCSETMACADDR
 262 .It Dv VMIO_SIOCSIFFLAGS
 263 VMware
 264 .Dv SIOCSIFFLAGS .
 265 .El
 266 .Sh SEE ALSO
 267 .Xr inet 4 ,
 268 .Xr intro 4