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