Skip to content

feat(installer): offer min finalize-install when the host needs it - #2143

Merged
norrietaylor merged 32 commits into
mainfrom
feat/2129-installer-finalize-offer
Oct 10, 2026
Merged

norrietaylor merged 32 commits into
mainfrom
feat/2129-installer-finalize-offer

Conversation

@norrietaylor

@norrietaylor norrietaylor commented Oct 9, 2026 •

Copy link
Copy Markdown
Member

Root cause

The curl … | sh installer never elevates, and until now it said nothing about what the host still lacked beyond an AppArmor-only note on restricted Ubuntu hosts (scripts/install.sh's "Linux host advisory"). Box names, the classifier tree and KVM access went unmentioned, so the first min failed or printed a wall of advisories. The deb/rpm/apk postinstall and the Arch hook likewise ran only the AppArmor loader.

Fix

At the end of an install the installer runs the just-installed min's probe once: min finalize-install --show --script (exit 0 whatever it finds; the summary on stderr, and on stdout the one script a run executes, printed only while some item is missing). One call, because every probe reads the daemon and, with none running, waits out its connect retries.

  • Finished host (no ✗ in the summary), or a min too old to know the command: nothing is added to today's output.
  • Something missing: the installer prints the summary (the probe's own warning: lines filtered out) and, with a terminal attached, asks Finish setup now? This runs one sudo command. [Y/n]; the default is yes, and Enter runs min finalize-install with its stdin on the terminal, so sudo's own password prompt is the second consent. The run's stdout (the same summary again, then its closing lines) is filtered against the probe's summary, so the status block appears once and the closing lines — Running boxes pick this up on their next start., and after a kvm-group join KVM group membership starts at your next login … — reach the operator; its prompt is on the terminal and its outcome on stderr.
  • Declined, or no terminal: it prints run `min finalize-install` when you're ready; without a terminal, use: and, on the next line, the file route f=$(mktemp) && min finalize-install --show --script > "$f" && sudo sh "$f". It never blocks.
  • Nothing runnable: a waiting names item (every fresh install, until the first min starts a daemon) gets the summary and when to come back; a cannot-only host gets the summary alone. No question, no pointer to a step that would run nothing.
  • A failed step is shown as ✗ setup did not finish; retry with ... and the installer still exits 0.
  • Every printed command names min as the current shell resolves it: bare once the bin dir is on PATH, otherwise by its quoted path (on a fresh install it is not on PATH yet, as the closing card says).

The answer is read from the controlling terminal (MINIMAL_OVERRIDE_TTY seam), never stdin, which under curl … | sh is the script itself; the same seam the active-sessions prompt uses. The install mode has no --yes-style switch to honour (only --force-stop, which is about live sessions), so a terminal-less run takes the pointer path.

The AppArmor-only note and its MINIMAL_OVERRIDE_USERNS_SYSCTL seam are removed. The nfpm postinstall (deb/rpm/apk, scripts/package-nfpm.sh) and the Arch hook (packaging/arch/minimal-bin.install) keep running the shipped AppArmor loader first, wherever apparmor_parser is, on install and upgrade (it refreshes an installed profile and installs it on hosts that do not restrict user namespaces yet, neither of which the finalize item does), then run the script min finalize-install --show --script prints directly as root (no sudo, no prompt), never hard-failing. The probe and the script run under env -i PATH=… HOME=/root, so an env-preserving package manager (sudo -E) cannot point the names probe at the operator's daemon socket and install the resolver link and answerer service as a package side effect. One consequence of probing as root at package time: it never fixes the operator's kvm-group membership (root opens /dev/kvm fine and --provider is unset there, so the item probes done for root); the operator's own later min finalize-install, or the installer's offer on a curl … | sh host, is what adds them to the group.

The README's stale "the installer prints a hint" sentence points at min finalize-install.

Acceptance mapped to tests

Acceptance just test-installer case
A TTY install on a host that needs nothing shows no prompt (also: a waiting-only host gets the real waiting line and when to come back, no prompt, no pointer; a cannot-only host gets the summary alone; a min that cannot probe stays silent) installer_does_not_prompt_on_a_finished_host
A TTY install on a host with missing items shows the summary once and [Y/n], Enter (and y) runs the step with no arguments and the probe runs once; the same on a macOS host (names item); the probe's warnings are hidden; a failed step shows ✗ + a retry pointer by path and exits 0 installer_offers_finalize_install_on_a_tty
Declined, or no TTY: the spec's line and the file route are printed, once, naming min by path (bare when the bin dir is on PATH), only the probe runs, the installer never blocks installer_prints_the_pointer_when_declined_or_without_tty

The stub min in scripts/install_test.sh answers finalize-install --show --script from files under the home (finalize.summary / finalize.waiting / finalize.cannot hold the summary as the real command renders it, finalize.show.status, finalize.run.status), prints the summary on a bare run as the real command does, and records every invocation with its arguments in finalize.calls, which each case asserts in full.

Test plan

  • just test-installer (shellcheck, then sh and dash): 596 passed, 0 failed, natively on macOS and in the lima Linux VM (lima-test.sh feat/2129-installer-finalize-offer).
  • just lint-shell: 52 scripts passed, natively and in lima.
  • just lint-prose README.md: no alerts on the touched lines (the file's pre-existing alerts are untouched).
  • lima: cargo nextest run -p minimal finalize_install_show_json passes; cargo fmt -p minimal --check clean; cargo clippy -p minimal --all-targets -- -D warnings clean.
  • Not run: scripts/pkg-smoke.sh (needs the package boxes); the postinstall change is the same probe-and-run shape as the installer's, and the smoke's --apparmor branch still checks the shipped loader with --check.

Related

Closes #2129

One privileged step for every host need (NET-122, #2127): the
user-namespace profile, box names (resolver hook, minzoned, the
reserved range on macOS), the classifier tree and KVM group
membership, each probed on this host and carried in one script only
while it is missing. `--show` names the items, `--show --script`
prints the exact script a run executes, `--show --json` reports them
under `min/v1/finalize-install`, and `--undo` removes what the step
installed. Without a terminal the run goes through `sudo -n` or exits
1 with the file route.

BREAKING CHANGE: `min net setup` is removed with no alias; run
`min finalize-install` (`--show --script` replaces `--print`).

Closes #2127
…inalize-install's exit rules

A names item with no daemon port is a waiting item, not a host fact no
script can change: it is listed as waiting on a daemon under the summary,
the other items still run, and the host is not finished. The classifier
item is omitted until the step that renders it exists (#2128), so a
native Linux host can finish. A run that added the operator to the kvm
group ends with the login note; --undo takes --show only with --script;
the no-TTY pointer uses mktemp; the run's summary goes to stdout; a
daemon path an AppArmor tunable cannot name blocks the userns item.
At the end of an install the installer runs the just-installed `min`'s
probe (`finalize-install --show --json`). A finished host, or a `min` too
old to know the command, sees nothing new. Otherwise the installer prints
the `--show` summary and, while some item is missing and a terminal is
attached, asks `Finish setup now? This runs one sudo command. [Y/n]`
(default yes, Enter runs `min finalize-install`). Declined, nothing
runnable yet, or no terminal: it prints the file route
`f=$(mktemp) && min finalize-install --show --script > "$f" && sudo sh "$f"`
and never blocks. A failed step is shown as ✗ with a retry pointer and the
installer still exits 0.

The AppArmor-only note is removed: the user-namespace restriction is one
of the items the step probes. The deb/rpm/apk postinstall and the Arch
hook run the equivalent step as root (the printed script, run directly,
never prompting) in place of the AppArmor loader call.

install_test.sh's stub `min` answers the probe from files under the home
and records every invocation; the NET-122 cases
installer_offers_finalize_install_on_a_tty,
installer_prints_the_pointer_when_declined_or_without_tty and
installer_does_not_prompt_on_a_finished_host cover the three outcomes,
on Linux and on macOS.
The CLI reference says a declined or terminal-less install prints
`run \`min finalize-install\` when you're ready`; the installer now leads
with that line and keeps the file route for a caller without a terminal on
the line after it.
@norrietaylor
norrietaylor requested a review from a team as a code owner October 9, 2026 23:25
@coderabbitai

coderabbitai Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Warning

Review limit reached

  • Run on-demand review

This review includes 6 billable files and costs up to $1.50.

  • Ask an admin to make reviews automatic

Open in CodeRabbit

Reviews can continue after your included limit without a manual trigger. An admin must approve usage-based billing.

Or wait 35 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used all 3 included reviews currently available. Your 45 included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Essentials
  • Run ID: 1b13246a-4b10-4216-bad0-b9d7a7710a7a

📥 Commits

Reviewing files that changed from the base of the PR and between 83f7a40 and d9a4b9f.


📒 Files selected for processing (6)
  • README.md
  • packaging/arch/minimal-bin.install
  • packaging/nfpm.yaml
  • scripts/install.sh
  • scripts/install_test.sh
  • scripts/package-nfpm.sh

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Comment @coderabbitai help to get the list of available commands.

@minimal-foundry

minimal-foundry Bot commented Oct 9, 2026 •

Copy link
Copy Markdown
Contributor

Reading e2ca9c8cbe27.

This comment updates when the review finishes.

@mitodrummer mitodrummer left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I checked each point against the code at this head (and finalize_install.rs/list.rs from #2142). The inline comments are the ones that still hold. Two items fall outside the diff:

  • scripts/pkg-smoke.sh L16-21 still says the --apparmor lane "exercises [the postinstall's] parser-present branch". That branch is gone. Inside an unprivileged distrobox, the reinstall now runs min finalize-install --show --script, which emits a userns block only when apparmor_restrict_unprivileged_userns reads non-zero. So the lane only proves that the shipped loader's --check still parses the profile, and the comment (and the PR body's "the smoke's --apparmor branch still checks...") should say that.
  • Nit: docs/reference/linux-host-setup.md Option 2 still sends curl | sh users to ~/.local/share/minimal/apparmor/install-apparmor-profile.sh. That still works because the loader still ships, but it never mentions min finalize-install, which the README now points at.

Comment thread scripts/package-nfpm.sh Resolved
Comment thread packaging/arch/minimal-bin.install Resolved
Comment thread packaging/nfpm.yaml Resolved
Comment thread scripts/install.sh Resolved
Comment thread scripts/install.sh Resolved
Comment thread scripts/install.sh Resolved
Comment thread scripts/install.sh Resolved
Comment thread scripts/install.sh Resolved
Comment thread scripts/install_test.sh Resolved
…fer matches on

scripts/install.sh gates the finalize-install offer on the substring
"state":"missing" in the report's bytes; a pretty-printed report would
silently turn every offer off, so a test asserts no whitespace follows a
state key's colon.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — approval withheld

Verdict COMMENT — APPROVE withheld: 9 unresolved threads — mitodrummer scripts/package-nfpm.sh:346, mitodrummer packaging/arch/minimal-bin.install:12, mitodrummer packaging/nfpm.yaml:82, mitodrummer scripts/install.sh:1340, mitodrummer scripts/install.sh:1343, …. No findings.

std::process::exit runs no destructor and a piped stdout is
block-buffered, so `min finalize-install --show --json > report.json`
on an unfinished host wrote an empty file. Every exit in the command now
flushes both streams first, and a CLI test runs the binary with stdout
piped and asserts the whole report arrives with exit 1.
Review of the offer (#2143) found four defects, fixed here:

- One probe, not two or three. `finalize-install --show --script` gives
  the summary (stderr) and, only while some item is missing, the script
  (stdout), so one call decides everything; each extra call re-read the
  daemon and waited out its connect retries on every fresh install. The
  compactness test on the `--show --json` bytes goes with the JSON gate.
- The offer and the pointer only while some item is `missing`. A fresh
  host's names item is `waiting` until a daemon runs; it now gets the
  summary and when to come back, not a command that runs nothing and
  exits 1. A `cannot`-only host gets the summary and nothing else.
- The run's stdout is dropped: it prints the summary again before it
  elevates, so the operator saw the status block twice. Its prompt is on
  the terminal and its outcome on stderr, both kept.
- Every printed command names `min` as this shell resolves it: by its
  quoted path until the bin dir is on PATH, which on a fresh install it is
  not yet, so pasting the file route no longer fails on `min: not found`.
  The probe's own warnings (a skipped broken VM) are not the summary and
  are filtered out of the installer's output.

The stub `min` answers `--show --script` from the home's fixture files,
prints the summary on a bare run as the real command does, and the
waiting fixture carries the line the real command renders; a cannot-only
case and a bin-dir-on-PATH case join the three spec cases.
…robe's root env

Running only `min finalize-install` from the deb/rpm/apk postinstall and
the Arch hook lost two things the loader call did: an upgrade no longer
refreshed an installed profile (the item is done once the file exists),
and a host that does not restrict user namespaces today got no profile
for the kernel that will. The loader runs first again, wherever
apparmor_parser is, on install and upgrade; the finalize step follows for
the rest.

The probe and the script now run under `env -i PATH=… HOME=/root`: under
an env-preserving package manager the operator's HOME/XDG would point the
names probe at their daemon socket, turn the item missing, and install the
resolver link and answerer service as a package side effect.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 2 findings, 2 inline.

Comment thread scripts/install.sh Resolved
Comment thread scripts/install.sh Resolved
…pointer

The accepted run's stdout was dropped to hide the summary it repeats, which
also dropped its closing lines: after a kvm group join, the one place the
operator learns the membership starts at the next login. Filter the run's
stdout against the probe's summary instead, so the status block stays single
and the closing lines show.

The pointer's first line read 'or without a terminal:' to an operator who
just declined on one; phrase the two routes as alternatives.
…rded member on --undo

One operator per line, appended only when absent, so a second user's run no
longer overwrites the first's name, and --undo (and the installer's manual
remedy) walk every line instead of a single cat.

Also renames the installer's test-only root override from
MINIMAL_OVERRIDE_NET_SETUP_ROOT to MINIMAL_OVERRIDE_FINALIZE_INSTALL_ROOT to
match the command it serves.

@mitodrummer mitodrummer left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Our review comments are addressed; thanks. The linux-host-setup.md nit (no mention of min finalize-install) can ride with the #2141 docs update.

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 1 finding, 1 inline.

Comment thread scripts/install.sh Resolved
… its detection

maybe_remove_finalize_install detected the classifier tree under
$_fi_root but printed a remedy against the bare $_cls_root; every other
artifact roots both. The remedy now quotes "$_fi_root$_cls_root", and the
installer test asserts it names the seeded root.
The accepted run rebuilds the probe's plan, so its stderr repeats the
'warning: skipping VM' lines the summary path filters. Capture the run's
stderr and print it with the same filter, on success and failure alike;
sudo's prompt is on the terminal, not that stream. The stub emits the
warning on its run too, and the failed case asserts the run's own error
is shown while the warning is not.
Base automatically changed from feat/2127-finalize-install to main October 10, 2026 04:47

@minimal-foundry minimal-foundry Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

minimal-review — advisory review

Verdict COMMENT — 1 finding, 1 inline.

Comment thread scripts/install.sh Resolved
@norrietaylor
norrietaylor disabled auto-merge October 10, 2026 05:28
@norrietaylor
norrietaylor merged commit a6357c2 into main Oct 10, 2026
6 checks passed
@norrietaylor
norrietaylor deleted the feat/2129-installer-finalize-offer branch October 10, 2026 05:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Installer: offer min finalize-install when the host needs it

2 participants