跳至主要内容

Bootstrap a router host declaratively

routerd can describe most first-boot host preparation in the router YAML. The goal is not to replace an installer, but to keep the router-specific drift out of ad hoc shell history.

Package dependencies​

Use Package for OS packages that routerd controllers and managed helper daemons need.

apiVersion: system.routerd.net/v1alpha1
kind: Package
metadata:
  name: router-service-dependencies
spec:
  packages:
    - os: ubuntu
      manager: apt
      names:
        - dnsmasq
        - nftables
        - conntrack
        - kmod
        - wireguard-tools
        - tailscale

Kernel modules​

Use KernelModule for Linux kernel modules that must be loaded before firewall, conntrack, WireGuard, or NFLOG integrations become useful.

apiVersion: system.routerd.net/v1alpha1
kind: KernelModule
metadata:
  name: router-kernel-modules
spec:
  modules:
    - nf_conntrack
    - nfnetlink_log
    - wireguard
  runtime: true
  persistent: true
  optional: true

On Ubuntu and Debian, runtime: true runs modprobe and persistent: true writes /etc/modules-load.d/90-routerd-<name>.conf. On NixOS, routerd records the resource as declarative-only because modules should be owned by the NixOS configuration. On FreeBSD, the resource is reported as unsupported.

Sysctl profile​

Use SysctlProfile for forwarding, conntrack accounting, and router-oriented kernel defaults. Override only the values that differ from the profile.

apiVersion: system.routerd.net/v1alpha1
kind: SysctlProfile
metadata:
  name: router-runtime
spec:
  profile: router-linux
  runtime: true
  persistent: true
  overrides:
    net.netfilter.nf_conntrack_udp_timeout: "60"

Existing host networking​

Use NetworkAdoption when the base OS already has DHCP or resolver behavior that conflicts with routerd's resource model. It is the documented place for networkd and resolved drop-ins instead of one-off edits under /etc/systemd.

Use SystemdUnit for explicit local units that should be installed and enabled by routerd. routerd-managed DHCP, DNS, PPPoE, healthcheck, Tailscale, and helper daemon units are generated from their own resource kinds; do not duplicate those units manually unless you are intentionally adopting a local service.

Apply order​

For a remote router, keep the operational order conservative:

  1. Install the routerd binaries and a minimal config.
  2. Validate the full config.
  3. Run a dry-run apply.
  4. Confirm management interface and SSH are protected.
  5. Apply.
  6. Verify routerctl status, forwarding, DNS, and the Web Console.