nix-router-optimized NixOS 24.11 / Unstable
Modular NixOS Routing Engine

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.

Netfilter / nftables FastTrack Flowtables VRRP (RFC 5798) ISC Kea DHCPv4/v6 Technitium TSIG CAKE SQM Multi-Queue SMP IRQ
Deterministic Compilation

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.

Stage 01

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.

Stage 02

Derived Subsystems

Netfilter chains, Kea lease pools, Technitium DNS zones, and CAKE qdiscs are generated automatically. Cross-subsystem addressing drift is mathematically impossible.

Stage 03

Immutable Closures

Build outputs produce bit-reproducible NixOS generations. Deployments via deploy-rs execute automated canary checks with instantaneous rollback on network connectivity loss.

Stage 04

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.

Redundant Architecture

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

Primary: Active Path
Standby: Passive Path
Heartbeat / Sync
ISP Cable Modem Single Dynamic Lease (Golden MAC) Unmanaged L2 WAN Switch PRIMARY: router (VM) WAN: enp6s17 (Active, Golden MAC) LAN: enp6s16 (VIP 10.10.10.1/16) ✓ Kea DHCPv4 Server (Active) ✓ IPv6 SendRA + TSIG Primary DNS ✓ FastTrack Flowtable Active ✓ VRRP MASTER (Priority 150) STANDBY: elitedesk (BM) WAN: enp1s0f0 (always-down) LAN: enp1s0f1 (10.10.10.4/16) ⚠ Kea DHCP Disabled (Manual) ⚠ IPv6 RA Suppressed ✓ Secondary DNS (AXFR Replicated) ✓ VRRP BACKUP (Priority 100) VRRP + conntrackd Managed L2 Switch (LAN Subnets 10.10.0.0/16)
Event 01

VRRP Heartbeat Expiry

Keepalived detects 3 consecutive missed VRRP advertisements on the internal LAN link and transitions to MASTER.

Event 02

VIP Ownership & ARP

Floating IP 10.10.10.1 is assigned to the standby LAN interface; gratuitous ARPs update switch MAC tables.

Event 03

Golden MAC Ingress

Standby WAN link transitions from always-down to active, assuming the cloned ISP MAC to acquire the lease.

Event 04

DNS & DDNS Promotion

Technitium secondary zones are promoted to Primary via local API hooks, restoring authoritative DDNS updating.

Architectural Tradeoffs

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.
Read Full Technical Report (FREEBSD-OPNSENSE-COMPARISON.md) →
Flake Specifications

Production Gateway Examples

Copyable NixOS configurations demonstrating core gateway topologies, high availability, and zone security.

configuration.nix
# 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;
}
Composable Architecture

Framework Module Index

38+ composable NixOS modules spanning core networking, packet filtering, high availability, and telemetry.

router-networking
Core

systemd-networkd driver for WAN DHCP/static, IPv6 Prefix Delegation (/56), and routed downstream interfaces.

router-ha
Core

Dual-node VRRP high availability with Golden MAC cloning, preemption delays, and single-active unit orchestration.

router-firewall
Packet Filter

Role-aware nftables policy engine with FastTrack flowtables, SIP-friendly bypass, hairpin NAT, and bogon filters.

router-zones
Packet Filter

Declarative zone security matrix (WAN, LAN, IoT, DMZ) with high-level cross-zone traffic allowances and drops.

router-technitium
DNS

Technitium DNS integration with automated API token creation, TSIG AXFR secondary replication, and DoH/DoT.

router-kea
DHCP

ISC Kea DHCPv4 server with RFC 2136/TSIG dynamic DNS registration, option 108 (IPv6-mostly), and HA hooks.

router-optimizations
Core

NIC offload negotiation (TSO/GSO/GRO), ring buffer expansion, and symmetric multi-queue SMP IRQ affinity.

router-tailscale
VPN

Subnet router and exit node automation with declarative route advertisements and firewall policy wiring.

router-wireguard
VPN

Kernel WireGuard tunnels for site-to-site mesh topologies and roadwarrior VPN access with declarative peers.

router-network-security
Packet Filter

Passive AF_PACKET sensor wrapper for Suricata IDS with EveBox interface, plus Snort 3 and Zeek integrations.

router-dashboard
Core

Lightweight status monitoring on port 8888 showing interface throughput, active connections, and tunnel status.

dns-blocklists
DNS

Declarative DNS ad-blocking presets (Hagezi, OISD, StevenBlack) with automated 24h cron updates.