iptables module¶

Ip6tablesChains ¶

The ip6tables chains and their policies in one table.

Commands:

ip6tables-save -t <table> 2> /dev/null || sudo -n ip6tables-save -t <table> 2> /dev/null || true

Returns:

dict[str, str]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_ip6tables_chains.py.

Ip6tablesPersistence ¶

Whether the live ip6tables rules match a saved snapshot file.

Commands:

sh -c 'live=$( (ip6tables-save 2>/dev/null || sudo -n ip6tables-save 2>/dev/null) | sed '"'"'/^#/d'"'"'); saved=$(sed '"'"'/^#/d'"'"' <path> 2>/dev/null || true); [ -n "$live" ] && [ "$live" = "$saved" ] && echo synced || echo drifted'

Returns:

bool

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_ip6tables_persistence.py.

Ip6tablesRules ¶

The ip6tables rules of one table, as parsed rule definitions.

Commands:

ip6tables-save -t <table> 2> /dev/null || sudo -n ip6tables-save -t <table> 2> /dev/null || true

Returns:

list[IptablesRule]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_ip6tables_rules.py.

Ip6tablesRulesOrdered ¶

The ip6tables rules with line numbers and packet/byte counters.

Commands:

ip6tables -t <table> -L <chain> -n -v -x --line-numbers 2> /dev/null || sudo -n ip6tables -t <table> -L <chain> -n -v -x --line-numbers 2> /dev/null || true

Returns:

list[IptablesOrderedRule]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_ip6tables_rules_ordered.py.

Ip6tablesTables ¶

The ip6tables tables currently loaded in the kernel.

Commands:

cat /proc/net/ip6_tables_names 2>/dev/null || true

Returns:

list[str]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_ip6tables_tables.py.

Ip6tablesVersion ¶

The installed ip6tables release and its legacy-vs-nft backend.

Commands:

ip6tables --version

Returns:

IptablesVersionInfo | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_ip6tables_version.py.

IpSet ¶

Attributes:

Name	Type	Description
`type`		The set's type (`hash:ip`, `hash:net`, `bitmap:port`, ...).
`revision`		The kernel set-type revision number.
`header`		The `Header:` line's creation parameters (`family inet hashsize 1024 maxelem 65536`), as printed.
`size_in_memory`		The set's in-memory size in bytes.
`references`		How many iptables rules reference the set.
`members`		The set's entries, one string per member (`10.0.0.5`, `192.168.0.0/24`, `10.0.0.5,tcp:80`); per-member counters/timeout suffixes are dropped, and an empty set reads [].

IpSets ¶

The ipset containers, their types and their members.

Commands:

ipset list 2> /dev/null || sudo -n ipset list 2> /dev/null || true

Returns:

dict[str, IpSet]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_ip_sets.py.

IptablesChains ¶

The iptables chains and their policies in one table.

Commands:

iptables-save -t <table> 2> /dev/null || sudo -n iptables-save -t <table> 2> /dev/null || true

Returns:

dict[str, str]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_iptables_chains.py.

IptablesModules ¶

The loaded xt_* iptables match/target kernel modules.

Commands:

lsmod | grep '^xt_' || true

Returns:

list[str]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_iptables_modules.py.

IptablesOrderedRule ¶

Attributes:

Name	Type	Description
`chain`		The chain the rule lives in (from the `Chain` header).
`number`		The 1-based rule number within its chain (the `--line-numbers` column).
`packets`		The exact packets counter (`-x`, never K/M-scaled).
`bytes`		The exact bytes counter (`-x`, never K/M-scaled).
`target`		The rule's target column (`ACCEPT`, `DROP`, a user chain, ...).
`protocol`		The protocol column as printed (`tcp`, `udp`, `all`, or a numeric protocol on some releases).
`opt`		The options column, usually `--`.
`in_interface`		The incoming interface column (`*` for any).
`out_interface`		The outgoing interface column (`*` for any).
`source`		The source address/CIDR column (`0.0.0.0/0` for any).
`destination`		The destination address/CIDR column.
`options`		The trailing match/target detail text (`tcp dpt:22`, `ctstate RELATED,ESTABLISHED`, ...), `""` when the row carried none.

IptablesPersistence ¶

Whether the live iptables rules match a saved snapshot file.

Commands:

sh -c 'live=$( (iptables-save 2>/dev/null || sudo -n iptables-save 2>/dev/null) | sed '"'"'/^#/d'"'"'); saved=$(sed '"'"'/^#/d'"'"' <path> 2>/dev/null || true); [ -n "$live" ] && [ "$live" = "$saved" ] && echo synced || echo drifted'

Returns:

bool

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_iptables_persistence.py.

IptablesRule ¶

Attributes:

Name	Type	Description
`chain`		The chain the rule lives in (the `-A` argument).
`jump`		The rule's target (the `-j` argument), when the line carried one.
`protocol`		The protocol match (`tcp`, `udp`, ...), when set.
`source`		The source address/CIDR match, when set.
`destination`		The destination address/CIDR match, when set.
`in_interface`		The incoming interface match, when set.
`out_interface`		The outgoing interface match, when set.
`not_protocol`		The negated protocol match (`! -p`), when set.
`not_source`		The negated source match (`! -s`), when set.
`not_destination`		The negated destination match (`! -d`), when set.
`not_in_interface`		The negated incoming interface match, when set.
`not_out_interface`		The negated outgoing interface match, when set.
`log_prefix`		The LOG target's `--log-prefix` value, when set.
`to_destination`		The DNAT target's `--to-destination` value, when set.
`to_source`		The SNAT target's `--to-source` value, when set.
`to_ports`		The REDIRECT target's `--to-ports` value, when set.
`extras`		Every unmapped flag as sorted `[flag, value]` pairs (`-m` modules, `--dport`, `--comment`, `--log-level`, ...), absent when the rule carried none.

IptablesRules ¶

The iptables rules of one table, as parsed rule definitions.

Commands:

iptables-save -t <table> 2> /dev/null || sudo -n iptables-save -t <table> 2> /dev/null || true

Returns:

list[IptablesRule]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_iptables_rules.py.

IptablesRulesOrdered ¶

The iptables rules with line numbers and packet/byte counters.

Commands:

iptables -t <table> -L <chain> -n -v -x --line-numbers 2> /dev/null || sudo -n iptables -t <table> -L <chain> -n -v -x --line-numbers 2> /dev/null || true

Returns:

list[IptablesOrderedRule]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_iptables_rules_ordered.py.

IptablesTables ¶

The iptables tables currently loaded in the kernel.

Commands:

cat /proc/net/ip_tables_names 2>/dev/null || true

Returns:

list[str]

Raises:

HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_iptables_tables.py.

IptablesVersion ¶

The installed iptables release and its legacy-vs-nft backend.

Commands:

iptables --version

Returns:

IptablesVersionInfo | None

Raises:

CommandNotFoundError, HostConnectionError

Examples:

Examples can be found in examples/modules/iptables/iptables_iptables_version.py.

IptablesVersionInfo ¶

Attributes:

Name	Type	Description
`version`		The iptables release string, as printed after the `v` (e.g. `1.8.9`).
`backend`		The packet-filtering backend the binary drives: `nf_tables` or `legacy`. A release too old to print a parenthesized backend reads `legacy` (the nft backend arrived in 1.8).

chain `async` ¶

chain(
    ctx: OpContext,
    chain: str,
    present: bool = True,
    table: str = "filter",
    policy: str | None = None,
    version: int = 4,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add, remove or update an iptables chain.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`chain`	`str`	The name of the chain to manage.	required
`present`	`bool`	Whether the chain should exist. Defaults to True.	`True`
`table`	`str`	The iptables table the chain belongs to. Defaults to "filter".	`'filter'`
`policy`	`str \| None`	The policy the chain should have (built-in chains only -- the kernel rejects `-P` on user chains). Defaults to None.	`None`
`version`	`int`	Whether to target iptables (4) or ip6tables (6). Defaults to 4.	`4`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated iptables chain commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/iptables/iptables_chain.py.

flush `async` ¶

flush(
    ctx: OpContext,
    chain: str | None = None,
    table: str = "filter",
    version: int = 4,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Flush the rules of one chain, or of every chain in a table.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`chain`	`str \| None`	The chain to flush; None flushes every chain of the table. Defaults to None.	`None`
`table`	`str`	The iptables table to flush. Defaults to "filter".	`'filter'`
`version`	`int`	Whether to target iptables (4) or ip6tables (6). Defaults to 4.	`4`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated iptables flush commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/iptables/iptables_flush.py.

ipset `async` ¶

ipset(
    ctx: OpContext,
    set_name: str,
    set_type: str = "hash:ip",
    entries: tuple[str, ...] = (),
    present: bool = True,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Manage an ipset container and its members.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`set_name`	`str`	The name of the set to manage.	required
`set_type`	`str`	The set type used when creating it (`hash:ip`, `hash:net`, `hash:ip,port`, ...). An existing set of a different type raises `ValueError` rather than silently recreating it. Defaults to "hash:ip".	`'hash:ip'`
`entries`	`tuple[str, ...]`	The member entries to add (`present=True`) or remove (`present=False`); with `present=False` and no entries the whole set is destroyed. Membership is additive -- entries not listed are left alone. Defaults to ().	`()`
`present`	`bool`	Whether the set (and the listed entries) should exist. Defaults to True.	`True`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated ipset commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/iptables/iptables_ipset.py.

policy `async` ¶

policy(
    ctx: OpContext,
    chain: str,
    policy: str,
    table: str = "filter",
    version: int = 4,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Set the default policy of a built-in iptables chain.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`chain`	`str`	The built-in chain whose policy to set (`INPUT`, `FORWARD`, `OUTPUT`, `PREROUTING`, `POSTROUTING` -- which exist depends on the table).	required
`policy`	`str`	The policy target: `ACCEPT`, `DROP`, `QUEUE` or `RETURN`.	required
`table`	`str`	The iptables table the chain belongs to. Defaults to "filter".	`'filter'`
`version`	`int`	Whether to target iptables (4) or ip6tables (6). Defaults to 4.	`4`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated iptables policy commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/iptables/iptables_policy.py.

restore `async` ¶

restore(
    ctx: OpContext,
    path: str,
    version: int = 4,
    noflush: bool = False,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Atomically load iptables rules from a snapshot file on the host.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`path`	`str`	The host-side iptables-restore format file to load (upload it with `files.put` first when it lives on the controller).	required
`version`	`int`	Whether to restore iptables (4) or ip6tables (6) rules. Defaults to 4.	`4`
`noflush`	`bool`	Whether to append the file's rules without flushing the existing ones (`iptables-restore -n`). Defaults to False.	`False`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated iptables-restore commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/iptables/iptables_restore.py.

rule `async` ¶

rule(
    ctx: OpContext,
    chain: str,
    jump: str,
    present: bool = True,
    table: str = "filter",
    append: bool = True,
    version: int = 4,
    position: int | None = None,
    protocol: str | None = None,
    not_protocol: str | None = None,
    source: str | None = None,
    not_source: str | None = None,
    destination: str | None = None,
    not_destination: str | None = None,
    in_interface: str | None = None,
    not_in_interface: str | None = None,
    out_interface: str | None = None,
    not_out_interface: str | None = None,
    to_destination: str | None = None,
    to_source: str | None = None,
    to_ports: int | str | None = None,
    log_prefix: str | None = None,
    log_level: int | str | None = None,
    destination_port: int | None = None,
    source_port: int | None = None,
    destination_ports: tuple[int | str, ...] = (),
    source_ports: tuple[int | str, ...] = (),
    ctstate: tuple[str, ...] = (),
    limit: str | None = None,
    limit_burst: int | None = None,
    match_set: tuple[str, str] | None = None,
    comment: str | None = None,
    extras: str = "",
    **kwargs: Any,
) -> AsyncGenerator[Command]

Add or remove an iptables rule, with typed match extensions.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`chain`	`str`	The chain this rule should live in.	required
`jump`	`str`	The target of the rule (`ACCEPT`, `DROP`, `LOG`, `DNAT`, a user chain, ...).	required
`present`	`bool`	Whether the rule should exist. Defaults to True.	`True`
`table`	`str`	The iptables table this rule belongs to. Defaults to "filter".	`'filter'`
`append`	`bool`	Whether to append (True) or insert at the top (False) when adding the rule. Defaults to True.	`True`
`version`	`int`	Whether to target iptables (4) or ip6tables (6). Defaults to 4.	`4`
`position`	`int \| None`	The 1-based line number to insert a new rule at (overrides `append`); an existing rule is never repositioned. Defaults to None.	`None`
`protocol`	`str \| None`	Filter by protocol (`tcp`, `udp`, ...; case-insensitive). Defaults to None.	`None`
`not_protocol`	`str \| None`	Negated protocol filter. Defaults to None.	`None`
`source`	`str \| None`	Filter by source address/CIDR. Defaults to None.	`None`
`not_source`	`str \| None`	Negated source filter. Defaults to None.	`None`
`destination`	`str \| None`	Filter by destination address/CIDR. Defaults to None.	`None`
`not_destination`	`str \| None`	Negated destination filter. Defaults to None.	`None`
`in_interface`	`str \| None`	Filter by incoming interface. Defaults to None.	`None`
`not_in_interface`	`str \| None`	Negated incoming interface filter. Defaults to None.	`None`
`out_interface`	`str \| None`	Filter by outgoing interface. Defaults to None.	`None`
`not_out_interface`	`str \| None`	Negated outgoing interface filter. Defaults to None.	`None`
`to_destination`	`str \| None`	Where to route when `jump="DNAT"` (requires `table="nat"`). Defaults to None.	`None`
`to_source`	`str \| None`	Where to route when `jump="SNAT"` (requires `table="nat"`). Defaults to None.	`None`
`to_ports`	`int \| str \| None`	Where to route when `jump="REDIRECT"` (requires `table="nat"`). Defaults to None.	`None`
`log_prefix`	`str \| None`	Log prefix when `jump="LOG"`. Defaults to None.	`None`
`log_level`	`int \| str \| None`	Syslog level when `jump="LOG"` (0-7 or a level name). Defaults to None.	`None`
`destination_port`	`int \| None`	Destination port shortcut (requires `protocol`). Defaults to None.	`None`
`source_port`	`int \| None`	Source port shortcut (requires `protocol`). Defaults to None.	`None`
`destination_ports`	`tuple[int \| str, ...]`	Multiport destination match, e.g. `(80, 443)` or `("8000:9000",)` (requires `protocol`). Defaults to ().	`()`
`source_ports`	`tuple[int \| str, ...]`	Multiport source match (requires `protocol`). Defaults to ().	`()`
`ctstate`	`tuple[str, ...]`	Conntrack state match, e.g. `("ESTABLISHED", "RELATED")`. Defaults to ().	`()`
`limit`	`str \| None`	Rate limit match, e.g. `"50/sec"` or `"10/min"`. Defaults to None.	`None`
`limit_burst`	`int \| None`	Burst allowance for `limit` (requires `limit`). Defaults to None.	`None`
`match_set`	`tuple[str, str] \| None`	An ipset match as `(set_name, direction)` where direction is `src`, `dst` or a comma combination (e.g. `("blacklist", "src")`); manage the set with `iptables.ipset`. Defaults to None.	`None`
`comment`	`str \| None`	Rule comment (the `comment` match -- the reliable idempotency/auditing marker). Defaults to None.	`None`
`extras`	`str`	Raw iptables extension arguments for anything the typed parameters do not cover (e.g. `"-m physdev --physdev-in eth0"`). Defaults to "".	`''`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated iptables rule commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/iptables/iptables_rule.py.

save `async` ¶

save(
    ctx: OpContext,
    path: str | None = None,
    version: int = 4,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Persist the live iptables rules to a snapshot file on the host.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`path`	`str \| None`	The host-side file to write; None picks `/etc/iptables/rules.v4` (version 4) or `/etc/iptables/rules.v6` (version 6), the iptables-persistent locations. Defaults to None.	`None`
`version`	`int`	Whether to save iptables (4) or ip6tables (6) rules. Defaults to 4.	`4`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	Generated iptables-save commands.

Raises:

HostConnectionError, ValueError

Examples:

Examples can be found in examples/modules/iptables/iptables_save.py.

zero `async` ¶

zero(
    ctx: OpContext,
    chain: str | None = None,
    table: str = "filter",
    version: int = 4,
    **kwargs: Any,
) -> AsyncGenerator[Command]

Zero the packet and byte counters of one chain, or of a whole table.

Parameters:

Name	Type	Description	Default
`ctx`	`OpContext`	Execution context for the operation.	required
`chain`	`str \| None`	The chain whose counters to zero; None zeroes every chain of the table. Defaults to None.	`None`
`table`	`str`	The iptables table to zero. Defaults to "filter".	`'filter'`
`version`	`int`	Whether to target iptables (4) or ip6tables (6). Defaults to 4.	`4`
`**kwargs`	`Any`	Additional keyword arguments.	`{}`

Yields:

Name	Type	Description
`Command`	`AsyncGenerator[Command]`	The iptables zero command, always (the operation is
	`AsyncGenerator[Command]`	stateless).

Raises:

ValueError

Examples:

Examples can be found in examples/modules/iptables/iptables_zero.py.

iptables module¶

Ip6tablesChains ¶

Ip6tablesPersistence ¶

Ip6tablesRules ¶

Ip6tablesRulesOrdered ¶

Ip6tablesTables ¶

Ip6tablesVersion ¶

IpSet ¶

IpSets ¶

IptablesChains ¶

IptablesModules ¶

IptablesOrderedRule ¶

IptablesPersistence ¶

IptablesRule ¶

IptablesRules ¶

IptablesRulesOrdered ¶

IptablesTables ¶

IptablesVersion ¶

IptablesVersionInfo ¶

chain async ¶

flush async ¶

ipset async ¶

policy async ¶

restore async ¶

rule async ¶

save async ¶

zero async ¶

chain `async` ¶

flush `async` ¶

ipset `async` ¶

policy `async` ¶

restore `async` ¶

rule `async` ¶

save `async` ¶

zero `async` ¶