NAME
tun — IP network tunnel driver
SYNOPSIS
#include <net/tun.h>
open("/dev/tun
n
", mode);
DESCRIPTION
When IP packets are written to
/dev/tunn
or
/dev/tunn+M,
they will be
received by the kernel's IP layer on the network interface
dun.
When the kernel's IP layer sends packets to the IP
interface
dun,
they will be available for reading on
/dev/tunn
or
/dev/tunn+M.
Instead of having hardware and an associated kernel interface that
support network functions, the
tun
driver allows a network
interface to be implemented as a user-space process. While talking to
the same set of tunnel drivers on the same system, different network
interface processes can implement different IP encapsulation methods,
such as RFC 877 for use over CCITT X.25-based public data networks, or
RFC 1055 SLIP or RFC 1548/1332 PPP for use over dedicated lines
and dialup modems.
The
tun
driver provides support for a pair of devices
collectively known as an
IP tunnel.
The two devices
comprising a tunnel are known as the
inbound
and
outbound
sides, similar to the pairing between
/dev/ttyn
(the
inbound terminal) and
/dev/cun
(the outbound `auto-call unit'
available on many systems).
The outbound side's minor device number is that of the inbound side
plus
M,
though they together appear to IP as one interface.
If both the inbound and outbound sides of a tunnel device are open,
packets received from IP are delivered to only the inbound side.
On HP-UX systems,
M
is 64.
If a TCP packet received from IP
is part of a telnet, rlogin, or FTP command stream, it
will be put in a fast queue. All packets in the fast queue
are delivered to the user before any packets in the normal queue.
Config
pseudo-device tun[n]
Ioctls
A few special
ioctls
are provided for use on the
/dev/tun*
devices to supply the functionality needed by
applications programs to emulate real hardware interfaces. The
complete list of supported
ioctls
is:
- TUIOSPTPT
Set or clear the
IFF_POINTOPOINT
in the associated network interface.
- TUIOSADRMD
Set or clear `address mode', in which packets read are prefaced with
four octets containing the destination IP address in network byte
order.
The third argument is a pointer to an integer containing either a zero
or a one, indicating whether `address mode' should be cleared or set,
respectively.
If both `address mode' and `packed buffer mode' are set, each packet's
length will come first, followed by the packet's destination address,
followed by the packet itself.
- TUIOGADRMD
Get the current status of `address mode'.
- TUIOSPKBMD
Set or clear `packed buffer mode' where multiple packets are encoded
in single read/write buffers. The third argument is a pointer to an
integer containing either a zero or a one, indicating whether `packed
buffer mode' should be cleared or set, respectively. If set (1), each
packet is preceded by four octets representing the next packet's
length in octets. The following packet will then be aligned to the
next multiple of four octets. If cleared (0), packets will be
delivered one per read(3) from the tunnel device. If both `address
mode' and `packed buffer mode' are set, each packet's length will come
first, followed by the packet's address, followed by the packet
itself.
- TUIOGPKBMD
Get the current status of `packed buffer mode'.
- TUIOSPKMAX
Set the max number of IP frames to send back in a packet buffer read.
- TUIOGPKMAX
Get the
PKMAX
value.
- TUIOSPKPAD
Set the number of long word zeroes to put on the front of each packet
read in packed buffer mode.
- TUIOGPKPAD
Get the number of pad words.
- TUIOSNAME
Set the interface name (may only be invoked by the superuser).
- TUIOGNAME
Get the interface name.
- FIONBIO
Set or clear non-blocking mode for I/O operations.
EXAMPLES
#include <net/tun.h>
int tun_fd = -1, len;
char *packet;
tun_fd = open("/dev/tun0", O_RDWR);
ioctl(tun_fd, TUIOSNAME, "du");
len = read(tun_fd, packet, size);
write(tun_fd, packet, len);
ERRORS
If a packet is delivered to the interface for an address family other
than
AF_INET,
EAFNOSUPPORT
will be returned.
FILES
- /dev/tun0 through /dev/tunM-1
`inbound' tunnel devices
- /dev/tunM through /dev/tun2*M-1
`outbound' tunnel devices
AUTHOR
tun
was developed by the Progressive Systems.
SEE ALSO
ppp.Auth(4),
ppp.Devices(4),
ppp.Dialers(4),
ppp.Filter(4),
ppp.Keys(4),
ppp.Systems(4),
pppd(1),
RFC 1548,
RFC 1332,
RFC 1144,
RFC 1055,
RFC
877,
and
(for
philosophical
comparison
only)
RFC 1241.