NOTE:   !!!!PLEASE READ THIS!!!!

There has been a change in the semantics of IPTables::IPv4 as of 0.98.
In the future, if you have changes which you intend to have applied back
to the kernel, you must EXPLICITLY call the commit() method on the table
handle. Letting the DESTROY handle execute will simply call iptc_free()
now. This is useful for if someone wants to just see the rules, or play
with adding rules to chains, without actually changing the kernel side.
The ability to do this was provided through a recent update to libiptc.

Introduction:

IPTables::IPv4 is a Perl module, written in C using the XS toolset, and
built on top of libiptc from netfilter/iptables. It provides an interface
over libiptc, with match and target module handling, to allow Perl scripts
to manipulate kernel firewalling, NAT/masquerade, and packet mangling rules.

This particular module has certain advantages over other similar modules:

  - Instead of constructing command lines and feeding them to the command
    line 'iptables' tool, the actual libiptc routines are used to
    manipulate rules. Not only is this faster because of the removal of
    fork()/exec() overhead, but there's an additional speed boost because
    the script only needs to get the state of a table once. Changes are
    then applied to it in local memory, then committed back to the kernel.

  - Instead of trying to adapt the iptables utility's code wholesale to
    Perl, which is awkward at best, I've built up code on top of libiptc
    that is expressly designed for use with Perl. Therefore, at least in
    this programmer's opinion, it integrates far better with Perl scripts,
    allowing rule analysis and manipulation in ways nothing else can.

  - Instead of representing the individual rules (or entries, as libiptc
    calls them) as some sort of object, which makes them hard to properly
    serialize and reconstitute, rules are represented simply as hashes.

  - This module also provides a tie()'d data structure, %IPTables::IPv4,
    through which rule manipulation can be done. The level of integration
    with Perl makes this feasible with no extra XS code - the tie() classes
    themselves are pure Perl.

  - This code includes a snap of libiptc, with a few minor changes to
    correct error string problems I discovered. That means that this
    package is 100% self-contained - it does not require any acrobatics
    with installing libiptc.a and the libiptc/iptables headers in unusual
    locations to build.

I am also now including support for IPv6 firewalling rules, by way of the
IPTables::IPv6 module. I have ported several modules for use with
IPTables::IPv6, so it should at least be moderately useful. I've ported
all the standard modules, so it should be reasonably useful. I don't yet
have embedded docs for the modules, but they function like the IPv4 ones
(except for icmpv6 - there are fewer ICMPv6 types, and the field name is
'icmpv6-type' - look at the source if you're curious). HL and hl are like
TTL and ttl for IPv4, so use them in the same way. eui64 takes no options.

Please see the embedded POD documentation (perldoc IPTables::IPv4), or the
included PDF, for full details on using the IPTables::IPv4 module.

Quick how-to on building IPTables:

tar zxf IPTables-IPv4-<version>.tar.gz -C <target dir>
cd <target dir>/IPTables-IPv4-<version>
perl Makefile.PL
make
make test # from here on must be as root! this will fail if not!
make install

Note about "make test":

Doing "make test" will save your current ruleset, clear all rules, and
restore the saved rules when the test sequence finishes. If it starts 'make
test' and doesn't complete, or you have to break out of it for some reason,
do the following:

   IPT_IPV4_MODPATH=${PWD}/modules perl -Iblib/lib -Iblib/arch \
        t/99restore_ruleset.t

at a prompt, from within the IPTables-IPv4-<version> directory. This will
restore the ruleset that the first test script saved (in /tmp/ruleset.txt).

Modules:

Presently, match and target modules are provided for everything that is
in the stock 2.4.20 kernel. Some of the matches and targets in
patch-o-matic are also supported, but not all. If you want more supported,
look at the modules sources in the modules/ subdirectory and use them as
a model for constructing your own module. If you can write a test case
as well, that would also be helpful - it will allow its behavior to be
verified at build time.

Patches/Submissions:

Submissions of bug fixes, new modules, etc., will be gladly accepted into
the CVS tree. Unified diffs ('diff -u' style) are preferred, as they are
the most human-readable form. I will continue to develop and improve
IPTables::IPv4, but I can't guarantee that I will support every match and
target module in as timely a fashion as you may need. If it's not something
I use, I may not be familiar enough with it to port it, or give it the
testing and attention it deserves, so submissions of new modules are
particularly welcome.

Mailing list:

I've set up a mailing list for discussion, bug reporting, etc. about the
IPTables::IPv4 module. If you wish to subscribe, go to:

    http://lists.sourceforge.net/lists/listinfo/iptperl-general

and subscribe. Non-member posting has been disabled for the list, so you
must subscribe to post to the list.

Reporting bugs:

This code has been used in production scenarios, and has had some beating
done on it. However, bugs may remain, but I have tried to eliminate all I
can. If you come across a bug, please e-mail me about it. The more detail
you can provide, the better - script examples and strace/ltrace output,
GDB backtraces, and other such debugging material can be invaluable in
tracking down what happened, and why.

--
Derrik Pates
dpates@dsdk12.net