Ubuntu Server router control, declared in YAML

Begin here, in this order

Learn six network words

You only need WAN, LAN, IP address, gateway, DHCP, and DNS for the first lab. The guide explains them without assuming networking experience.

WAN
LAN
DHCP
DNS

Learn the six basics →

Prepare an isolated Ubuntu Server lab

Use a spare VM or host with console access or a separate management NIC. Do not make the first live change on a production or only router.

Ubuntu Server
console access
separate management NIC

Set up the lab →

Write one small router job

Start with interfaces and a narrow LAN service, then add DHCP, DNS, and outbound IPv4 NAT one responsibility at a time.

Interface
DHCPv4Server
NAT44Rule

Build the first router →

FreeBSD and NixOS: groundwork

Install layout and service-manager integration scaffolding exist, but native platform renderers and feature parity are still pending. Start your first router on Ubuntu Server.

Ubuntu Server primary
FreeBSD groundwork
NixOS groundwork

See platform status →

Then make the first safe change

Follow this order. Validation and dry-run do not change the host network. The console apply and daemon can; use a console or independent management path. Use routerctl only after the daemon is running.

Learn the basics

WAN / LAN / DHCP / DNS

Prepare an Ubuntu lab

console / management NIC

Write YAML

router.yaml

Validate only

routerd validate

Isolated dry-run

routerd apply --once --dry-run

Console apply (live)

routerd apply --once

Daemon, then inspect

routerd serve → routerctl

Ubuntu Server: check first, then go live

Install routerd on a spare Ubuntu Server VM or host, place the sample YAML at the path below, and keep a console or independent management path available before the live step.

Read the Ubuntu Server installation guide →

1. Validate the file only

This checks YAML and resource rules. It does not change the host network and does not need routerd to be running.

sudo routerd validate --config /usr/local/etc/routerd/router.yaml

2. Run an isolated dry-run

This uses temporary state, ledger, and status paths while it exercises the one-shot apply path. It does not apply network changes or write routerd’s normal state files; no daemon or routerctl command is involved.

LAB_DIR="$(mktemp -d)"
sudo routerd apply --config /usr/local/etc/routerd/router.yaml --once --dry-run --skip-service-manager --state-file "$LAB_DIR/state.db" --ledger-file "$LAB_DIR/ledger.db" --status-file "$LAB_DIR/status.json"

3. Apply live from the console

This changes the host network and then exits. Run it only from the lab console or with an independent management path available.

# Live one-shot apply: changes the host network, then exits.
sudo routerd apply --config /usr/local/etc/routerd/router.yaml --once

4. Start the daemon; then use routerctl

routerd serve is live and continues to reconcile the host network. After it starts, use another terminal for routerctl.

# Start the live daemon from the console.
sudo routerd serve --config /usr/local/etc/routerd/router.yaml

# Only after routerd serve is running, use another terminal.
sudo routerctl get status
sudo routerctl get events --limit 20

routerd is pre-release v1alpha1 software. Do not use the first live run on the only router or only remote-management path for a network.

After the daemon starts, check the router

routerctl talks to the running local routerd daemon. It is for checking an already-running router, not for the standalone validation and dry-run steps above.

routerctl get status

Check the resource phases reported by the running daemon before changing anything else.

routerctl doctor

Run focused health diagnostics through the daemon after the router is up.

routerctl get events

Review recent controller events when a resource does not reach the expected phase.

Keep the host console available

A console or separate management path is the recovery path if a live network change affects remote access.