diff options
Diffstat (limited to 'static/netbsd/man4/tun.4')
| -rw-r--r-- | static/netbsd/man4/tun.4 | 299 |
1 files changed, 299 insertions, 0 deletions
diff --git a/static/netbsd/man4/tun.4 b/static/netbsd/man4/tun.4 new file mode 100644 index 00000000..601148f5 --- /dev/null +++ b/static/netbsd/man4/tun.4 @@ -0,0 +1,299 @@ +.\" $NetBSD: tun.4,v 1.26 2022/05/01 00:25:42 gutteridge Exp $ +.\" +.\" Copyright (c) 1996-2006 The NetBSD Foundation, Inc. +.\" All rights reserved. +.\" +.\" This code is derived from software contributed to The NetBSD Foundation +.\" by der Mouse. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS +.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED +.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR +.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS +.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR +.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF +.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS +.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN +.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) +.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE +.\" POSSIBILITY OF SUCH DAMAGE. +.\" +.Dd September 27, 2020 +.Dt TUN 4 +.Os +.Sh NAME +.Nm tun +.Nd tunnel software network interface +.Sh SYNOPSIS +.Cd pseudo-device tun +.Sh DESCRIPTION +The +.Nm tun +interface is a software loopback mechanism that can be loosely +described as the network interface analog of the +.Xr pty 4 , +that is, +.Nm tun +does for network interfaces what the +.Nm pty +driver does for terminals. +.Pp +The +.Nm tun +driver, like the +.Nm pty +driver, provides two interfaces: an interface like the usual facility +it is simulating +.Po +a network interface in the case of +.Nm tun , +or a terminal for +.Nm pty +.Pc , +and a character-special device +.Dq control +interface. +.Pp +To use a +.Nm tun +device, the administrator must first create the interface. +This can be done by using the +.Xr ifconfig 8 +.Cm create +command, or via the +.Dv SIOCIFCREATE +ioctl. +An +.Fn open +call on +.Pa /dev/tun Ns Sy N +will also create a network interface with the same unit number of +that device if it doesn't exist yet. +.Pp +The network interfaces should be named +.Sy tun Ns Ar 0 , +.Sy tun Ns Ar 1 , +etc. +Each interface supports the usual network-interface +.Xr ioctl 2 Ns s , +such as +.Dv SIOCSIFADDR +and +.Dv SIOCSIFNETMASK , +and thus can be used with +.Xr ifconfig 8 +like any other interface. +At boot time, they are +.Dv POINTOPOINT +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 +.Po +it appears there as +.Dq output +.Pc ; +writing a packet to the control device generates an input +packet on the network interface, as if the +.Pq non-existent +hardware had just received it. +.Pp +The tunnel device, normally +.Pa /dev/tun Ns Sy N , +is exclusive-open +.Po +it cannot be opened if it is already open +.Pc +and is restricted to the super-user +.Pq regardless of file system permissions . +A +.Fn read +call will return an error +.Pq Er EHOSTDOWN +if the interface is not +.Dq ready +(which means that the interface +address has not been set). +Once the interface is ready, +.Fn read +will return a packet if one is available; if not, it will either block +until one is or return +.Er EAGAIN , +depending on whether non-blocking I/O has been enabled. +If the packet +is longer than is allowed for in the buffer passed to +.Fn read , +the extra data will be silently dropped. +.Pp +Packets can be optionally prepended with the destination address as presented +to the network interface output routine +.Pq Sq Li tunoutput . +The destination address is in +.Sq Li struct sockaddr +format. +The actual length of the prepended address is in the member +.Sq Li sa_len . +The packet data follows immediately. +A +.Xr write 2 +call passes a packet in to be +.Dq received +on the pseudo-interface. +Each +.Fn write +call supplies exactly one packet; the packet length is taken from the +amount of data provided to +.Fn write . +Writes will not block; if the packet cannot be accepted for a +transient reason +.Pq e.g., no buffer space available , +it is silently dropped; if the reason is not transient +.Pq e.g., packet too large , +an error is returned. +If +.Dq link-layer mode +is on +.Pq see Dv TUNSLMODE No below , +the actual packet data must be preceded by a +.Sq Li struct sockaddr . +The driver currently only inspects the +.Sq Li sa_family +field. +The following +.Xr ioctl 2 +calls are supported +.Pq defined in Aq Pa net/if_tun.h : +.Bl -tag -width TUNSIFMODE +.It Dv TUNSDEBUG +The argument should be a pointer to an +.Va int ; +this sets the internal debugging variable to that value. +What, if anything, this variable controls is not documented here; +see the source code. +.It Dv TUNGDEBUG +The argument should be a pointer to an +.Va int ; +this stores the internal debugging variable's value into it. +.It Dv TUNSIFMODE +The argument should be a pointer to an +.Va int ; +its value must be either +.Dv IFF_POINTOPOINT +or +.Dv IFF_BROADCAST +(optionally +.Dv IFF_MULTICAST +may be or'ed into the value). +The type of the corresponding +.Em tun Ns Sy n +interface is set to the supplied type. +If the value is anything else, an +.Er EINVAL +error occurs. +The interface must be down at the time; if it is up, an +.Er EBUSY +error occurs. +.It Dv TUNSLMODE +The argument should be a pointer to an +.Va int ; +a non-zero value turns off +.Dq multi-af +mode and turns on +.Dq link-layer +mode, causing packets read from the tunnel device to be prepended with +network destination address. +.It Dv TUNGIFHEAD +The argument should be a pointer to an +.Va int ; +the ioctl sets the value to one if the device is in +.Dq multi-af +mode, and zero otherwise. +.It Dv TUNSIFHEAD +The argument should be a pointer to an +.Va int ; +a non-zero value turns off +.Dq link-layer +mode, and enables +.Dq multi-af +mode, where every packet is preceded with a four byte address family. +.It Dv FIONBIO +Turn non-blocking I/O for reads off or on, according as the argument +.Va int Ns 's +value is or isn't zero. +.Pq Writes are always non-blocking. +.It Dv FIOASYNC +Turn asynchronous I/O for reads +.Po +i.e., generation of +.Dv SIGIO +when data is available to be read +.Pc off or on, according as the argument +.Va int Ns 's +value is or isn't zero. +.It Dv FIONREAD +If any packets are queued to be read, store the size of the first one +into the argument +.Va int ; +otherwise, store zero. +.It Dv TIOCSPGRP +Set the process group to receive +.Dv SIGIO +signals, when asynchronous I/O is enabled, to the argument +.Va int +value. +.It Dv TIOCGPGRP +Retrieve the process group value for +.Dv SIGIO +signals into the argument +.Va int +value. +.El +.Pp +The control device also supports +.Xr select 2 +for read; selecting for write is pointless, and always succeeds, since +writes are always non-blocking. +.Pp +On the last close of the data device, by default, the interface is +brought down +.Po as if with +.Dq ifconfig tun Ns Sy n No down +.Pc . +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. +.Ss LINK STATE +When an application has opened the +.Nm +character device the link is considered up, otherwise down. +As such, it is best to open the character device once connectivity has +been established so that Duplicate Address Detection, if applicable, +can be performed. +If connectivity is lost, the character device should be closed. +.Sh SEE ALSO +.Xr ioctl 2 , +.Xr read 2 , +.Xr select 2 , +.Xr write 2 , +.Xr inet 4 , +.Xr intro 4 , +.Xr ifconfig 8 +.Sh HISTORY +.An -split +IPv6 support comes mostly from +.Fx +and was added in +.Nx 4.0 +by +.An Rui Paulo +.Aq rpaulo@NetBSD.org . |