IPTabl...ainMgr(3pm)

📦
version 1.6 · 4 versions
, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu resolute, ubuntu stonking

💖 IPTables::ChainMgr 💖

okay so bestie, buckle up 🎀 this is the manual page for IPTables::ChainMgr, a 3pm-section page — that's "User Contributed Perl Documentation", the part of the man pages where the Perl modules live. It's giving certified banger, fr fr. ✨

🌸 NAME 🌸

IPTables::ChainMgr — a Perl extension for manipulating iptables and ip6tables policies. periodt. 💅

🦋 SYNOPSIS 🦋

okay so first things first, you load the thing and you set up your options. Watch this:

use IPTables::ChainMgr;

my $ipt_bin = '/usr/sbin/iptables'; # can set this to /usr/sbin/ip6tables

my %opts = (
    'use_ipv6' => 0,         # can set to 1 to force ip6tables usage
    'ipt_rules_file' => '',  # optional file path from
                             # which to read iptables rules
    '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 = IPTables::ChainMgr->new(%opts)
    or die "[*] Could not acquire IPTables::ChainMgr object";

my $rv = 0;
my $out_ar = [];
my $errs_ar = [];

quick vibe check on that: $ipt_bin is your binary, and you can point it at /usr/sbin/ip6tables if you're feeling IPv6 today. The use_ipv6 option can be flipped to 1 to force ip6tables usage, ipt_rules_file is an optional file path to read iptables rules from, and then there's debug, verbose, plus the advanced girlies: ipt_alarm (max seconds to wait for iptables execution, default 5), ipt_exec_style ('waitpid', 'system', or 'popen'), and ipt_exec_sleep (a delay between iptables commands — default is 0). no cap. 💜

Then you make the object, and if new fails you die with [*] Could not acquire IPTables::ChainMgr object. And you keep three little variables around: $rv, $out_ar, $errs_ar. Those three are your besties for literally every call. 🫶

🧚 Checking, flushing, deleting, policy-ing 🧚

# 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');
}

# set the policy on the FORWARD table to DROP
$ipt_obj->set_chain_policy('filter', 'FORWARD', 'DROP');

# create new iptables chain in the 'filter' table
$ipt_obj->create_chain('filter', 'CUSTOM');

# translate a network into the same representation that iptables or
# ip6tables uses (e.g. '10.1.2.3/24' is properly represented as '10.1.2.0/24',
# and '0000:0000:00AA:0000:0000:AA00:0000:0001/64' = '0:0:aa::/64')
$normalized_net = $ipt_obj->normalize_net('10.1.2.3/24');

# 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');

So chain_exists('filter', 'CUSTOM') asks "is CUSTOM chillin' in the filter table?" If $rv says yes, you flush_chain('filter', 'CUSTOM') to yeet all its rules, then delete_chain('filter', 'INPUT', 'CUSTOM') to delete the chain and any jump rule to it in INPUT. The way that set_chain_policy('filter', 'FORWARD', 'DROP') just sets the FORWARD table policy to DROP? iconic. create_chain('filter', 'CUSTOM') spins up a brand new chain. normalize_net translates a network into the exact representation iptables or ip6tables uses — '10.1.2.3/24' comes out as '10.1.2.0/24', and '0000:0000:00AA:0000:0000:AA00:0000:0001/64' becomes '0:0:aa::/64'. And add_jump_rule('filter', 'INPUT', 4, 'CUSTOM') drops a jump from INPUT into CUSTOM at the 4th rule position. slay. 🔥

🍓 Finding and adding IP rules 🍓

# find rule that allows all traffic from 10.1.2.0/24 to 192.168.1.2
($rule_num, $chain_rules) = $ipt_obj->find_ip_rule('10.1.2.0/24', '192.168.1.2',
    'filter', 'INPUT', 'ACCEPT', {'normalize' => 1});

# find rule that allows all TCP port 80 traffic from 10.1.2.0/24 to
# 192.168.1.1
($rule_num, $chain_rules) = $ipt_obj->find_ip_rule('10.1.2.0/24', '192.168.1.2',
    'filter', 'INPUT', 'ACCEPT', {'normalize' => 1, 'protocol' => 'tcp',
    's_port' => 0, 'd_port' => 80});

# add rule at the 5th rule position to allow all traffic from
# 10.1.2.0/24 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.0/24',
    '192.168.1.2', 5, 'filter', 'INPUT', 'ACCEPT', {});

# add rule at the 4th rule position to allow all traffic from
# 10.1.2.0/24 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.0/24',
    '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.0/24 to 192.168.1.2 via port 80
($rv, $out_ar, $errs_ar) = $ipt_obj->append_ip_rule('10.1.2.0/24',
    '192.168.1.2', 'filter', 'CUSTOM', 'ACCEPT',
    {'protocol' => 'tcp', 's_port' => 0, 'd_port' => 80});

find_ip_rule gives you back ($rule_num, $chain_rules) — the rule number and the chain's rules — and you can pass a hashref of extras like {'normalize' => 1}, or add 'protocol' => 'tcp', 's_port' => 0, 'd_port' => 80 for the TCP port 80 girlies. Note that the second find_ip_rule example is for "all TCP port 80 traffic from 10.1.2.0/24 to 192.168.1.1" per the comment, with 192.168.1.2 in the actual call — copying the example exactly, bestie, don't @ me. 😭

add_ip_rule takes the source, the destination, the rule position, the table, the chain, the target, and a hashref of extras — {} if you have nothing to add. append_ip_rule is the same shape but it appends at the end of the chain instead of at a position. Both hand you back ($rv, $out_ar, $errs_ar). 💅

🌈 The ip6tables analogs 🌈

# for each of the examples above, here are ip6tables analogs
# (requires instantiating the IPTables::ChainMgr object with
# /usr/sbin/ip6tables): find rule that allows all traffic from fe80::200:f8ff:fe21:67cf
# to 0:0:aa::/64
($rule_num, $chain_rules) = $ipt_obj->find_ip_rule('fe80::200:f8ff:fe21:67cf', '0:0:aa::/64',
    'filter', 'INPUT', 'ACCEPT', {'normalize' => 1});

# find rule that allows all TCP port 80 traffic from fe80::200:f8ff:fe21:67c to 0:0:aa::/64
($rule_num, $chain_rules) = $ipt_obj->find_ip_rule('fe80::200:f8ff:fe21:67cf', '0:0:aa::/64',
    'filter', 'INPUT', 'ACCEPT', {'normalize' => 1, 'protocol' => 'tcp',
    's_port' => 0, 'd_port' => 80});

# add rule at the 5th rule position to allow all traffic from
# fe80::200:f8ff:fe21:67c to 0:0:aa::/64 via the INPUT chain in the filter table
($rv, $out_ar, $errs_ar) = $ipt_obj->add_ip_rule('fe80::200:f8ff:fe21:67cf',
    '0:0:aa::/64', 5, 'filter', 'INPUT', 'ACCEPT', {});

# add rule at the 4th rule position to allow all traffic from
# fe80::200:f8ff:fe21:67c to 0:0:aa::/64 over TCP port 80 via the CUSTOM chain
# in the filter table
($rv, $out_ar, $errs_ar) = $ipt_obj->add_ip_rule('fe80::200:f8ff:fe21:67cf',
    '0:0:aa::/64', 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 fe80::200:f8ff:fe21:67c to 0:0:aa::/64 via port 80
($rv, $out_ar, $errs_ar) = $ipt_obj->append_ip_rule('fe80::200:f8ff:fe21:67cf',
    '0:0:aa::/64', 'filter', 'CUSTOM', 'ACCEPT',
    {'protocol' => 'tcp', 's_port' => 0, 'd_port' => 80});

same energy, different address family ✨ — these are the ip6tables analogs of everything above, and they need you to instantiate the IPTables::ChainMgr object with /usr/sbin/ip6tables. 🦋

👑 One arbitrary command, because why not 👑

# run an arbitrary iptables command and collect the output
($rv, $out_ar, $errs_ar) = $ipt_obj->run_ipt_cmd(
        '/usr/sbin/iptables -v -n -L');

run_ipt_cmd runs literally whatever command you hand it and collects the output back into ($rv, $out_ar, $errs_ar). main character energy. 🎀

💖 DESCRIPTION 💖

The IPTables::ChainMgr package provides an interface to manipulate iptables and ip6tables policies on Linux systems through the direct execution of iptables/ip6tables commands. 💅

Also, plot twist: the 'firewalld' infrastructure on Fedora21 is also supported, through execution of the 'firewall-cmd' binary. 🫶

So, could you make a Perl extension of libiptc provided by the Netfilter project? Sure — it's possible, and it has been done, by the IPTables::libiptc module available from CPAN. But it is also easy enough to just execute iptables/ip6tables commands directly in order to both parse and change the configuration of the policy. 😌

And the bonus: this simplifies installation, because 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. no compiling era, we love to see it. 🌈

✨ FUNCTIONS ✨

The IPTables::ChainMgr extension hands you an object interface to these functions, bestie: 💅

chain_exists($table, $chain) 🕵️‍♀️

Okay so this one checks if a chain (like 'INPUT') exists inside the table you picked (like 'filter'). It's the vibe check for custom chains — did someone already add it to the running iptables/ip6tables policy? Like, is it there or not?

The return values are, like with so many IPTables::ChainMgr functions, an array of three things: a numeric value, plus both the stdout and stderr of the iptables or ip6tables command as array references. Example invocation:

($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 "/usr/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 "/usr/sbin/ip6tables -t filter -v -n -L CUSTOM".

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 "/usr/sbin/iptables -t filter -N CUSTOM", or for ip6tables "/usr/sbin/ip6tables -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 command "/usr/sbin/iptables -t filter -F CUSTOM" or "/usr/sbin/ip6tables -t filter -F CUSTOM".

set_chain_policy($table, $chain, $target) 👑

This function sets the policy of a built-in chain (iptables/ip6tables does not allow this for non built-in chains) to the specified target:

($rv, $out_ar, $errs_ar) = $ipt_obj->set_chain_policy('filter', 'FORWARD', 'DROP');

In this example, the following command is executed behind the scenes: "/usr/sbin/iptables -t filter -P FORWARD DROP" or "/usr/sbin/ip6tables -t filter -P FORWARD DROP".

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

($rulenum, $chain_rules) = $ipt_obj->find_ip_rule('10.1.2.0/24',
    '192.168.1.2', 'filter', 'INPUT', 'ACCEPT', {'normalize' => 1});
if ($rulenum) {
    print "matched rule $rulenum out of $chain_rules rules\n";
}
($rulenum, $chain_rules) = $ipt_obj->find_ip_rule('10.1.2.0/24',
    '192.168.1.2', 'filter', 'INPUT', 'ACCEPT',
    {'normalize' => 1, 'protocol' => 'tcp', 's_port' => 0, 'd_port' => 80});
if ($rulenum) {
    print "matched rule $rulenum out of $chain_rules rules\n";
}
($rulenum, $chain_rules) = $ipt_obj->find_ip_rule('fe80::200:f8ff:fe21:67cf/128',
  '0:0:aa::/64', 'filter', 'INPUT', 'ACCEPT', {'normalize' => 1});
if ($rulenum) {
    print "matched rule $rulenum out of $chain_rules rules\n";
}
($rulenum, $chain_rules) = $ipt_obj->find_ip_rule('fe80::200:f8ff:fe21:67cf/128',
    '0:0:aa::/64', 'filter', 'INPUT', 'ACCEPT',
    {'normalize' => 1, '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');

normalize_net($net) 🪄

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:

print $ipt_obj->normalize_net('10.1.2.3/24'), "\n" # prints '10.1.2.0/24'
print $ipt_obj->normalize_net('0000:0000:00AA:0000:0000:AA00:0000:0001/64'), "\n" # prints '0:0:aa::/64'

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('/usr/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 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 latest version of the IPTables::ChainMgr extension can be found on CPAN and also here:

Source control is provided by git:

🫶 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 and fwsnort projects. Please send email to this address if there are any questions, comments, or bug reports.

Copyright (C) 2005-2015 Michael Rash. All rights reserved.

This module is free software. You can redistribute it and/or modify it under the terms of the Artistic License 2.0. More information can be found here: http://www.perl.com/perl/misc/Artistic.html

This program is distributed "as is" in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.

That's a wrap, bestie 💅 — this page came from perl v5.30.3 on 2020-10-08, and the page is IPTabl...ainMgr(3pm). Stay iconic! 🎀

📦 where this page comes from