= genpac(5) Gokul Das B v0.1.0 :doctype: manpage :manmanual: Genpac Configuration Manual :mansource: Genpac {revnumber} :source-highlighter: pygments == Name genpac - System-wide and user-level configuration == Description The configuration for genpac consists of the following: . _Subuid_ and _Subgid_ allocation (in `/etc/subuid` and `/etc/subgid` files) . Filesystem permissions (in `/etc/fstab`) . Genpac configuration (in `$XDG_CONFIG_HOME/genpac/config.toml`) === Backends A backend is the underlying mechanism used for snapshotting. The choice of the backend depends on the filesystem in which the workspace resides, and is configured in the genpac configuration file. The following backends are available: *none*:: The default backend if one is not specified in the configuration file. This backend will mean that none of the snapshotting operations (creation and deletion of chroots) are available. *plain*:: This backend uses regular directory operations (_mkdir_, _cp_ & _rm_) to do snapshotting. This backend has the disadvantage that each new snapshot is a complete new copy with no file deduplication. The storage requirement becomes cumulative. This backend should therefore be used only if other options are not available. *btrfs*:: Uses _btrfs subvolumes_ to do snapshotting. This can be used only if the workspace is on a btrfs volume. The advantage of this backend is that each snapshot is a copy-on-write replica. Files common to snapshots are deduplicated, until they are overwritten. The storage requirement is therefore much less than that of the plain backend. == Configuration === Subuid & Subgid allocation Applications like Portage may require the use of privileged UIDs and GIDs within the sandbox. For example, Portage uses UID 0 (root) and UID 250 (for a system user that builds the packages). In order to make it unprivileged outside the sandbox, we map those UIDs/GIDs in the sandbox user namespace to several unprivileged UIDs/GIDs in the root/host namespace. What appears like UID 0 and 250 inside the sandbox will actually be some other UID/GID in the root namespace. Refer *namespaces(7)*, *subuid(5)* and *newidmap(1)* for more details on this. This sort of mapping is common to many unprivileged container runtimes like _podman_ and _incus_. Consequently, the same instructions apply for _genpac_ as well. Refer *<>* for details on how to assign subuids and subgids. Subuids are assigned in the file `/etc/subuid` and subgids in `/etc/subgid`. Both follow the same general format: [listing] larry:1001000000:1000000 Separated by colons (:) are username, starting UID/GID and number of IDs mapped. It's recommended to map at least 65536 IDs to the applicable user. === Filesystem permissions The ability to create and delete snapshots depend on the filesystem and backend of the workspace. While these are self-explanatory, some backends like _btrfs_ have quirks that are noted here. ==== Btrfs backend btrfs filesystems generally allow creation of subvolumes (for snapshots in this case) if the user has write permissions. However, deletion of subvolumes require that the btrfs volume be mounted with the *user_subvol_rm_allowed* option in `/etc/fstab` file. Refer *btrfs(5)* for more details, including the reasoning behind this design. Further details are available in this StackOverflow answer: <>. IMPORTANT: Furthermore, it seems that this option works only if it is applied to the first mounted subvolume in the volume <>. The rest of the subvolumes inherit this option. == Genpac configuration The genpac configuration file is `$XDG_CONFIG_HOME/genpac/config.toml`. This is `$HOME/.config/genpac/config.toml` by default, unless `$XDG_CONFIG_HOME` is set. The file is in TOML <> format. === Path variables section *vars.path* is currently the only _variables section_ in config.toml. It stores paths for substitution in paths in other parts of the configuration. This section is completely optional and customizable. .Typical example: [,toml] ---- [vars.paths] configs = "~/myproject/configs" overlay = "~/myproject/overlay" repodir = "/var/db/repos" portage = "/etc/portage" ---- The keys are the variable names. Keys can be subsituted in any path variable using the format: `$\{varname}`. === Workspace section This section defines the features of the workspace directory. .Example: [,toml] ---- [workspace] location = "~/chroots" backend = "btrfs" ---- CAUTION: Make sure that the you have read and write access to the workspace location. This should preferably be within you home directory. The backend must also match the filesystem in which the workspace resides. === Snapshot section This section is used only by the _snapshot_ subcommand. We can optionally designate a chroot as the default _template_ here. This is useful in avoiding having to type out the full source chroot name while creating new chroots. A template chroot is no different from regular chroots in any other way. .Example: [,toml] ---- [snapshot] template = "base" ---- NOTE: As is the convention, all chroots are identified by their names and not paths. Names are the top-level directory names of chroots within the workspace. === IDMaps section This section is used by commands that enters the sandbox. That includes the _snapshot_ and _extract_ subcommands. .Example: [,toml] ---- [idmaps] uid = [[0, 1000, 1], [1, 2000001, 65535]] gid = [[0, 1000, 1], [1, 2000001, 65535]] ---- The uid and gid maps are specified as arrays of 3-tuples. The values within the 3-tuple follow the same convention as *newuidmap(1)*: * First value: Starting UID/GID inside the sandbox * Second value: Corresponding starting UID/GID in the root/host namespace * Third value: Number of UIDs/GIDs mapped (in both namespaces) [CAUTION] ==== * It's easy to get this wrong and prevent the sandbox from launching * Make sure that all the mapped UIDs/GIDs are designated to you in `/etc/sub[u|g]id`. Sandbox will fail otherwise * If in doubt, follow the examples here and change incrementally ==== The convention is to map UID/GID 0 (root) inside the sandbox to your own primary UID/GID (usually 1000, but may vary). This way, you can edit and manage any root files inside the chroot directly. The rest of the privileged UIDs/GIDs in the sandbox (1 to 999, or beyond) may be mapped to your assigned sub-UIDs/GIDs. === Sandbox section This section is used exclusively by the _sandbox_ subcommand. .Example: [,toml] ---- [sandbox] command = "/bin/bash --login" tmpfs-size = 10 ---- command:: The default command to launch if the user doesn't supply one. This is usually a shell. tmpfs-size:: The size of _tmpfs_ in GiB to assign to `/var/tmp/portage` for building packages. This is optional. If omitted or set to 0, regular storage will be used instead of tmpfs. Refer <> for more information. === Sandbox repository mounts This section is used to mount repositories on host system into the chroot. The advantage of this is that it's not required to sync repos on each chroot. .Example: [,toml] ---- [sandbox.mounts.repos] gentoo = "${repodir}/gentoo" guru = "${repodir}/guru" mypkgs = "${overlay}" ---- The key is the name of the repo. The repo will be mounted at `/var/db/repos/` inside the chroots. The corresponding values give the actual location of the repos on the host. These paths can use path variable substitution if desired. NOTE: The repos are mounted read-only inside the chroot. This prevents accidental modification from inside the chroot. However, they are still modifiable from the host using regular methods, depending upon your permissions. The changes made to the repos on the host reflect immediately inside the chroot sandbox. === Sandbox file mounts This is useful for maintaining certain configuration files independently from the chroots. Examples includes make.conf and package.use files. Another significant example is `/etc/profile` file. A patch is provided with this project to create a profile file that automatically displays the active sandbox/chroot name in the bash prompt. .Example: [,toml] ---- [[sandbox.mounts.files]] src = "${configs}/profile" dest = "/etc/profile" ---- src:: Location of the file on the host system. Path variable substitution is available. dest:: Location inside the chroot where the file is to be mounted. Path variable substitution is avialable. [NOTE] ==== * This section is an array. It can be repeated as many times as there are files to mount. * The mount is read-only, just like repo mounts. Same conditions apply. ==== == Example .Full sample config.toml: [,toml] ---- include::../examples/config.toml[lines=9..-1] ---- == See Also *genpac*(1), *namespaces*(7), *subuid*(5), *subgid*(5), *newuidmap*(1), *newgidmap*(1), *btrfs*(5) [#gw-subid,reftext=Gentoo wiki: Subuid subgid [1]] *[1]* https://wiki.gentoo.org/wiki/Subuid_subgid [#so-btrfs,reftext=[2]] *[2]* https://unix.stackexchange.com/a/91921 [#aw-btrfs,reftext=[3]] *[3]* https://bbs.archlinux.org/viewtopic.php?pid=1848289#p1848289 [#toml,reftext=[4]] *[4]* https://toml.io/en/ [#gw-tmpfs,reftext=Gentoo wiki: Portage TMPDIR [5]] *[5]* https://wiki.gentoo.org/wiki/Portage_TMPDIR_on_tmpfs