The IPTables::ChainMgr package provides an interface to manipulate iptables and ip6tables policies on Linux systems through the direct execution of iptables/ip6tables commands. Although making a perl extension of libiptc provided by the Netfilter project is possible (and has been done by the IPTables::libiptc module available from CPAN), it is also easy enough to just execute iptables/ip6tables 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 or ip6tables binary instead of having to compile against a library.

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/ip6tables 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 or ip6tables command in the form of array references. So, an example invocation of the chain_exists() function would be:

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. As with all IPTables::ChainMgr functions, if the IPTables::ChainMgr object was instantiated with the ip6tables binary path, then the above command would become "/sbin/ip6tables -t filter -v -n -L 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.

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 four examples; the first is to find an ACCEPT rule for 10.1.2.0/24 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. The third and forth examples illustrate ip6tables analogs of the first two examples with source IP fe80::200:f8ff:fe21:67cf/128 and destination network: 0:0:aa::/64

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:

This function translates an IP/network into the same representation that iptables or ip6tables uses upon listing a policy. The first example shows an IPv4 network and how iptables lists it, and the second is an IPv6 network:

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":

The IPTables::ChainMgr extension is closely associated with the IPTables::Parse extension, and both are heavily used by the psad and fwsnort projects to manipulate iptables policies based on various criteria (see the psad(8) and fwsnort(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 IPTables::ChainMgr extension was written by Michael Rash <mbr@cipherdyne.org> to support the psad and fwsnort projects. Please send email to this address if there are any questions, comments, or bug reports.