Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion docs/kb/how-tos/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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]]
- [[post-download-scripts|Post Download Scripts]]
- [[lets-encrypt-setup|Set up Let's Encrypt on a FOG server]]
222 changes: 222 additions & 0 deletions docs/kb/how-tos/lets-encrypt-setup.md
Original file line number Diff line number Diff line change
@@ -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 2>/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`
5 changes: 5 additions & 0 deletions docs/kb/integrations/external-ca-lets-encrypt.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down