From 97959af899756de08c96136b4b4e4acd1b3d05ea Mon Sep 17 00:00:00 2001 From: Ilker Manap Date: Fri, 30 Oct 2026 02:26:25 +0100 Subject: [PATCH] docs: agents over HTTPS Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 4 ++++ INSTALL.md | 2 +- README.md | 22 ++++++++++++++++++++++ 3 files changed, 27 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 479f56c..98eff01 100644 --- a/CHANGELOG.md +++ b/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). diff --git a/INSTALL.md b/INSTALL.md index b442b22..4b44fd7 100644 --- a/INSTALL.md +++ b/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--linux-amd64.tar.gz` holds the binary, `deploy/` and `agent/`. From a checkout, `deploy/bootstrap.sh` builds the binary diff --git a/README.md b/README.md index 15ff537..5dafd76 100644 --- a/README.md +++ b/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 `: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=`. 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,