# 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).