diff --git a/docs/kb/how-tos/index.md b/docs/kb/how-tos/index.md index 43075d9..c41c9c3 100644 --- a/docs/kb/how-tos/index.md +++ b/docs/kb/how-tos/index.md @@ -25,4 +25,5 @@ More advanced/situational guides: - [[uefi-boot-entries|Managing UEFI Boot Entries (efibootmgr)]] - [[deploy-dual-boot-multi-disk-image|Deploying a Dual-Boot Multi-Disk Image]] - [[add-extend-a-2nd-virtual-hdd|Add & Extend a 2nd Virtual HDD]] -- [[post-download-scripts|Post Download Scripts]] \ No newline at end of file +- [[post-download-scripts|Post Download Scripts]] +- [[lets-encrypt-setup|Set up Let's Encrypt on a FOG server]] \ No newline at end of file diff --git a/docs/kb/how-tos/lets-encrypt-setup.md b/docs/kb/how-tos/lets-encrypt-setup.md new file mode 100644 index 0000000..480c424 --- /dev/null +++ b/docs/kb/how-tos/lets-encrypt-setup.md @@ -0,0 +1,222 @@ +--- +title: Set up Let's Encrypt on a FOG server +aliases: + - Set up Let's Encrypt on a FOG server + - Let's Encrypt walkthrough + - ACME setup + - Public certificate setup +description: End-to-end walkthrough for putting a publicly-issued certificate on a FOG server, including HTTPS netboot and automatic renewal +context_id: lets-encrypt-setup +tags: + - how-to + - certificates + - pki + - acme + - lets-encrypt + - netboot +--- + +# Set up Let's Encrypt on a FOG server + +A certificate from a public certificate authority buys a FOG server two things +FOG's own authority cannot: browsers trust it with no import, and **iPXE can +validate it during netboot with no rebuilt binary**. This walks through it end +to end. + +>[!note] Terms used on this page +>**ACME** is the protocol Let's Encrypt uses to issue and renew certificates +>automatically. **DNS-01** is one of its challenge types: you prove you control +>a domain by putting a record in its DNS, rather than by serving a file over +>port 80. **FQDN** is the server's full DNS name, like `fog.example.com`. +>**Leaf** is the server's own certificate, as opposed to the authority that +>signed it. + +## What this gets you, and what it does not + +| | With a public certificate | +|---|---| +| Browsers and the API | Trusted with no CA import | +| iPXE netboot over HTTPS | Works with **no** iPXE rebuild | +| Secure Boot | Unaffected — staged and signed either way | +| fog-client | **Read the caveat at the end before rolling this out** | + +## Before you start + +**You need an FQDN, and the booting clients need to resolve it.** A certificate +is issued to a name; no public authority will issue one for a private IP, and +iPXE fails the TLS handshake on a name mismatch even after the chain itself +validates. The DNS servers your DHCP hands out have to answer for that name. + +**The server does not need to be reachable from the internet.** Use a **DNS-01** +challenge and the only thing that has to be public is the DNS record, not the +FOG server. That is the normal shape for an imaging server on a private network. + +You will need an ACME client — `acme.sh` and `certbot` are both fine — and API +credentials for whoever hosts your DNS. + +## Step 1 — issue the certificate + +Get a certificate for the FQDN using a DNS-01 challenge. With `acme.sh` and a +generic DNS provider: + +```bash +acme.sh --issue --dns dns_yourprovider -d fog.example.com +``` + +Or with `certbot`: + +```bash +certbot certonly --preferred-challenges dns \ + --manual -d fog.example.com +``` + +Install the result somewhere stable that your renewal process will keep +updating — `/etc/letsencrypt/live/fog.example.com/` for certbot, or wherever +`acme.sh --install-cert` puts it. **Do not** copy the files into FOG's own PKI +tree; the point of the next step is to tell FOG they live elsewhere and are not +FOG's to manage. + +> **Cloudflare DNS-01 recipe** +> +> *To be filled in — @darksidemilk has a working Cloudflare DNS-challenge recipe +> to contribute here. Until then, use your provider's DNS-01 plugin as above; +> nothing on the rest of this page depends on which provider you use.* + +## Step 2 — tell FOG the certificate is not its to manage + +Edit [[install-fogsettings|/opt/fog/.fogsettings]] and set: + +```bash +acmeLeaf='yes' +publicWebCert='yes' +sslPrivKey='/etc/letsencrypt/live/fog.example.com/privkey.pem' +sslPubCert='/etc/letsencrypt/live/fog.example.com/fullchain.pem' +``` + +These are two different statements and you want both: + +- **`acmeLeaf='yes'`** — *something other than FOG renews this leaf.* It stops + the installer regenerating the certificate from its original signing request + while your ACME client owns the key, which produces a certificate/key + mismatch that stops the web server. It also stops FOG locking the private key + to `root:root 0600`, which would break a renewal hook running as anyone else. +- **`publicWebCert='yes'`** — *this certificate chains to a public root.* This + is what moves netboot to HTTPS, because it tells FOG that iPXE will be able + to validate the chain on its own. + +Either one on its own tells FOG the certificate was issued elsewhere. Neither +implies the other, and all four combinations are real — an **internal** ACME +server such as step-ca is `acmeLeaf='yes'` with `publicWebCert='no'`. + +## Step 3 — make FOG address itself by name + +Two places have to agree with the name on the certificate. + +**The installer's idea of the hostname**, if `hostname -f` does not already +return the FQDN: + +```bash +./installfog.sh --hostname fog.example.com +``` + +**`FOG_WEB_HOST`**, in the web interface under +FOG Configuration → FOG Settings → Web Server. This one is easy to miss and +breaks netboot in a way that looks like a certificate problem: + +>[!warning] Set FOG_WEB_HOST or HTTPS netboot fails after the first hop +>The boot script the installer writes chains to the server by hostname, so the +>first request succeeds. But `boot.php` then rebuilds every later URL — the +>kernel, the init, `MOK.der`, the background image — from `FOG_WEB_HOST`, which +>holds the server's **IP address** on a fresh install and is not updated by +>upgrades. Every one of those fetches then fails iPXE's name check. +> +>Set it to the same FQDN the certificate is issued to. Nothing in the installer +>does this for you. + +## Step 4 — run the installer + +```bash +cd /path/to/fogproject/bin +./installfog.sh --install-mode public-cert +``` + +`public-cert` sets `httpProto=https`, `netbootProto=https`, `publicWebCert=yes` +and leaves the iPXE rebuild off — which is the whole point, since a public +certificate needs no rebuild. See +[[netboot-transport-and-pki|Netboot Transport and PKI]]. + +The installer will not re-issue your leaf, will not touch its key permissions, +and will refuse to write a boot script that chains to an IP over HTTPS rather +than completing and leaving you unable to boot. + +## Step 5 — verify + +**The served chain**, from another machine: + +```bash +openssl s_client -connect fog.example.com:443 -servername fog.example.com /dev/null \ + | openssl x509 -noout -subject -issuer -dates +``` + +The issuer should be your public CA, and the subject should be the FQDN. + +**The boot script** actually names the FQDN: + +```bash +grep chain /tftpboot/default.ipxe +``` + +It should read `https://fog.example.com/fog/service/ipxe/boot.php`, not an IP. + +**A real client.** Netboot one machine and watch it get past `boot.php` to the +menu. Getting to the menu and then failing on a later fetch is the +`FOG_WEB_HOST` symptom from step 3. + +## Renewal + +Renewal is your ACME client's job, not FOG's. FOG reads the files where you +pointed it, so a renewal that writes to the same paths needs nothing from FOG — +only a web server reload: + +```bash +systemctl reload nginx # or: systemctl reload httpd / apache2 +``` + +Wire that into your client's post-renewal hook. + +>[!note] Nothing re-runs the installer for you +>A renewed **leaf** needs no installer run. A changed **issuing intermediate** +>is different, and Let's Encrypt does rotate intermediates — see the caveat +>below and [[external-ca-lets-encrypt#renewal-and-rotation|Renewal and rotation]]. + +## The fog-client caveat — check this before a fleet rollout + +The certificate zones were separated in 1.6: the **Web TLS** certificate this +page swaps out, and the **Client Communication** certificate fog-client uses, +are no longer the same material. +[[pki-zones|FOG PKI Infrastructure]] records the cost of changing the Web TLS +zone as *"None. Browsers just need the issuer trusted."* + +But [[external-ca-lets-encrypt|External CA & Let's Encrypt Certificates]] also +documents fog-client as pinning `ca.cert.der` and requiring that exact +certificate in the served chain — which a Let's Encrypt chain does not contain, +and which LE's intermediate rotation would break even if it did. That passage +predates the zone split and has not been re-verified against it. + +**The two pages disagree, and this one is not going to guess.** Before rolling a +public certificate out to a fleet running fog-client, swap it on the server and +confirm that **one** already-registered client still checks in. If it does, the +zone split has done its job. If it does not, the pinning caveat still applies +and an internal ACME CA is the better fit — see +[[external-ca-lets-encrypt#recommended-internal-acme-ca-step-ca|the step-ca recommendation]], +which gives you ACME automation with a stable pinned CA. + +Netboot and browser trust are unaffected either way. + +## See also + +- [[netboot-transport-and-pki|Netboot Transport and PKI]] — why a public certificate needs no iPXE rebuild +- [[external-ca-lets-encrypt|External CA & Let's Encrypt Certificates]] — the reference behind this walkthrough +- [[pki-zones|FOG PKI Infrastructure]] — the three certificate zones +- [[install-fogsettings|The .fogsettings file]] — `acmeLeaf`, `publicWebCert` and the paths +- [[command-line-options|Fog installer command line options]] — `--install-mode`, `--hostname` diff --git a/docs/kb/integrations/external-ca-lets-encrypt.md b/docs/kb/integrations/external-ca-lets-encrypt.md index 5fca17c..27d7ba6 100644 --- a/docs/kb/integrations/external-ca-lets-encrypt.md +++ b/docs/kb/integrations/external-ca-lets-encrypt.md @@ -105,6 +105,11 @@ section. >[[pki-glossary|the PKI glossary]] if the terms here and there don't line up >for you. +>[!tip] Looking for the steps rather than the reasoning? +>[[lets-encrypt-setup|Set up Let's Encrypt on a FOG server]] is the +>walkthrough: issue the certificate, point FOG at it, get HTTPS netboot +>working, and wire up renewal. + --- ## How iPXE validates HTTPS