/ 
Linux-TunTap-0.001
River stage zero No dependents
/ Linux::TunTap

NAME

Linux::TunTap - Userspace network device

SYNOPSIS

use Linux::TunTap;

my $tap=new Linux::TunTap;

while(my $packet=get_raw()) {
  # do something with the data, e.g. send it down a tunnel
}

DESCRIPTION

This is an object-oriented Perl module that interfaces with the Linux tuntap driver. tuntap is a virtual network device that sends and receives packets to and from userspace rather than a physical interface.

The normal use of the tuntap device is to write tunnels and bridges between networks. This would tend to imply that you have two hosts on separate networks as the endpoints, and some means of passing data between the tunnel endpoints, e.g. by wrapping the unsupported or firewalled data in a protocol that may pass.

Configuration of a tunnel and the security implications of doing so are out of the scope of this document.

If your problem is more one of wanting to inspect passing packets, rather than receiving packets and sending replies, you may find that IPTables::IPv4::IPQueue suits your needs better.

ATTRIBUTES

interface
my $if=$tun->{interface};

Retrieves the name of the tuntap interface, e.g. "tun0".

METHODS

new( [ PARAM => value, ... ] )

This creates a new tuntap interface and returns a handle to it.

Parameters: NAME.

my $tap=new Linux::TunTap;
my $tap2=new Linux::TunTap(NAME => 'tap%d');

If you specify NAME, it will attempt to create a tuntap device with that name. You may put a %d format specifier into the name, to ensure uniqueness.

It will throw an exception if the tuntap interface could not be created. Your attention is drawn to "SYSTEM REQUIREMENTS" which discusses what is required for successful creation of an interface.

get_raw( [ timeout ] )
my $packet=$tun->get_raw();

This reads a raw packet from the tunnel, with an optional timeout. If the timeout is omitted, this will block until data is available. Otherwise, the timeout value is the maximum time in seconds to wait. If there is a timeout, an empty string is returned.

The raw packet is returned if it could be read, otherwise undef will be returned to indicate an I/O error (use $! to find out what that error was.)

In this context, raw means the raw output of tuntap, which includes a four byte header prepended to the IP (or whatever) packet. The output of get_raw() is suitable for using as an argument for put_raw() to reinject the packet.

put_raw( packet )
$tun->get_raw($packet)
  or die "Failed to send to network: $!";

This write a raw packet to the tunnel. A false value will be returned if the write failed, if it was undef, $! will say what the error was.

SYSTEM REQUIREMENTS

You need a kernel with tuntap, either compiled in, or as a module. The module's name is tun.o. Currently, only Linux 2.4 is supported. Linux 2.2 tuntap has a different API and is currently not supported by this module. Linux 2.6 is untested.

You also need the tuntap device node, a character special file with the name /dev/net/tun with major number 10 and minor number 200. You can create it like this:

# mkdir /dev/net
# mknod /dev/net/tun c 10 200
# chmod 0700 /dev/net/tun

Your script needs to have appropriate permissions to access /dev/net/tun. If created as described, you will need to run as root.

WARNINGS

Because Linux will not generally allow you to run commands such as ifconfig(8) as a non-root user, you will usually find that your script will need to run as root unless you make special arrangements.

You are playing with raw network packets in the kernel. This means that you have somewhat more low-level access to the network than is normally allowed by mere mortals. It might be possible (although unlikely) to cause a kernel panic through careless use.

Creating tunnels to bypass firewalls may be a violation of your terms of service and/or a criminal offence.

As you are running as root, taking arbitrary unchecked data from the public Internet, and creating a weak spot in the security infrastructure, now is an excellent time to read up on taint mode.

SEE ALSO

The Linux documentation on tuntap in the kernel source: .../Documentation/networking/tuntap.txt.

The many RFCs on IP networking: http://www.rfc-editor.org/rfc.html.

Hall, Eric A. Internet Core Protocols. Sebastopol, CA: O'Reilly & Associates Inc., 2000. ISBN 1-56592-572-6.

BUGS

Only Linux 2.4 style tuntap devices are supported.

No means to inspect Ethernet frames is provided.

COPYRIGHT

Copyright (c) 2004 Peter Corlett <abuse@cabal.org.uk>. All Rights Reserved.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.