IPTables::ChainMgr(3) User Contributed Perl DocumentationIPTables::ChainMgr(3)NAMEIPTables::ChainMgr - Perl extension for manipulating iptables policies
SYNOPSIS
use IPTables::ChainMgr;
my %opts = (
'iptables' => '/sbin/iptables',
'iptout' => '/tmp/iptables.out',
'ipterr' => '/tmp/iptables.err',
'debug' => 0,
'verbose' => 0
### advanced options
'ipt_alarm' => 5, ### max seconds to wait for iptables execution.
'ipt_exec_style' => 'waitpid', ### can be 'waitpid',
### 'system', or 'popen'.
'ipt_exec_sleep' => 1, ### add in time delay between execution of
### iptables commands (default is 0).
);
my $ipt_obj = new IPTables::ChainMgr(%opts)
or die "[*] Could not acquire IPTables::ChainMgr object";
my $rv = 0;
my $out_ar = [];
my $errs_ar = [];
# check to see if the 'CUSTOM' chain exists in the filter table
($rv, $out_ar, $errs_ar) = $ipt_obj->chain_exists('filter', 'CUSTOM');
if ($rv) {
print "CUSTOM chain exists.\n";
### flush all rules from the chain
$ipt_obj->flush_chain('filter', 'CUSTOM');
### now delete the chain (along with any jump rule in the
### INPUT chain)
$ipt_obj->delete_chain('filter', 'INPUT', 'CUSTOM');
}
# create new iptables chain in the 'filter' table
$ipt_obj->create_chain('filter', 'CUSTOM');
# add rule to jump packets from the INPUT chain into CUSTOM at the
# 4th rule position
$ipt_obj->add_jump_rule('filter', 'INPUT', 4, 'CUSTOM');
# find rule that allows all traffic from 10.1.2.3 to 192.168.1.2
($rv, $rule_num) = $ipt_obj->find_ip_rule('10.1.2.3', '192.168.1.2',
'filter', 'INPUT', 'ACCEPT', {});
# find rule that allows all TCP port 80 traffic from 10.1.2.3 to
# 192.168.1.1
($rv, $rule_num) = $ipt_obj->find_ip_rule('10.1.2.3', '192.168.1.2',
'filter', 'INPUT', 'ACCEPT', {'protocol' => 'tcp', 's_port' => 0,
'd_port' => 80});
# add rule at the 5th rule position to allow all traffic from
# 10.1.2.3 to 192.168.1.2 via the INPUT chain in the filter table
($rv, $out_ar, $errs_ar) = $ipt_obj->add_ip_rule('10.1.2.3',
'192.168.1.2', 5, 'filter', 'INPUT', 'ACCEPT', {});
# add rule at the 4th rule position to allow all traffic from
# 10.1.2.3 to 192.168.1.2 over TCP port 80 via the CUSTOM chain
# in the filter table
($rv, $out_ar, $errs_ar) = $ipt_obj->add_ip_rule('10.1.2.3',
'192.168.1.2', 4, 'filter', 'CUSTOM', 'ACCEPT',
{'protocol' => 'tcp', 's_port' => 0, 'd_port' => 80});
# append rule at the end of the CUSTOM chain in the filter table to
# allow all traffic from 10.1.2.3 to 192.168.1.2 via port 80
($rv, $out_ar, $errs_ar) = $ipt_obj->append_ip_rule('10.1.2.3',
'192.168.1.2', 'filter', 'CUSTOM', 'ACCEPT',
{'protocol' => 'tcp', 's_port' => 0, 'd_port' => 80});
# run an arbitrary iptables command and collect the output
($rv, $out_ar, $errs_ar) = $ipt_obj->run_ipt_cmd(
'/sbin/iptables -v -n -L');
DESCRIPTION
The "IPTables::ChainMgr" package provide an interface to manipulate
iptables policies on Linux systems through the direct execution of
iptables commands. Although making a perl extension of libiptc
provided by the iptables project is possible (and has been done by the
IPTables::libiptc module available from CPAN), it is also easy enough
to just execute iptables commands directly in order to both parse and
change the configuration of the policy. Further, this simplifies
installation since the only external requirement is (in the spirit of
scripting) to be able to point IPTables::ChainMgr at an installed
iptables binary instead of having to compile against a library.
FUNCTIONS
The IPTables::ChainMgr extension provides an object interface to the
following functions:
chain_exists($table, $chain)
This function tests whether or not a chain (e.g. 'INPUT') exists
within the specified table (e.g. 'filter'). This is most useful to
test whether a custom chain has been added to the running iptables
policy. The return values are (as with many IPTables::ChainMgr
functions) an array of three things: a numeric value, and both the
stdout and stderr of the iptables command in the form of array
references. So, an example invocation of the chain_exists()
function would be:
($rv, $out_ar, $errs_ar) = $ipt_obj->chain_exists('filter', 'CUSTOM');
If $rv is 1, then the CUSTOM chain exists in the filter table, and
0 otherwise. The $out_ar array reference contains the output of
the command "/sbin/iptables -t filter -v -n -L CUSTOM", which will
contain the rules in the CUSTOM chain (if it exists) or nothing (if
not). The $errs_ar array reference contains the stderr of the
iptables command.
create_chain($table, $chain)
This function creates a chain within the specified table. Again,
three return values are given like so:
($rv, $out_ar, $errs_ar) = $ipt_obj->create_chain('filter', 'CUSTOM');
Behind the scenes, the create_chain() function in the example above
runs the iptables command "/sbin/iptables -t filter -N CUSTOM".
flush_chain($table, $chain)
This function flushes all rules from chain in the specified table,
and three values are returned:
($rv, $out_ar, $errs_ar) = $ipt_obj->flush_chain('filter', 'CUSTOM');
The flush_chain() function in the example above executes the
iptables command "/sbin/iptables -t filter -F CUSTOM"
delete_chain($table, $jump_from_chain, $chain)
This function deletes a chain from the specified table along with
any jump rule to which packets are jumped into this chain:
($rv, $out_ar, $errs_ar) = $ipt_obj->delete_chain('filter', 'INPUT', 'CUSTOM');
Internally a check is performed to see whether the chain exists
within the table, and global jump rules are removed from the jump
chain before deletion (a chain cannot be deleted until there are no
references to it). In the example above, the CUSTOM chain is
deleted after any jump rule to this chain from the INPUT chain is
also deleted.
find_ip_rule($src, $dst, $table, $chain, $target, %extended_info)
This function parses the specified chain to see if there is a rule
that matches the $src, $dst, $target, and (optionally) any
%extended_info criteria. The return values are the rule number in
the chain (or zero if it doesn't exist), and the total number of
rules in the chain. Below are two examples; the first is to find
an ACCEPT rule for 10.1.2.3 to communicate with 192.168.1.2 in the
INPUT chain, and the second is the same except that the rule is
restricted to TCP port 80:
($rulenum, $chain_rules) = $ipt_obj->find_ip_rule('10.1.2.3',
'192.168.1.2', 'filter', 'INPUT', 'ACCEPT', {});
if ($rulenum) {
print "matched rule $rulenum out of $chain_rules rules\n";
}
($rulenum, $chain_rules) = $ipt_obj->find_ip_rule('10.1.2.3',
'192.168.1.2', 'filter', 'INPUT', 'ACCEPT',
{'protocol' => 'tcp', 's_port' => 0, 'd_port' => 80});
if ($rulenum) {
print "matched rule $rulenum out of $chain_rules rules\n";
}
add_ip_rule($src, $dst, $rulenum, $table, $chain, $target,
%extended_info)
This function inserts a rule into the running iptables chain and
table at the specified rule number. Return values are success or
failure along with the iptables stdout and stderr.
append_ip_rule($src, $dst, $table, $chain, $target, %extended_info)
This function appends a rule at the end of the iptables chain in
the specified table. Return values are success or failure along
with the iptables stdout and stderr.
delete_ip_rule($src, $dst, $table, $chain, $target, %extended_info)
This function searches for and then deletes a matching rule within
the specified chain. Return values are success or failure along
with the iptables stdout and stderr.
add_jump_rule($table, $from_chain, $rulenum, $to_chain)
This function adds a jump rule (after making sure it doesn't
already exist) into the specified chain. The $rulenum variable
tells the function where within the calling chain the new jump rule
should be placed. Here is an example to force all packets
regardless of source or destination to be jumped to the CUSTOM
chain from the INPUT chain at rule 4:
($rv, $out_ar, $errs_ar) = $ipt_obj->add_jump_rule('filter', 'INPUT', 4, 'CUSTOM');
run_ipt_cmd($cmd)
This function is a generic work horse function for executing
iptables commands, and is used internally by IPTables::ChainMgr
functions. It can also be used by a script that imports the
IPTables::ChainMgr extension to provide a consistent mechanism for
executing iptables. Three return values are given: success (1) or
failure (0) of the iptables command (yes, this backwards from the
normal exit status of Linux/*NIX binaries), and array references to
the iptables stdout and stderr. Here is an example to list all
rules in the user-defined chain "CUSTOM":
($rv, $out_ar, $errs_ar) = $ipt_obj->run_ipt_cmd('/sbin/iptables -t filter -v -n -L CUSTOM');
if ($rv) {
print "rules:\n";
print for @$out_ar;
}
SEE ALSO
The IPTables::ChainMgr extension is closely associated with the
IPTables::Parse extension, and both are heavily used by the psad,
fwsnort, and fwknop projects to manipulate iptables policies based on
various criteria (see the psad(8), fwsnort(8), and fwknop(8) man
pages). As always, the iptables(8) man page provides the best
information on command line execution and theory behind iptables.
Although there is no mailing that is devoted specifically to the
IPTables::ChainMgr extension, questions about the extension will be
answered on the following lists:
The psad mailing list: http://lists.sourceforge.net/lists/listinfo/psad-discuss
The fwknop mailing list: http://lists.sourceforge.net/lists/listinfo/fwknop-discuss
The fwsnort mailing list: http://lists.sourceforge.net/lists/listinfo/fwsnort-discuss
The latest version of the IPTables::ChainMgr extension can be found at:
http://www.cipherdyne.org/modules/
CREDITS
Thanks to the following people:
Franck Joncourt <franck.mail@dthconnex.com>
Grant Ferley
Darien Kindlund
AUTHOR
The IPTables::ChainMgr extension was written by Michael Rash
<mbr@cipherdyne.org> to support the psad, fwknop, and fwsnort projects.
Please send email to this address if there are any questions, comments,
or bug reports.
COPYRIGHT AND LICENSE
Copyright (C) 2005-2008 by Michael Rash
This library is free software; you can redistribute it and/or modify it
under the same terms as Perl itself, either Perl version 5.8.5 or, at
your option, any later version of Perl 5 you may have available.
perl v5.14.2 2012-01-11 IPTables::ChainMgr(3)
