Skip to content

Run a router

These pages are for operators who run nodes of a router image, one whose modules list the router layer, chalkos.nixosModules.router. They build on Operate nodes: a router installs, upgrades and recovers like any node, and its interfaces and addresses are Network documents as on any node. A router's own documents, of router.chalkos.dev, set how it forwards, what its firewall lets through, whom it exchanges routes with over BGP, which links share a routing table, how it translates IPv6 to IPv4 and resolves names, which addresses it leases, which peers reach it through WireGuard, and whom it serves time.

To see a router run first, Quick start: router runs one with a client on its LAN as virtual machines, in about 15 minutes.

Set up

These pages give a node its router config and its firewall.

  • Set up a router


    Write the Router document, choose the interfaces of the node API and check what the router loaded.

    Read

  • Filter and translate traffic


    Group interfaces into zones, write policies between them and to the router, and masquerade or forward ports.

    Read

Route

These pages decide where the router sends traffic.

  • Route with BGP


    Give the router a BGP instance, peer on its links or at addresses, filter routes with policies and check the sessions.

    Read

  • Separate routing with VRFs


    Put links into VRFs with tables of their own, run a BGP instance in each and import routes between them, while the node API stays in the default VRF.

    Read

  • Route traffic by policy


    Send traffic by source, port or DSCP into a VRF, another table or through another router, whatever its destination's route.

    Read

Serve the networks

These pages give the router's networks their services.

  • Translate to IPv4 and resolve names


    Give IPv6-only networks the IPv4 internet through NAT64, answer their queries with DNS64 and local zones, and check the translations.

    Read

  • Lease addresses with DHCP


    Lease IPv4 and IPv6 addresses on the router's links from pools and reservations, give clients their options and PXE clients their boot files, delegate IPv6 prefixes and relay DHCP to other servers, in each VRF.

    Read

  • Run WireGuard


    Give the router a WireGuard interface with keys from Secrets, add peers such as a laptop and check their handshakes.

    Read

  • Serve time with NTP


    Let the router answer NTP for its networks, serve its own clock without a source and list the clients it answered.

    Read