From 0820e796bde2ac0defad16e6b5b98830018ab968 Mon Sep 17 00:00:00 2001 From: JJ Fullmer Date: Wed, 2 Sep 2026 16:00:10 -0600 Subject: [PATCH] Say which customizations tree wins, and document marking a boot file to keep Three gaps the page did not cover. The two-trees table said what each directory IS but not the rule that makes them different. The rule is the point: /opt restores by ABSENCE, /etc adopts by PRESENCE, and that is why one directory could not do both jobs -- adopting by presence would let a backup FOG made for itself outrank a freshly shipped file, and restoring by absence would let a certificate you deliberately placed be ignored the moment FOG shipped one of the same name. "Yours to place" reads as a promise about where you put a file. It is a promise about the NAME: what FOG saves is everything in the live directory the shipped source tree does not contain. The corollary was missing and is easy to get wrong, so it is now a warning callout -- name a file bzImage and FOG wins. kernel-backups/keep/ and the Keep button were not documented anywhere. Added under Kernels and inits, with the two reasons it exists: a per-release sibling is deliberately not part of a numbered generation, and marking one of the six default names achieves close to nothing. Also separates being FOUND (header magic, any name, no configuration) from being KEPT, which are different questions that read like one. Plus a note that each readme.txt is FOG's own and may be rewritten, since FOG can now correct its own text -- and that editing one stops that for good. Companion to FOGProject/fogproject#1703. --- .../server/supported-customizations.md | 47 +++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/docs/management/server/supported-customizations.md b/docs/management/server/supported-customizations.md index b2a377f..d3ff95d 100644 --- a/docs/management/server/supported-customizations.md +++ b/docs/management/server/supported-customizations.md @@ -50,6 +50,16 @@ work this way. **Not preserved** means exactly that. Those cases are listed at the end rather than left for you to discover. +**"Yours to place" is about names, not locations.** A file survives because +what FOG saves is *everything in the live directory that the shipped source +tree does not contain* — so it is the **name** that earns the protection, not +where you put it. + +>[!warning] +>If you give your file the same name as one FOG ships, FOG wins. Your +>`bzImage` is not yours; that is the name of the kernel FOG installs, and it +>is replaced on every run. Use a name of your own, or mark the file to keep. + ## The two customizations directories There are two. They are not interchangeable, and they run in **opposite @@ -59,6 +69,7 @@ directions**. Each carries a `readme.txt` saying which is which. |---|---|---| | Written by | **FOG** | **you** | | What it is | copies FOG makes of your files before it rebuilds the tree they live in, and restores from afterward | an input FOG only ever reads | +| Conflict rule | restores by **absence** — a saved file is put back only when the rebuilt tree no longer has it | adopts by **presence** — what you put there overrides what FOG would otherwise generate | | Holds | `ipxe-bg/`, `ipxe-legacy/`, `kernel-backups/` | `pki/` | Strictly the first is `$fogprogramdir/customizations`. It sits outside the web @@ -72,6 +83,17 @@ config-management run already capture. Kernels and boot images are large, rebuildable binaries, and the filesystem standard does not put binaries under `/etc`. FOG's own PKI moved to `/etc/fog/pki` for the same reason. +The conflict rules are the deeper reason, and they are why one directory could +not do both jobs. Adopting by presence would let a backup FOG made for itself +outrank a freshly shipped file; restoring by absence would let a certificate you +deliberately placed be ignored the moment FOG shipped one of the same name. One +rule each is what keeps "FOG's copy" and "yours" distinguishable. + +>[!note] +>Each `readme.txt` is FOG's own note and a later version may rewrite it, so +>that it can correct itself when something changes. **Edit one and FOG leaves +>it alone from then on**, permanently. + --- ## iPXE boot menu background @@ -159,6 +181,31 @@ kept by default; change that with `installfog.sh --kernel-backup-count N`. Restoring re-signs the kernels if Secure Boot is configured, since a restored kernel carries its old signature and the signing key may have rotated. +### Marking a boot file to keep + +The kernel and init update pages list what is actually on disk, with a **Keep** +button on each row. Marking a file copies it into +`/opt/fog/customizations/kernel-backups/keep/`, and a later run puts it back if +it has gone missing from the live tree. Unmark it and the copy is removed. + +This is the one thing under `/opt/fog/customizations` written on *your* +instruction rather than as part of a rebuild. FOG still does the writing, so it +stays a directory you never need to touch by hand. + +It exists because two reasonable-sounding expectations do not hold on their own: + +- A **per-release sibling** such as `bzImage.5.15.0` is deliberately not part of + a numbered generation — a generation would multiply the same bytes by the + generation count — so without a mark it survives only until the next upgrade. +- Marking one of the **six default names** achieves close to nothing, since + picking up the new kernel is the point of an update. Mark the sibling, or a + file under a name of your own. + +FOG decides what a boot file is by reading its header rather than its name, so a +hand-compiled kernel under any name appears in the **Host Kernel** dropdown with +nothing to configure. Being *found* and being *kept* are separate questions: +that answers the first, and the naming rule or a mark answers the second. + --- ## Web certificates you bring