diff --git a/docs/installation/server/command-line-options.md b/docs/installation/server/command-line-options.md index 6dc477f5..506cd72f 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. 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 | +| `--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