class

Bootstrap::SysrootNamespace

Inherits Bootstrap::CLI < Reference < Object

SysrootNamespace encapsulates user/mount namespaces and optional rootfs mounting to provide a sudo-less entrypoint into the sysroot when supported by the kernel.

Constants

APPARMOR_USERNS_RESTRICTED_VALUE = "1"

Linux kernel sysctl: Documentation/admin-guide/LSM/apparmor.rst

APPARMOR_USERNS_SYSCTL_PATH = "/proc/sys/kernel/apparmor_restrict_unprivileged_userns"
CLONE_NEWIPC = 134217728
CLONE_NEWNET = 1073741824
CLONE_NEWNS = 131072

Namespace and mount constants from Linux headers:

  • linux/sched.h (CLONE_NEW*)
  • linux/mount.h (MS_*)
CLONE_NEWUSER = 268435456
CLONE_NEWUTS = 67108864
DEFAULT_PATH = "/opt/sysroot/bin:/opt/sysroot/sbin:/usr/bin:/usr/sbin:/bin:/sbin"
MNT_DETACH = 2
MS_BIND = 4096_u64
MS_NODEV = (1_u64 << 2)
MS_NOEXEC = (1_u64 << 3)
MS_NOSUID = (1_u64 << 1)
MS_PRIVATE = (1_u64 << 18)
MS_RDONLY = (1_u64 << 0)
MS_REC = 16384_u64
MS_REMOUNT = (1_u64 << 5)
USERNS_TOGGLE_DISABLED_VALUE = "0"
USERNS_TOGGLE_ENABLED_VALUE = "1"

Linux kernel sysctl: Documentation/admin-guide/sysctl/kernel.rst

USERNS_TOGGLE_PATH = "/proc/sys/kernel/unprivileged_userns_clone"

Class methods

aliases

Return additional command aliases for sysroot namespace tooling.

Source
apparmor_restriction(current_path : Path = Path["/proc/self/attr/current"], userns_sysctl_path : Path = Path[APPARMOR_USERNS_SYSCTL_PATH]) : String | Nil

Returns a restriction message if AppArmor confinement is detected. This checks the current label and the sysctl that restricts unprivileged user namespaces.

Source
bind_mount_file(source : String | Path, target : Path)

Bind-mounts a source file to a file target.

Source
collect_restrictions(proc_root : Path = Path["/proc"], filesystems_path : Path = Path["/proc/filesystems"], proc_status_path : Path = Path["/proc/self/status"], userns_toggle_path : String = USERNS_TOGGLE_PATH) : Array(String)

Collects restriction messages that can prevent user-namespace mounts of proc/sys/dev from succeeding on the current host.

Source
ensure_unprivileged_userns_clone_enabled!(path : String = USERNS_TOGGLE_PATH)

Raises a NamespaceError with a clear diagnostic when user namespaces are disabled via the kernel toggle.

Source
enter_rootfs(rootfs : String, extra_binds : Array(Tuple(Path, Path)) = [] of Tuple(Path, Path), bind_host_dev : Bool = true, unmount_old_root : Bool = true)

Enter the provided rootfs by unsharing namespaces, bind-mounting the rootfs, mounting /proc, /dev, and /sys, then pivoting into the new root. When bind_host_dev is true, /dev is bind-mounted recursively from the host (Linux From Scratch kernfs style) to avoid relying on dev-enabled tmpfs inside user namespaces. When unmount_old_root is true, the old root is detached after pivot_root.

Source
enter_rootfs_with_setup(rootfs : String, extra_binds : Array(Tuple(Path, Path)) = [] of Tuple(Path, Path), home : String = "/root", extra_env : Hash(String, String) = {} of String => String, run_alpine_setup : Bool = false) : Nil

Enter a rootfs and apply the standard environment/toolchain setup.

Source
help_entries

Describe help output entries for sysroot namespace commands.

Source
missing_filesystems(path : Path, required : Array(String)) : Array(String)

Returns a list of filesystem types that are missing from /proc/filesystems.

Source
run(args : Array(String), command_name : String) : Int32

Dispatch sysroot namespace subcommands by command name.

Source
seccomp_mode(status_path : Path = Path["/proc/self/status"]) : String | Nil

Returns the seccomp mode from /proc/self/status, or nil when absent.

Source
summary

Summarize the sysroot namespace CLI behavior for help output.

Source
unprivileged_userns_clone_enabled?(path : String = USERNS_TOGGLE_PATH) : Bool

Returns true when unprivileged user namespace cloning is enabled. If the toggle path does not exist or contains an unexpected value, default to false for safety.

Source
unshare_namespaces(uid : Int32 = LibC.getuid.to_i32, gid : Int32 = LibC.getgid.to_i32)

Create a new user namespace, map the current uid/gid, and then unshare the mount namespace. This preserves the common unprivileged flow: unshare(CLONE_NEWUSER) -> write uid/gid maps -> unshare(CLONE_NEWNS).

Source

Nested types