Skip to main content

nftables

Knocknoc integrates with nftables to dynamically control network access on a Linux host. When a user authenticates, their IP address is added to an nftables named set, and removed again when their access ends. Your own rules reference that set with @setname to protect a service.

The agent runs on the host itself, so no remote access or API credentials are needed. Use nftables instead of IPSet on hosts that use nftables natively, including anything fronted by firewalld or shorewall-nft.

Knocknoc only changes the contents of the set you nominate. It never adds, removes, or reorders rules, so your filtering policy stays yours.

Requirements

  • The Knocknoc agent installed and running on the nftables host.
  • nftables installed, version 0.9.0 or later.
  • nftables enabled for Knocknoc with knocker enable nftables.
  • One or more named sets in your nftables configuration, and rules that reference them.

Set Names

nftables identifies a set by family, table, and name, so Knocknoc references a set by its full name:

<family>:<table>:<set>

A set knock4 in table myfilter of family inet is inet:myfilter:knock4. Each part may contain only letters, digits, and _ . -.

A set holds one address family, so you nominate an IPv4 set and an IPv6 set separately. They do not have to be in the same table.

Setup

Step 1: Install the Agent

Deploy the Knocknoc orchestration agent on the host running nftables. It connects out to the Knocknoc server over WebSocket and needs no inbound port.

Step 2: Enable nftables for Knocknoc

On the host, run:

knocker enable nftables
knocker status nftables

enable prepares the host, and status confirms it. It also creates a few sets in table inet knocknoc (knoc_ssh_v4, knoc_ssh_v6, knoc_http_v4, knoc_http_v6) as working examples, if you would rather not declare your own to start with.

Step 3: Declare Your Set and Rules

Declare the sets you want Knocknoc to manage in your nftables configuration (for example /etc/nftables.conf), so they are restored at boot, and add rules that match on them with @setname. For example, to protect SSH:

table inet myfilter {
	set knock4 {
		type ipv4_addr
		flags interval, timeout
	}

	set knock6 {
		type ipv6_addr
		flags interval, timeout
	}

	chain input {
		type filter hook input priority filter; policy drop;
		ct state established,related accept
		ip saddr @knock4 tcp dport 22 accept
		ip6 saddr @knock6 tcp dport 22 accept
	}
}
Flag Effect
interval Lets the set hold CIDR ranges. Without it, only single addresses are stored.
timeout Lets each entry carry an expiry time, so access is withdrawn on time even if the host cannot reach the Knocknoc server. Recommended.
auto-merge Not supported. It merges entries into ranges, so individual addresses can no longer be managed. Sets using it are not offered.

Interval sets cannot hold overlapping entries: with 10.0.0.0/24 already in the set, adding 10.0.0.5 is rejected. If your users can be allowed overlapping ranges, use a set without flags interval, which stores each address on its own.

Apply the configuration:

nft -c -f /etc/nftables.conf   # validate
nft -f /etc/nftables.conf      # apply

Step 4: Create the Knoc

  1. In the Knoc wizard, under I want to protect..., choose Linux, *BSD, Solaris, HP-UX.

  2. Select the agent on the nftables host, then choose the nftables named sets (Linux) option.

    If the nftables option is unavailable, run knocker status nftables on the host.

  3. Enter your set names in IPv4 Set Name and IPv6 Set Name, as family:table:set (e.g. inet:myfilter:knock4). The wizard lists the sets it found on the host. At least one of the two is required.

  4. Use Validate connection to check the sets, then save.

Step 5: Assign Users and Test

  1. Assign users and/or groups to the Knoc.

  2. Log in as a test user.

  3. Confirm the IP appears in the set:

    nft list set inet myfilter knock4

  4. Verify access through the service the rule protects.

  5. On logout, or when the user's access expires, confirm the IP is removed.

Troubleshooting

No Sets Listed for the Agent

Confirm the sets exist right now with nft list sets. A set declared in a file that has not been applied since the last reboot will not be there. Sets using auto-merge are never listed.

IP Added but Access Still Blocked

  1. Confirm a rule references the set with @setname, in a chain that sees the traffic.
  2. Check rule ordering: an earlier drop in the same chain wins.
  3. Check the family, hook, interface, protocol, and port match the traffic.
  4. An IPv6 client is matched only by the IPv6 set.

Entries Disappear After a Reboot or Ruleset Reload

nftables sets live in the kernel ruleset, so a reboot or a flush ruleset (which a stock /etc/nftables.conf starts with) removes them. Declare your sets in a file that is applied at boot, after anything that flushes.

nftables Documentation References

Back to top