README.md

Introduction

About python-iptables

Iptables is the tool that is used to manage netfilter, the
standard packet filtering and manipulation framework under Linux. As the
iptables manpage puts it:

Iptables is used to set up, maintain, and inspect the tables of IPv4
packet filter rules in the Linux kernel. Several different tables may
be defined.

Each table contains a number of built-in chains and may also contain
user- defined chains.

Each chain is a list of rules which can match a set of packets. Each
rule specifies what to do with a packet that matches. This is called a
target, which may be a jump to a user-defined chain in the same table.

Python-iptables provides a pythonesque wrapper via python bindings to
iptables under Linux. Interoperability with iptables is achieved via
using the iptables C libraries (libiptc, libxtables, and the
iptables extensions), not calling the iptables binary and parsing its
output. It is meant primarily for dynamic and/or complex routers and
firewalls, where rules are often updated or changed, or Python programs
wish to interface with the Linux iptables framework..

If you are looking for ebtables python bindings, check out
python-ebtables.

Python-iptables supports Python 2.6, 2.7 and 3.4.

Installing via pip

The usual way:

pip install --upgrade python-iptables

Compiling from source

First make sure you have iptables installed (most Linux distributions
install it by default). Python-iptables needs the shared libraries
libiptc.so and libxtables.so coming with iptables, they are
installed in /lib on Ubuntu.

You can compile python-iptables in the usual distutils way:

% cd python-iptables
% python setup.py build

If you like, python-iptables can also be installed into a
virtualenv:

% mkvirtualenv python-iptables
% python setup.py install

If you install python-iptables as a system package, make sure the
directory where distutils installs shared libraries is in the dynamic
linker's search path (it's in /etc/ld.so.conf or in one of the files
in the folder /etc/ld.co.conf.d). Under Ubuntu distutils by default
installs into /usr/local/lib.

Now you can run the tests:

% sudo PATH=$PATH ./test.py
WARNING: this test will manipulate iptables rules.
Don't do this on a production machine.
Would you like to continue? y/n y
[...]

The PATH=$PATH part is necessary after sudo if you have installed
into a virtualenv, since sudo will reset your environment to a
system setting otherwise..

Once everything is in place you can fire up python to check whether the
package can be imported:

% sudo PATH=$PATH python
>>> import iptc
>>>

Of course you need to be root to be able to use iptables.

Using a custom iptables install

If you are stuck on a system with an old version of iptables, you can
install a more up to date version to a custom location, and ask
python-iptables to use libraries at that location.

This creates a rule that will match TCP packets coming in on eth0, with
a source IP address of 192.168.1.0/255.255.255.0.

A rule may contain matches and a target. A match is like a filter
matching certain packet attributes, while a target tells what to do with
the packet (drop it, accept it, transform it somehow, etc). One can
create a match or target via a Rule:

Match and target parameters can be changed after creating them. It is
also perfectly valid to create a match or target via instantiating them
with their constructor, but you still need a rule and you have to add
the matches and the target to their rule manually:

However, when a match or a target takes multiple parameter values, that
needs to be passed in as a list. Let's assume you have created and set
up an ipset called blacklist via the ipset command. To create a
rule with a match for this set:

Note how this time a list was used for the parameter value, since the
set match match_set parameter expects two values. See the iptables
manpages to find out what the extensions you use expect. See
ipset for more information.

When you are ready constructing your rule, add them to the chain you
want it to show up in:

To instantiate a target or match, we can either create an object like
above, or use the rule.create_target(target_name) and
rule.create_match(match_name) methods. For example, in the code above
target could have been created as:

>>> target = rule.create_target("DROP")

instead of:

>>> target = iptc.Target(rule, "DROP")
>>> rule.target = target

The former also adds the match or target to the rule, saving a call.

Another example, using a target which takes parameters. Let's mark
packets going to 192.168.1.2 UDP port 1234 with 0xffff:

Autocommit

Python-iptables by default automatically performs an iptables commit
after each operation. That is, after you add a rule in
python-iptables, that will take effect immediately.

It may happen that you want to batch together certain operations. A
typical use case is traversing a chain and removing rules matching a
specific criteria. If you do this with autocommit enabled, after the
first delete operation, your chain's state will change and you have to
restart the traversal. You can do something like this: