share/man/man4/tap.4

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