diff options
Diffstat (limited to 'static/freebsd/man4/tun.4 3.html')
| -rw-r--r-- | static/freebsd/man4/tun.4 3.html | 225 |
1 files changed, 225 insertions, 0 deletions
diff --git a/static/freebsd/man4/tun.4 3.html b/static/freebsd/man4/tun.4 3.html new file mode 100644 index 00000000..3d05a7a4 --- /dev/null +++ b/static/freebsd/man4/tun.4 3.html @@ -0,0 +1,225 @@ +<table class="head"> + <tr> + <td class="head-ltitle">TUN(4)</td> + <td class="head-vol">Device Drivers Manual</td> + <td class="head-rtitle">TUN(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">tun</code> — <span class="Nd">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">To compile this driver into the kernel, place the following line + in your kernel configuration file:</p> +<div class="Bd Pp Bd-indent"><code class="Cd">device tuntap</code></div> +<p class="Pp">Alternatively, to load the driver as a module at boot time, place + the following lines in <a class="Xr">loader.conf(5)</a>:</p> +<div class="Bd Pp Bd-indent Li"> +<pre>if_tuntap_load="YES"</pre> +</div> +</section> +<section class="Sh"> +<h1 class="Sh" id="DESCRIPTION"><a class="permalink" href="#DESCRIPTION">DESCRIPTION</a></h1> +<p class="Pp">The <code class="Nm">tun</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">tun</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">tun</code> driver, like the + <a class="Xr">pty(4)</a> driver, provides two interfaces: an interface like + the usual facility it is simulating (a network interface in the case of + <code class="Nm">tun</code>, or a terminal for <a class="Xr">pty(4)</a>), + and a character-special device “control” interface. A client + program transfers IP (by default) packets to or from the + <code class="Nm">tun</code> “control” interface. The + <a class="Xr">tap(4)</a> interface provides similar functionality at the + Ethernet layer: a client will transfer Ethernet frames to or from a + <a class="Xr">tap(4)</a> “control” interface.</p> +<p class="Pp">The network interfaces are named + “<code class="Li">tun0</code>”, + “<code class="Li">tun1</code>”, etc., one for each control + device that has been opened. These network interfaces persist until the + <span class="Pa">if_tuntap.ko</span> module is unloaded, or until removed + with the <a class="Xr">ifconfig(8)</a> command.</p> +<p class="Pp"><code class="Nm">tun</code> devices are created using interface + cloning. This is done using the “ifconfig tun<b class="Sy">N</b> + <span class="No">create</span>” command. This is the preferred method + of creating <code class="Nm">tun</code> devices. The same method allows + removal of interfaces. For this, use the “ifconfig + tun<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.tun.devfs_cloning</var> is non-zero, the + <code class="Nm">tun</code> interface permits opens on the special control + device <span class="Pa">/dev/tun</span>. When this device is opened, + <code class="Nm">tun</code> will return a handle for the lowest unused + <code class="Nm">tun</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">tun</code>, such as + <a class="Xr">ppp(8)</a> 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 in the same way that + network interfaces persist (see above).</p> +<p class="Pp">Each interface supports the usual network-interface + <a class="Xr">ioctl(2)</a>s, such as <code class="Dv">SIOCAIFADDR</code> and + thus can be used with <a class="Xr">ifconfig(8)</a> like any other + interface. At boot time, they are <code class="Dv">POINTOPOINT</code> + interfaces, but this can be changed; see the description of the control + device, below. When the system chooses to transmit a packet on the network + interface, the packet can be read from the control device (it appears as + “input” there); writing a packet to the control device + generates an input packet on the network interface, as if the (non-existent) + hardware had just received it.</p> +<p class="Pp">The tunnel device + (<span class="Pa">/dev/tun</span><var class="Ar">N</var>) is exclusive-open + (it cannot be opened if it is already open). A <a class="Xr">read(2)</a> + call will return an error (<code class="Er">EHOSTDOWN</code>) if the + interface is not “ready” (which means that the control device + is open and the interface's address has been set).</p> +<p class="Pp">Once the interface is ready, <a class="Xr">read(2)</a> will return + a packet 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 packet is longer than is allowed + for in the buffer passed to <a class="Xr">read(2)</a>, the extra data will + be silently dropped.</p> +<p class="Pp" id="tunoutput">If the <code class="Dv">TUNSLMODE</code> ioctl has + been set, packets read from the control device will be prepended with the + destination address as presented to the network interface output routine, + <a class="permalink" href="#tunoutput"><code class="Fn">tunoutput</code></a>(). + The destination address is in <var class="Vt">struct sockaddr</var> format. + The actual length of the prepended address is in the member + <var class="Va">sa_len</var>. If the <code class="Dv">TUNSIFHEAD</code> + ioctl has been set, packets will be prepended with a four byte address + family in network byte order. <code class="Dv">TUNSLMODE</code> and + <code class="Dv">TUNSIFHEAD</code> are mutually exclusive. In any case, the + packet data follows immediately.</p> +<p class="Pp">A <a class="Xr">write(2)</a> call passes a packet in to be + “received” on the pseudo-interface. If the + <code class="Dv">TUNSIFHEAD</code> ioctl has been set, the address family + must be prepended, otherwise the packet is assumed to be of type + <code class="Dv">AF_INET</code>. Each <a class="Xr">write(2)</a> call + supplies exactly one packet; the packet length is taken from the amount of + data provided to <a class="Xr">write(2)</a> (minus any supplied address + family). Writes will not block; if the packet 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., packet too large), an error is + returned.</p> +<p class="Pp">The following <a class="Xr">ioctl(2)</a> calls are supported + (defined in + <code class="In"><<a class="In">net/if_tun.h</a>></code>):</p> +<dl class="Bl-tag"> + <dt id="TUNSDEBUG"><a class="permalink" href="#TUNSDEBUG"><code class="Dv">TUNSDEBUG</code></a></dt> + <dd>The argument should be a pointer to an <var class="Vt">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="TUNGDEBUG"><a class="permalink" href="#TUNGDEBUG"><code class="Dv">TUNGDEBUG</code></a></dt> + <dd>The argument should be a pointer to an <var class="Vt">int</var>; this + stores the internal debugging variable's value into it.</dd> + <dt id="TUNSIFINFO"><a class="permalink" href="#TUNSIFINFO"><code class="Dv">TUNSIFINFO</code></a></dt> + <dd>The argument should be a pointer to an <var class="Vt">struct + tuninfo</var> and allows setting the MTU and the baudrate of the tunnel + device. The type must be the same as returned by + <code class="Dv">TUNGIFINFO</code> or set to + <code class="Dv">IFT_PPP</code> else the <a class="Xr">ioctl(2)</a> call + will fail. The <var class="Vt">struct tuninfo</var> is declared in + <code class="In"><<a class="In">net/if_tun.h</a>></code>. + <p class="Pp">The use of this ioctl is restricted to the super-user.</p> + </dd> + <dt id="TUNGIFINFO"><a class="permalink" href="#TUNGIFINFO"><code class="Dv">TUNGIFINFO</code></a></dt> + <dd>The argument should be a pointer to an <var class="Vt">struct + tuninfo</var>, where the current MTU, type, and baudrate will be + stored.</dd> + <dt id="TUNSIFMODE"><a class="permalink" href="#TUNSIFMODE"><code class="Dv">TUNSIFMODE</code></a></dt> + <dd>The argument should be a pointer to an <var class="Vt">int</var>; its + value must be either <code class="Dv">IFF_POINTOPOINT</code> or + <code class="Dv">IFF_BROADCAST</code> and should have + <code class="Dv">IFF_MULTICAST</code> OR'd into the value if multicast + support is required. The type of the corresponding + “<code class="Li">tun</code><var class="Ar">N</var>” + interface is set to the supplied type. If the value is outside the above + range, an <code class="Er">EINVAL</code> error is returned. The interface + must be down at the time; if it is up, an <code class="Er">EBUSY</code> + error is returned.</dd> + <dt id="TUNSLMODE"><a class="permalink" href="#TUNSLMODE"><code class="Dv">TUNSLMODE</code></a></dt> + <dd>The argument should be a pointer to an <var class="Vt">int</var>; a + non-zero value turns off “multi-af” mode and turns on + “link-layer” mode, causing packets read from the tunnel + device to be prepended with the network destination address (see + above).</dd> + <dt id="TUNSIFPID"><a class="permalink" href="#TUNSIFPID"><code class="Dv">TUNSIFPID</code></a></dt> + <dd>Will set the pid owning the tunnel device to the current process's + pid.</dd> + <dt id="TUNSIFHEAD"><a class="permalink" href="#TUNSIFHEAD"><code class="Dv">TUNSIFHEAD</code></a></dt> + <dd>The argument should be a pointer to an <var class="Vt">int</var>; a + non-zero value turns off “link-layer” mode, and enables + “multi-af” mode, where every packet is preceded with a four + byte address family.</dd> + <dt id="TUNGIFHEAD"><a class="permalink" href="#TUNGIFHEAD"><code class="Dv">TUNGIFHEAD</code></a></dt> + <dd>The argument should be a pointer to an <var class="Vt">int</var>; the + ioctl sets the value to one if the device is in “multi-af” + mode, and zero otherwise.</dd> + <dt id="TUNSTRANSIENT"><a class="permalink" href="#TUNSTRANSIENT"><code class="Dv">TUNSTRANSIENT</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">tun</code> device. A + transient <code class="Nm">tun</code> will be destroyed upon last + close.</dd> + <dt id="TUNGTRANSIENT"><a class="permalink" href="#TUNGTRANSIENT"><code class="Dv">TUNGTRANSIENT</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="Vt">int</var>'s value is or is not zero. (Writes are always + non-blocking.)</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="Vt">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 packets are queued to be read, store the size of the first one into + the argument <var class="Vt">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="Vt">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="Vt">int</var> value.</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, by default, the interface is + brought down (as if with <code class="Nm">ifconfig</code> + <var class="Ar">tunN</var> <code class="Cm">down</code>). All queued packets + are thrown away. If the interface is up when the data device is not open + output packets are always thrown away rather than letting them pile up.</p> +</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">ioctl(2)</a>, <a class="Xr">read(2)</a>, + <a class="Xr">select(2)</a>, <a class="Xr">write(2)</a>, + <a class="Xr">devname(3)</a>, <a class="Xr">inet(4)</a>, + <a class="Xr">intro(4)</a>, <a class="Xr">pty(4)</a>, + <a class="Xr">tap(4)</a>, <a class="Xr">ifconfig(8)</a></p> +</section> +<section class="Sh"> +<h1 class="Sh" id="AUTHORS"><a class="permalink" href="#AUTHORS">AUTHORS</a></h1> +<p class="Pp">This manual page was originally obtained from + <span class="Ux">NetBSD</span>.</p> +</section> +</div> +<table class="foot"> + <tr> + <td class="foot-date">March 17, 2020</td> + <td class="foot-os">FreeBSD 15.0</td> + </tr> +</table> |