0014: the two identity files, and what an appliance says about backup #6

Open

marcos-mendez wants to merge 2 commits from docs/decision-0014-appliance-identity into main

marcos-mendez commented

2026-09-28 00:17:27 -03:00

(Migrated from github.com)

Does /etc/turnkey_version keep its name? Yes, and its format too.
It is a published interface, not branding: measured on a live appliance
on 2026-09-28, five things parse it (turnkey-version, the sysversion
library, keel.inspect.app, three inithooks files, and a tklbam hook),
and every one of those parsers is prefix sensitive. keel inspect
reports the appliance as missing for a string that does not begin
turnkey-. Keel writes /etc/keel_version beside it, the same four
fields with its own prefix, and everything an operator is shown reads
that one and falls back to the other.

The question uncovered a live defect. keel-core's changelog was renamed
to keel-core-19.0 on 2026-09-27 and fab derives /etc/turnkey_version
from the changelog's package name, so the next core layer would have
written keel-core-19.0-trixie-amd64 into a file none of those readers
accepts. The published layer predates the rename, so nothing shipped is
affected. Keel-Linux/common#5 normalises the prefix so the rule is
enforced rather than hoped for.

What does the appliance say about backup? One line: not configured,
no backup service yet, confconsole when there is one. No instruction to
run tklbam-init, because that links the machine to another project's
Hub, and no URL, because the documentation page it would point at
answers 404 today.

Implemented in Keel-Linux/common#5 and Keel-Linux/keel-core#9. Neither
this nor those should be merged before the maintainer has ruled on the
note: the status line says proposed.

Issue Keel-Linux/tracker#6 asked for an appliance to stop announcing itself as TurnKey at login, and said the two hard parts belong in a decision note rather than in a commit message. This is that note. It covers those two questions and nothing else. **Does `/etc/turnkey_version` keep its name?** Yes, and its format too. It is a published interface, not branding: measured on a live appliance on 2026-09-28, five things parse it (`turnkey-version`, the `sysversion` library, `keel.inspect.app`, three inithooks files, and a tklbam hook), and every one of those parsers is prefix sensitive. `keel inspect` reports the appliance as missing for a string that does not begin `turnkey-`. Keel writes `/etc/keel_version` beside it, the same four fields with its own prefix, and everything an operator is shown reads that one and falls back to the other. The question uncovered a live defect. keel-core's changelog was renamed to `keel-core-19.0` on 2026-09-27 and fab derives `/etc/turnkey_version` from the changelog's package name, so the next core layer would have written `keel-core-19.0-trixie-amd64` into a file none of those readers accepts. The published layer predates the rename, so nothing shipped is affected. Keel-Linux/common#5 normalises the prefix so the rule is enforced rather than hoped for. **What does the appliance say about backup?** One line: not configured, no backup service yet, confconsole when there is one. No instruction to run `tklbam-init`, because that links the machine to another project's Hub, and no URL, because the documentation page it would point at answers 404 today. Implemented in Keel-Linux/common#5 and Keel-Linux/keel-core#9. Neither this nor those should be merged before the maintainer has ruled on the note: the status line says proposed.

marcos-mendez commented

2026-09-28 01:34:57 -03:00

(Migrated from github.com)

Reviewed together with Keel-Linux/keel-core#9, Keel-Linux/common#5 and #4.

Checked the factual claims rather than taking them, because this note is what the next person will reason from:

The reader table is accurate. I confirmed sysversion (AppVer, get_turnkey_release, fmt_sysversion), keel.inspect.app.probe_appliance, inithooks/firstboot.d/29tagid with lib/tagid.sh, bin/secalerts.sh (which reads it indirectly, out of /etc/apt/apt.conf.d/01turnkey), and /etc/tklbam/hooks.d/maria-db-changes, whose sed -En "s|turnkey-[a-z0-9-]+-..." is prefix sensitive exactly as claimed.
The three parser quotations are correct verbatim, including that probe_appliance reports the appliance as missing rather than mis-parsing it.
"The published layer predates the rename" holds: the changelog rename is bf6d721 of 2026-09-27, the published core layer is 2026-09-26, and the booted core in keel-core's gate log still prints Welcome to Core, TurnKey GNU/Linux 19.0, which only a turnkey- string produces.
"It runs after every overlay, conf script, patch and removelist" is right, and stated more carefully here than in the companion pull request: root.patched/post follows root.patched/body, whose last action is the common removelists-final, and only root.patched/cleanup comes after it. The claim that a conf script could not do this job is also right, since conf scripts run in root.patched/body.
keellinux.org/docs/ is 404 and the site serves two pages, both measured today. The reasoning for printing no URL is sound, and the URL the login does print, https://github.com/keel-linux/confconsole, resolves and is public.
"It promises a place, not a service" survives contact with confconsole: it has no backup surface at all today, and the TKLBAM status it computes is only logged, never rendered, so an operator who follows the line finds nothing rather than finding another project's backup client.
0014 is free; the open 0015 in #3 does not collide.

One observation rather than a finding: the reasoning in section 1 puts Keel-specific behaviour in common because it is shared by every appliance, while the companion recipe change keeps the login out of common to leave it offerable upstream (decision 0008). Both are defensible and both are argued, but the note is the place where the rule for choosing between them would live, and it does not state one. A sentence saying that the compatibility surface goes in common and the operator-facing surface goes in the product would settle the next case without another decision note.

Approve

Clean above LOW. The claims that would be expensive to be wrong about are each checkable and each checked out.

Reviewed together with Keel-Linux/keel-core#9, Keel-Linux/common#5 and #4. Checked the factual claims rather than taking them, because this note is what the next person will reason from: - The reader table is accurate. I confirmed `sysversion` (`AppVer`, `get_turnkey_release`, `fmt_sysversion`), `keel.inspect.app.probe_appliance`, `inithooks/firstboot.d/29tagid` with `lib/tagid.sh`, `bin/secalerts.sh` (which reads it indirectly, out of `/etc/apt/apt.conf.d/01turnkey`), and `/etc/tklbam/hooks.d/maria-db-changes`, whose `sed -En "s|turnkey-[a-z0-9-]+-..."` is prefix sensitive exactly as claimed. - The three parser quotations are correct verbatim, including that `probe_appliance` reports the appliance as missing rather than mis-parsing it. - "The published layer predates the rename" holds: the changelog rename is bf6d721 of 2026-09-27, the published core layer is 2026-09-26, and the booted core in keel-core's gate log still prints `Welcome to Core, TurnKey GNU/Linux 19.0`, which only a `turnkey-` string produces. - "It runs after every overlay, conf script, patch and removelist" is right, and stated more carefully here than in the companion pull request: `root.patched/post` follows `root.patched/body`, whose last action is the common removelists-final, and only `root.patched/cleanup` comes after it. The claim that a conf script could not do this job is also right, since conf scripts run in `root.patched/body`. - `keellinux.org/docs/` is 404 and the site serves two pages, both measured today. The reasoning for printing no URL is sound, and the URL the login does print, `https://github.com/keel-linux/confconsole`, resolves and is public. - "It promises a place, not a service" survives contact with confconsole: it has no backup surface at all today, and the TKLBAM status it computes is only logged, never rendered, so an operator who follows the line finds nothing rather than finding another project's backup client. - 0014 is free; the open 0015 in #3 does not collide. One observation rather than a finding: the reasoning in section 1 puts Keel-specific behaviour in `common` because it is shared by every appliance, while the companion recipe change keeps the login out of `common` to leave it offerable upstream (decision 0008). Both are defensible and both are argued, but the note is the place where the rule for choosing between them would live, and it does not state one. A sentence saying that the compatibility surface goes in `common` and the operator-facing surface goes in the product would settle the next case without another decision note. ## Approve Clean above LOW. The claims that would be expensive to be wrong about are each checkable and each checked out.

This pull request can be merged automatically.

This branch is out-of-date with the base branch

You are not authorized to merge this pull request.

View command line instructions

Checkout

From your project repository, check out a new branch and test the changes.

git fetch -u origin docs/decision-0014-appliance-identity:docs/decision-0014-appliance-identity

git switch docs/decision-0014-appliance-identity

Merge

Merge the changes and update on Forgejo.

Warning: The "Autodetect manual merge" setting is not enabled for this repository, you will have to mark this pull request as manually merged afterwards.

git switch main

git merge --no-ff docs/decision-0014-appliance-identity

git switch docs/decision-0014-appliance-identity

git rebase main

git switch main

git merge --ff-only docs/decision-0014-appliance-identity

git switch docs/decision-0014-appliance-identity

git rebase main

git switch main

git merge --no-ff docs/decision-0014-appliance-identity

git switch main

git merge --squash docs/decision-0014-appliance-identity