diff mbox series

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

Message ID 20260821131229.2235147-2-felix.moessbauer@siemens.com
State Under Review
Headers show
Series [v2,1/2] add script to check if the current environment supports rootless builds | expand

Commit Message

Felix Moessbauer Aug. 21, 2026, 1:12 p.m. UTC 
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 mbox series

Patch

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: