326 lines
7.7 KiB
Groff
326 lines
7.7 KiB
Groff
.\" $NetBSD: tun.4,v 1.1 1996/06/25 22:17:37 pk Exp $
|
|
.\" $FreeBSD$
|
|
.\" Based on PR#2411
|
|
.\"
|
|
.Dd November 30, 2014
|
|
.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.
|
|
A client program transfers IP (by default) packets to or from the
|
|
.Nm
|
|
.Dq control
|
|
interface.
|
|
The
|
|
.Xr tap 4
|
|
interface provides similar functionality at the Ethernet layer:
|
|
a client will transfer Ethernet frames to or from a
|
|
.Xr tap 4
|
|
.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 tap 4 ,
|
|
.Xr ifconfig 8
|
|
.Sh AUTHORS
|
|
This manual page was originally obtained from
|
|
.Nx .
|