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