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