start of replacement tun page; from mdw

2 files changed, 216 insertions, 2 deletions

diff --git a/share/man/man4/Makefile b/share/man/man4/Makefile
index 61552380cce..58efdb8e85b 100644
--- a/share/man/man4/Makefile
+++ b/share/man/man4/Makefile
@@ -1,4 +1,4 @@
-#	$OpenBSD: Makefile,v 1.235 2003/03/09 01:19:33 deraadt Exp $
+#	$OpenBSD: Makefile,v 1.236 2003/03/09 18:51:30 deraadt Exp $
 
 MAN=	aac.4 ac97.4 addcom.4 adv.4 aha.4 ahb.4 ahc.4 aic.4 \
 	ami.4 amdpm.4 amphy.4 an.4 aria.4 ast.4 atalk.4 atapiscsi.4 \
@@ -28,7 +28,7 @@ MAN=	aac.4 ac97.4 addcom.4 adv.4 aha.4 ahb.4 ahc.4 aic.4 \
 	sl.4 sm.4 spp.4 sppp.4 sqphy.4 ss.4 st.4 ste.4 stge.4 sti.4 stp.4 \
 	sv.4 systrace.4 \
 	tb.4 tcic.4 tcp.4 termios.4 ti.4 tl.4 tlphy.4 \
-	tp.4 tqphy.4 trm.4 tty.4 twe.4 tx.4 txp.4 txphy.4 \
+	tp.4 tqphy.4 trm.4 tty.4 tun.4 twe.4 tx.4 txp.4 txphy.4 \
 	uaudio.4 ubsa.4 ubsec.4 ucom.4 udp.4 udsbr.4 uftdi.4 ugen.4 uhci.4 \
 	uhid.4 uhidev.4 uk.4 ukbd.4 \
 	ukphy.4 ulpt.4 umct.4 umidi.4 umodem.4 ums.4 umass.4 unix.4 upl.4 \
diff --git a/share/man/man4/tun.4 b/share/man/man4/tun.4
new file mode 100644
index 00000000000..96c853806f3
--- /dev/null
+++ b/share/man/man4/tun.4
@@ -0,0 +1,214 @@
+.\"	$OpenBSD: tun.4,v 1.23 2003/03/09 18:51:36 deraadt Exp $
+.\"
+.\" Copyright (c) 2003 Marcus D. Watts  All rights reserved.
+.\"
+.\" 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, and the entire permission notice in its entirety,
+.\"    including the disclaimer of warranties.
+.\" 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.
+.\" 3. The name of the author may not be used to endorse or promote
+.\"    products derived from this software without specific prior
+.\"    written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED ``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
+.\" MARCUS D. WATTS 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 Mar 9, 2003
+.Dt TUN 4
+.Os
+.Sh NAME
+.Nm tun
+.Nd network tunnel pseudo-device
+.Sh SYNOPSIS
+.Cd pseudo-device tun Op Ar count
+.Pp
+.Fd #include <sys/types.h>
+.Fd #include <net/if_tun.h>
+.Sh DESCRIPTION
+The
+.Nm
+driver provides a network interface pseudo-device.
+Packets sent to this interface can be read by a userland process
+and processed as desired.
+Packets written by the userland process are injected back into
+the kernel networking subsystem.
+By default 2 such interfaces are provided.
+.Pp
+The
+.Nm
+driver normally appears as a character special device,
+.Pa /dev/tun0 ,
+.Pa /dev/tun1 ,
+etc.
+Each device has the exclusive open property; it cannot be opened
+if it is already open and in use by another process.
+Each read returns at most one packet; if insufficient
+buffer space is provided, the packet is truncated.
+Each write supplies exactly one packet.
+Each packet read or written is prefixed with a tunnel header consisting of
+a 4 byte network byte order integer containing the address family.
+On the last close of the device, all packets are discarded,
+the device is marked down, and all routes via the device
+are removed.
+.Pp
+Writes never block.
+If the protocol queue is full, the packet is dropped,
+a ``collision'' is counted, and
+.Er ENOBUFS
+is returned.
+.Pp
+In additional to the usual network interface
+ioctl commands described in
+.Xr netintro 4 ,
+the following special commands defined in
+.Aq Pa net/if_tun.h
+are supported:
+.Pp
+.Bl -tag -width indent -compact
+.It Dv TUNGIFINFO (struct tuninfo)
+.It Dv TUNSIFINFO (struct tuninfo)
+can be used to get or set the interface characteristics.
+.Bd -literal
+/* iface info */
+struct tuninfo {
+        u_int   mtu;
+        u_short type;
+        u_short flags;
+        u_int   baudrate;
+};
+.Ed
+.Va flags
+sets the interface flags, and
+can include one or more of
+.Dv IFF_UP ,
+.Dv IFF_POINTOPOINT ,
+.Dv IFF_MULTICAST ,
+.Dv IFF_BROADCAST .
+It defaults to
+.Dv IFF_POINTOPOINT .
+It is an error to set both
+.Dv IFF_POINTOPOINT
+and
+.Dv IFF_BROADCAST .
+.\" should say what type affects...
+.Va type
+defaults to
+.Dv IFT_PROPVIRTUAL
+but can be set to
+.Dv IFT_PPP .
+This sets the interface media address header type.
+.Pp
+.It Dv TUNSIFMODE Fa int *flags
+Can be used to just set the interface flags.
+.It Dv FIONBIO Fa int *flag
+can be to use to set non-blocking I/O.
+.It Dv FIOASYNC Fa int *flag
+can be used to cause signal
+.Dv SIGIO
+to be sent when a packet can be read.
+.It Dv TIOCSPGRP Fa int *pgpp
+.It Dv TIOCGPGRP Fa int *pgrp
+Get or set the process group to which signals might be sent
+via
+.Dv FIOASYNC .
+.It Dv FIONREAD Fa int *count
+Gets the byte count of the next packet available to be read.
+.El
+.Sh FILES
+.Bl -tag -width /dev/tun* -compact
+.It Pa /dev/tun*
+.El
+.Sh ERRORS
+If open fails,
+.Xr errno 2
+may be set to one of:
+.Bl -tag -width Er
+.It Bq Eq EPERM
+Only the superuser may open the device.
+.It Bq Eq ENXIO
+Not that many devices configured.
+.It Bq Eq EBUSY
+Device was already open.
+.El
+.Pp
+If a
+.Xr write 2
+call fails,
+.Xr errno 2
+is set to one of
+.Bl -tag -width Er
+.It Bq Eq EMSGSIZE
+The packet supplied was too small or too large.
+The maximum sized packet allowed is currently 16384 bytes.
+.It Bq Eq ENOBUFS
+The were no mbufs, or
+the queue for the outgoing protocol is full.
+.It Bq Eq EAFNOSUPPORT
+The address family specified in the tunnel header was not
+recognized.
+.El
+.Pp
+Ioctl commands may fail with
+.Bl -tag -width Er
+.It Bq EBUSY
+.Dv TUNSIFMODE
+and the interface was up.
+.It Bq EINVAL
+Attempt to set both
+.Dv IFF_POINTOPOINT
+and
+.Dv IFF_BROADCAST
+with
+.Dv TUNSIFMODE .
+.It Bq ENOTTY
+Unrecognized ioctl command.
+.El
+.Pp
+A
+.Xr read 2
+call may fail because of
+.Bl -tag -width Er
+.It Bq Eq EHOSTDOWN
+The device is not ready.
+The device must have an
+.Xr inet 4
+interface address assigned to it, such as via
+.Dv SIOCSIFADDR .
+.It Bq Eq EWOULDBLOCK
+Non-blocking I/O was selected and no packets were available.
+.El
+.Pp
+An attempt to send a packet out via the interface may fail with
+.Bl -tag -width Er
+.It Bq Eq EHOSTDOWN
+The device is not ready.
+The device must have an
+.Xr inet 4
+interface address assigned to it, such as via
+.Dv SIOCSIFADDR .
+.El
+.Sh SEE ALSO
+.Xr intro 4
+.Xr inet 4
+.Xr netintro 4 ,
+.Xr ifconfig 8
+.Sh BUGS
+There is no way to set TUN_STAYUP.
+.br
+.Dv TUNSIFINFO
+does no checking on
+.Va flags .
+