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