1IPTables::ChainMgr(3) User Contributed Perl DocumentationIPTables::ChainMgr(3)
2
6 IPTables::ChainMgr - Perl extension for manipulating iptables policies
7
9 use IPTables::ChainMgr;
10 my %opts = (
12 'iptables' => '/sbin/iptables',
13 'iptout' => '/tmp/iptables.out',
14 'ipterr' => '/tmp/iptables.err',
15 'debug' => 0,
16 'verbose' => 0
17 ### advanced options
19 'ipt_alarm' => 5, ### max seconds to wait for iptables execution.
20 'ipt_exec_style' => 'waitpid', ### can be 'waitpid',
21 ### 'system', or 'popen'.
22 'ipt_exec_sleep' => 1, ### add in time delay between execution of
23 ### iptables commands (default is 0).
24 );
25 my $ipt_obj = new IPTables::ChainMgr(%opts)
27 or die "[*] Could not acquire IPTables::ChainMgr object";
28 my $rv = 0;
30 my $out_ar = [];
31 my $errs_ar = [];
32 # check to see if the 'CUSTOM' chain exists in the filter table
34 ($rv, $out_ar, $errs_ar) = $ipt_obj->chain_exists('filter', 'CUSTOM');
35 if ($rv) {
36 print "CUSTOM chain exists.\n";
37 ### flush all rules from the chain
39 $ipt_obj->flush_chain('filter', 'CUSTOM');
40 ### now delete the chain (along with any jump rule in the
42 ### INPUT chain)
43 $ipt_obj->delete_chain('filter', 'INPUT', 'CUSTOM');
44 }
45 # create new iptables chain in the 'filter' table
47 $ipt_obj->create_chain('filter', 'CUSTOM');
48 # add rule to jump packets from the INPUT chain into CUSTOM at the
50 # 4th rule position
51 $ipt_obj->add_jump_rule('filter', 'INPUT', 4, 'CUSTOM');
52 # find rule that allows all traffic from 10.1.2.3 to 192.168.1.2
54 ($rv, $rule_num) = $ipt_obj->find_ip_rule('10.1.2.3', '192.168.1.2',
55 'filter', 'INPUT', 'ACCEPT', {});
56 # find rule that allows all TCP port 80 traffic from 10.1.2.3 to
58 # 192.168.1.1
59 ($rv, $rule_num) = $ipt_obj->find_ip_rule('10.1.2.3', '192.168.1.2',
60 'filter', 'INPUT', 'ACCEPT', {'protocol' => 'tcp', 's_port' => 0,
61 'd_port' => 80});
62 # add rule at the 5th rule position to allow all traffic from
64 # 10.1.2.3 to 192.168.1.2 via the INPUT chain in the filter table
65 ($rv, $out_ar, $errs_ar) = $ipt_obj->add_ip_rule('10.1.2.3',
66 '192.168.1.2', 5, 'filter', 'INPUT', 'ACCEPT', {});
67 # add rule at the 4th rule position to allow all traffic from
69 # 10.1.2.3 to 192.168.1.2 over TCP port 80 via the CUSTOM chain
70 # in the filter table
71 ($rv, $out_ar, $errs_ar) = $ipt_obj->add_ip_rule('10.1.2.3',
72 '192.168.1.2', 4, 'filter', 'CUSTOM', 'ACCEPT',
73 {'protocol' => 'tcp', 's_port' => 0, 'd_port' => 80});
74 # append rule at the end of the CUSTOM chain in the filter table to
76 # allow all traffic from 10.1.2.3 to 192.168.1.2 via port 80
77 ($rv, $out_ar, $errs_ar) = $ipt_obj->append_ip_rule('10.1.2.3',
78 '192.168.1.2', 'filter', 'CUSTOM', 'ACCEPT',
79 {'protocol' => 'tcp', 's_port' => 0, 'd_port' => 80});
80 # run an arbitrary iptables command and collect the output
82 ($rv, $out_ar, $errs_ar) = $ipt_obj->run_ipt_cmd(
83 '/sbin/iptables -v -n -L');
84
86 The "IPTables::ChainMgr" package provide an interface to manipulate
87 iptables policies on Linux systems through the direct execution of
88 iptables commands. Although making a perl extension of libiptc
89 provided by the iptables project is possible (and has been done by the
90 IPTables::libiptc module available from CPAN), it is also easy enough
91 to just execute iptables commands directly in order to both parse and
92 change the configuration of the policy. Further, this simplifies
93 installation since the only external requirement is (in the spirit of
94 scripting) to be able to point IPTables::ChainMgr at an installed
95 iptables binary instead of having to compile against a library.
96
98 The IPTables::ChainMgr extension provides an object interface to the
99 following functions:
100 chain_exists($table, $chain)
102 This function tests whether or not a chain (e.g. 'INPUT') exists
103 within the specified table (e.g. 'filter'). This is most useful to
104 test whether a custom chain has been added to the running iptables
105 policy. The return values are (as with many IPTables::ChainMgr
106 functions) an array of three things: a numeric value, and both the
107 stdout and stderr of the iptables command in the form of array
108 references. So, an example invocation of the chain_exists()
109 function would be:
110 ($rv, $out_ar, $errs_ar) = $ipt_obj->chain_exists('filter', 'CUSTOM');
112 If $rv is 1, then the CUSTOM chain exists in the filter table, and
114 0 otherwise. The $out_ar array reference contains the output of
115 the command "/sbin/iptables -t filter -v -n -L CUSTOM", which will
116 contain the rules in the CUSTOM chain (if it exists) or nothing (if
117 not). The $errs_ar array reference contains the stderr of the
118 iptables command.
119 create_chain($table, $chain)
121 This function creates a chain within the specified table. Again,
122 three return values are given like so:
123 ($rv, $out_ar, $errs_ar) = $ipt_obj->create_chain('filter', 'CUSTOM');
125 Behind the scenes, the create_chain() function in the example above
127 runs the iptables command "/sbin/iptables -t filter -N CUSTOM".
128 flush_chain($table, $chain)
130 This function flushes all rules from chain in the specified table,
131 and three values are returned:
132 ($rv, $out_ar, $errs_ar) = $ipt_obj->flush_chain('filter', 'CUSTOM');
134 The flush_chain() function in the example above executes the
136 iptables command "/sbin/iptables -t filter -F CUSTOM"
137 delete_chain($table, $jump_from_chain, $chain)
139 This function deletes a chain from the specified table along with
140 any jump rule to which packets are jumped into this chain:
141 ($rv, $out_ar, $errs_ar) = $ipt_obj->delete_chain('filter', 'INPUT', 'CUSTOM');
143 Internally a check is performed to see whether the chain exists
145 within the table, and global jump rules are removed from the jump
146 chain before deletion (a chain cannot be deleted until there are no
147 references to it). In the example above, the CUSTOM chain is
148 deleted after any jump rule to this chain from the INPUT chain is
149 also deleted.
150 find_ip_rule($src, $dst, $table, $chain, $target, %extended_info)
152 This function parses the specified chain to see if there is a rule
153 that matches the $src, $dst, $target, and (optionally) any
154 %extended_info criteria. The return values are the rule number in
155 the chain (or zero if it doesn't exist), and the total number of
156 rules in the chain. Below are two examples; the first is to find
157 an ACCEPT rule for 10.1.2.3 to communicate with 192.168.1.2 in the
158 INPUT chain, and the second is the same except that the rule is
159 restricted to TCP port 80:
160 ($rulenum, $chain_rules) = $ipt_obj->find_ip_rule('10.1.2.3',
162 '192.168.1.2', 'filter', 'INPUT', 'ACCEPT', {});
163 if ($rulenum) {
164 print "matched rule $rulenum out of $chain_rules rules\n";
165 }
166 ($rulenum, $chain_rules) = $ipt_obj->find_ip_rule('10.1.2.3',
168 '192.168.1.2', 'filter', 'INPUT', 'ACCEPT',
169 {'protocol' => 'tcp', 's_port' => 0, 'd_port' => 80});
170 if ($rulenum) {
171 print "matched rule $rulenum out of $chain_rules rules\n";
172 }
173 add_ip_rule($src, $dst, $rulenum, $table, $chain, $target,
175 %extended_info)
176 This function inserts a rule into the running iptables chain and
177 table at the specified rule number. Return values are success or
178 failure along with the iptables stdout and stderr.
179 append_ip_rule($src, $dst, $table, $chain, $target, %extended_info)
181 This function appends a rule at the end of the iptables chain in
182 the specified table. Return values are success or failure along
183 with the iptables stdout and stderr.
184 delete_ip_rule($src, $dst, $table, $chain, $target, %extended_info)
186 This function searches for and then deletes a matching rule within
187 the specified chain. Return values are success or failure along
188 with the iptables stdout and stderr.
189 add_jump_rule($table, $from_chain, $rulenum, $to_chain)
191 This function adds a jump rule (after making sure it doesn't
192 already exist) into the specified chain. The $rulenum variable
193 tells the function where within the calling chain the new jump rule
194 should be placed. Here is an example to force all packets
195 regardless of source or destination to be jumped to the CUSTOM
196 chain from the INPUT chain at rule 4:
197 ($rv, $out_ar, $errs_ar) = $ipt_obj->add_jump_rule('filter', 'INPUT', 4, 'CUSTOM');
199 run_ipt_cmd($cmd)
201 This function is a generic work horse function for executing
202 iptables commands, and is used internally by IPTables::ChainMgr
203 functions. It can also be used by a script that imports the
204 IPTables::ChainMgr extension to provide a consistent mechanism for
205 executing iptables. Three return values are given: success (1) or
206 failure (0) of the iptables command (yes, this backwards from the
207 normal exit status of Linux/*NIX binaries), and array references to
208 the iptables stdout and stderr. Here is an example to list all
209 rules in the user-defined chain "CUSTOM":
210 ($rv, $out_ar, $errs_ar) = $ipt_obj->run_ipt_cmd('/sbin/iptables -t filter -v -n -L CUSTOM');
212 if ($rv) {
213 print "rules:\n";
214 print for @$out_ar;
215 }
216
218 The IPTables::ChainMgr extension is closely associated with the
219 IPTables::Parse extension, and both are heavily used by the psad,
220 fwsnort, and fwknop projects to manipulate iptables policies based on
221 various criteria (see the psad(8), fwsnort(8), and fwknop(8) man
222 pages). As always, the iptables(8) man page provides the best
223 information on command line execution and theory behind iptables.
224 Although there is no mailing that is devoted specifically to the
226 IPTables::ChainMgr extension, questions about the extension will be
227 answered on the following lists:
228 The psad mailing list: http://lists.sourceforge.net/lists/listinfo/psad-discuss
230 The fwknop mailing list: http://lists.sourceforge.net/lists/listinfo/fwknop-discuss
231 The fwsnort mailing list: http://lists.sourceforge.net/lists/listinfo/fwsnort-discuss
232 The latest version of the IPTables::ChainMgr extension can be found at:
234 http://www.cipherdyne.org/modules/
236
238 Thanks to the following people:
239 Franck Joncourt <franck.mail@dthconnex.com>
241 Grant Ferley
242 Darien Kindlund
243
245 The IPTables::ChainMgr extension was written by Michael Rash
246 <mbr@cipherdyne.org> to support the psad, fwknop, and fwsnort projects.
247 Please send email to this address if there are any questions, comments,
248 or bug reports.
249
251 Copyright (C) 2005-2008 by Michael Rash
252 This library is free software; you can redistribute it and/or modify it
254 under the same terms as Perl itself, either Perl version 5.8.5 or, at
255 your option, any later version of Perl 5 you may have available.
256perl v5.12.0 2009-02-12 IPTables::ChainMgr(3)