Typed, topology-driven edge routing and deterministic failover.
A pure NixOS framework for high-throughput edge gateways, stateful Netfilter packet filtering, and dual-node VRRP failover on commodity x86_64 and aarch64 hardware. Zero mutable runtime state.
The 4-Stage Synthesis Pipeline
Rather than mutating system state via web forms or disjoint scripts, configurations are compiled deterministically from a single typed topology definition.
Typed Topology
Physical interfaces, subnets, VLANs, and zone assignments are declared once as strict Nix expressions. Evaluation-time assertions detect subnet collisions and invalid MTUs before build time.
Derived Subsystems
Netfilter chains, Kea lease pools, Technitium DNS zones, and CAKE qdiscs are generated automatically. Cross-subsystem addressing drift is mathematically impossible.
Immutable Closures
Build outputs produce bit-reproducible NixOS generations. Deployments via deploy-rs execute
automated canary checks with instantaneous rollback on network connectivity loss.
Dataplane Offload
Established TCP/UDP streams enter FastTrack flowtables, bypassing Netfilter evaluation. Hardware offloads and multi-queue SMP IRQ distribution balance line-rate traffic across CPU cores.
Reference High-Availability Topology
Dual-node active/passive failover evaluated on production homelab hardware: virtualized primary with Intel 2.5GbE paired with a bare-metal standby with Intel 10GbE SFP+.
Physical Wiring & Layer-2 Interconnect
VRRP Heartbeat Expiry
Keepalived detects 3 consecutive missed VRRP advertisements on the internal LAN link and transitions to MASTER.
VIP Ownership & ARP
Floating IP 10.10.10.1 is assigned to the standby LAN interface; gratuitous ARPs update switch MAC tables.
Golden MAC Ingress
Standby WAN link transitions from always-down to active, assuming the cloned ISP MAC to acquire the lease.
DNS & DDNS Promotion
Technitium secondary zones are promoted to Primary via local API hooks, restoring authoritative DDNS updating.
Comparative Analysis: Linux/NixOS vs. BSD Stacks
A technical evaluation of subsystem primitives, operational predictability, and dataplane performance against FreeBSD appliances (OPNsense/pfSense) and vanilla OpenBSD.
| Subsystem | nix-router-optimized (Linux) | OPNsense / pfSense (FreeBSD) | Vanilla OpenBSD |
|---|---|---|---|
| State & Config Model | Pure Nix expressions; typed schema evaluation; cryptographic store paths; zero mutable runtime drift. |
Imperative PHP web UI modifying monolithic on-disk config.xml database.
|
Plaintext flat files (/etc/pf.conf, hostname.if*); manual sync.
|
| Deployment & Rollback |
Atomic generations; immediate bootloader rollback; deploy-rs automated canary checks.
|
In-place package updates; rollback requires ZFS boot environments or full disk backups. | Manual system backups; kernel rollback via boot prompt. |
| Packet Filter Engine |
Netfilter (nftables) with FastTrack flowtables (L4 connection tracking bypass).
|
FreeBSD pf (derived from OpenBSD pf, rewritten for multi-core SMP).
|
OpenBSD pf (cleanest syntax, strict single-threaded state evaluation).
|
| Dataplane Offloading | Kernel flowtables; NIC ring buffer tuning; eBPF / XDP hook support. | Standard kernel packet path; no native XDP or flowtable bypass equivalent. | Standard kernel packet path; strict security-first architecture. |
| High Availability | Keepalived (VRRP RFC 5798) with preemption delays and single-active unit scripts. | CARP (IP Protocol 112) integrated with FreeBSD kernel. |
CARP + ifstated state machine daemons.
|
| Connection State Sync |
conntrackd (FTFW protocol, unicast or multicast).
|
pfsync (multicast kernel state replication).
|
pfsync (standard reference implementation).
|
| Hardware Scaling | Explicit MSI-X SMP affinity, RPS, XPS, and CPU core pinning across queues. | Driver-dependent interrupt handling; multi-threaded kernel network stack. | Historically single-lock network stack; bounded multi-gigabit throughput. |
Production Gateway Examples
Copyable NixOS configurations demonstrating core gateway topologies, high availability, and zone security.
# Single Gateway with FastTrack flowtables, Kea DHCP, and Unbound { inputs, ... }: { imports = [ inputs.router-optimized.nixosModules.router-networking inputs.router-optimized.nixosModules.router-dhcp inputs.router-optimized.nixosModules.router-dns-service inputs.router-optimized.nixosModules.router-firewall inputs.router-optimized.nixosModules.router-optimizations ]; services.router-networking = { enable = true; wan.device = "eth0"; routedInterfaces.lan = { device = "eth1"; ipv4Address = "192.168.1.1/24"; dns = [ "192.168.1.1" ]; ipv6SendRA = true; }; }; services.router-dhcp.enable = true; services.router-dns-service = { enable = true; provider = "unbound"; }; services.router-firewall.enable = true; services.router-optimizations = { enable = true; interfaces = { wan = { device = "eth0"; role = "wan"; bandwidth = "1Gbit"; }; lan = { device = "eth1"; role = "lan"; }; }; }; }
# Dual-Node VRRP Pair with ISP Golden MAC Spoofing { services.router-ha = { enable = true; role = "master"; # Configured as "backup" on standby node virtualIp = "10.10.10.1/16"; # Floating LAN gateway IP vrrpInterface = "enp6s16"; # Dedicated LAN link vrrpPasswordFile = "/run/agenix/vrrp-password"; # Systemd credential outside store preemptDelay = 300; # Wait 300s after reboot before claiming VIP wan = { enable = true; interface = "enp6s17"; clonedMac = "02:76:c6:01:2a:b0"; # Cloned ISP modem lease MAC }; singleActiveUnits = [ "kea-dhcp4-server.service" "inadyn.service" ]; }; }
# Declarative Netfilter Zone Security Matrix { services.router-zones = { enable = true; zones = { wan.interfaces = [ "wan0" ]; lan.interfaces = [ "lan0" ]; iot.interfaces = [ "lan0.30" ]; dmz.interfaces = [ "lan0.50" ]; }; policies = [ { fromZone = "lan"; toZone = "wan"; action = "accept"; } { fromZone = "iot"; toZone = "wan"; action = "accept"; } { fromZone = "iot"; toZone = "lan"; action = "drop"; } # Isolate IoT subnet { fromZone = "dmz"; toZone = "lan"; action = "drop"; } ]; }; }
# Composable PPPoE Uplink with Secret Decoupling { services.router-networking = { enable = true; wan.device = "ppp0"; wan.manageWithNetworkd = false; }; services.router-pppoe = { enable = true; physicalDevice = "enp1s0"; interfaceName = "ppp0"; username = "fiber-user@isp.net"; credentialsFile = "/run/secrets/pppoe.conf"; # Decrypted in RAM, out of store }; services.router-firewall.tcpMssClamp.enable = true; }
Framework Module Index
38+ composable NixOS modules spanning core networking, packet filtering, high availability, and telemetry.
systemd-networkd driver for WAN DHCP/static, IPv6 Prefix Delegation (/56), and routed downstream interfaces.
Dual-node VRRP high availability with Golden MAC cloning, preemption delays, and single-active unit orchestration.
Role-aware nftables policy engine with FastTrack flowtables, SIP-friendly bypass, hairpin NAT, and bogon filters.
Declarative zone security matrix (WAN, LAN, IoT, DMZ) with high-level cross-zone traffic allowances and drops.
Technitium DNS integration with automated API token creation, TSIG AXFR secondary replication, and DoH/DoT.
ISC Kea DHCPv4 server with RFC 2136/TSIG dynamic DNS registration, option 108 (IPv6-mostly), and HA hooks.
NIC offload negotiation (TSO/GSO/GRO), ring buffer expansion, and symmetric multi-queue SMP IRQ affinity.
Subnet router and exit node automation with declarative route advertisements and firewall policy wiring.
Kernel WireGuard tunnels for site-to-site mesh topologies and roadwarrior VPN access with declarative peers.
Passive AF_PACKET sensor wrapper for Suricata IDS with EveBox interface, plus Snort 3 and Zeek integrations.
Lightweight status monitoring on port 8888 showing interface throughput, active connections, and tunnel status.
Declarative DNS ad-blocking presets (Hagezi, OISD, StevenBlack) with automated 24h cron updates.