[PATCH v2 1/2] add script to check if the current environment supports rootless builds

[PATCH v2 1/2] add script to check if the current environment supports rootless builds

['Felix Moessbauer' via isar-users]

Running builds in rootless mode has a lot of non obvious pre conditions.
To help the user check if his system is configured correctly, we provide
a script that checks the needed features. If a feature is missing, it
issues an error regarding what likely is the root cause.

Signed-off-by: Felix Moessbauer <felix.moessbauer@siemens.com>
---
Changes since v1:
- ensure rootless is enabled before calling bitbake-getvar
- add -v option to print the RUN_PRIVILEGED_CMD variable
 scripts/isar-check-rootless | 55 +++++++++++++++++++++++++++++++++++++
 1 file changed, 55 insertions(+)
 create mode 100755 scripts/isar-check-rootless

diff --git a/scripts/isar-check-rootless b/scripts/isar-check-rootless
new file mode 100755
index 00000000..b5197111
--- /dev/null
+++ b/scripts/isar-check-rootless
@@ -0,0 +1,55 @@
+#!/bin/sh
+# Copyright (C) 2026 Siemens AG
+# SPDX-License-Identifier: MIT
+#
+# Helper script to check if the current environment supports unprivileged
+# rootless builds with unshare.
+# Returns 0 if supported, otherwise returns 1 and prints an error message to stderr.
+
+verbose=0
+if [ "$1" = "-v" ]; then
+	verbose=1
+fi
+
+if ! run_privileged_cmd=$( \
+	BB_ENV_PASSTHROUGH_ADDITIONS="${BB_ENV_PASSTHROUGH_ADDITIONS} ISAR_ROOTLESS" \
+	ISAR_ROOTLESS=1 bitbake-getvar -q --value RUN_PRIVILEGED_CMD); then
+	echo "error: cannot determine RUN_PRIVILEGED_CMD from BitBake" >&2
+	exit 1
+fi
+
+[ "$verbose" = 0 ] || echo "RUN_PRIVILEGED_CMD: $run_privileged_cmd" >&2
+
+if ! ${run_privileged_cmd} /bin/sh <<'EOF'
+	failed=0
+
+	fail() {
+		echo "error: $1" >&2
+		echo "       likely cause: $2" >&2
+		failed=1
+	}
+
+	mountpoint=$(mktemp -d)
+	if [ -n "$mountpoint" ]; then
+		if ! mount -t proc proc "$mountpoint"; then
+			fail "cannot mount procfs in the user namespace" \
+				"procfs is over-mounted by the container runtime, or the host security policy blocks procfs mounts"
+		else
+			umount "$mountpoint"
+		fi
+		rmdir "$mountpoint"
+	fi
+
+	if ! setpriv --reuid=nobody --regid=nogroup --clear-groups /usr/bin/true; then
+		fail "cannot execute as nobody:nogroup in the user namespace" \
+			"the subuid / subgid ID range is too small or incomplete"
+	fi
+
+	exit "$failed"
+EOF
+then
+	echo "error: unprivileged rootless builds are not supported; see the checks above" >&2
+	exit 1
+fi
+
+echo "unprivileged rootless builds are supported"
-- 
2.55.0

-- 
You received this message because you are subscribed to the Google Groups "isar-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to isar-users+unsubscribe@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/isar-users/20260821131229.2235147-1-felix.moessbauer%40siemens.com.

[PATCH v2 2/2] user_manual: document rootless build mode

['Felix Moessbauer' via isar-users]

Currently only the requirements for privileged execution are documented.
As we now support rootless execution as well, document this - along with
the requirements check script.

Signed-off-by: Felix Moessbauer <felix.moessbauer@siemens.com>
---
 doc/user_manual.md | 31 +++++++++++++++++++++++++++++--
 1 file changed, 29 insertions(+), 2 deletions(-)

diff --git a/doc/user_manual.md b/doc/user_manual.md
index dcc3f560..6c6814dd 100644
--- a/doc/user_manual.md
+++ b/doc/user_manual.md
@@ -140,9 +140,15 @@ To run images built for QEMU, you also need to install the related package:
 apt install qemu
 ```
 
-### Setup Sudo
+Isar has two execution modes: privileged (default), and rootless. The mode
+only determines how Isar obtains the privileges needed during a build; it does
+not affect the generated artifacts. The following sections describe their
+respective host requirements and setup.
 
-Isar requires `sudo` rights without password to work with `chroot`. To add them, use the following steps:
+### Privileged Builds
+
+Privileged execution requires `sudo` rights without password to work with `chroot`.
+To add them, use the following steps:
 ```
  # visudo
 ```
@@ -154,6 +160,27 @@ In the editor, allow the current user to run sudo without a password, e.g.:
 Replace `<user>` with your username. Use the tab character between the username and parameters.
 The second line will make sure your proxy settings will not get lost when using `sudo`. Include it if you are in the unfortunate position to having to deal with that.
 
+### Rootless Builds
+
+As an alternative to the privileged `schroot` backend, Isar can build using unprivileged user namespaces.
+To verify that the current host and user support rootless builds, run the
+following command after [initializing the build directory](#initialize-the-build-directory):
+
+```
+$ scripts/isar-check-rootless
+```
+
+Enable rootless builds in `conf/local.conf`:
+
+```
+ISAR_ROOTLESS = "1"
+```
+
+Files produced inside a rootless namespace can have ownership that the calling
+user cannot remove directly. Use `scripts/isar-clean-builddir --rootless <dir>`
+to clean a build directory with mixed ownership. When using a container, run
+the cleanup script from the same container environment that created the files.
+
 ### Check out Isar
 
 Clone the Isar repository:
-- 
2.55.0

-- 
You received this message because you are subscribed to the Google Groups "isar-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to isar-users+unsubscribe@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/isar-users/20260821131229.2235147-2-felix.moessbauer%40siemens.com.

Re: [PATCH v2 1/2] add script to check if the current environment supports rootless builds

[Zhihang Wei]

Applied to next, thanks.

Zhihang

On 8/21/26 15:12, 'Felix Moessbauer' via isar-users wrote:
> Running builds in rootless mode has a lot of non obvious pre conditions.
> To help the user check if his system is configured correctly, we provide
> a script that checks the needed features. If a feature is missing, it
> issues an error regarding what likely is the root cause.
>
> Signed-off-by: Felix Moessbauer <felix.moessbauer@siemens.com>
> ---
> Changes since v1:
> - ensure rootless is enabled before calling bitbake-getvar
> - add -v option to print the RUN_PRIVILEGED_CMD variable
>   scripts/isar-check-rootless | 55 +++++++++++++++++++++++++++++++++++++
>   1 file changed, 55 insertions(+)
>   create mode 100755 scripts/isar-check-rootless
>
> diff --git a/scripts/isar-check-rootless b/scripts/isar-check-rootless
> new file mode 100755
> index 00000000..b5197111
> --- /dev/null
> +++ b/scripts/isar-check-rootless
> @@ -0,0 +1,55 @@
> +#!/bin/sh
> +# Copyright (C) 2026 Siemens AG
> +# SPDX-License-Identifier: MIT
> +#
> +# Helper script to check if the current environment supports unprivileged
> +# rootless builds with unshare.
> +# Returns 0 if supported, otherwise returns 1 and prints an error message to stderr.
> +
> +verbose=0
> +if [ "$1" = "-v" ]; then
> +	verbose=1
> +fi
> +
> +if ! run_privileged_cmd=$( \
> +	BB_ENV_PASSTHROUGH_ADDITIONS="${BB_ENV_PASSTHROUGH_ADDITIONS} ISAR_ROOTLESS" \
> +	ISAR_ROOTLESS=1 bitbake-getvar -q --value RUN_PRIVILEGED_CMD); then
> +	echo "error: cannot determine RUN_PRIVILEGED_CMD from BitBake" >&2
> +	exit 1
> +fi
> +
> +[ "$verbose" = 0 ] || echo "RUN_PRIVILEGED_CMD: $run_privileged_cmd" >&2
> +
> +if ! ${run_privileged_cmd} /bin/sh <<'EOF'
> +	failed=0
> +
> +	fail() {
> +		echo "error: $1" >&2
> +		echo "       likely cause: $2" >&2
> +		failed=1
> +	}
> +
> +	mountpoint=$(mktemp -d)
> +	if [ -n "$mountpoint" ]; then
> +		if ! mount -t proc proc "$mountpoint"; then
> +			fail "cannot mount procfs in the user namespace" \
> +				"procfs is over-mounted by the container runtime, or the host security policy blocks procfs mounts"
> +		else
> +			umount "$mountpoint"
> +		fi
> +		rmdir "$mountpoint"
> +	fi
> +
> +	if ! setpriv --reuid=nobody --regid=nogroup --clear-groups /usr/bin/true; then
> +		fail "cannot execute as nobody:nogroup in the user namespace" \
> +			"the subuid / subgid ID range is too small or incomplete"
> +	fi
> +
> +	exit "$failed"
> +EOF
> +then
> +	echo "error: unprivileged rootless builds are not supported; see the checks above" >&2
> +	exit 1
> +fi
> +
> +echo "unprivileged rootless builds are supported"

-- 
You received this message because you are subscribed to the Google Groups "isar-users" group.
To unsubscribe from this group and stop receiving emails from it, send an email to isar-users+unsubscribe@googlegroups.com.
To view this discussion visit https://groups.google.com/d/msgid/isar-users/aa0eb471-8aa9-4ca8-aaab-a010aaecb0d5%40ilbers.de.