docs(linux-setup): cleanup, simplify - #1092
Conversation
📝 WalkthroughWalkthroughThe Linux host setup reference now explains Ubuntu 24.04+ user-namespace restrictions, clarifies diagnostic symptoms, and documents host-wide, minimald-specific, and kernel-level remediation options. ChangesLinux host setup guidance
Estimated code review effort: 1 (Trivial) | ~5 minutes Possibly related PRs
Suggested reviewers: Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Comment |
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/reference/linux-host-setup.md`:
- Around line 44-57: Add a prominent security warning immediately before “Option
1” in the Linux host setup documentation, stating that the host-wide setting
disables Ubuntu’s unprivileged-user-namespace restriction for every program,
weakens kernel-exploit mitigation, and persists across reboots. Advise users to
prefer Option 2 whenever possible.
- Around line 58-89: Add a concise note in the AppArmor installation section
stating that any already-running minimald instance must be restarted to acquire
the newly installed profile label, and clarify that the change applies to future
or restarted instances.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 736389be-7684-4037-8a72-4a20278fc6ba
📒 Files selected for processing (1)
docs/reference/linux-host-setup.md
| ## Option 1: enable unprivileged user namespace creation host-wide | ||
|
|
||
| Ubuntu's intended accommodation is a profile that grants the binary the `userns` | ||
| permission, the same thing the distro ships for `rootlesskit`, `runc`, and | ||
| `podman`. minimal ships one in `packaging/apparmor/`: | ||
| The following disables the restriction for every program on the host until the next reboot: | ||
|
|
||
| ```console | ||
| $ sudo scripts/install-apparmor-profile.sh | ||
| loaded the minimald AppArmor profile (/etc/apparmor.d/minimald) | ||
| $ sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 | ||
| ``` | ||
|
|
||
| To persist this change across reboots, create a file in `/etc/sysctl.d/`: | ||
|
|
||
| ```console | ||
| $ sudo sh -c "echo 'kernel.apparmor_restrict_unprivileged_userns=0' > /etc/sysctl.d/enable-user-ns.conf" | ||
| ``` | ||
|
|
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
Add a security warning before recommending the host-wide option.
This disables Ubuntu’s unprivileged-user-namespace restriction for every program and persists that weaker posture. Ubuntu documents that this also removes mitigation against kernel exploits, so explicitly warn users and prefer Option 2 when possible. (discourse.ubuntu.com)
Suggested wording
## Option 1: enable unprivileged user namespace creation host-wide
+> **Security warning:** This disables an AppArmor security restriction for
+> every program on the host. Prefer Option 2 unless host-wide enablement is
+> required.
+
The following disables the restriction for every program on the host until the next reboot:📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| ## Option 1: enable unprivileged user namespace creation host-wide | |
| Ubuntu's intended accommodation is a profile that grants the binary the `userns` | |
| permission, the same thing the distro ships for `rootlesskit`, `runc`, and | |
| `podman`. minimal ships one in `packaging/apparmor/`: | |
| The following disables the restriction for every program on the host until the next reboot: | |
| ```console | |
| $ sudo scripts/install-apparmor-profile.sh | |
| loaded the minimald AppArmor profile (/etc/apparmor.d/minimald) | |
| $ sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 | |
| ``` | |
| To persist this change across reboots, create a file in `/etc/sysctl.d/`: | |
| ```console | |
| $ sudo sh -c "echo 'kernel.apparmor_restrict_unprivileged_userns=0' > /etc/sysctl.d/enable-user-ns.conf" | |
| ``` | |
| ## Option 1: enable unprivileged user namespace creation host-wide | |
| > **Security warning:** This disables an AppArmor security restriction for | |
| > every program on the host. Prefer Option 2 unless host-wide enablement is | |
| > required. | |
| The following disables the restriction for every program on the host until the next reboot: | |
🧰 Tools
🪛 markdownlint-cli2 (0.23.1)
[warning] 49-49: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 55-55: Dollar signs used before commands without showing output
(MD014, commands-show-output)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/linux-host-setup.md` around lines 44 - 57, Add a prominent
security warning immediately before “Option 1” in the Linux host setup
documentation, stating that the host-wide setting disables Ubuntu’s
unprivileged-user-namespace restriction for every program, weakens
kernel-exploit mitigation, and persists across reboots. Advise users to prefer
Option 2 whenever possible.
| ## Option 2: install minimald's AppArmor profile | ||
|
|
||
| If you installed minimal with the `curl … | sh` installer rather than from a | ||
| checkout, the same loader ships alongside the binaries; run it with root: | ||
| If you installed Minimal with the `curl … | sh` installer, you can | ||
| grant user namespace creation to minimald alone instead of | ||
| system-wide: | ||
|
|
||
| ```console | ||
| $ sudo bash ~/.local/share/minimal/apparmor/install-apparmor-profile.sh | ||
| loaded the minimald AppArmor profile (/etc/apparmor.d/minimald) | ||
| ``` | ||
|
|
||
| The installer prints this exact hint on its own when it detects the restriction | ||
| on the host, so you do not have to know to look for it. | ||
| The only change to your system is allowing minimald to create user | ||
| namespaces. To remove the profile run: | ||
|
|
||
| The profile **confines nothing**: it is declared `flags=(unconfined)`, so it | ||
| does not restrict what minimald may do. It exists only to give minimald a named | ||
| AppArmor label, because on Ubuntu only a *labelled* program can be granted | ||
| `userns`. Installing it neither sandboxes minimald nor weakens the host. | ||
| ```console | ||
| $ sudo bash ~/.local/share/minimal/apparmor/install-apparmor-profile.sh --uninstall | ||
| ``` | ||
|
|
||
| It attaches to minimald at the paths it is normally installed to: `/usr/bin`, | ||
| `/usr/local/bin`, and `~/.local/bin` (where the installer puts | ||
| it). A binary somewhere else (a dev build in `target/debug`, or a custom | ||
| `MINIMAL_BIN`) needs that path named explicitly, because AppArmor matches | ||
| profiles by executable path: | ||
| If you built minimald from source on an Ubuntu system, run | ||
| the following script in the source directory to allow it to create | ||
| user namespaces: | ||
|
|
||
| ```console | ||
| $ sudo scripts/install-apparmor-profile.sh --path "$PWD/target/debug/minimald" | ||
| ``` | ||
|
|
||
| Re-run the installer after moving or reinstalling the binary. To remove the | ||
| profile: `sudo scripts/install-apparmor-profile.sh --uninstall` (from a | ||
| checkout) or `sudo bash ~/.local/share/minimal/apparmor/install-apparmor-profile.sh --uninstall` | ||
| (curl-installed). `minimal`'s own uninstaller | ||
| (`curl … | sh -s -- --uninstall`) also offers to remove this system profile, | ||
| prompting on a terminal, or printing the root command otherwise. | ||
|
|
||
| ## Alternative: lift the restriction host-wide | ||
|
|
||
| If you cannot install a profile, turn the restriction off: | ||
| To remove the AppArmor profile: | ||
|
|
||
| ```console | ||
| $ sudo sysctl -w kernel.apparmor_restrict_unprivileged_userns=0 # until reboot | ||
| $ sudo scripts/install-apparmor-profile.sh --uninstall # from a checkout | ||
| ``` | ||
|
|
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
scripts=()
while IFS= read -r path; do
scripts+=("$path")
done < <(fd -a -t f 'install-apparmor-profile\.sh$')
((${`#scripts`[@]} > 0)) || {
echo "No AppArmor installer script found" >&2
exit 1
}
for path in "${scripts[@]}"; do
echo "== $path =="
rg -n -- '--uninstall|--path|restart|reload' "$path"
doneRepository: gominimal/minimal
Length of output: 207
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
printf 'Files:\n'
fd -a -t f 'install-apparmor-profile\.sh$' .
printf '\nScript outlines:\n'
for path in $(fd -a -t f 'install-apparmor-profile\.sh$' .); do
echo "== $path =="
wc -l "$path"
sed -n '1,220p' "$path"
echo
doneRepository: gominimal/minimal
Length of output: 4897
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
echo "Searching for AppArmor installer scripts..."
find . -type f -name 'install-apparmor-profile.sh' -o -type f -path '*/install-apparmor-profile.sh' | sort
echo
echo "Searching for AppArmor references..."
rg -n --hidden --glob '!**/.git/**' 'install-apparmor-profile|apparmor|minimald' .Repository: gominimal/minimal
Length of output: 50374
🏁 Script executed:
#!/usr/bin/env bash
set -euo pipefail
sed -n '240,260p' scripts/session-e2e.sh
printf '\n---\n'
sed -n '440,458p' justfile
printf '\n---\n'
sed -n '58,92p' docs/reference/linux-host-setup.mdRepository: gominimal/minimal
Length of output: 3512
Add a restart note for running minimald instances. A daemon started before this step will keep its old AppArmor label until it is restarted, so the docs should call that out here.
🧰 Tools
🪛 LanguageTool
[grammar] ~69-~69: Ensure spelling is correct
Context: ... only change to your system is allowing minimald to create user namespaces. To remove th...
(QB_NEW_EN_ORTHOGRAPHY_ERROR_IDS_1)
🪛 markdownlint-cli2 (0.23.1)
[warning] 73-73: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 81-81: Dollar signs used before commands without showing output
(MD014, commands-show-output)
[warning] 87-87: Dollar signs used before commands without showing output
(MD014, commands-show-output)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/linux-host-setup.md` around lines 58 - 89, Add a concise note
in the AppArmor installation section stating that any already-running minimald
instance must be restarted to acquire the newly installed profile label, and
clarify that the change applies to future or restarted instances.
|
STE linting looks good c: |
Summary
Simplify linux-setup page about enabling unprivileged user namespace creation
Testing
It rendered ok in my editors markdown mode
Checklist
BREAKING CHANGE:footer present if this is a breaking change (no breaking changes)Note
Rewrite Linux host setup documentation to clarify sandboxing and user namespace configuration
kernel.unprivileged_userns_clonealongsideCONFIG_USER_NSanduser.max_user_namespaces.Macroscope summarized 86ac1ef.
Summary by CodeRabbit