= genpac(1) Gokul Das B v0.1.0 :doctype: manpage :manmanual: Genpac Command Manual :mansource: Genpac {revnumber} == Name genpac - Manage unprivileged and sandboxed Gentoo chroots for testing Ebuild packages. == Synopsis [subs=+quotes] ---- *genpac* [*-h*|*--help*] [*-v*|*--verbose*] [*-q*|*quiet*] [*-n*|*--dry-run*] *sandbox*|*sbox* _CHROOT_ [_COMMAND_ ...] *snapshot*|*snap* *list*|*ls* *add*|*make*|*mk*|*create* <**--template**|*--blank*|*--source* _SOURCE_> _TARGET_ *del*|*delete*|*rm* _TARGET_ *extract* _ARCHIVE_ _CHROOT_ *remap* _SOURCE_ _DESTINATION_ *help* [_COMMAND_] ---- == Description *Genpac* is a development tool used for creating, managing and using unprivileged and sandboxed Gentoo chroots for the purpose of developing Ebuild packages. New chroots may be created blank, copied from another chroot or made from Gentoo stage3 sysroot archive. Sandboxed applications can be launched inside the chroot using genpac. Genpac uses bubblewrap *bwrap(1)* to achieve the sandboxing. Sandboxed applications have superuser privileges inside the sandboxed chroot, allowing the use of Portage tools to test the Ebuild. However, these applications have regular user privileges outside the sandbox and chroot - allowing regular user to test Ebuilds without using sudo/doas or other superuser privileges. The files inside the chroot are owned by the regular user, though they appear to be owned by the superuser inside the sandbox. Thus, these files can be edited and managed by the regular user without any privileges. === Terminology The following terminology will be used throughout the manuals for genpac: [horizontal] *Workspace*:: A directory that holds all the chroots. Preferably within user's home directory. *Chroot*:: A top-level directory within the workspace that holds a GNU/Linux root filesystem (It may also be empty, prior to being populated by such a filesystem). Chroots are identified by just the directory name component (the suffix) of the directory path. Full path is not used anywhere in genpac commands. *Snapshot*:: Snapshotting is an operation where a chroot's is duplicated. The snapshot captures the state of the original chroot at time of snapshotting. But the two chroots may diverge later on. The words _chroot_ and _snapshot_ are used interchangably to mean the same thing. *Backend*:: The underlying system used for snapshotting. Refer *genpac(5)* for more details. *Template*:: A chroot designated as the default source for snapshotting. A template chroot has no difference from a regular chroot. It exists only as a convenience feature to shorten snapshotting commands. Refer _snapshot_ subcommand for more details. *Target*:: A chroot that's the subject of a genpac command. == Configuration This command needs system-wide _subuid/subgid allocation_ and user-level _genpac configuration_ to function. These need to be configured before using the command. Refer *genpac(5)* on how to do this. == Options === Global Options *--help*, *-h*:: Print help and usage message and exit. *--verbose*, *-v*:: Provide extra information on stderr, corresponding to _debug_ level. Can be used up to 2 times for more detailed output, up to _trace_ level. *--quiet*, *-q*:: Silence all information on stderr, except _error_ and _warning_ level messages. Conflicts with verbose and dry-run options. *--dry-run*, *-n*:: Display steps to be taken with the specified command, without actually executing it. This implies verbosity level _debug_. NOTE: Default verbosity level is _info_. === Sandboxing [subs=+quotes] ---- *genpac sandbox* [_OPTIONS_] _CHROOT_ [_COMMAND_] *genpac sbox* [_OPTIONS_] _CHROOT_ [_COMMAND_] ---- Start a _command_ inside a bubblewrap sandbox in the given _chroot_. *CHROOT*:: The chroot to enter. This is the name alone and not the full path. *COMMAND*:: The command/application to run inside the chroot. Usually a shell like bash or zsh. The command specified in the configuration file is used, if not specified here. *OPTIONS*:: All <> apply. === Listing chroots [subs=+quotes] ---- *genpac snapshot list* [_OPTIONS_] *genpac snap ls* [_OPTIONS_] ---- List all _chroots_/_snapshots_ in the _workspace_. *OPTIONS*:: All <> apply. === Creating chroots [subs=+quotes] ---- *genpac snapshot add* [_OPTIONS_] <**--template**|*--blank*|*--source* _SOURCE_> _TARGET_ *genpac snap make* [_OPTIONS_] <**-t**|*-b*|*-s* _SOURCE_> _TARGET_ *genpac snap mk* [_OPTIONS_] <**-t**|*-b*|*-s* _SOURCE_> _TARGET_ *genpac snap create* [_OPTIONS_] <**-t**|*-b*|*-s* _SOURCE_> _TARGET_ ---- Create a new _snapshot_/_chroot_ within the workspace. *--template*, *-t*:: Create a new snapshot from the designated default template chroot. *--source*, *-s* _SOURCE_:: Create a new snapshot from the specified source chroot. This chroot must exist within the workspace. *--blank*, *-b*:: Create a blank/empty chroot. Such chroots are not usable until they are populated by a Linux root like Gentoo stage3 archive. Refer to <> for more details. *TARGET*:: The name of the chroot/snapshot to create in the workspace. It must not already exist. *OPTIONS*:: All <> apply. [IMPORTANT] ==== The ability to create/delete chroots depend on the _backend_. For example, _None_ backend can do neither. Meanwhile _Btrfs_ backend can usually create snapshots without any issue. But deleting snapshots may require additional system configuration. See *genpac(5)* for additional details. ==== === Deleting chroots [subs=+quotes] ---- *genpac snapshot del* [_OPTIONS_] _TARGET_ *genpac snap delete* [_OPTIONS_] _TARGET_ *genpac snap rm* [_OPTIONS_] _TARGET_ ---- Delete a _snapshot_/_chroot_ from the _workspace_. *TARGET*:: The name of the chroot/snapshot to delete. *OPTIONS*:: All <> apply. It must exist. === Extracting root [subs=+quotes] ---- *genpac extract* [_OPTIONS_] _ARCHIVE_ _CHROOT_ ---- Extract a Gentoo stage3 archive into a given _chroot_ in the _workspace_. This chroot must exist and must be empty. Refer <> on how to do this. The extraction process applies proper ownership and permissions to the contents in the root. Note that root archives are also known to work. *ARCHIVE*:: Absoulte or relative path to the Gentoo root archive. This is usually a file of the form `stage3-*.tar.xz`. *CHROOT*:: The name of an empty chroot in the workspace. *OPTIONS*:: All <> apply. It must exist. === Remapping root archive [subs=+quotes] ---- *genpac remap* [_OPTIONS_] _SOURCE_ _DESTINATION_ ---- Convert Gentoo stage3 archive into a modified archive with content UIDs and GIDs remapped according to the configured IDMap and archive format changed from PAX to GNU format. [NOTE] ==== This feature is available only if genpac is built with the _remap_ feature enabled. It is disabled by default. Remapped archive was the method used earlier to create a chroot with proper ID mapping. This is no longer necessary and may be safely neglected. It's retained only in case that it may be useful in some other way. ==== *SOURCE*:: Absolute or relative path to the source archive. It must be a tar archive with PAX-format headers (and extended metadata) and compressed with the xz algorithm (*.tar.xz). *DESTINATION*:: Absolute or relative path to which the remapped archive must be written. This is again, an xz compressed tar archive, but with GNU tar headers. *OPTIONS*:: All <> apply. It must exist. == See Also *genpac*(5), *bwrap*(1), *tar*(1), *btrfs*(8)