# 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](https://wiki.gentoo.org/wiki/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](https://github.com/containers/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](https://www.rust-lang.org/) stable toolchain Older toolchains (>=1.56) may work. But this isn't verified. The recommended way to install the toolchain is using [rustup](https://rustup.rs/). Refer [rustup documentation](https://www.rust-lang.org/tools/install) for more details. **Runtime dependencies:** 1. [Bubblewrap](https://github.com/containers/bubblewrap) for sandboxing 2. [Tar](https://www.gnu.org/software/tar/) for extraction of stage3 archive ### Build The application can be built by running the following inside the source tree: ```sh 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: ```sh 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](doc) directory: - Configuration - Usage These are provided as [AsciiDoc](https://asciidoc.org/) 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](https://lists.sr.ht/~gokuldas/projects) as: - [email patches](https://git-send-email.io/), or - [git request-pull](https://git-scm.com/docs/git-request-pull) over email You are required to [sign-off](https://docs.pi-hole.net/guides/github/how-to-signoff/) your commits - which means that you certify your contributions under [Developer Certificate of Origin](https://developercertificate.org/). 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](https://git.sr.ht/~gokuldas/free-software/tree/HEAD/CONTRIBUTING.md) 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](LICENSE) or visit [FSF website](https://www.gnu.org/licenses/gpl-3.0.en.html).