abrown38andClaude Opus 5.5
8a69038ab5
- stewardd init asks for the first administrator's name on a terminal.
- Tokens can be rotated (steward token rotate, POST /tokens/{id}/rotate,
Rotate in the web UI), with a grace period for the old secret, as in
Jarl. Schema migration 2 adds the token columns.
- Read-only users see the settings and a subnet's settings locked,
instead of editable fields without a Save button.
- The New token dialog only offers roles within what the user may do.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
110 lines
4.1 KiB
Markdown
110 lines
4.1 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
|
|
```
|
|
|
|
It asks for the administrator's name (`admin` if you just press Enter;
|
|
your own name is better, since each person should have an account) and
|
|
password. `-u NAME` gives the name without asking.
|
|
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.
|