docs: agents over HTTPS

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

CHANGELOG.md

@@ -87,6 +87,10 @@ region and `deploy/install-rack.sh` on rack hosts (new dnsmasq layout, signed ra
   accepted only from the machine's own address (its static lease); through a rack, the rack's
   `X-Forwarded-For` entry counts. A machine without a fixed address binds a job to its first user.
   `agent_source_check: false` turns this off.
+- **Agents over HTTPS.** Rack controllers get a server certificate for their own host and serve
+  the agents' endpoints and images on 443. Agents accept the CA by the fingerprint on the PXE
+  command line and do not fall back to HTTP. Old agents keep working over HTTP. The commissioning
+  image has to be rebuilt to get the new agents.
 - **BMC certificates.** HTTPS BMCs (Redfish, Proxmox) are pinned on first use. The certificate
   is read in a handshake that carries no credentials, and a changed certificate gets none
   (`tls_fingerprint`; cleared on an address change or a BMC firmware update by Rollcall).

INSTALL.md

@@ -17,7 +17,7 @@ exists.
 | Network access | a default route; the internet or a mirror for packages and cloud images |
 | Later: provisioning network | an interface of this host (or of a rack controller) on the VLAN where machines PXE-boot |
 | Later: BMC network | the rack controller must reach the machines' BMCs (IPMI, Redfish) |
-| Ports | DHCP 67/udp and TFTP 69/udp on the provisioning network; HTTP 80 for machines; HTTPS 443 for people and rack controllers |
+| Ports | DHCP 67/udp and TFTP 69/udp on the provisioning network; HTTP 80 and HTTPS 443 for machines (agents use 443); HTTPS 443 for people and rack controllers |
 
 The release bundle `rollcall-<version>-linux-amd64.tar.gz` holds the binary,
 `deploy/` and `agent/`. From a checkout, `deploy/bootstrap.sh` builds the binary

README.md

@@ -401,6 +401,28 @@ The lab runs both: `pxe-server` (embedded, 10.213.77.0/24) and `pxe-rack2`
 pxe-rack2 and its virtual BMC on pxe-rack2. Rack ↔ region traffic is mutual
 TLS (next section), so the BMC passwords of queued commands are encrypted.
 
+
+### Agents over HTTPS
+
+Agents talk to their rack controller over HTTPS: the commissioning agent,
+the deploy agent and the image download. The region gives each rack a
+server certificate for its own URL's host (`CN=rack-server:NAME`, server
+use only, never one of the region's addresses). The rack serves the
+agents' endpoints on `<host>:443` as well as on HTTP; `tls_listen` in
+`rack.json` changes the port, `off` turns it off. The embedded rack uses
+the region's own HTTPS listener.
+
+The pxelinux command line carries `rollcall.tls=https://HOST` and
+`rollcall.ca=<SHA-256 of the CA>`. An agent fetches `/ca.pem`, accepts it
+only by that fingerprint, and from then on uses HTTPS with it. When TLS
+was asked for and fails, it does not fall back to HTTP.
+
+What stays on HTTP: live-boot fetching the commissioning squashfs, and
+`/ca.pem` itself (checked by its fingerprint). This keeps BMC passwords
+and seed files from anyone who only listens, and from an HTTP server
+posing as the rack. TFTP and the kernel and initrd stay unauthenticated,
+so an attacker who can rewrite boot files on the wire is not stopped;
+that needs UEFI Secure Boot with signed images.
 ### DHCP already on the network: proxy DHCP
 
 Where the site's DHCP server keeps handing out addresses (a corporate DHCP,