Chain

The Chain class provides access to a chain’s rules with methods to enumerate rules, find rules based on match and/or target, create new rules, delete existing rules. Chain instances also provide access to the number of packets/bytes that have traversed a chain by appropriately aggregating the per-rule statistics provided by iptables(8).

BuiltinChain is a subclass of Chain that additionally provides access to the policy-related attributes of builtin chains.

---

class Chain(chain_name: str)

This class is used to represent an iptables chain. A chain contains a list of rules which can be referenced by number (rule numbers start with 1).

A Chain instance is iterable, returning the chain’s rules.

The Chain class supports the standard len() function returning the number of rules in the chain.

The Chain class supports integer-based indexing (slices are not supported). Positive integers are interpreteted as rule numbers, i.e. indexing starts at 1. Index 0 will raise an IndexError. Negative index values are supported with -1 identifying the last rule, -2 identifying the penultimate rule, etc.

Parameters:

chain_name – real chain name

is_builtin() → bool

Returns True if this is a built-in chain (e.g. INPUT)

has_rules() → bool

Returns True if the chain contains any rules (note that a Chain instance can also be used directly in a boolean content; if empty, it evaluates to False).

get_reference_count() → int

Returns the reference count of a (non-builtin) chain; returns 0 for builtin chains

get_packet_count() → int

Returns the packet count of the chain

get_byte_count() → int

Returns the byte count of the chain

get_real_name() → str

Returns the real chain name

get_logical_name() → str

Returns the logical chain name

has_unparsed_rules() → bool

Returns True if the chain contains unparsed rules

get_unparsed_rule_count() → int

Returns the number of unparsed rules

get_rule_count() → int

Returns the number of rules in the chain (note that the standard len() function is also supported)

get_rules() → List[ChainRule]

Returns a list that contains the chain rules.

iter_rules(*, chain_target=False, uses_goto=False, match_count: Optional[int] = None, match: Optional[Match] = None) → Iterator[ChainRule]

Returns an iterator for the chain rules. The rules returned by the iterator depend on the arguments:

Parameters:

• chain_target – if True, return rules where the target is a chain

• uses_goto – if True, return rules that use goto

• match_count – if not None, return rules that have that number of matches

• match – if not None, return rules that have a matching Match in their match list; if the match has no criteria set, it will match any :class:Match instance of the same class

find_rule_by_target_lcn(logical_chain_name: str) → List[ChainRule]

Return a list of rules with the specified chain as a target

Parameters:

logical_chain_name – identifies the chain targeted by the rule

find_rule_by(*, match: Optional[Match] = None, is_only_match=True, target: Optional[Target] = None) → List[ChainRule]

Return a list of ChainRule objects where the rule contains the specified match object or has the specified target (target comparison is by name). If both match and target are specified, returned rules must satisfy both criteria. If no match or target is present, an empty list is returned.

Parameters:

• match – Match object to compare against; if match is None, do not perform any match comparisons; if match is a MatchNone object, this will match a rule that has no matches

• is_only_match – if True the specified match must be the only match used in the rule

• target – Target object to compare against; if target is None, do not perform any target comparisons; if target is a TargetNone object, this will match a rule that has no target

get_pft() → IptablesPacketFilterTable

Returns the IptablesPacketFilterTable where this chain belongs

flush() → None

Delete all rules from this chain

append_rule(rule: ChainRule) → None

Append the new rule at the end of the chain

Raises an IptablesError if the rule is already part of a chain

insert_rule(rule: ChainRule, rulenum=0) → None

Insert the new rule at the beginning of the chain (by default) or as rule number rulenum.

Raises an IptablesError if the rule is already part of a chain

Parameters:

• rule – the ChainRule to insert

• rulenum – rule number (starting with 1) for the inserted rule

delete_rule(rule: ChainRule) → None

Delete the specified rule.

Raises an IptablesError if the rule is not part of this chain.

delete_rulenum(rulenum: int) → None

Delete the rule with the specified rule number

Raises an IptablesError if the number is invalid

Parameters:

rulenum – rule number (numbering starts from 1)

delete_rule_by_pred(pred: Callable[[ChainRule], bool]) → int

Delete all rules for which pred returns True.

Parameters:

pred – a Callable object

Return type:

number of deleted rules

delete_rule_if(*, match: Optional[Match] = None, target: Optional[Target] = None) → int

Delete all rules with the specified match and/or target. If no match or target is present, this is a no-op.

Parameters:

• match – Match object to compare against; the comparison will be successful if this is the only match used in the rule; if match is None, do not perform any match comparisons; if match is a MatchNone object, this will match a rule that has no matches

• target – Target object to compare against; if target is None, do not perform any target comparisons; if target is a TargetNone object, this will match a rule that has no target

Return type:

number of deleted rules

delete_rule_by_target_chain(chain: Chain) → int

Delete all rules that jump/goto the specified chain.

Parameters:

chain – a Chain object

Return type:

number of deleted rules

zero_counters() → None

Zero the packet and byte counters of this chain in the kernel.

classmethod create_from_existing(line_list: List[str], pft: IptablesPacketFilterTable, log_parsing_failures=True) → Chain

Parse a set of lines from the output of iptables -xnv into a Chain object.

It raises an IptablesParsingError if there is a parsing error.

Parameters:

• line_list – list of iptables(8) output lines

• pft – an IptablesPacketFilterTable object

• log_parsing_failures – if True, log any parsing failures

Return type:

a Chain object

---

class BuiltinChain(chain_name, policy: Target, packet_count: int, byte_count: int)

Bases: Chain

This class is used to represent an iptables built-in chain.

Instances of this class are not intended to be created by the user; they are created when processing the output of iptables(8)

Parameters:

• chain_name – builtin chain name

• policy – chain policy target

• packet_count – number of packets that were processed according to the policy

• byte_count – number of bytes for packets that were processed according to the policy

static is_builtin() → bool

Return type:

always returns True

get_policy() → Target

Returns the policy target of this builtin chain

get_policy_packet_count() → int

Returns the number of packets that were handled as per the chain policy

get_policy_byte_count() → int

Returns the number of bytes that were handled as per the chain policy

set_policy(policy: Target) → None

Set the policy target of this builtin chain