Gentoo Packaging Environment (genpac)

Genpac is a development tool for managing unprivileged and sandboxed Gentoo chroots for testing Ebuild packages.

Use case: Gentoo ebuilds have to be tested in a clean, minimal Gentoo chroot to ensure that any required dependencies are not masked or hidden by packages already installed in the system. This requires a clean test environment. While there are many ways to do this, most recommended methods require either a full container/VM manager or chroots with superuser privileges.

Genpac takes an approach that utilizes an ordinary chroot (unlike VMs or container tools), but with the restricted privileges of a regular non-admin user account. Genpac achieves this using bubblewrap (a sandboxing tool) and Linux user namespaces with UID/GID mapping. More details of this is given in the configuration documentation.

Functions, Features & Advantages

Genpac is capable of the following:

1. Manage several chroots in a predefined workspace directory
2. Create new chroots from one of the following:

• A Gentoo stage3 archive (or even root archive of other distros)
• Another chroot
• A chroot that's designated as a default template

3. Start a sandboxed application inside one of the chroots with:

• Read-only mounts of repositories and configuration files (needs system configuration)
• Root privileges inside the chroot (necessary for Portage tools)
• No root privileges or filesystem access outside the chroot

4. Delete chroots when they are no longer needed (needs system configuration)
5. (Optional, disabled by default) Convert stage3 archive with remapping of UIDs/GIDs

Genpac supports the following chroot backends:

• None (does nothing)
• Btrfs (complete)
• Plain directories (planned)
• Bcachefs (planned)

This has several advantages over the traditional methods:

• Easy management of chroots with single-word names and simple commands
• It's not necessary to remember or script the necessary mounts or bubblewrap parameters
• Read-only mounts make it impossible to corrupt repos or config files inside the sandbox
  • These are still editable from the host namespace
  • Changes from outside reflect immediately inside the sandbox
  • A patch for /etc/profile is provided, that displays the active chroot in the prompt
• Chroot contents are owned by the regular user
  • Chroot contents can be edited by the regular user with familiar tools and no additional permissions
  • Extraction of stage3 archive doesn't require superuser privileges, even if the archive contains files with different UIDs/GIDs
• Even if an application manages to jailbreak the sandbox, its privileges are limited by that of the regular user

Installation

An ebuild will eventually be provided to install the application. It may require useflags to be set to install documentation and optional features. The rest of this section deals with how to install genpac from source.

Dependencies

Build-time dependencies:

1. The latest stable Rust stable toolchain

Older toolchains (>=1.56) may work. But this isn't verified. The recommended way to install the toolchain is using rustup. Refer rustup documentation for more details.

Runtime dependencies:

1. Bubblewrap for sandboxing
2. Tar for extraction of stage3 archive

Build

The application can be built by running the following inside the source tree:

cargo build --release

Add the --features=rempap flag if you need the remap feature. It's alright to avoid this feature for regular use.

The application may then be copied from target/release/genpac to any directory included in the PATH variable. Alternatively, run the following to build and install genpac into the cargo binaries directory:

cargo install --locked --path .

Make sure that the cargo binaries directory (usually ~/.cargo/bin/) is included in the PATH variable.

Setup

Genpac requires two simple types of configuration:

• System-level subuid & subgid allocation (in /etc/subuid and /etc/subgid files)
• User-level application configuration (in ~/.config/genpac/config.toml)

Refer configuration documentation for more details.

Documentation

The following documentation is made available in the doc directory:

• Configuration
• Usage

These are provided as AsciiDoc files. It may be converted to and viewed as HTML, PDF or man pages.

Status & Contribution

The application is ready for regular use and may be considered as beta quality. However, the 1.0 release is delayed for further testing and any meaningful feature requests.

Contributions are welcome. Modifications may be sent to my sourcehut projects mailing list as:

• email patches, or
• git request-pull over email

You are required to sign-off your commits - which means that you certify your contributions under Developer Certificate of Origin. Your contributions will be added with the same license as the rest of the project, except under explicitly specified circumstances. Please refer the detailed contributor guidelines if you need more information.

License

Copyright (C) 2023 Gokul Das B

The contents of repository are covered by GNU General Public License version 3 or later (GNU GPLv3 or later). You may use, modify or distribute the code under the terms of this license. For more details, please refer the LICENSE or visit FSF website.