# Steward 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](https://gitea.adbraun.lol/adam/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, the Jarl's steward runs the hold's daily business, keeping the keys among other things. Steward hands out the hold's addresses. ## 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](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. * **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](docs/design.md)). ## Quick start On Debian or Ubuntu, from the package registry (see [docs/install.md](docs/install.md) for other ways): ```sh 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: ```sh 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](docs/install.md): packages, building from source, first steps * [subnets.md](docs/subnets.md): subnets, interfaces, pools, reservations, options, leases, and how addresses are chosen * [options.md](docs/options.md): the options Steward knows and how to write their values * [kea.md](docs/kea.md): moving from Kea * [cli.md](docs/cli.md): the `steward` command line client * [api.md](docs/api.md): the REST API * [configuration.md](docs/configuration.md): `/etc/steward/steward.yaml` * [permissions.md](docs/permissions.md): users, roles, grants and API tokens * [operations.md](docs/operations.md): backups, logs, upgrades, troubleshooting * [validation.md](docs/validation.md): every check and what it means * [design.md](docs/design.md): how Steward is built, and what 0.1 leaves out * [development.md](docs/development.md): building, testing, releasing ## Status Steward 0.1.0 is in development. ## Licence MIT, see [LICENSE](LICENSE).