1 files changed, 313 insertions, 0 deletions
diff --git a/share/man/man4/tun.4 b/share/man/man4/tun.4
new file mode 100644
index 000000000000..b5139a7cdf0d
--- /dev/null
+++ b/share/man/man4/tun.4
@@ -0,0 +1,313 @@
+.\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $
+.\" $FreeBSD$
+.\" Based on PR#2411
+.\"
+.Dd February 4, 2007
+.Dt TUN 4
+.Os
+.Sh NAME
+.Nm tun
+.Nd tunnel software network interface
+.Sh SYNOPSIS
+.Cd device tun
+.Sh DESCRIPTION
+The
+.Nm
+interface is a software loopback mechanism that can be loosely
+described as the network interface analog of the
+.Xr pty 4 ,
+that is,
+.Nm
+does for network interfaces what the
+.Xr pty 4
+driver does for terminals.
+.Pp
+The
+.Nm
+driver, like the
+.Xr pty 4
+driver, provides two interfaces: an interface like the usual facility
+it is simulating
+(a network interface in the case of
+.Nm ,
+or a terminal for
+.Xr pty 4 ) ,
+and a character-special device
+.Dq control
+interface.
+.Pp
+The network interfaces are named
+.Dq Li tun0 ,
+.Dq Li tun1 ,
+etc., one for each control device that has been opened.
+These network interfaces persist until the
+.Pa if_tun.ko
+module is unloaded, or until removed with the
+.Xr ifconfig 8
+command.
+.Pp
+.Nm
+devices are created using interface cloning.
+This is done using the
+.Dq ifconfig tun Ns Sy N No create
+command.
+This is the preferred method of creating
+.Nm
+devices.
+The same method allows removal of interfaces.
+For this, use the
+.Dq ifconfig tun Ns Sy N No destroy
+command.
+.Pp
+If the
+.Xr sysctl 8
+variable
+.Va net.link.tun.devfs_cloning
+is non-zero, the
+.Nm
+interface
+permits opens on the special control device
+.Pa /dev/tun .
+When this device is opened,
+.Nm
+will return a handle for the lowest unused
+.Nm
+device (use
+.Xr devname 3
+to determine which).
+.Pp
+.Bf Em
+Disabling the legacy devfs cloning functionality may break existing
+applications which use
+.Nm ,
+such as
+.Xr ppp 8
+and
+.Xr ssh 1 .
+It therefore defaults to being enabled until further notice.
+.Ef
+.Pp
+Control devices (once successfully opened) persist until
+.Pa if_tun.ko
+is unloaded in the same way that network interfaces persist (see above).
+.Pp
+Each interface supports the usual network-interface
+.Xr ioctl 2 Ns s ,
+such as
+.Dv SIOCAIFADDR
+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
+(it appears as
+.Dq 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.
+.Pp
+The tunnel device
+.Pq Pa /dev/tun Ns Ar N
+is exclusive-open
+(it cannot be opened if it is already open).
+A
+.Xr read 2
+call will return an error
+.Pq Er EHOSTDOWN
+if the interface is not
+.Dq ready
+(which means that the control device is open and the interface's
+address has been set).
+.Pp
+Once the interface is ready,
+.Xr read 2
+will return a packet if one is available; if not, it will either block
+until one is or return
+.Er EWOULDBLOCK ,
+depending on whether non-blocking I/O has been enabled.
+If the packet is longer than is allowed for in the buffer passed to
+.Xr read 2 ,
+the extra data will be silently dropped.
+.Pp
+If the
+.Dv TUNSLMODE
+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,
+.Fn tunoutput .
+The destination address is in
+.Vt struct sockaddr
+format.
+The actual length of the prepended address is in the member
+.Va sa_len .
+If the
+.Dv TUNSIFHEAD
+ioctl has been set, packets will be prepended with a four byte address
+family in network byte order.
+.Dv TUNSLMODE
+and
+.Dv TUNSIFHEAD
+are mutually exclusive.
+In any case, the packet data follows immediately.
+.Pp
+A
+.Xr write 2
+call passes a packet in to be
+.Dq received
+on the pseudo-interface.
+If the
+.Dv TUNSIFHEAD
+ioctl has been set, the address family must be prepended, otherwise the
+packet is assumed to be of type
+.Dv AF_INET .
+Each
+.Xr write 2
+call supplies exactly one packet; the packet length is taken from the
+amount of data provided to
+.Xr write 2
+(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.
+.Pp
+The following
+.Xr ioctl 2
+calls are supported
+(defined in
+.In net/if_tun.h ) :
+.Bl -tag -width ".Dv TUNSIFMODE"
+.It Dv TUNSDEBUG
+The argument should be a pointer to an
+.Vt 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
+.Vt int ;
+this stores the internal debugging variable's value into it.
+.It Dv TUNSIFINFO
+The argument should be a pointer to an
+.Vt struct tuninfo
+and allows setting the MTU, the type, and the baudrate of the tunnel
+device.
+The
+.Vt struct tuninfo
+is declared in
+.In net/if_tun.h .
+.Pp
+The use of this ioctl is restricted to the super-user.
+.It Dv TUNGIFINFO
+The argument should be a pointer to an
+.Vt struct tuninfo ,
+where the current MTU, type, and baudrate will be stored.
+.It Dv TUNSIFMODE
+The argument should be a pointer to an
+.Vt int ;
+its value must be either
+.Dv IFF_POINTOPOINT
+or
+.Dv IFF_BROADCAST
+and should have
+.Dv IFF_MULTICAST
+OR'd into the value if multicast support is required.
+The type of the corresponding
+.Dq Li tun Ns Ar N
+interface is set to the supplied type.
+If the value is outside the above range, an
+.Er EINVAL
+error is returned.
+The interface must be down at the time; if it is up, an
+.Er EBUSY
+error is returned.
+.It Dv TUNSLMODE
+The argument should be a pointer to an
+.Vt 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
+the network destination address (see above).
+.It Dv TUNSIFPID
+Will set the pid owning the tunnel device to the current process's pid.
+.It Dv TUNSIFHEAD
+The argument should be a pointer to an
+.Vt 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 TUNGIFHEAD
+The argument should be a pointer to an
+.Vt int ;
+the ioctl sets the value to one if the device is in
+.Dq multi-af
+mode, and zero otherwise.
+.It Dv FIONBIO
+Turn non-blocking I/O for reads off or on, according as the argument
+.Vt int Ns 's
+value is or is not zero.
+(Writes are always non-blocking.)
+.It Dv FIOASYNC
+Turn asynchronous I/O for reads
+(i.e., generation of
+.Dv SIGIO
+when data is available to be read)
+off or on, according as the argument
+.Vt int Ns 's
+value is or is not zero.
+.It Dv FIONREAD
+If any packets are queued to be read, store the size of the first one
+into the argument
+.Vt 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
+.Vt int
+value.
+.It Dv TIOCGPGRP
+Retrieve the process group value for
+.Dv SIGIO
+signals into the argument
+.Vt 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
+(as if with
+.Nm ifconfig Ar tunN Cm down ) .
+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.
+.Sh SEE ALSO
+.Xr ioctl 2 ,
+.Xr read 2 ,
+.Xr select 2 ,
+.Xr write 2 ,
+.Xr devname 3 ,
+.Xr inet 4 ,
+.Xr intro 4 ,
+.Xr pty 4 ,
+.Xr ifconfig 8
+.Sh AUTHORS
+This manual page was originally obtained from
+.Nx .