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>
112 lines
4.6 KiB
Markdown
112 lines
4.6 KiB
Markdown
# 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
|
|
|
|
1. Install Steward and start it ([install.md](install.md)). While Kea
|
|
serves the network, Steward serves nothing: it has no subnets yet.
|
|
2. See what the import would do:
|
|
|
|
```sh
|
|
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:`).
|
|
3. Import:
|
|
|
|
```sh
|
|
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.
|
|
4. Stop Kea:
|
|
|
|
```sh
|
|
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:
|
|
|
|
1. the subnet's (or its shared network's) `interface`;
|
|
2. the interface on this server with an address in the subnet;
|
|
3. 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:
|
|
|
|
```sh
|
|
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.
|