IP-TUN(8)

NAME
ip-tun - implement RFC-2003 IP-in-IP tunnels

SYNOPSIS
ip-tun [-dvrlgq] [-p pnum] [-f fnum] [-t tnum] tun-src tun-dst tun-mask src dst

DESCRIPTION
ip-tun establishes an RFC-2003 style IP encapsulation tunnel using a tun(4) kernel interface combined with divert sockets and IP firewall rules.

tun-src and tun-dst are the source and destination IPv4 addresses used on the inside of the tunnel.

tun-mask is the netmask used on the tunnel, typically "255.255.255.252"

src and dst are the source and destination IPv4 addresses used on the outer IP header.

All addresses and netmasks can be specified as DNS names ( full or partially qualified), or dotted-decimal. Only IPv4 is supported. The following checks are also performed:

src dst

tun-src tun-dst

tun-src & tun-mask
    tun-dst & tun-mask

src is an existing interface address

The options are as follows:

-d  Do NOT run as a daemon, i.e., after the tun(4) device is created, remain attached to the console.

-v  Print the version number and exit.

-r  Do NOT create the default point-to-point route, e.g., as ifconfig(8) would have done. This is preferable for systems running dynamic routing, e.g., gated(8) or routed(8).

-l  DO add the loopback alias lo(4) to the source end of the tunnel. This is NOT a feature of ifconfig(8) of a tun(4) device, so the default is to NOT create that alias. The alias is removed when the tunnel is dismantled.

-g  Force the kernel variable ‘ net.inet.ip.forwarding = 1 ’ ( make as a gateway, via sysctl(8)). If not set, ip-tun tests for ip-forwarding, and quits if it is not set. Forwarding is required for the recirculation of packets between ip-tun and the kernel.

-q  Make it as quiet as possible. No output at all if everything goes well.

-P  Print out the PID of the process. Useful so other programs can kill(1) ip-tun later. [-P] overrides [-q].

-p pnum
    Set the divert(4) socket port number to pnum, rather than searching for an available port. These port numbers must be unique on each host for each tunnel. If not provided, pnum defaults to the range 8000-9000.

-f fnum
    Set the ipfirewall(4) rule number to fnum, rather than searching for an available rule number. Note that rule numbers need not be unique. If not provided, fnum defaults to the range 50-60.

-t tnum
    Set the tun(4) device number to tnum, rather than searching for an available device. If not supplied, tnum defaults to search all tunnel devices.

Note that pnum, tnum, and fnum can be supplied as ranges, as in "low-high". In this case, the range supplied is searched, from low to high ( low high), except for [-t], where ANY tunnel in the supplied range will suffice.

ip-tun modifies interface addresses and routes, and so must be run as root.

ip-tun performs several functions:

configures
as if running the command:

    ifconfig tunN tunnel-source tunnel-dest -netmask tunnel-mask

adds IP firewall rules
to shunt encapsulated packets to a divert socket

spawns an encapsulation/decapsulation process
that encapsulates packets received on the tunnel and decapsulates packets received on the divert socket

adds the default
route(4) rule appropriate to the tunnel, as if:

    route add tunnel-dest -iface tunN

adds an alias to the loopback
( currently disabled) to allow the near-end of the tunnel to correctly process packets, as if:

    ifconfig lo0 alias tunnel-source

ip-tun runs in foreground; to remove the tunnel, kill the process either directly or via kill(1)

Another simple tunnel program, nos-tun(8), runs a similar daemon off of a tun(4) device. Encapsulated packets are received on tun(4); decapsulated packets are directed to the process by using a socket(2) bound to SOCK_RAW and the appropriate protocol number.

However, IPv4 is already bound to the kernel's IP processing system, so user programs cannot bind to that protocol without affecting kernel IP processing. One alternative is to do that binding, process all IP packets, and decapsulate only the appropriate ones. Unmodified packets are returned to the kernel. This is a security risk, moving all incoming packet processing into user space unnecessarily. It also affects the performance of all input packet processing.

Instead, ip-tun takes advantage of ipfirewall(4) rules to direct only appropriately addressed and encapsulated packets to a divert(4) socket. Its performance is limited only by the addition of the kernel firewall rules, and the performance of ip-tun itself.

ip-tun requires

•   at least one a free tun(4) device

•   a kernel compiled with ‘options IPFIREWALL’ and ‘options IPDIVERT’ as per ipfirewall(4) ( may also want ‘options IPFIREWALL_DEFAULT_TO_ACCEPT’).

ip-tun requires both source and destination addresses for both inner and outer headers. This is required to support multiple tunnels between two machines, and to control the source address of the tunnels.

RETURN VALUES
The ip-tun command returns an exit status of 0 if configuration of its devices succeeds. It returns a status of the error causing the abort if it fails.

ip-tun contains internal checks for OS version ( 3.2 or greater), KAME IPv6 patches ( it prints a warning - KAME's gif interfaces, gifconfig(8), are preferable, and there are potential interactions (see BUGS)), and the IPFIREWALL and IPDIVERT kernel options.

EXAMPLES
This end, a FreeBSD box on address 192.168.59.34:

    ip-tun 10.0.0.1 10.0.0.2 255.255.255.252 192.168.59.34 192.168.56.45

Remote box on address 192.168.56.45. Given are commands for FreeBSD KAME gifconfig(8)

    ifconfig gif0 10.0.0.1 10.0.0.2 netmask 255.255.255.252 up
    gifconfig gif0 192.168.59.34 192.168.56.45

SIGNAL HANDLING
The following signals have the specified effect when sent to ip-tun using the kill(1) command:

INT Tells ip-tun to exit, and cleans up interface configurations and routes. Note - tun(4) devices retain configuration information even when configured "down"

SEE ALSO
X-Bone(8), nos-tun(8), tun(4), divert(4), ipfirewall(4), route(4), ifconfig(8), gifconfig(8), sysctl(8), lo(0), kill(1),

STANDARDS
ip-tun conforms to the requirements of RFC-2003, "IP Encapsulation within IP," C. Perkins, Oct. 1996. IP options and header value encapsulation and decapsulation are handled as required. Inner IP header TTL is decremented as a side-effect of kernel-based IP forwarding.

The encapsulator does not fragment packets on its own; if encapsulation creates packets larger than the current MTU, they will fail on delivery.

ip-tun does not emit ICMP errors, e.g., if the MTU is exceeded due to encapsulation, TTL is zero after encapsulation or decapsulation, etc. All events are handled by silent discards, or success. It is assumed that kernel IP forwarding will handle most cases correctly before reaching ip-tun

AUTHORS
Joe Touch <touch@isi.edu> designed the program, updated it, and wrote this man page.

Stephen Suryaputra <ssuryapu@nortelnetworks.com> wrote the program while a graduate student at USC/ISI.

BUGS
The current version is highly incompatible with the FreeBSD KAME patches ( IPv6 and IPSEC); this should be OK, since KAME's gif tunnels are preferable, and make ip-tun unnecessary. The problem lies with gifconfig(8) 's inability to release its association with a tunnel device, and ip-tun 's current inability to detect that association and avoid its use. The current ip-tun warns if KAME is detected.

If there are ipfirewall(4) rules that would affect the packets in the tunnel, they must precede ( lower rule number) the number ip-tun uses.

The current version supports only IPv4 in IPv4 tunnels.

COPYING

    See the copyright info. and disclaimers in the source code.