steward/docs/install.md

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:

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

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). 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:

   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.

4. Start Steward:

   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:

   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:

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.