From 174eba148a48a2103531fdddcf5d5a593278ec33 Mon Sep 17 00:00:00 2001 From: joerg Date: Sun, 7 Sep 1997 11:27:08 +0000 Subject: Import NetBSD's tun(4) man page. Obtained from: NetBSD --- share/man/man4/tun.4 | 216 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 216 insertions(+) create mode 100644 share/man/man4/tun.4 (limited to 'share/man/man4') diff --git a/share/man/man4/tun.4 b/share/man/man4/tun.4 new file mode 100644 index 0000000..2f813d8 --- /dev/null +++ b/share/man/man4/tun.4 @@ -0,0 +1,216 @@ +.\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $ +.\" Based on PR#2411 +.\" +.Dd March 10, 1996 +.Dt TUN 4 +.Os NetBSD 1.1 +.Sh NAME +.Nm tun +.Nd tunnel software network interface +.Sh SYNOPSIS +.Cd pseudo-device tun Op Ar count +.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 +The network interfaces are named +.Sy tun Ns Ar 0 , +.Sy tun Ns Ar 1 , +etc, as many in all as the +.Ar count +figure given on the +.Sy pseudo-device +line. Each one 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 as +.Dq input +there +.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. A +.Fn read +call will return an error +.Pq Er EHOSTDOWN +if the interface is not +.Dq ready +.Po +which means that the control device is open and the interface's +address has been set +.Pc . +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 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 +.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 Ns : +.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 +.Dv IFF_POINTOPOINT +or +.Dv IFF_BROADCAST . +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 on +.Dq link-layer +mode, causing packets read from the tunnel device to be prepended with +network destination address. +.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 nonblocking . +.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. +.Po If the interface is up when the data device is not open +output packets are always +thrown away rather than letting them pile up +.Pc . +.Sh SEE ALSO +.Xr intro 4 , +.Xr inet 4 +.Sh BUGS +Currently is IP-only. -- cgit v1.1