diff options
Diffstat (limited to 'static/freebsd/man4/tap.4 3.html')
| -rw-r--r-- | static/freebsd/man4/tap.4 3.html | 201 |
1 files changed, 201 insertions, 0 deletions
diff --git a/static/freebsd/man4/tap.4 3.html b/static/freebsd/man4/tap.4 3.html new file mode 100644 index 00000000..a3a4b9f2 --- /dev/null +++ b/static/freebsd/man4/tap.4 3.html @@ -0,0 +1,201 @@ +<table class="head"> + <tr> + <td class="head-ltitle">TAP(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">TAP(4)</td> + </tr> +</table> +<div class="manual-text"> +<section class="Sh"> +<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1> +<p class="Pp"><code class="Nm">tap</code>, <code class="Nm">vmnet</code> + — <span class="Nd">Ethernet tunnel software network + interface</span></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1> +<p class="Pp"><code class="Cd">device tuntap</code></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">tap</code> interface is a software loopback + mechanism that can be loosely described as the network interface analog of + the <a class="Xr">pty(4)</a>, that is, <code class="Nm">tap</code> does for + network interfaces what the <a class="Xr">pty(4)</a> driver does for + terminals.</p> +<p class="Pp">The <code class="Nm">tap</code> driver, like the + <a class="Xr">pty(4)</a> driver, provides two interfaces: an interface like + the usual facility it is simulating (an Ethernet network interface in the + case of <code class="Nm">tap</code>, or a terminal for + <a class="Xr">pty(4)</a>), and a character-special device + “control” interface. A client program transfers Ethernet + frames to or from the <code class="Nm">tap</code> “control” + interface. The <a class="Xr">tun(4)</a> interface provides similar + functionality at the network layer: a client will transfer IP (by default) + packets to or from a <a class="Xr">tun(4)</a> “control” + interface.</p> +<p class="Pp">The network interfaces are named + “<code class="Li">tap0</code>”, + “<code class="Li">tap1</code>”, etc., one for each control + device that has been opened. These Ethernet network interfaces persist until + <span class="Pa">if_tuntap.ko</span> module is unloaded, or until removed + with "ifconfig destroy" (see below).</p> +<p class="Pp"><code class="Nm">tap</code> devices are created using interface + cloning. This is done using the “ifconfig tap<b class="Sy">N</b> + <span class="No">create</span>” command. This is the preferred method + of creating <code class="Nm">tap</code> devices. The same method allows + removal of interfaces. For this, use the “ifconfig + tap<b class="Sy">N</b> <span class="No">destroy</span>” command.</p> +<p class="Pp">If the <a class="Xr">sysctl(8)</a> variable + <var class="Va">net.link.tap.devfs_cloning</var> is non-zero, the + <code class="Nm">tap</code> interface permits opens on the special control + device <span class="Pa">/dev/tap</span>. When this device is opened, + <code class="Nm">tap</code> will return a handle for the lowest unused + <code class="Nm">tap</code> device (use <a class="Xr">devname(3)</a> to + determine which).</p> +<p class="Pp"></p> +<div class="Bf Em">Disabling the legacy devfs cloning functionality may break + existing applications which use <code class="Nm">tap</code>, such as VMware + and <a class="Xr">ssh(1)</a>. It therefore defaults to being enabled until + further notice.</div> +<p class="Pp">Control devices (once successfully opened) persist until + <span class="Pa">if_tuntap.ko</span> is unloaded or the interface is + destroyed.</p> +<p class="Pp">Each interface supports the usual Ethernet network interface + <a class="Xr">ioctl(2)</a>s and thus can be used with + <a class="Xr">ifconfig(8)</a> like any other Ethernet interface. When the + system chooses to transmit an Ethernet frame on the network interface, the + frame can be read from the control device (it appears as + “input” there); writing an Ethernet frame to the control + device generates an input frame on the network interface, as if the + (non-existent) hardware had just received it.</p> +<p class="Pp" id="read">The Ethernet tunnel device, normally + <span class="Pa">/dev/tap</span><b class="Sy">N</b>, is exclusive-open (it + cannot be opened if it is already open) and is restricted to the super-user, + unless the <a class="Xr">sysctl(8)</a> variable + <var class="Va">net.link.tap.user_open</var> is non-zero. If the + <a class="Xr">sysctl(8)</a> variable + <var class="Va">net.link.tap.up_on_open</var> is non-zero, the tunnel device + will be marked “up” when the control device is opened. A + <a class="permalink" href="#read"><code class="Fn">read</code></a>() call + will return an error (<code class="Er">EHOSTDOWN</code>) if the interface is + not “ready”. Once the interface is ready, + <code class="Fn">read</code>() will return an Ethernet frame if one is + available; if not, it will either block until one is or return + <code class="Er">EWOULDBLOCK</code>, depending on whether non-blocking I/O + has been enabled. If the frame is longer than is allowed for in the buffer + passed to <code class="Fn">read</code>(), the extra data will be silently + dropped.</p> +<p class="Pp" id="write">A <a class="Xr">write(2)</a> call passes an Ethernet + frame in to be “received” on the pseudo-interface. Each + <a class="permalink" href="#write"><code class="Fn">write</code></a>() call + supplies exactly one frame; the frame length is taken from the amount of + data provided to <code class="Fn">write</code>(). Writes will not block; if + the frame cannot be accepted for a transient reason (e.g., no buffer space + available), it is silently dropped; if the reason is not transient (e.g., + frame too large), an error is returned. The following + <a class="Xr">ioctl(2)</a> calls are supported (defined in + <code class="In"><<a class="In">net/if_tap.h</a>></code>):</p> +<dl class="Bl-tag"> + <dt id="TAPSIFINFO"><a class="permalink" href="#TAPSIFINFO"><code class="Dv">TAPSIFINFO</code></a></dt> + <dd>Set network interface information (line speed and MTU). The type must be + the same as returned by <code class="Dv">TAPGIFINFO</code> or set to + <code class="Dv">IFT_ETHER</code> else the <a class="Xr">ioctl(2)</a> call + will fail. The argument should be a pointer to a <var class="Va">struct + tapinfo</var>.</dd> + <dt id="TAPGIFINFO"><a class="permalink" href="#TAPGIFINFO"><code class="Dv">TAPGIFINFO</code></a></dt> + <dd>Retrieve network interface information (line speed, MTU and type). The + argument should be a pointer to a <var class="Va">struct + tapinfo</var>.</dd> + <dt id="TAPSDEBUG"><a class="permalink" href="#TAPSDEBUG"><code class="Dv">TAPSDEBUG</code></a></dt> + <dd>The argument should be a pointer to an <var class="Va">int</var>; this + sets the internal debugging variable to that value. What, if anything, + this variable controls is not documented here; see the source code.</dd> + <dt id="TAPGDEBUG"><a class="permalink" href="#TAPGDEBUG"><code class="Dv">TAPGDEBUG</code></a></dt> + <dd>The argument should be a pointer to an <var class="Va">int</var>; this + stores the internal debugging variable's value into it.</dd> + <dt id="TAPGIFNAME"><a class="permalink" href="#TAPGIFNAME"><code class="Dv">TAPGIFNAME</code></a></dt> + <dd>Retrieve network interface name. The argument should be a pointer to a + <var class="Va">struct ifreq</var>. The interface name will be returned in + the <var class="Va">ifr_name</var> field.</dd> + <dt id="TAPSTRANSIENT"><a class="permalink" href="#TAPSTRANSIENT"><code class="Dv">TAPSTRANSIENT</code></a></dt> + <dd>The argument should be a pointer to an <var class="Va">int</var>; this + sets the transient flag on the <code class="Nm">tap</code> device. A + transient <code class="Nm">tap</code> will be destroyed upon last + close.</dd> + <dt id="TAPGTRANSIENT"><a class="permalink" href="#TAPGTRANSIENT"><code class="Dv">TAPGTRANSIENT</code></a></dt> + <dd>The argument should be a pointer to an <var class="Va">int</var>; this + stores the current state (enabled or disabled) of the transient flag into + it.</dd> + <dt id="FIONBIO"><a class="permalink" href="#FIONBIO"><code class="Dv">FIONBIO</code></a></dt> + <dd>Turn non-blocking I/O for reads off or on, according as the argument + <var class="Va">int</var>'s value is or is not zero (Writes are always + nonblocking).</dd> + <dt id="FIOASYNC"><a class="permalink" href="#FIOASYNC"><code class="Dv">FIOASYNC</code></a></dt> + <dd>Turn asynchronous I/O for reads (i.e., generation of + <code class="Dv">SIGIO</code> when data is available to be read) off or + on, according as the argument <var class="Va">int</var>'s value is or is + not zero.</dd> + <dt id="FIONREAD"><a class="permalink" href="#FIONREAD"><code class="Dv">FIONREAD</code></a></dt> + <dd>If any frames are queued to be read, store the size of the first one into + the argument <var class="Va">int</var>; otherwise, store zero.</dd> + <dt id="TIOCSPGRP"><a class="permalink" href="#TIOCSPGRP"><code class="Dv">TIOCSPGRP</code></a></dt> + <dd>Set the process group to receive <code class="Dv">SIGIO</code> signals, + when asynchronous I/O is enabled, to the argument + <var class="Va">int</var> value.</dd> + <dt id="TIOCGPGRP"><a class="permalink" href="#TIOCGPGRP"><code class="Dv">TIOCGPGRP</code></a></dt> + <dd>Retrieve the process group value for <code class="Dv">SIGIO</code> signals + into the argument <var class="Va">int</var> value.</dd> + <dt id="SIOCGIFADDR"><a class="permalink" href="#SIOCGIFADDR"><code class="Dv">SIOCGIFADDR</code></a></dt> + <dd>Retrieve the Media Access Control (<code class="Dv">MAC</code>) address of + the “remote” side. This command is used by the VMware port + and expected to be executed on descriptor, associated with control device + (usually <span class="Pa">/dev/vmnet</span><b class="Sy">N</b> or + <span class="Pa">/dev/tap</span><b class="Sy">N</b>). The + <var class="Va">buffer</var>, which is passed as the argument, is expected + to have enough space to store the <code class="Dv">MAC</code> address. At + the open time both “local” and “remote” + <code class="Dv">MAC</code> addresses are the same, so this command could + be used to retrieve the “local” <code class="Dv">MAC</code> + address.</dd> + <dt id="SIOCSIFADDR"><a class="permalink" href="#SIOCSIFADDR"><code class="Dv">SIOCSIFADDR</code></a></dt> + <dd>Set the Media Access Control (<code class="Dv">MAC</code>) address of the + “remote” side. This command is used by VMware port and + expected to be executed on a descriptor, associated with control device + (usually <span class="Pa">/dev/vmnet</span><b class="Sy">N</b>).</dd> +</dl> +<p class="Pp">The control device also supports <a class="Xr">select(2)</a> for + read; selecting for write is pointless, and always succeeds, since writes + are always non-blocking.</p> +<p class="Pp">On the last close of the data device, the interface is brought + down (as if with “ifconfig tap<b class="Sy">N</b> + <span class="No">down</span>”) and has all of its configured + addresses deleted unless the device is a <i class="Em">VMnet</i> device, or + has <code class="Dv">IFF_LINK0</code> flag set. All queued frames are thrown + away. If the interface is up when the data device is not open, output frames + are thrown away rather than letting them pile up.</p> +<p class="Pp">The <code class="Nm">tap</code> device can also be used with the + VMware port as a replacement for the old <i class="Em">VMnet</i> device + driver. <i class="Em">VMnet</i> devices do not <a class="Xr">ifconfig(8)</a> + themselves down when the control device is closed. Everything else is the + same.</p> +<p class="Pp">In addition to the above mentioned <a class="Xr">ioctl(2)</a> + calls, there is an additional one for the VMware port.</p> +<dl class="Bl-tag"> + <dt id="VMIO_SIOCSIFFLAGS"><a class="permalink" href="#VMIO_SIOCSIFFLAGS"><code class="Dv">VMIO_SIOCSIFFLAGS</code></a></dt> + <dd>VMware <code class="Dv">SIOCSIFFLAGS</code>.</dd> +</dl> +</section> +<section class="Sh"> +<h1 class="Sh" id="SEE_ALSO"><a class="permalink" href="#SEE_ALSO">SEE + ALSO</a></h1> +<p class="Pp"><a class="Xr">inet(4)</a>, <a class="Xr">intro(4)</a>, + <a class="Xr">tun(4)</a></p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">January 13, 2020</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |