adam/steward

0 Fork 0

Files

T

abrown38andClaude Opus 5.5 3c0808591f Steward 0.1.0 (in development): a DHCPv4 server with a web UI, API and CLI

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>

2026-10-14 12:14:07 +01:00

4.6 KiB

Raw Blame History

Moving from Kea

steward import kea reads a Kea DHCPv4 configuration (kea-dhcp4.conf) and Kea's lease file, and makes them Steward's: clients keep their addresses, and reservations and options carry over.

Steps

Install Steward and start it (install.md). While Kea serves the network, Steward serves nothing: it has no subnets yet.
See what the import would do:
```
sudo steward import kea /etc/kea/kea-dhcp4.conf \
    --leases /var/lib/kea/kea-leases4.csv -n
```
It lists the subnets and reservations it would create, how it mapped things (note:), and what it can't bring over (not imported:).
Import:
```
sudo steward import kea /etc/kea/kea-dhcp4.conf --leases /var/lib/kea/kea-leases4.csv
```
Steward now wants to serve the subnets. Its sockets can't open while Kea holds port 67: steward status says so, and stewardd retries every 30 seconds.
Stop Kea:
```
sudo systemctl disable --now kea-dhcp4-server
```
Within 30 seconds Steward serves the interfaces (steward status). Clients renew with it as their leases come due. They keep their addresses, because their leases were imported.

Going back is the same in reverse: stop Steward (systemctl disable --now steward) and start Kea. Kea still has its own lease file. Leases Steward handed out in between aren't in it, but Kea pings before it offers an address, and clients renew or rebind.

What is imported

Kea	Steward
`valid-lifetime` (global, shared network, subnet)	the settings' lease time, and subnets' own where they differ
`option-data` (global, shared network, subnet, reservation)	options at the same level; a subnet gets its shared network's
`subnet4`: `subnet`, `pools`, `interface`	subnets with their pools and interface
`shared-networks`	their subnets, all on the shared network's interface
`reservations` with `hw-address` or `client-id` and `ip-address`, `hostname`	reservations
`decline-probation-period`	the decline hold
`user-context.comment` or `comment` of a subnet	the subnet's comment
the lease file: active and declined leases, and released ones	leases (the last line of each address wins)

Options are matched by Kea's names, which Steward uses too, or by code. Hex data ("csv-format": false) is read as hex.

Interfaces. Every Steward subnet needs its interface. The import takes, in order:

the subnet's (or its shared network's) interface;
the interface on this server with an address in the subnet;
the only interface in Kea's interfaces-config, when there is just one.

When none of these applies, the import says which subnets need one. Give it with --interface PREFIX=IFACE, once per subnet:

sudo steward import kea kea-dhcp4.conf --interface 10.0.20.0/24=eth0.20

Lease files. Kea's memfile is a log, and its lease file cleanup moves older lines to kea-leases4.csv.2. Give both, older first: --leases /var/lib/kea/kea-leases4.csv.2 --leases /var/lib/kea/kea-leases4.csv. Leases outside the imported subnets are left out (the import says how many). Leases in a database (MySQL, PostgreSQL) can't be read. Export them with the lease commands hook (lease4-get-all) into a memfile first, or let clients get new leases.

What isn't imported

The import lists these as not imported: instead of dropping them silently:

client classes, and pools or options tied to them;
options of a pool (Steward sets options per subnet) and options in other spaces (vendor option spaces);
reservations by duid, circuit-id or flex-id, and reservations without an ip-address;
relays (relay), next-server, boot-file-name and other BOOTP fields;
hooks, DHCP-DDNS, and any other section (Dhcp6, Logging, Control-agent).

<?include ...?> isn't followed: paste the included files in first.

Kea is not authoritative by default; Steward is. The import notes this. Steward answers a client asking for an address that doesn't belong on its interface with a NAK, so the client gets a correct one at once. If another DHCP server still shares one of the networks, turn this off: steward settings set --authoritative off.

Importing again

Importing over an existing configuration needs --replace. A subnet with the same network, and a reservation with the same address, keep their IDs, and subnets keep the names given in Steward, since Kea has none. So importing the same file again changes nothing, and after an edit in Kea only the differences show. The import is one history entry: steward history undo ID takes it back, except for the imported leases.

4.6 KiB Raw Blame History