IPTables::libiptc(3)

💖 IPTables::libiptc — the perl page, but make it make sense 💖

ok so bestie, this is a page from the User Contributed Perl Documentation section of the manual, and it's all about IPTables::libiptc(3). sit down, grab a boba, and let's get into it because this one is genuinely lowkey iconic 🫶

---

✨ NAME ✨

IPTables::libiptc — a Perl extension for iptables libiptc. that's it, that's the name 💅

---

🌸 SYNOPSIS 🌸

look at this, it's giving very much "hello world but make it firewall":

use IPTables::libiptc;

$table = IPTables::libiptc::init('filter');

$table->create_chain("mychain");

# Its important to commit/push-back the changes to the kernel
$table->commit();

ok but fr fr, that comment in the middle? # Its important to commit/push-back the changes to the kernel — that is NOT me being dramatic, that is the actual source code comment, and it is telling you the truth. if you don't commit, your changes just vibe in userspace and never reach the kernel. embarrassing. don't be that girl. 💀

---

🦋 DESCRIPTION 🦋

so this package gives you a perl interface to the netfilter/iptables C-code and the library libiptc. periodt.

why is this module even a thing, you ask? the advantages, bestie, are:

• you can do many rule changes very fast 🔥
• several rule changes get committed atomically — all together, no half-finished nonsense ✨

this module is heavily inspired by the CPAN module IPTables-IPv4. but here's the tea: IPTables-IPv4 could not be used, because it has not been kept up-to-date with the newest iptables extensions. and that's not a skill issue on the maintainer's part, it's a design issue — the module contains every extension, so it needs to port them individually. every single one. exhausting, honestly. 😭

this package takes a whole different approach: it links with the system's libiptc.a library and depends on dynamic loading of iptables extensions available on the system. so whatever extensions your system has, that's what you get. main character energy, adapt to your environment. 💅

the module only exports the libiptc chain manipulation functions. all rule manipulations are done through the iptables.c do_command function. and because iptables.c is not made as a library, the package unfortunately needs to maintain/contain this C file. yeah. it just carries it around. it's a whole thing. 🙈

🌈 Iptables kernel to userspace design 🌈

the reasoning behind making this module comes from how iptables/libiptc communicate with the kernel. so listen:

iptables/libiptc transfers the entire ruleset from kernel to userspace, and back again after making some changes to the ruleset.

that is a fairly large operation if you're only changing a single rule. and ngl, that is actually the behavior of the iptables command.

so with this knowledge, it makes sense to make several changes before commit'ing the changes (the entire ruleset) back to the kernel. and that is exactly the behavior/purpose of this perl module. 🎀

this is also what makes it so very fast for many rule changes. and it gives the property of several rule changes being committed atomically. slay. ✨

---

👑 METHODS 👑

most methods will return 1 for success, or 0 for failure (and on failure, set $! to a string describing the reason for the failure). unless otherwise noted, you can assume that all methods will use this convention. noted. moving on. 💖

💜 Chain Operations 💜

get_policy

my ($policy)                      = $table->get_policy('chainname');
my ($policy, $pkt_cnt, $byte_cnt) = $table->get_policy('chainname');

this returns an array containing the default policy, plus the number of packets and bytes which have reached the default policy, in the chain "chainname". and if "chainname" does not exist, or if it is not a built-in chain, an empty array will be returned, and $! will be set to a string containing the reason. so check your $!, bestie, it's literally telling you what went wrong. 🫶

set_policy

$success = $table->set_policy('chainname', 'target');
$success = $table->set_policy('chainname', 'target', 'pkt_cnt', 'byte_cnt');
($success, $old_policy, $old_pkt_cnt, $old_pkt_cnt) = $table->set_policy('chainname', 'target');

sets the default policy. set_policy can be called several ways. upon successful setting of the policy the old policy and counters are returned. the counter setting values are optional. so if you don't pass counters, cool, you just don't. easy. ✨

create_chain

$success = $table->create_chain('chainname');

makes a chain. that's the whole thing. 💅

is_chain

$success = $table->is_chain('chainname');

checks if the chain exist. (yes, "exist", that's the original wording, we don't fix grammar in manpages, we only fix vibes.) 🌸

buildin

$success = $table->builtin('chainname');

tests if the chainname is a buildin chain. 👀 yes the heading says buildin and the method call says builtin — that's not me, that's just how the page is, and we're keeping every detail exactly as-is because that is the whole assignment. not me being pedantic, me being faithful. 🎀

delete_chain

$success = $table->delete_chain('chainname');

tries to delete the chain, returns false if it could not. sometimes chains just don't want to leave. it's not you, it's the references. 🙈

get_references

$refs = $table->get_references('chainname');

get a count of how many rules reference/jump to this chain. basically a popularity check. how many rules are linking to this chain's post. 💅

🧚 Listing Operations 🧚

list_chains

@array            = $table->list_chains();
$number_of_chains = $table->list_chains();

lists all chains. and in SCALAR context it returns the number of chains. so the same method does two completely different things depending on how you call it, and honestly? iconic behavior. 🔥

list_rules_IPs

@array           = $table->list_rules_IPs('type', 'chainname');
$number_of_rules = $table->list_rules_IPs('type', 'chainname');

this function lists the (rules) source or destination IPs from a given chain. the "type" is either "src" or "dst" for source and destination IPs. the netmask is also listed together with the IPs, but separated by a / character. and if chainname does not exist, undef is returned. so watch out for that undef, bestie, it will not warn you, it will just be undef at you. 😭

⭐ Rules Operations ⭐

no rules manipulation functions is mapped/export from libiptc — instead the iptables do_command function is exported to this purpose. that's the deal. that's the arrangement. 🤝

🌟 Iptables commands (from iptables.h) 🌟

iptables_do_command

$table->iptables_do_command(\@array_ref)

example of an array which contains a command:

my @array = ("-I", "test", "-s", "4.3.2.1", "-j", "ACCEPT");
$table->iptables_do_command(\@array);

look at that. an array ref, passed straight in, doing a full iptables insert. that's the whole vibe. 🫶

---

🌈 EXPORT 🌈

None by default.

💖 Exportable constants 💖

IPT_MIN_ALIGN

that's the one. the whole list. the entire squad. 💅

---

🔥 SEE ALSO 🔥

module source also available here: https://github.com/netoptimizer/CPAN-IPTables-libiptc/

the Netfilter/iptables homepage: http://www.netfilter.org

iptables(8)

go read them, i'll wait. 📚✨

---

🎀 AUTHOR 🎀

Jesper Dangaard Brouer, <hawk@diku.dk> or <hawk@people.netfilter.org>. two emails, because one is never enough when you're the main character. 💌

💫 Authors SVN version information 💫

$LastChangedDate$
$Revision$
$LastChangedBy$

the classic SVN keywords, just sitting there, waiting to be expanded. we love a relic. 🏺

---

👑 COPYRIGHT AND LICENSE 👑

Copyright (C) 2006-2011 by Jesper Dangaard Brouer

this program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

so yeah, it's GPL v2-or-later, bestie. that's the license. respect the license. 🫡

---

💀 POD ERRORS 💀

hey! the above document had some coding errors, which are explained below:

around line 141:

    You forgot a '=back' before '=head1'

around line 206:

    You forgot a '=back' before '=head2'

around line 208:

    '=item' outside of any '=over'

around line 227:

    You forgot a '=back' before '=head2'

around line 235:

    '=item' outside of any '=over'

around line 245:

    You forgot a '=back' before '=head1'

not the POD errors catching strays at the end of the page 😭 but we keep them, because the page has them, and we do not edit the truth. even the messy parts. especially the messy parts. 💅

---

and that's the whole thing, bestie! this page is from perl v5.42.0, dated 2025-07-25, so it's fresh-ish and it's all yours. go commit your ruleset. go make chains. go be the firewall admin you were always meant to be. 🦋💖✨ periodt.