abrown38andClaude Opus 5.5
3c0808591f
Subnets served per interface, pools, reservations, options at three levels, leases in SQLite saved before the ACK, ping and decline conflict checks, validated changes with history and undo, users and tokens, an audit log, a Kea importer, a sandboxed systemd unit and Debian packages. Tested with real udhcpc and dhcpcd clients in Docker (scripts/e2e.sh). Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
106 lines
3.9 KiB
Markdown
106 lines
3.9 KiB
Markdown
# Installing Steward
|
|
|
|
Steward runs on Linux (stewardd uses Linux socket options). It is tested
|
|
on Debian 13 and Ubuntu 24.04. The CLI also runs on macOS and Windows.
|
|
|
|
## From the package registry
|
|
|
|
The release workflow publishes Debian packages to the Gitea registry,
|
|
`stable` for releases and `testing` for release candidates. Jarl's packages come from the same registry. If apt already has it
|
|
(`/etc/apt/sources.list.d/jarl.list`), `sudo apt install steward` is all
|
|
it takes. Otherwise add it:
|
|
|
|
```sh
|
|
sudo install -d /etc/apt/keyrings
|
|
sudo curl -fsSL https://gitea.adbraun.lol/api/packages/adam/debian/repository.key -o /etc/apt/keyrings/gitea-adam.asc
|
|
echo "deb [signed-by=/etc/apt/keyrings/gitea-adam.asc] https://gitea.adbraun.lol/api/packages/adam/debian stable main" \
|
|
| sudo tee /etc/apt/sources.list.d/gitea-adam.list
|
|
sudo apt update
|
|
sudo apt install steward
|
|
```
|
|
|
|
For release candidates too, add the `testing` distribution: the same
|
|
`deb` line with `testing` instead of `stable`.
|
|
|
|
There are two packages:
|
|
|
|
* **`steward`** is the server: `/usr/bin/stewardd`, the systemd units
|
|
`steward.service`, `steward-backup.service` and `steward-backup.timer`,
|
|
and the `steward` user and directories. It creates
|
|
`/etc/steward/steward.yaml` on the first install and never touches it
|
|
again. It depends on `steward-cli`.
|
|
* **`steward-cli`** is the CLI, `/usr/bin/steward`. It can be installed
|
|
alone on any machine to manage Steward remotely.
|
|
|
|
The release page also has `.deb` files, tarballs and the CLI for Linux,
|
|
macOS and Windows.
|
|
|
|
## From source
|
|
|
|
```sh
|
|
make # bin/stewardd, bin/steward (Go, as in go.mod)
|
|
sudo make install # /usr/local/bin, units in /etc/systemd/system
|
|
sudo systemd-sysusers steward.conf && sudo systemd-tmpfiles --create steward.conf
|
|
sudo chgrp steward /etc/steward /etc/steward/steward.yaml && sudo systemctl daemon-reload
|
|
```
|
|
|
|
`make deb` builds the packages (`DEB_ARCH=arm64` for another architecture).
|
|
|
|
## First steps
|
|
|
|
1. **Settings** are in `/etc/steward/steward.yaml`
|
|
([configuration.md](configuration.md)). By default the web UI and API
|
|
listen on `127.0.0.1:8067`. To reach them from your network, add an
|
|
address there, ideally with TLS or behind a TLS reverse proxy.
|
|
2. **Create the database and the first administrator:**
|
|
|
|
```sh
|
|
sudo -u steward stewardd init
|
|
```
|
|
3. **Stop any other DHCP server** on the interfaces Steward will serve
|
|
(Kea, isc-dhcp-server, dnsmasq): only one program can use an
|
|
interface's port 67. Moving from Kea: [kea.md](kea.md).
|
|
4. **Start Steward:**
|
|
|
|
```sh
|
|
sudo systemctl enable --now steward
|
|
```
|
|
5. **Add a subnet** for each network, on the interface its clients are
|
|
on, in the web UI or with the CLI. On the server, root needs no token:
|
|
|
|
```sh
|
|
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
|
|
sudo steward settings set --option domain-name-servers=10.0.10.2 --option domain-name=lan
|
|
sudo steward status
|
|
```
|
|
|
|
The server needs an address in each subnet, on its interface: that is
|
|
where clients renew. For VLANs, set up a VLAN interface for each (for
|
|
example with systemd-networkd or `/etc/network/interfaces`), with an
|
|
address in its subnet.
|
|
|
|
**Firewall:** allow UDP port 67 in on the served interfaces. Replies go
|
|
out to UDP port 68. With nftables:
|
|
|
|
```
|
|
udp dport 67 iifname { "eth0", "eth0.20" } accept
|
|
```
|
|
|
|
## From another machine
|
|
|
|
Install `steward-cli`, make a token, and set the server:
|
|
|
|
```sh
|
|
sudo steward token create laptop # on the server; prints the token once
|
|
steward config set server https://dhcp.example.com:8067
|
|
steward config set token # paste it
|
|
steward status
|
|
```
|
|
|
|
## Upgrading
|
|
|
|
`apt upgrade` restarts a running stewardd, and stewardd upgrades its
|
|
database when it starts. Take a backup first if you like
|
|
(`sudo -u steward stewardd backup`); the daily timer keeps 30 days of them.
|