Skip to main content

Concepts

Lighthouse is an RFC-compliant DHCP server. This page covers the DHCP model it implements.

Subnets & pools​

A subnet is one served network, identified by its CIDR. Within a subnet you define one or more pools — ranges of addresses Lighthouse hands out — and can exclude specific addresses. A pool can be class-restricted so only matching clients draw from it (e.g. a PXE-only pool); plain pools stay open to everyone.

Reservations​

A reservation pins a specific address (and optionally a hostname) to a client, matched by its MAC address or client-id (RFC 4361 — this is how Windows clients identify themselves). A reserved address always wins over the dynamic pool.

Options​

DHCP options carry the extra settings clients need — default gateway (routers), DNS (domain_name_servers), domain name, NTP servers, and dozens more. Lighthouse implements the full RFC 2132 option codec by registered name, and lets you send custom options by numeric code for anything vendor-specific. Options can be set per-subnet and per-class.

Client classification​

A client class matches clients by vendor class (option 60), user class (option 77), or MAC OUI prefix. Classes can override options and gate access to class-restricted pools — the basis for handing PXE clients different boot settings, for instance.

Lease lifecycle​

Lighthouse implements the standard DHCPv4 exchange — DISCOVER → OFFER, REQUEST → ACK — and honors the T1 renew and T2 rebind timers. It expires and reclaims leases, frees them on RELEASE, quarantines conflicting addresses on DECLINE, and answers INFORM with options only. When it's authoritative it sends a DHCPNAK for addresses it can't honor, and it allocates deterministically so a client tends to keep the same address. Optional ping-before-offer adds conflict detection.

PXE boot​

Arch-aware boot directives direct BIOS and UEFI clients to a boot server and file (RFC 4578). Lighthouse directs the boot; the bundled read-only TFTP server (lighthouse-tftpd) can serve the files.

IPv6​

Lighthouse runs an independent stateful DHCPv6 engine (RFC 8415) alongside DHCPv4, sharing the same lease store, config, and UI. It handles the full v6 exchange (Solicit/Advertise/Request/Reply, Renew/Rebind/Release/Decline/Confirm/Information-Request) and supports:

  • IA_NA — stateful address assignment, keyed by DUID (+IAID).
  • IA_PD — prefix delegation, with a configurable delegated prefix length.
  • v6 reservations by DUID, and v6 DNS / domain-search options.
note

DHCPv6 is stateful address assignment. Stateless autoconfiguration (SLAAC) is the router's job, not the DHCP server's. The v6 engine is off by default — enable it in config.

Dynamic DNS​

With lighthouse-ddnsd, Lighthouse can register client hostnames into DNS as leases are granted and released (RFC 2136 updates, authenticated with TSIG).

High availability​

For redundancy, run two or more engines against a shared PostgreSQL lease store in active-active HA — both answer every request, and the database arbitrates so no address is handed out twice. See Operations.