# 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.