netpolicyd

What it is

netpolicyd holds a desired network configuration for a Linux host — routes, policy rules, addresses, firewall, NAT, traffic control and sysctls — and applies it with ip, nft, tc and sysctl. netpolicyctl is its control panel: a terminal UI with an easy mode and an advanced mode, plus a CLI.

What it manages

Surface	Applied with
Policies	High-level ordered rules expanded to ip rule / table routes / NAT
Routes and IP rules	ip route, ip rule
Addresses and links	ip addr, ip link
Firewall and NAT	nftables (masquerade, SNAT, forward helpers)
IP lists	Named CIDR groups, compiled to nft sets
Traffic control	HTB egress shaping and ingress policing
Sysctls	ip_forward, rp_filter, …

It also shows live state: a read-only dump of the host's firewall and routing, and interface rates plus socket inventory from /proc/net/dev and ss.

The apply model

1. Desired objects are written through the API (or replaced in bulk with PUT /v1/desired).
2. POST /v1/apply builds an ordered command plan. ?dry_run=1 returns the same plan without touching the host.
3. The managed firewall is rendered as one nft -f script that declares, deletes and redefines the inet netpolicyd table in a single transaction — no half-applied window, no stacked duplicates. Rules outside that table are left alone.
4. IP lists become named nft sets, not one rule per address, so a large country list is a set lookup instead of thousands of rules.
5. Policy routes live in a priority band netpolicyd owns. Rules in that band that the current generation didn't ask for are pruned — but never when the keep-list is empty, because right after a restart "empty" means "not told yet", not "nothing should exist".

Example: source-based egress

curl -s -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"name":"src-via-gre-lab","priority":10,
       "subjects":[{"kind":"cidr","value":"10.77.0.4/32"}],
       "destination":{"kind":"any","value":"0.0.0.0/0"},
       "action":"egress","egress_name":"gre-lab","source_cidr":"10.77.0.4/32"}' \
  http://127.0.0.1:51910/v1/policies
netpolicyctl apply

This plans an ip rule and a routing table defaulting via gre-lab, plus masquerade out that device unless an explicit NAT already covers it.

Limits

• Desired state is in memory. After a restart something — a control plane or a script — must push it again; kernel state stays until then.
• Live apply needs CAP_NET_ADMIN. Without the ip binary, or with --mock, it only plans.
• Keep the API on loopback or a private management network.

Stack

Go, Bubble Tea for the TUI, nftables, iproute2, tc. Licensed under the GNU AGPL v3.