From c5688314b514f5c856ce39bdadcbae76c0cb4bc8 Mon Sep 17 00:00:00 2001
From: Ilker Manap <ilker@Ilkers-MacBook-Pro.local>
Date: Fri, 30 Oct 2026 19:13:18 +0100
Subject: [PATCH] docs: fixed leases on the site's DHCP server

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 CHANGELOG.md |  3 +++
 INSTALL.md   |  2 ++
 README.md    | 51 +++++++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 56 insertions(+)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b5cae5c..67943e3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -14,6 +14,9 @@ publish a tag that has no section here.
   the PowerDNS API (ownership by RRset comment) or RFC 2136 dynamic update with TSIG (ownership by a
   `_rollcall.<name>` TXT marker and update prerequisites, so foreign records are never overwritten;
   drift is detected by querying). `rollcall dns`, `rollcall dns sync [-dry]`, a doctor check.
+- Fixed leases on the site's DHCP server for proxy-mode VLANs (`dhcp_reservations`), for Kea with
+  `host_cmds` (Kea 3.0+) and OpenWrt (rpcd). Rollcall's own leases are reconciled; foreign ones are
+  reported. `rollcall reservations`.
 - Firmware updates over Redfish. A package repository on the region (`rollcall firmware import`
   from a file or URL, served to BMCs through rack controllers) and each machine's firmware inventory.
   - Update jobs: hand-over, task watch through BMC restarts, optional power cycle, version check
diff --git a/INSTALL.md b/INSTALL.md
index 4b44fd7..632137c 100644
--- a/INSTALL.md
+++ b/INSTALL.md
@@ -149,6 +149,8 @@ region's version.
 ## Integrations
 
 - **NetBox (or Infoblox) as the address authority.** `ipam` in `config.json`: see README, External IPAM.
+- **The site's DHCP server keeps the addresses (proxy DHCP).** `dhcp_reservations` writes machines'
+  planned addresses there as fixed leases (Kea 3.0+, OpenWrt): see README, Fixed leases.
 - **DNS names without an IPAM authority.** `dns` in `config.json` (PowerDNS API or RFC 2136
   with TSIG): see README, DNS provider.
 - **Certificates for machines.** Delegate a name-constrained intermediate to an ACME
diff --git a/README.md b/README.md
index 5dafd76..654c69d 100644
--- a/README.md
+++ b/README.md
@@ -448,6 +448,57 @@ deploy/bootstrap.sh --iface eth1 --proxy-dhcp           # the same at install ti
 Verified in the lab with a separate DHCP server on the provisioning network:
 commissioning and three deployments in a row through the proxy.
 
+#### Fixed leases on the site's DHCP server (Kea, OpenWrt)
+
+With a reservation driver, machines on proxy VLANs still get the addresses
+Rollcall plans: every such address becomes a fixed lease (the MAC of its
+interface, the address, the hostname) on the site's server. This is the
+counterpart of Infoblox's `fixedaddress`. Leases are reconciled on every
+address change and every `sync_interval`. Rollcall changes or deletes only
+its own leases; one held by someone else (same MAC or address) is reported
+as a conflict.
+
+```json
+"dhcp_reservations": {
+  "provider": "kea",
+  "url": "http://kea.example:8000",
+  "user": "rollcall",
+  "password_file": "/etc/rollcall/kea.pw"
+}
+```
+
+- **kea:** the control API with the `host_cmds` hook, open source since Kea
+  3.0; Debian's Kea 2.6 lacks it and the driver says so.
+  - Ownership goes in `user-context {"rollcall": machine}`.
+  - With a hosts database the leases are kept there. Without one they go
+    into the running configuration, and `config-write` saves them
+    (`persist: false` turns that off).
+- **openwrt:** rpcd over HTTP (`url: http://router`). Fixed leases are
+  `host` sections in `/etc/config/dhcp` with `option rollcall`, followed by
+  `uci commit` and a dnsmasq reload. Give Rollcall its own rpcd login with
+  only this:
+
+  ```json
+  /usr/share/rpcd/acl.d/rollcall.json
+  { "rollcall": { "description": "Rollcall fixed DHCP leases",
+      "read":  { "ubus": { "uci": ["get"] }, "uci": ["dhcp"] },
+      "write": { "ubus": { "uci": ["add", "delete", "commit"], "rc": ["init"] }, "uci": ["dhcp"] } } }
+  ```
+
+  and a `config login` in `/etc/config/rpcd` (username, an MD5-crypt
+  password, `list read/write 'rollcall'`).
+
+```
+rollcall reservations            # provider, last sync, conflicts
+rollcall reservations sync -dry
+```
+
+IPv6 addresses are skipped: DHCPv6 reservations are keyed on DUIDs, not
+MACs. So are interfaces without a single MAC, such as bonds.
+
+Verified in the lab against Kea 3.0.5 and OpenWrt 25.12.6: the machine got
+its planned address from the site's server and not from the pool.
+
 ## Certificate authority and TLS
 
 The region is the installation's certificate authority, as the llmgw control