nftables

Manages a single nftables rule inside an existing chain, identified by its canonical text (family + table + chain + rule). Idempotent: re-applying an unchanged declaration reports no change.

Category: Firewall (base)

States

State	Meaning
`present`	The chain contains a rule whose canonical text equals `rule`; appended, or inserted at `index` when set.
`absent`	The chain contains no rule whose text equals `rule`; all matching rules are deleted.

Parameters

Parameter	Type	Required	Description
`table`	string	yes	Existing table the chain lives in (the module does not create tables).
`chain`	string	yes	Existing chain to manage the rule in (the module does not create chains).
`rule`	list	yes	The rule expression only — match + statement, no verb/family/table/chain, e.g. `tcp dport 22 accept`. A string is whitespace-split; a list of args is used as-is. Write it in nft’s canonical form.
`family`	string		Address family: one of `ip`, `ip6`, `inet`, `arp`, `bridge`, `netdev`. Default: `inet`.
`index`	int		0-based insert position (`nft insert rule … index N`); omit to append. State `present` only.
`save`	string		Absolute path; after a change, `nft list ruleset` output is written there.

Examples

Allow inbound SSH

nftables:
  allow-ssh:
    state: present
    table: filter
    chain: input
    rule: tcp dport 22 accept

Insert a rule at the top of the chain and persist the ruleset

index: 0 inserts before existing rules; save dumps the full ruleset after the change.

nftables:
  drop-bad-source:
    state: present
    family: ip
    table: filter
    chain: input
    rule: ip saddr 10.0.0.0/8 drop
    index: 0
    save: /etc/nftables.conf

Remove a rule

nftables:
  remove-telnet:
    state: absent
    table: filter
    chain: input
    rule: tcp dport 23 accept

Notes

Linux only (nft-native); the nft-native sibling of the iptables module — the two manage different rulesets and do not coordinate.
Rule matching compares against nft’s canonical rendering (what nft list chain prints), so write rule in canonical form — e.g. tcp dport ssh accept will not match a stored tcp dport 22 accept and would be re-added every run.
The chain and table must already exist; the module creates neither, nor manages base-chain hooks/priority/policy, sets, maps, or flowtables.
index and order management: the module never moves an existing rule. index only affects where a new rule is inserted; it is rejected with state absent.
Out of scope (planned, #115): structured rule params, rule ordering/re-placement, table/chain management, and matching by handle or comment.

iptables security