跳至主要内容

LAN-side services

This page introduces the routerd resources that handle the LAN side of a router: addresses on the inside interface, DHCPv4 / DHCPv6 leases, IPv6 Router Advertisement, and the local DNS resolver.

The companion page on the WAN side covers how the router gets its upstream addresses; this page is what the router publishes to the inside.

Service split​

routerd splits LAN service across two daemons with clear boundaries:

  • dnsmasq handles DHCPv4, DHCPv6, DHCP relay, and IPv6 Router Advertisement.
  • routerd-dns-resolver handles DNS zones, conditional forwarding, cache, and query logging.

Keeping DHCP next to dnsmasq avoids reimplementing a battle-tested DHCP server. Keeping DNS in routerd-dns-resolver lets us model resolver policy as typed routerd resources (DNSResolver, DNSZone).

Summary table​

ConcernResourceDaemon backing it
LAN interface addressIPv4StaticAddress, IPv6DelegatedAddress(kernel)
DHCPv4 scopeDHCPv4Serverdnsmasq
DHCPv4 reservationDHCPv4Reservationdnsmasq
DHCPv6 (stateless / stateful)DHCPv6Serverdnsmasq
IPv6 Router AdvertisementIPv6RouterAdvertisementdnsmasq (RA mode)
DNS zone (local authoritative)DNSZonerouterd-dns-resolver
DNS resolver listenerDNSResolverrouterd-dns-resolver
DHCP lease event relay(built-in)routerd-dhcp-event-relay

DHCPv4 scope​

- apiVersion: net.routerd.net/v1alpha1
  kind: DHCPv4Server
  metadata:
    name: lan-dhcpv4
  spec:
    interface: lan
    addressPool:
      start: 192.0.2.64
      end: 192.0.2.191
      leaseTime: 12h
    gatewayFrom:
      resource: IPv4StaticAddress/lan-base
      field: address
    dnsServerFrom:
      - resource: IPv4StaticAddress/lan-base
        field: address
    ntpServerFrom:
      - resource: IPv4StaticAddress/lan-base
        field: address
    domain: lan.example.org

Use a separate range for automatic clients and reserve a smaller block for fixed-address devices if it makes operations clearer.

Static DHCPv4 reservation​

- apiVersion: net.routerd.net/v1alpha1
  kind: DHCPv4Reservation
  metadata:
    name: smart-meter
  spec:
    server: lan-dhcpv4
    macAddress: "02:00:00:00:00:01"
    hostname: smart-meter
    ipAddress: 192.0.2.10

DHCPv4Reservation renders to a dnsmasq host reservation entry. It also gives the Web Console and event log a stable resource name for the device, independent of its current IP.

IPv6 RA and DHCPv6​

For an IPv6 LAN, publish RDNSS in Router Advertisement so Android clients can pick up the resolver (Android does not use DHCPv6 for DNS configuration). For Windows clients you usually also need a DHCPv6 stateless server.

- apiVersion: net.routerd.net/v1alpha1
  kind: IPv6RouterAdvertisement
  metadata:
    name: lan-ra
  spec:
    interface: lan
    prefixFrom:
      resource: IPv6DelegatedAddress/lan-base
      field: address
    mFlag: false
    oFlag: true
    rdnssFrom:
      - resource: IPv6DelegatedAddress/lan-base
        field: address
    dnssl:
      - lan.example.org
    mtu: 1454

- apiVersion: net.routerd.net/v1alpha1
  kind: DHCPv6Server
  metadata:
    name: lan-dhcpv6
  spec:
    interface: lan
    mode: stateless
    dnsServersFrom:
      - resource: IPv6DelegatedAddress/lan-base
        field: address
    domainSearch:
      - lan.example.org

Use mode: stateful or mode: both only when DHCPv6 address assignment (in addition to SLAAC) is required.

Local DNS zone​

- apiVersion: net.routerd.net/v1alpha1
  kind: DNSZone
  metadata:
    name: lan
  spec:
    zone: lan.example.org
    ttl: 300
    records:
      - hostname: router
        ipv4From:
          resource: IPv4StaticAddress/lan-base
          field: address
        ipv6From:
          resource: IPv6DelegatedAddress/lan-base
          field: address
    dhcpDerived:
      sources:
        - DHCPv4Server/lan-dhcpv4
        - DHCPv6Server/lan-dhcpv6
      hostnameSuffix: lan.example.org
      ddns: true
      ttl: 60

Manual records are placed under records:. Records derived from DHCP leases come from dhcpDerived.sources. The two are merged at lookup time.

DNS resolver listener​

- apiVersion: net.routerd.net/v1alpha1
  kind: DNSResolver
  metadata:
    name: lan-resolver
  spec:
    listen:
      - name: lan
        addressFrom:
          - resource: IPv4StaticAddress/lan-base
            field: address
          - resource: IPv6DelegatedAddress/lan-base
            field: address
        port: 53
        sources: [local-zone, default]
    sources:
      - name: local-zone
        kind: zone
        match:
          - lan.example.org
        zoneRef:
          - DNSZone/lan
      - name: default
        kind: upstream
        match:
          - "."
        upstreams:
          - https://dns.example.net/dns-query
          - udp://1.1.1.1:53
    cache:
      enabled: true
      maxEntries: 10000

The resolver listens on every address routerd derives from the referenced status fields. New IPv6 addresses (e.g. on PD renewal) are picked up without a restart.

Verification​

# Confirm the LAN interface has both v4 and v6
routerctl describe Interface/lan

# Watch DHCP events live
routerctl events --topic 'routerd.dhcp.lease.**' --resource DHCPv4Server/lan-dhcpv4

# Resolve a name through the local resolver
dig @<lan-ip> router.lan.example.org
dig @<lan-ip> example.com

Operational notes​

  • Begin with routerctl plan and --dry-run. Only enable the real LAN listener after the management path and a known rollback are ready.
  • If you replace dnsmasq leases manually, restart routerd-dhcp-event-relay so the in-memory state catches up. Prefer changing the lease through routerd.
  • Keep upstream public resolvers as a fallback: routerd-dns-resolver will demote a forwarder that fails health checks but only if a working alternative exists.

See also​