The python API in python-iptables tries to mimic the logic of iptables. You have
- Tables, TABLE_FILTER, TABLE_NAT and TABLE_MANGLE. They can be used to filter packets, do network address translation or modify packets in various ways.
- Chains inside tables. Each table has a few built-in chains, but you can also create your own chains and jump into them from other chains. When you create your chains you should also specify which table it will be used in.
- Each chain has zero or more rules. A rule specifies what kind of packets to match (matches, each rule can have zero, one or more matches) and what to do with them (target, each rule has one of them). Iptables implements a plethora of match and target extensions.
- Matches, specifying when a rule needs to be applied to a packet. To create a match object you also has to specify the rule to which it belongs.
- Targets, specifying what to do when a rule is applied to a packet. To create a target object you also has to specify the rule to which it belongs.
The python API is quite high-level and hides the low-level details from the user. Using only the classes Table, Chain, Rule, Match and Target virtually anything can be achieved that you can do with iptables from the command line.
A table is the most basic building block in iptables.
The interface provided by Table is rather low-level, in fact it maps to libiptc API calls one by one, and take low-level iptables structs as parameters. It is encouraged to use Chain, Rule, Match and Target to achieve what is wanted instead, since they hide the low-level details from the user.
name is the name of the table, if it already exists it is returned. autocommit specifies that any iptables operation that changes a rule, chain or table should be committed immediately.
Returns True if chain is a built-in chain.
List of chains in the table.
Close the underlying connection handle to iptables.
Commit any pending operation.
Returns the first rule in chain or None if it is empty.
Flush and delete all non-builtin chains the table.
Returns the standard target in entry.
Returns True if chain exists as a chain.
Returns the next rule after prev_rule.
Commit any pending operation and refresh the status of iptables.
Returns any pending iptables error from the previous operation.
Rules are contained by chains.
iptables has built-in chains for every table, and users can also create additional chains. Rule targets can specify to jump into another chain and continue processing its rules, or return to the caller chain.
table is the table this chain belongs to, name is the chain’s name.
If a chain already exists with name in table it is returned.
Append rule to the end of the chain.
Delete chain from its table.
Removes rule from the chain.
Flush all rules from the chain.
This method returns a tuple pair of the packet and byte counters of the chain.
Returns the policy of the chain.
This method returns the target of rule if it is a standard target, or None if it is not.
Insert rule as the first entry in the chain if position is 0 or not specified, else rule is inserted in the given position.
Returns whether the chain is a built-in one.
Rename chain to new_name.
This is the list of rules currently in the chain.
Set the chain policy to policy. If counters is not None, the chain counters are also adjusted.
This method zeroes the packet and byte counters of the chain.
If the end of a built-in chain is reached or a rule in a built-in chain with target RETURN is matched, the target specified by the chain policy determines the fate of the packet.
Matches are extensions which can match for special header fields or other attributes of a packet.
Target and match extensions in iptables have parameters. These parameters are implemented as instance attributes in python. However, to make the names of parameters legal attribute names they have to be converted. The rule is to cut the leading double dash from the name, and replace dashes in parameter names with underscores so they are accepted by python as attribute names. E.g. the TOS target has parameters –set-tos, –and-tos, –or-tos and –xor-tos; they become target.set_tos, target.and_tos, target.or_tos and target.xor_tos, respectively. The value of a parameter is always a string, if a parameter does not take any value in the iptables extension, an empty string “” should be used.
rule is the Rule object this match belongs to; it can be changed later via set_rule(). name is the name of the iptables match extension (in lower case), match is the raw buffer of the match structure if the caller has it. Either name or match must be provided. revision is the revision number of the extension that should be used; different revisions use different structures in C and they usually only work with certain kernel versions.
This is the C structure used by the extension.
This is the buffer holding the C structure used by the extension.
Reset the match.
Parameters are set to their default value, any flags are cleared.
This is the full size of the underlying C structure.
This is the size of the part of the underlying C structure that is used in userspace.
Targets specify what to do with a packet when a match is found while traversing the list of rule entries in a chain.
Target and match extensions in iptables have parameters. These parameters are implemented as instance attributes in python. However, to make the names of parameters legal attribute names they have to be converted. The rule is to cut the leading double dash from the name, and replace dashes in parameter names with underscores so they are accepted by python as attribute names. E.g. the TOS target has parameters –set-tos, –and-tos, –or-tos and –xor-tos; they become target.set_tos, target.and_tos, target.or_tos and target.xor_tos, respectively. The value of a parameter is always strings, if a parameter does not take any value in the iptables extension, an empty string “” should be used.
rule is the Rule object this match belongs to; it can be changed later via set_rule(). name is the name of the iptables target extension (in upper case), target is the raw buffer of the target structure if the caller has it. Either name or target must be provided. revision is the revision number of the extension that should be used; different revisions use different structures in C and they usually only work with certain kernel versions.
Reset the match. Parameters are set to their default value, any flags are cleared.
This is the full size of the underlying C structure.
This attribute is used for standard targets. It can be set to ACCEPT, DROP, RETURN or to a name of a chain the rule should jump into.
This is the C structure used by the extension.
This is the buffer holding the C structure used by the extension.
This is the size of the part of the underlying C structure that is used in userspace.
Rules are entries in chains.
entry is the ipt_entry buffer or None if the caller does not have it. chain is the chain object this rule belongs to.
Adds a match to the rule. One can add any number of matches.
This is the destination network address with an optional network mask in string form.
This means that the rule refers to the second and further fragments of fragmented packets. It can be True or False.
This is the input network interface e.g. eth0. A wildcard match can be achieved via + e.g. ppp+ matches any ppp interface.
This is the raw mask buffer as iptables uses it when removing rules.
This is the list of matches held in this rule.
This is the output network interface e.g. eth0. A wildcard match can be achieved via + e.g. ppp+ matches any ppp interface.
This is the transport layer protocol.
Removes match from the list of matches.
This is the raw rule buffer as iptables expects and returns it.
This is the source network address with an optional network mask in string form.
This is the target of the rule.