steward/README.md

Steward

Every Hold has a steward at the door; this one gives each newcomer an address.

Steward is a DHCPv4 server you configure through a web UI, a REST API and a command line client, all three backed by the same API. It is the companion of Jarl, the BIND manager, and works the same way: every change is checked as a whole before it is used, is recorded in a history where it can be undone, and is audited.

In Skyrim, a steward greets whoever comes to the door and sees to their needs. Steward is the first thing a device meets when it joins your network: it greets it, gives it an address, and tells it the way around (the router, the DNS servers).

What it does

• Subnets per interface. Each subnet names the network interface it is served on (eth0, eth0.20, br-iot). Clients only get addresses from the subnets of the interface their request came in on, so each VLAN gets its own addresses, whatever its clients ask for.
• Pools, reservations and options. Pools are ranges handed out to any client. Reservations fix a client's address, by MAC address or client identifier, optionally with a host name and options of its own. Options can be set for every subnet, per subnet and per reservation; the most specific wins. The common options have names (routers, domain-name-servers, domain-search, ntp-servers, classless-static-route, …), and any other can be set by number.
• Leases that survive. Leases live in SQLite and are written before the client gets its answer, so a crash or a restart never hands an address out twice. A client that comes back gets the address it had.
• Conflict checks. An address is pinged before it is offered. One that answers, or that a client declines, is held back for a day.
• Changes you can trust. Each change is validated as a whole, with errors that say what is wrong and how to fix it. A dry run shows what a change would do; the history shows every change, field by field, and undoes any of them.
• Easy to watch. The dashboard shows each interface and whether it is served, how full each subnet's pools are, and any problems. The Activity page lists the latest DHCP messages, so you can see why a device didn't get an address.
• Moving from Kea. steward import kea reads a kea-dhcp4.conf and Kea's lease file, so clients keep their addresses (docs/kea.md).
• Users and tokens. Each user and API token gets permissions: an administrator, or config, leases and audit access, read or write. On the server itself, root needs no setup: the CLI uses stewardd's local socket.
• HTTPS on its own. Give it a name and a Jarl token, and Steward gets its web UI's certificate from Let's Encrypt and renews it, with Jarl publishing the DNS-01 challenge. It checks the whole path first, so a broken setup never wastes Let's Encrypt's rate limits (docs/certificates.md).
• One small service. stewardd is one static binary, run by a sandboxed systemd unit whose only privilege is binding port 67. Debian packages and a daily backup timer are included.

Not yet: relays (giaddr), DHCPv6, failover, client classes, and registering clients' names in DNS through Jarl (docs/design.md).

Quick start

On Debian or Ubuntu, from the package registry (see docs/install.md for other ways):

sudo apt install steward
sudo -u steward stewardd init          # asks for the admin password
sudo systemctl enable --now steward

sudo steward subnet add 10.0.10.0/24 --interface eth0 --name office \
    --pool 10.0.10.100-10.0.10.199 \
    --option routers=10.0.10.1 --option domain-name-servers=10.0.10.2
sudo steward settings set --option domain-name=lan
sudo steward reservation add 10.0.10.20 aa:bb:cc:dd:ee:01 --hostname nas
sudo steward status

The web UI is on http://127.0.0.1:8067/ (see listen in /etc/steward/steward.yaml).

Coming from Kea:

sudo steward import kea /etc/kea/kea-dhcp4.conf --leases /var/lib/kea/kea-leases4.csv -n   # look first
sudo steward import kea /etc/kea/kea-dhcp4.conf --leases /var/lib/kea/kea-leases4.csv
sudo systemctl disable --now kea-dhcp4-server

Documentation

• install.md: packages, building from source, first steps
• subnets.md: subnets, interfaces, pools, reservations, options, leases, and how addresses are chosen
• options.md: the options Steward knows and how to write their values
• kea.md: moving from Kea
• certificates.md: HTTPS with a certificate from Let's Encrypt, through Jarl
• jarl.md: connecting Steward to Jarl, and what its token may do
• cli.md: the steward command line client
• api.md: the REST API
• configuration.md: /etc/steward/steward.yaml
• permissions.md: users, roles, grants and API tokens
• operations.md: backups, logs, upgrades, troubleshooting
• validation.md: every check and what it means
• design.md: how Steward is built, and what 0.1 leaves out
• development.md: building, testing, releasing

Status

Version 0.1.0 is the current release: a DHCPv4 server with subnets per interface, reservations (by MAC address, client ID or either, with their own lease time), a web UI, REST API and CLI, Kea import, the web UI's certificate through Jarl, clients' last-seen times and a choice of address order per subnet and pool. 0.2.0 is in testing (0.2.0-rc.3): allow and deny lists per subnet, every option of a DHCP message in words in the activity log, failed logins logged for Guard and fail2ban, and reserving a lease at another address of its subnet.

Licence

MIT, see LICENSE.