From 65a67b484ca21cb00dc3d93728fd02498cc0e3c4 Mon Sep 17 00:00:00 2001 From: JJ Fullmer Date: Tue, 18 Aug 2026 21:01:10 -0600 Subject: [PATCH 1/2] Document the install modes and every undocumented installer flag Four options existed in the installer and appeared nowhere in these docs at all: --install-mode, --public-web-cert, --rebuild-ipxe-with-my-ca and --https-redirect. Two more, --netboot-proto and --boot-delay, were documented only on other pages. The pasted --help block was old enough to predate all of them. Regenerated that block from the installer itself rather than editing it by hand, which is also how the ordering bug in usage() got found and fixed upstream of this. Added a section for the four install modes with the tuple each one writes, and a table for the individual transport options they are shorthand for. Three things a reader can currently only learn by being bitten: - -S no longer means what it did. Before 1.6 it decided the web protocol, the redirect and whether iPXE was recompiled; it now means only the redirect, which is what its help text always claimed. - --install-mode does not touch the redirect, despite the prompt describing standard as 'no redirect'. An upgraded -S server keeps it whichever mode is chosen. - http-only does not persist. httpProto returns to https on every run, so the flag has to be passed again on each upgrade. Also corrected the Secure Boot section, which still described the flat pre-PKI layout -- a key at /opt/fog/secureboot/MOK.key that is 'never regenerated'. That layout is gone: there is an enrolled CA in pki/secureboot/ca/ and a rotatable signing leaf in leaf/, which is the whole point of the split and is why --secureboot-ca-cert exists. That flag was undocumented here too. Added the name-constraint options, including the one an admin supplying an enterprise intermediate needs to know: iPXE only understands dNSName and iPAddress subtrees, and a CA carrying anything else fails to parse. Front matter loses in-progress/updating-content and gains a real description; the -S line's 'comunication' typo goes with the regenerated block. Verified with a full Quartz build: no errors, unparsed-wikilink count still 12. The one unresolved target is the sibling branch's new page. Co-Authored-By: Claude --- .../server/command-line-options.md | 352 +++++++++++++----- 1 file changed, 258 insertions(+), 94 deletions(-) diff --git a/docs/installation/server/command-line-options.md b/docs/installation/server/command-line-options.md index 6dc477f5..7cd3b514 100644 --- a/docs/installation/server/command-line-options.md +++ b/docs/installation/server/command-line-options.md @@ -2,99 +2,223 @@ title: Fog installer command line options aliases: - Fog installer command line options -description: Fog installer command line options + - installfog.sh options + - Installer flags +description: Every option the FOG installer accepts, what it changes, and which ones are remembered in .fogsettings context_id: command-line-options tags: - - in-progress - - updating-content - installation - fog-server + - configuration + - certificates + - secure-boot --- - # Fog installer command line options -The FOG installer has quite a few command line options. See the output -below. You might want force FOG to setup the web interface via HTTPS, -change the web root directory, or install to a non-default location. - - ./installfog.sh --help - Usage: ./installfog.sh [-h?odEUHSCKYyXTFl] [-f ] [-N ] - [-D ] [-c ] - [-W ] [-B ] - [-s <192.168.1.10>] [-e <192.168.1.254>] - -h -? --help Display this info - -o --oldcopy Copy back old data - -d --no-defaults Don't guess defaults - -U --no-upgrade Don't attempt to upgrade - -H --no-htmldoc No htmldoc, means no PDFs - -S --force-https Force HTTPS for all comunication - -C --recreate-CA Recreate the CA Keys - -K --recreate-keys Recreate the SSL Keys - --external-ca Sign FOG's server certificate with an - existing external/intermediate CA instead - of generating a self-signed CA - --ca-cert Path to the intermediate CA certificate (PEM) - --ca-key Path to the intermediate CA private key (PEM) - --ca-root Path to the root CA certificate (PEM) - --web-ca-cert Bring your own CA for the WEB zone: the - intermediate that signs this server's - vhost certificate - --web-ca-key Private key matching --web-ca-cert - --web-ca-root Root certificate --web-ca-cert chains to - (all three are required together) - -Y -y --autoaccept Auto accept defaults and install - -f --file Use different update file - -c --ssl-path Specify the ssl path - defaults to /opt/fog/snapins/ssl - -D --docroot Specify the Apache Docroot for fog - defaults to OS DocumentRoot - -W --webroot Specify the web root url want fog to use - (E.G. http://127.0.0.1/fog, - http://127.0.0.1/) - Defaults to /fog/ - --fogprogramdir Specify the FOG base directory - defaults to /opt/fog - remembered in /etc/fog/fog.conf, so it - only needs giving on a first install - -N --mysqldbname Specify the FOG database name - defaults to fog - -B --backuppath Specify the backup path - --uninstall Uninstall FOG. Removes FOG's own files, - services and config, and restores the - files FOG replaced. Your database, - images, snapins, SSL CA and the fog - account are KEPT unless purged below. - Packages are never removed. - --dry-run With --uninstall, list what would be - removed and exit without changing anything - --force With --uninstall, skip the typed - confirmation (-Y does NOT skip it) - --purge-db Also drop the FOG database - --purge-images Also delete the image storage - --purge-snapins Also delete the snapins - --purge-ssl Also delete the SSL CA. This permanently - breaks every deployed fog-client - --purge-user Also delete the fog Linux account - --purge-all All of the --purge-* options above - -s --startrange DHCP Start range - -e --endrange DHCP End range - -E --no-exportbuild Skip building nfs file - -X --exitFail Do not exit if item fails - -T --no-tftpbuild Do not rebuild the tftpd config file - -F --no-vhost Do not overwrite vhost file - -l --list-packages List of the basic packages FOG needs for install or is currently installed for FOG - --secure-boot-key Private key used to re-sign the FOS - kernels for UEFI Secure Boot - --secure-boot-cert Certificate matching --secure-boot-key - (both are required together) - --no-secure-boot Do not generate a Secure Boot signing - key, and leave the FOS kernels unsigned - --no-ca-trust Do not add this server's CA to this - server's own system trust store +The FOG installer takes a lot of options. Most installs need none of them — +the defaults are chosen for the common case, and anything you do pass is +recorded in [[install-fogsettings|the .fogsettings file]] so an upgrade keeps +it without you passing it again. + +>[!note] Options beat the stored value +>The installer reads `.fogsettings` first and applies your command line after, +>so you never have to clear a setting before overriding it. The exception is +>`--install-mode`, which is a preset: it is applied *before* the individual +>options, so those still win over it. + +## The four install modes + +`--install-mode` sets four settings at once, and is the easiest way to pick a +combination that works. Full reasoning in +[[netboot-transport-and-pki|Netboot Transport and PKI]]. + +| Mode | `httpProto` | `netbootProto` | `publicWebCert` | `rebuildIpxeWithMyCA` | +|---|---|---|---|---| +| `standard` *(default)* | https | http | no | no | +| `http-only` | http | http | no | no | +| `public-cert` | https | **https** | **yes** | no | +| `embed-ca` | https | **https** | no | **yes** | + +An attended install offers these as a numbered prompt. Under `-y` it does not +ask and you get `standard` unless you passed something else. + +>[!warning] `--install-mode` does not touch the HTTP→HTTPS redirect +>Despite what the prompt says about `standard` meaning "no redirect", no mode +>sets or clears `httpsRedirect`. A server that was upgraded from a `-S` install +>keeps its redirect whichever mode you pick. Use `--no-https-redirect` to turn +>it off. + +>[!warning] `http-only` does not persist +>`httpProto` is set back to `https` on every run — 443 listens on every install +>either way — so `--install-mode http-only` applies to the run you pass it on. +>Pass it again on each upgrade, or it silently reverts. + +## Transport options + +These are the individual settings the modes above are shorthand for. Any of +them can be given on its own. + +| Option | What it does | +| --- | --- | +| `--netboot-proto http\|https` | The protocol iPXE uses to fetch `boot.php`. Defaults to `http`; moves to `https` when the certificate is public or iPXE was rebuilt with your CA. Passing it explicitly is **remembered**, so a later run will not re-derive it | +| `--public-web-cert` | States that the web certificate chains to a **public** root, so iPXE can validate it with no rebuild. Needs an FQDN, not an IP. Also stops FOG re-issuing the leaf | +| `--rebuild-ipxe-with-my-ca` | Recompiles iPXE with the configured CA embedded, for HTTPS netboot behind a **private** CA. Adds 10–25 minutes to this and every future install | +| `-S`, `--force-https`, `--https-redirect` | Redirect HTTP to HTTPS, **and send HSTS**. All three spellings are the same option | +| `--no-force-https`, `--no-https-redirect` | Serve both HTTP and HTTPS without redirecting. This is the default | +| `--boot-delay <0-120>` | Seconds a client waits before its first DHCP attempt, for switches slow to come out of STP or port power-save. `0` writes no delay. Any non-zero value gives BIOS clients exactly ten seconds, because that is the only pre-built BIOS binary | +| `--no-public-web-cert`, `--no-rebuild-ipxe-with-my-ca` | Undo the corresponding option | + +>[!important] `-S` no longer means what it used to +>Before 1.6 `-S`/`--force-https` decided three unrelated things at once: the +>protocol FOG used for its own URLs, the redirect, and whether iPXE was +>recompiled. It now means **only** the redirect, which is what its help text +>always said. The other two are `--install-mode` and +>`--rebuild-ipxe-with-my-ca`. + +>[!warning] HTTPS netboot needs `FOG_WEB_HOST` set to the certificate's name +>The boot script the installer writes uses the server's hostname, but FOG +>rebuilds every later boot URL from the `FOG_WEB_HOST` setting in the web +>interface — which holds the server's **IP address** unless you change it. On +>`public-cert` or `embed-ca`, set it to the same FQDN the certificate is issued +>to, or every fetch after the first fails iPXE's name check. + +## The full option list + +``` +Usage: ./installfog.sh [-h?odEUHSCKYyXTFl] [-f ] [-N ] + [-D ] [-c ] + [-W ] [-B ] + [-s <192.168.1.10>] [-e <192.168.1.254>] + -h -? --help Display this info + -o --oldcopy Copy back old data + -d --no-defaults Don't guess defaults + -U --no-upgrade Don't attempt to upgrade + -H --no-htmldoc No htmldoc, means no PDFs + --install-mode Preset for the four settings below. + standard (default): HTTPS web UI, HTTP + netboot, no redirect, no rebuild + http-only: plain HTTP everywhere + public-cert: a publicly-trusted cert, so + netboot can use HTTPS with no rebuild + embed-ca: rebuild iPXE with your CA + (adds 10-25 min and a Secure Boot step) + -S --force-https Force the HTTP->HTTPS redirect + --https-redirect (same thing, clearer name) + --no-force-https Undo --force-https: serve both HTTP and + --no-https-redirect HTTPS without redirecting + --public-web-cert The web certificate chains to a PUBLIC + root, so iPXE can validate it without + a rebuild. Needs an FQDN, not an IP + --no-public-web-cert Undo --public-web-cert + --rebuild-ipxe-with-my-ca Rebuild iPXE embedding the + configured CA. Slow, and the + result is not upstream's signed + binary, so its MOK must be + enrolled before a client netboots + --no-rebuild-ipxe-with-my-ca Undo the above + --netboot-proto http or https: the protocol iPXE uses to + fetch boot.php. Defaults to http, and + to https when the certificate is public + or iPXE was rebuilt with your CA + --boot-delay seconds to sleep before the first DHCP + attempt, for switches slow out of STP or + powersave. 0 (default) writes no sleep. + -C --recreate-CA Recreate the CA Keys + -K --recreate-keys Recreate the SSL Keys + --external-ca Sign FOG's server certificate with an + existing external/intermediate CA instead + of generating a self-signed CA + --ca-cert Path to the intermediate CA certificate (PEM) + --ca-key Path to the intermediate CA private key (PEM) + --ca-root Path to the root CA certificate (PEM) + -Y -y --autoaccept Auto accept defaults and install + -f --file Use different update file + -c --ssl-path Specify the ssl path + defaults to /opt/fog/snapins/ssl + -D --docroot Specify the Apache Docroot for fog + defaults to OS DocumentRoot + -W --webroot Specify the web root url want fog to use + (E.G. http://127.0.0.1/fog, + http://127.0.0.1/) + Defaults to /fog/ + --fogprogramdir Specify the FOG base directory + defaults to /opt/fog + remembered in /etc/fog/fog.conf, so it + only needs giving on a first install + --hostname Override the vhost/cert hostname + defaults to `hostname -f`, remembered in .fogsettings + --extra-server-name Add an extra vhost/cert name (repeatable) + alongside the primary hostname and detected IPs + --internal-domain Permit this domain in the Web and Secure Boot + CAs' name constraints (repeatable). The server's + own domain is always permitted + --internal-subnet Restrict those CAs to this subnet, e.g. + 10.20.30.0/24 (repeatable). REPLACES the default + of all RFC1918 ranges + --no-sb-name-constraints Issue the Secure Boot CA without name + constraints. Use if firmware rejects the chain + --web-ca-cert/-key/-root Bring your own CA for the WEB zone only + (equivalent to --external-ca --ca-*) + --secureboot-ca-cert Your own SECURE BOOT intermediate: the + certificate enrolled in firmware. Pair it with + --secure-boot-key/--secure-boot-cert, which name + the code-signing leaf issued from it. Rotate the + leaf freely; the enrolled CA never changes + --kernel-backup-count How many prior kernel/init generations to + keep (default 3). Restore one with + bin/restorekernel.sh. See + docs/SUPPORTED_CUSTOMIZATIONS.md + --restore-kernel-backup Also restore the previous kernel/init set + this run. Used by updatefog.sh when reverting; + not normally passed by hand + -N --mysqldbname Specify the FOG database name + defaults to fog + -B --backuppath Specify the backup path + --uninstall Uninstall FOG. Removes FOG's own files, + services and config, and restores the + files FOG replaced. Your database, + images, snapins, SSL CA and the fog + account are KEPT unless purged below. + Packages are never removed. + --dry-run With --uninstall, list what would be + removed and exit without changing anything + --force With --uninstall, skip the typed + confirmation (-Y does NOT skip it) + --purge-db Also drop the FOG database + --purge-images Also delete the image storage + --purge-snapins Also delete the snapins + --purge-ssl Also delete the SSL CA. This permanently + breaks every deployed fog-client + --purge-user Also delete the fog Linux account + --purge-all All of the --purge-* options above + -s --startrange DHCP Start range + -e --endrange DHCP End range + -E --no-exportbuild Skip building nfs file + -X --exitFail Do not exit if item fails + -T --no-tftpbuild Do not rebuild the tftpd config file + -F --no-vhost Do not touch the vhost file at all. FOG + normally rewrites only the region between its + MANAGED BLOCK markers and leaves your own + additions alone, so skipping also skips its + security fixes to the parts it owns. + See docs/SUPPORTED_CUSTOMIZATIONS.md + -l --list-packages List of the basic packages FOG needs for install or is currently installed for FOG + --secure-boot-key Private key used to re-sign the FOS + kernels for UEFI Secure Boot + --secure-boot-cert Certificate matching --secure-boot-key + (both are required together) + --no-secure-boot Do not publish Secure Boot ENROLMENT + material: no MOK.der, no PK/KEK/db.auth, + and no 'Enroll Secure Boot Key' menu + entry. Binaries are still signed -- a + signature is inert with Secure Boot off + --no-ca-trust Do not add this server's CA to this + server's own system trust store +``` The `--uninstall`, `--dry-run`, `--force` and `--purge-*` options are -covered in detail in [Uninstalling the Fog server](uninstall-fog-server.md). +covered in detail in [[uninstall-fog-server|Uninstalling the Fog server]]. ## Certificate options @@ -124,6 +248,28 @@ than producing a server signed by the wrong thing. >what makes this safe to do on a running fleet without re-registering a single >machine. +### Name constraints + +FOG restricts the authorities it issues to a set of permitted names, so a +compromised CA cannot issue for the whole internet. + +| Option | What it does | +| --- | --- | +| `--internal-domain ` | Permit this domain in the Web and Secure Boot CAs' constraints. Repeatable. The server's own domain is always permitted | +| `--internal-subnet ` | Restrict those CAs to this subnet. Repeatable, and it **replaces** the default of all private ranges rather than adding to it | +| `--no-sb-name-constraints` | Issue the Secure Boot CA with no constraints at all. Use it if your firmware rejects the chain | + +>[!important] Constraints are fixed when a CA is first created +>FOG never re-mints an existing authority, so changing these on a server that +>already has one does nothing until you remove the intermediate as well. + +>[!warning] A CA you supply must constrain only by DNS name or IP address +>iPXE enforces name constraints, and only understands `dNSName` and +>`iPAddress` permitted subtrees. A CA carrying any other subtree type — or any +>`minimum`/`maximum` — **fails to parse**, and the whole chain with it. Leave +>your intermediate unconstrained or constrain it with those two only. This +>matters only when netboot is on HTTPS. + ### `--no-ca-trust` and the local trust store By default the installer adds this server's own CA to this server's system @@ -149,29 +295,47 @@ at a single CA so one import covers all of them, see ## Secure Boot options -Since FOG 1.6.0 the installer **generates a Secure Boot signing key by +Since FOG 1.6.0 the installer **generates Secure Boot signing material by default** and signs the FOS kernels with it, so a stock server always has a -certificate fingerprint to check and an enrollment kit to hand out. The three -options above only matter if you want to change that: +certificate fingerprint to check and an enrollment kit to hand out. + +FOG creates a Secure Boot **certificate authority** and enrols that, then +issues a separate **signing leaf** beneath it. Because firmware trusts the +issuer, the signing leaf can be rotated without a second trip to every machine. | Option | Use it when | | --- | --- | -| *(none)* | The default. A key is generated at `/opt/fog/secureboot/` on first install and **reused, never regenerated**, on every later upgrade. | +| *(none)* | The default. The material is generated on first install and **reused, never regenerated**, on every later upgrade. | | `--secure-boot-key` + `--secure-boot-cert` | You already have a signing key you want FOG to use. Both are required together; the certificate may be PEM or DER. Your key is never overwritten. | -| `--no-secure-boot` | You do not want a signing key or the root-only signing helper on this server. The FOS kernels are left unsigned. | +| `--secureboot-ca-cert` | You are supplying your own Secure Boot **intermediate** — the certificate enrolled in firmware. Pair it with the two above, which then name the code-signing leaf issued from it. | +| `--no-secure-boot` | You do not want enrollment material published: no `MOK.der`, no `PK`/`KEK`/`db.auth`, and no "Enroll Secure Boot Key" menu entry. | + +>[!note] `--no-secure-boot` declines enrollment, not signing +>Binaries are still signed. A signature is inert on a machine with Secure Boot +>off, so signing costs nothing; what the option turns off is publishing the +>material a client would enrol. `--no-secure-boot` is remembered in `.fogsettings`, so an upgrade will not hand back a key and a `sudoers` rule you deliberately declined. ->[!warning] The generated key is never regenerated, and that is deliberate +>[!warning] The signing key is never regenerated, and that is deliberate >A new signing key silently invalidates enrollment on **every machine that >already trusted the old one**, and nothing reports that until a client fails >to boot — long after the install that caused it. `--recreate-keys` and >`--recreate-CA` deliberately do not touch it. To rotate deliberately, remove ->`/opt/fog/secureboot/` and re-run the installer, then re-enroll every client. +>the directory and re-run the installer, then re-enroll every client. -The private key lives at `/opt/fog/secureboot/MOK.key`, `0600` inside a `0700` -directory owned by root. It is never copied into the web root and the web -server cannot read it — see +The material lives under `/opt/fog/pki/secureboot/`: the enrolled authority in +`ca/` and the signing leaf in `leaf/sign.{key,pem}`, private keys `0600` inside +a directory owned by root. Nothing there is copied into the web root and the +web server cannot read it — see [[secure-boot-signing|Secure Boot: signing FOS with your own key]] for the -full procedure and for what to do on each client. +full procedure and for what to do on each client, and +[[pki-zones|FOG PKI Infrastructure]] for the layout. + +## See also + +- [[netboot-transport-and-pki|Netboot Transport and PKI]] — what the install modes mean +- [[install-fogsettings|The .fogsettings file]] — where these options are remembered +- [[install-fog-server|Installing the FOG server]] +- [[dhcp-server-settings|DHCP server settings]] — where `--boot-delay` shows up on the client From c5fedfdca8afc7026607ba09fe95e0e34b5ef9ce Mon Sep 17 00:00:00 2001 From: JJ Fullmer Date: Wed, 19 Aug 2026 05:38:31 -0600 Subject: [PATCH 2/2] Stamp the rebuild cost correctly --rebuild-ipxe-with-my-ca said it adds 10-25 minutes to 'this and every future install'. The build is stamped against the pinned iPXE version, the embedded CA and the staged binary, and skipped when all three still match -- so it re-runs when one of those changes, not on every install. Rebuilt: no errors, unparsed-wikilink count still 12. Co-Authored-By: Claude --- docs/installation/server/command-line-options.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/installation/server/command-line-options.md b/docs/installation/server/command-line-options.md index 7cd3b514..506cd72f 100644 --- a/docs/installation/server/command-line-options.md +++ b/docs/installation/server/command-line-options.md @@ -63,7 +63,7 @@ them can be given on its own. | --- | --- | | `--netboot-proto http\|https` | The protocol iPXE uses to fetch `boot.php`. Defaults to `http`; moves to `https` when the certificate is public or iPXE was rebuilt with your CA. Passing it explicitly is **remembered**, so a later run will not re-derive it | | `--public-web-cert` | States that the web certificate chains to a **public** root, so iPXE can validate it with no rebuild. Needs an FQDN, not an IP. Also stops FOG re-issuing the leaf | -| `--rebuild-ipxe-with-my-ca` | Recompiles iPXE with the configured CA embedded, for HTTPS netboot behind a **private** CA. Adds 10–25 minutes to this and every future install | +| `--rebuild-ipxe-with-my-ca` | Recompiles iPXE with the configured CA embedded, for HTTPS netboot behind a **private** CA. The build takes 10–25 minutes but is stamped against the pinned iPXE version and the CA, so it re-runs only when one of those changes — not on every install | | `-S`, `--force-https`, `--https-redirect` | Redirect HTTP to HTTPS, **and send HSTS**. All three spellings are the same option | | `--no-force-https`, `--no-https-redirect` | Serve both HTTP and HTTPS without redirecting. This is the default | | `--boot-delay <0-120>` | Seconds a client waits before its first DHCP attempt, for switches slow to come out of STP or port power-save. `0` writes no delay. Any non-zero value gives BIOS clients exactly ten seconds, because that is the only pre-built BIOS binary |