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 17, 2018
   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 .Xr pty 4
  22 driver does for terminals.
  23 .Pp
  24 The
  25 .Nm
  26 driver, like the
  27 .Xr pty 4
  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 .Xr pty 4 ) ,
  34 and a character-special device
  35 .Dq control
  36 interface.
  37 A client program transfers Ethernet frames to or from the
  38 .Nm
  39 .Dq control
  40 interface.
  41 The
  42 .Xr tun 4
  43 interface provides similar functionality at the network layer:
  44 a client will transfer IP (by default) packets to or from a
  45 .Xr tun 4
  46 .Dq control
  47 interface.
  48 .Pp
  49 The network interfaces are named
  50 .Dq Li tap0 ,
  51 .Dq Li tap1 ,
  52 etc., one for each control device that has been opened.
  53 These Ethernet network interfaces persist until the
  54 .Pa if_tap.ko
  55 module is unloaded, or until removed with
  56 .Dq ifconfig destroy
  57 (see below).
  58 .Pp
  59 The
  60 .Nm
  61 devices are created using interface cloning.
  62 This is done using the
  63 .Dq ifconfig tap Ns Sy N No create
  64 command.
  65 This is the preferred method of creating
  66 .Nm
  67 devices.
  68 The same method allows removal of interfaces by using the
  69 .Dq ifconfig tap Ns Sy N No destroy
  70 command.
  71 .Pp
  72 The
  73 .Nm
  74 interface permits opens on the special control device
  75 .Pa /dev/tap .
  76 When this special device is opened,
  77 .Nm
  78 will return a handle for the lowest unused
  79 .Nm
  80 device (use
  81 .Xr devname 3
  82 to determine which).
  83 .Pp
  84 Control devices (once successfully opened) persist until the
  85 .Pa if_tap.ko
  86 module is unloaded or the interface is destroyed.
  87 .Pp
  88 Each interface supports the usual Ethernet network interface
  89 .Xr ioctl 2 Ns s
  90 and thus can be used with
  91 .Xr ifconfig 8
  92 like any other Ethernet interface.
  93 When the system chooses to transmit
  94 an Ethernet frame on the network interface, the frame can be read from
  95 the control device
  96 (it appears as
  97 .Dq input
  98 there);
  99 writing an Ethernet frame to the control device generates an input frame on
 100 the network interface, as if the
 101 (non-existent)
 102 hardware had just received it.
 103 .Pp
 104 The Ethernet tunnel device, normally
 105 .Pa /dev/tap Ns Sy N ,
 106 is exclusive-open
 107 (it cannot be opened if it is already open)
 108 and is restricted to the super-user, unless the
 109 .Xr sysctl 8
 110 variable
 111 .Va net.link.tap.user_open
 112 is non-zero.
 113 If the
 114 .Xr sysctl 8
 115 variable
 116 .Va net.link.tap.up_on_open
 117 is non-zero, the tunnel device will be marked
 118 .Dq up
 119 when the control device is opened.
 120 A
 121 .Fn read
 122 call will return an error
 123 .Pq Er EHOSTDOWN
 124 if the interface is not
 125 .Dq ready .
 126 Once the interface is ready,
 127 .Fn read
 128 will return an Ethernet frame if one is available; if not, it will
 129 either block until one is or return
 130 .Er EWOULDBLOCK ,
 131 depending on whether non-blocking I/O has been enabled.
 132 If the frame
 133 is longer than is allowed for in the buffer passed to
 134 .Fn read ,
 135 the extra data will be silently dropped.
 136 .Pp
 137 A
 138 .Xr write 2
 139 call passes an Ethernet frame in to be
 140 .Dq received
 141 on the pseudo-interface.
 142 Each
 143 .Fn write
 144 call supplies exactly one frame; the frame length is taken from the
 145 amount of data provided to
 146 .Fn write .
 147 Writes will not block; if the frame cannot be accepted
 148 for a transient reason
 149 (e.g., no buffer space available),
 150 it is silently dropped; if the reason is not transient
 151 (e.g., frame too large),
 152 an error is returned.
 153 The following
 154 .Xr ioctl 2
 155 calls are supported
 156 (defined in
 157 .In net/tap/if_tap.h ) :
 158 .Bl -tag -width ".Dv TAPSIFINFO"
 159 .It Dv TAPSDEBUG
 160 The argument should be a pointer to an
 161 .Va int ;
 162 this sets the internal debugging variable to that value.
 163 What, if anything, this variable controls is not documented here,
 164 see the source code.
 165 .It Dv TAPGDEBUG
 166 The argument should be a pointer to an
 167 .Va int ;
 168 this stores the internal debugging variable's value into it.
 169 .It Dv TAPSIFINFO
 170 Set network interface information (line speed and MTU).
 171 The type must be the same as returned by
 172 .Dv TAPGIFINFO
 173 or set to
 174 .Dv IFT_ETHER ,
 175 otherwise the
 176 .Xr ioctl 2
 177 call will fail.
 178 The argument should be a pointer to a
 179 .Va struct tapinfo .
 180 .It Dv TAPGIFINFO
 181 Retrieve network interface information (line speed, MTU and type).
 182 The argument should be a pointer to a
 183 .Va struct tapinfo .
 184 .It Dv TAPGIFNAME
 185 Retrieve network interface name.
 186 The argument should be a pointer to a
 187 .Va struct ifreq .
 188 The interface name will be returned in the
 189 .Va ifr_name
 190 field.
 191 .It Dv FIOASYNC
 192 Turn asynchronous I/O for reads
 193 (i.e., generation of
 194 .Dv SIGIO
 195 when data is available to be read)
 196 off or on, according as the argument
 197 .Va int Ns 's
 198 value is or is not zero.
 199 .It Dv FIONREAD
 200 If any frames are queued to be read, store the size of the first one into the argument
 201 .Va int ;
 202 otherwise, store zero.
 203 .It Dv TIOCSPGRP
 204 Set the process group to receive
 205 .Dv SIGIO
 206 signals, when asynchronous I/O is enabled, to the argument
 207 .Va int
 208 value.
 209 .It Dv TIOCGPGRP
 210 Retrieve the process group value for
 211 .Dv SIGIO
 212 signals into the argument
 213 .Va int
 214 value.
 215 .El
 216 .Pp
 217 The control device also supports
 218 .Xr select 2
 219 for read; selecting for write is pointless, and always succeeds, since
 220 writes are always non-blocking.
 221 .Pp
 222 On the last close of the data device, the interface is
 223 brought down
 224 (as if with
 225 .Dq ifconfig tap Ns Sy N No down ) .
 226 All queued frames are thrown away.
 227 If the interface is up when the data
 228 device is not open, output frames are thrown away rather than
 229 letting them pile up.
 230 .Sh SEE ALSO
 231 .Xr inet 4 ,
 232 .Xr tun 4 ,
 233 .Xr ifconfig 8