From 9cbe6d9a8c4e40a2d57f787c0a1d006f00d83bc1 Mon Sep 17 00:00:00 2001
From: linkst <2024023709@m.scnu.edu.cn>
Date: Sat, 1 Aug 2026 15:21:56 +0800
Subject: [PATCH] docs(sandbox): document newuidmap/newgidmap dependency for
 --map-auto fallback

The fallback candidate relies on the setuid newuidmap/newgidmap helpers
(uidmap package) plus a subuid/subgid range for the current user. Note in
the candidate docs that the startup probe rejects the candidate when those
are missing, so the plain --map-root-user form is used instead.
---
 rust/crates/runtime/src/sandbox.rs | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

diff --git a/rust/crates/runtime/src/sandbox.rs b/rust/crates/runtime/src/sandbox.rs
index 4eaaaf36..9bf5b0f2 100644
--- a/rust/crates/runtime/src/sandbox.rs
+++ b/rust/crates/runtime/src/sandbox.rs
@@ -290,8 +290,12 @@ fn command_exists(command: &str) -> bool {
 /// Most systems accept `--map-root-user` alone. On kernels or containers that
 /// block unprivileged writes to `/proc/self/uid_map` (e.g. GitHub Actions,
 /// restricted AppArmor profiles), util-linux instead delegates to the setuid
-/// `newuidmap`/`newgidmap` helpers when `--map-auto` is also present; that
-/// requires the current user to have a range in `/etc/subuid`/`/etc/subgid`.
+/// `newuidmap`/`newgidmap` helpers when `--map-auto` is also present.
+///
+/// That fallback therefore depends on the setuid helpers (the `uidmap`
+/// package on Debian/Ubuntu) and on the current user having a range in
+/// `/etc/subuid` and `/etc/subgid`. When either is missing, `--map-auto`
+/// fails and the startup probe rejects the candidate, keeping the plain form.
 const UNSHARE_MAPPING_CANDIDATES: &[&[&str]] = &[
     &["--user", "--map-root-user"],
     &["--user", "--map-root-user", "--map-auto"],