271 lines
7.4 KiB
Groff
271 lines
7.4 KiB
Groff
.\" $NetBSD: tun.4,v 1.17 2004/12/05 13:28:54 wiz Exp $
|
|
.\"
|
|
.\" Copyright (c) 1996-2003 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" 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 November 22, 2004
|
|
.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 exists 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 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.
|
|
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 inet 4 ,
|
|
.Xr intro 4
|
|
.Sh BUGS
|
|
Currently is IPv4-only.
|