Skip to content

Unroot 1.0.0

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 04 Aug 06:35
1.0.0
5902795

Initial Release — August 2026

unroot is a small, daemonless toolkit for entering, modifying, and transporting
Linux root filesystems. It brings together rootless multi-user chroots,
automatic QEMU emulation, and full-metadata archive transport in one binary.

Originally developed as the namespace engine for FFS, unroot is now a focused
Kernel Seeds project with its own release boundary and test matrix.

What's New

Three Explicit Modes

unroot keeps ownership choices explicit rather than guessing:

  • Managed rich roots — Unprivileged multi-user roots using subordinate UID/GID
    ranges. Perfect for build and packaging work without host root.
  • Native roots — Host-owned or mounted filesystems with native ownership.
    Requires sudo for conventional chroot behavior.
  • Single mode — Run commands as namespace root with the host filesystem
    visible. Trusted builds needing capabilities without subordinate IDs.

unroot never silently downgrades rich ownership to single-ID or escalates an
unprivileged request into host-root execution.

Rootfs Archives

  • unroot unpack ARCHIVE ROOT — Extract a tar archive into a managed rootfs
    with correct ownership mapping. Rich preservation is the default.
  • unroot pack ROOT ARCHIVE — Capture a rootfs with full metadata: permissions,
    timestamps, links, sparse files, ACLs, xattrs, file capabilities, and SELinux
    labels.
  • Automatic compression from suffix (.gz, .xz, .zst, etc.)
  • Host-specific .unroot metadata excluded from portable archives

Foreign Architecture Execution

  • Automatic architecture detection for ELF binaries and shebang interpreters
  • Private QEMU emulation for rich roots — active only inside the rootfs
  • Host-wide emulation for native mode (current boot only)
  • Explicit refusal with --emulation never or manual selection with
    --qemu and --qemu-cpu
  • Validated across x86-64 ↔ ARM64 in both directions

unroot handles execution compatibility. You remain responsible for distro
profiles, compiler flags, and CPU baselines.

Environment Control

  • --cwd — Set working directory inside the rootfs
  • --env VAR=value — Set explicit environment variables
  • --persist-env VAR — Copy selected variables from the host
  • --map-ro HOST:CONTAINER — Read-only host path mappings
  • Clean environment by default; bare commands require explicit PATH

Security Model

unroot is designed for trusted build, packaging, and rootfs-maintenance
workloads. It is not a hostile-code sandbox:

  • ✓ Private mount and PID namespaces
  • ✓ User namespace isolation (rich roots and single mode)
  • ✓ Namespace root ≠ host root
  • ✗ Shared network, IPC, hostname, cgroups, and kernel
  • ✗ No syscall filters, resource limits, or MAC policies

Use unroot with root filesystems and commands you trust.

What's Included

Binaries:

  • unroot — Static namespace engine (x86-64 and ARM64)
  • unroot-util — Dynamic helper for rich roots (included in packages)

Packages: Native .deb and .rpm packages for:

  • Debian 13 (Bookworm)
  • Ubuntu 24.04 LTS and 26.04
  • Fedora 44
  • Enterprise Linux 9 (Rocky Linux 9)

QEMU: Packages recommend the distribution's static QEMU user-mode emulator
for multi-architecture support, but it's not required — unroot works without it
for native roots. EL9 users should install QEMU separately if foreign execution
is needed.

All artifacts are built, tested, and validated by release CI before publication.

Known Limitations

  • First release focuses on entry and transport — no OCI packaging, overlays,
    or persistent sessions yet
  • Native mode registers host-wide binfmt_misc handlers (current boot only)
  • Requires Linux 5.12+ for --map-ro, 6.7+ for private rich-mode foreign
    execution
  • Subordinate UID/GID allocation required for rich roots (configured by
    distribution in /etc/subuid and /etc/subgid)

See Initial Public Release Scope for details
on what's deliberately outside this release.

Getting Started

# Enter a rootfs
unroot enter ~/rootfs

# Unpack an ARM64 Raspberry Pi rootfs on your x86-64 workstation
unroot unpack raspi4-rootfs.tar.xz ~/roots/raspi4
unroot enter ~/roots/raspi4

# Build as namespace root without sudo
unroot single --persist-env PATH -- make -j32

For complete usage examples, see README.md.

Assets 16
Loading