Import NetBSD's tun(4) man page.
Obtained from: NetBSD
This commit is contained in:
Joerg Wunsch
parent
fd03752a5d
commit
f15d3ed0f2
Notes:
svn2git
2020-12-20 02:59:44 +00:00
svn path=/vendor/NetBSD/dist/; revision=29195
216
share/man/man4/tun.4
Normal file
216
share/man/man4/tun.4
Normal file
@ -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.
|
||||
Loading…
Reference in New Issue
Block a user