20 KiB
Pacwrap User Manual
This document was generated by the pacwrap binary with version 0.8.4-43de5c7-RELEASE (14/09/2024) of the program.
NAME
pacwrap
SYNOPSIS
pacwrap [OPERATION | VERB] [ARGUMENTS] [TARGETS]
DESCRIPTION
A package management front-end which utilises libalpm to facilitate the creation of unprivileged, namespace containers with parallelised, filesystem-agnostic deduplication. These containers are constructed with bubblewrap to execute package transactions and launch applications.
This application is designed to allow for the creation and execution of secure, replicable containerised environments for general-purpose use. CLI and GUI applications are all supported. Once a container environment is configured, it can be re-established or replicated on any system.
Each long-option parameter can also be specified herein as a command verb for a matter of convenience. Additional command verb shortcuts are available and are documented alongside their relevancy.
OPERATIONS
-E, --exec, run
Invoke a container to execute the provided command sequence.
-S, --sync
Synchronize package databases and containers in aggregate.
-R, --remove
Remove packages from target containers in aggregate.
-C, --compose
Compose a container from configuration.
-Q, --query
Query package information from target container.
-P, --process
Manage and show status of running container processes.
-L, --list
List available containers managed by pacwrap.
-U, --utils
Engage miscellaneous utilities to manage containers.
-V, --version
Display version banner or information.
-h, --help <OPERATION | VERB | TOPIC>
Print the help manual to STDOUT.
EXECUTE
Invoke a container to execute the provided command sequence. Command verb run provides a
shortcut to this module.
Container name to spawn an instance of, along with the proceeding command-line sequence to execute. execute. All command-line parameters after the container name are passed through to execute inside of the container environment.
-s, --shell
Invoke a bash shell in the target container. Command verb shell provides a shortcut
to this module with this option.
-r, --root
Execute the provided command sequence with fakeroot and fakechroot.
EXAMPLES
$ pacwrap run firefox firefox
Launch firefox inside an instance of the firefox container.
$ pacwrap shell -r base
Open a fakeroot bash shell inside an instance of the base container.
SYNCHRONIZATION
Provides the facilities required to be able to synchronize and create containers in aggregate.
-y, --refresh
Synchronize remote package databases. Specify up to 2 times to force a refresh.
-u, --upgrade
Execute aggregate upgrade routine on all or specified containers. Use -t, --target[=CONTAINER] followed
by a list of packages to specify package targets. Packages applicable to a target must only be specified
after the target operand.
-c, --create
Create a container with the first specified target. A container type argument is also required. Command verb
init provides a shortcut to the synchronization module, equivalent to specifying the options -Syuc.
-b, --base
Base container type. Specify alongside -c, --create to assign this container type during creation.
This container type is used as the base layer for all downstream containers. Only one base container dependency per slice or aggregate is supported. Filesystem and package deduplication via slices and aggregate containers are recommended, but optional. This container type is not dependant.
-s, --slice
Slice container type. Specify alongside -c, --create to assign this container type during creation.
Requires a base dependency, and optionally one or more sliced dependencies, to ascertain foreign packages and influence ordering of downstream synchronization target(s). Container slicing provides the ability to install packages in a lightweight, sliced filesytem, which aid in the deduplication of common downstream package and filesystem dependencies.
Useful for graphics drivers, graphical toolkits, fonts, etc.; these are not meant for applications.
-a, --aggegrate
Aggregate container type. Specify alongside -c, --create to this assign container type during creation.
Requires a base dependency, and optionally one or more sliced dependencies, in order to acertain foreign packages and amalgamate the target. These containers are ideal for installing software with the aid of filesystem and package deduplication.
Useful for all general purpose applications, browsers, e-mail clients, or even terminal user interface applications such as IRC clients. It is recommended to base your containers on aggregate type containers.
-t, --target <CONTAINER> <..PACKAGE>
Declare a target container for the specified operation, followed by a list of package target(s).
-f, --filesystem
Force execution of filesystem synchronization target on all or specified containers. In combination with -o/--target-only, in addition to no other specified targets, filesystems will be synchronized without package synhcronization on on all applicable containers. This operation is useful for propagation of manual filesystem changes to all aggregate containers.
-o, --target-only
Apply specified operation on the specified target(s) only.
-d, --dep <CONTAINER>
Specify dependencies for a container create operation.
-p, --preview
Perform a dryrun operation on existing containers to preview changes applicable or otherwise specified. Only applicable to pre-existing targets and not create operations.
-l, --lazy-load
Enable lazy-database initialization for this transaction. NOTE: This feature is experimental.
Edge cases exist wherein the use of --force-foreign may be required.
--force-foreign
Force synchronization of foreign packages on resident container. Useful for when installing a new package in an aggregate container without all the prerequisite foreign dependencies synchronized to the resident container's package database.
--dbonly
Transact on resident containers with a database-only transaction.
--noconfirm
Override confirmation prompts and confirm all operations.
--disable-sandbox
Instruct libalpm to disable its own sandbox, utilizing landlock and seccomp, in order to mitigate potential issues with kernel compatibillity.
--debug
Use this option when reporting bugs.
EXAMPLES
$ pacwrap init --base --target base
Synchronize remotes and create a base-type container named base with no additional packages.
$ pacwrap -Syucst common gtk3 qt6-base --dep=base -st nvidia nvidia-utils --dep=base,common
Synchronize remote databases, create two sliced containers, one named common with the packages
gtk3, qt6-base, and another named nvidia with the package nvidia-utils.
$ pacwrap -Syucat mozilla firefox --dep=base,common,nvidia
Synchronize remote databases and upgrade container dependencies, then create aggregate container
named mozilla with the package firefox.
$ pacwrap -Sot mozilla thunderbird
Install thunderbird in the target container mozilla.
$ pacwrap -Sof
Synchronize filesystem state of all associated containers present in the data directory.
REMOVE
Remove packages from specified containers.
-s, --recursive
Recursively remove all target packages with the associated target container. This does not apply to packages upstream of a downstream container.
-c, --cascade
Remove all target packages with the associated target container, including all their associated dependencies, provided they are not required by other packages, and are not marked as being upstream of the target container.
-t, --target <CONTAINER>
Specify a target container for the specified operation. At least one container target is is required for package removal operations.
--force-foreign
Force the removal of foreign packages on target container. Useful for cleaning up the package database of foreign, upstream dependencies synchronized to the target container's package database.
-m, --delete
Delete root filesystem(s) of specified targets. Shortcout to -Ur.
-p, --preview
Preview operation and perform no transaction.
--dbonly
Transact on resident containers with a database-only transaction.
--noconfirm
Override confirmation prompts and confirm all operations.
--disable-sandbox
Instruct libalpm to disable its own sandbox, utilizing landlock and seccomp, in order to mitigate potential issues with kernel compatibillity.
--debug
Use this option when reporting bugs.
EXAMPLES
$ pacwrap -Rt firefox firefox
Remove the target package firefox from target container firefox.
$ pacwrap rm firefox
Delete the root filesystem for the firefox container.
COMPOSE
Compose containers from container configuration files. This functionality provides a way to deterministically compose containers from an established configuration.
<FILE_PATH>
Compose a container from the specified configuration file on disk. Unless a target is otherwise specified, the container will be initialized with a name derived from the filename provided.
-r, --reinitialize
Compose an available, existing container for composition. The pre-existing container root will be deleted and the container will be composited from the configuration data enumerated.
-t, --target <CONTAINER>
Specify a target container for the specified operation.
-f, --force
Disable sanity checks and force removal of container filesystem(s).
--reinitialize-all
Queues all available, existing containers for composition. All pre-existing container roots will be deleted and composited from the available configuration data enumerated.
-l, --lazy-load
Enable lazy-database initialization for this transaction. NOTE: This feature is experimental.
Edge cases exist wherein the use of --force-foreign may be required.
--from-config
Instruct pacwrap to populate configuration data from uninitialized containers. Under normal circumstances, configuration data will only be populated from containers with configuration data and an associative container root present. This option engages an alternate enuermation pathway to allow composition of dormant, uninitialized container configurations.
--noconfirm
Override confirmation prompts and confirm all operations.
--disable-sandbox
Instruct libalpm to disable its own sandbox, utilizing landlock and seccomp, in order to mitigate potential issues with kernel compatibillity.
--debug
Use this option when reporting bugs.
EXAMPLES
$ pacwrap compose -rt element element.yml
Reinitialize an existing container named element with its configuration derived from the file 'element.yml'.
$ pacwrap compose --reinitialize-all --from-config
Reinitialize all container configurations available in '$PACWRAP_CONFIG_DIR/container/'.
QUERY
Query package list on target container.
-q, --quiet
Quiet the output by truncating the package string.
-t, --target <CONTAINER>
Specify a target container for the specified operation.
-e, --explicit
Filter output to explicitly-marked packages.
EXAMPLE
$ pacwrap -Qqe base
Print a list of explicit packages from the base container to STDOUT.
PROCESS
Table a process list of running containers. Containers may be filtered on target and process depth.
-s, --summary
Enumerate a process summary of containers instantiated by pacwrap.
-i, --id-list
Enumerate a process id list of containers instantiated by pacwrap.
-k, --kill
Kill target containers and their associated processes.
-a, --all
Target all containers and enumerate their associated processes.
-d, --depth
Enumerate all processes at the specified depth associated with running containers.
-t, --target <CONTAINER>
Specify a target container for the specified operation.
--noconfirm
Override confirmation prompts and confirm all operations.
EXAMPLES
$ pacwrap -Psaxc
Print table enumerating all container processes to STDOUT with process arguments and execution path split into separate columns.
$ ps up "$(pacwrap -Pia)"
Enumerate container processes with ps via encapsulating an enumeration of pids from all instances
into a space-delimited bash string.
LIST
List all initialized containers presently managed by pacwrap.
This command module is a shortcut to -Ul. Command verb ls also is a
shortcut to this command module.
-t, --total
Display a total column.
-o, --on-disk
Display a size on disk column.
-b, --bytes
Toggle byte unit display.
EXAMPLES
$ pacwrap -Ld
Print container tabulation out to STDOUT with two total columns, one listing the container name, and the other detailing the total size-on-disk consumption displayed with byteunits.
$ pacwrap ls -btbts
Print container tabulation to STDOUT with three total columns, first listing the container name, second the total amount of bytes, and the last showing the total with byteunits. Then print a summation of total, actual consumption below.
UTILITIES
Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and maintenance of containers. Each utility is considered a command module and therefore can be shortcuted with a command verb.
-d, --desktop
Create desktop file to launch application inside of a pacwrap container.
-v, --view
Invoke $EDITOR to view file associated with pacwrap.
-e, --edit
Invoke $EDITOR to edit file associated with pacwrap.
-o, --open
Invoke default file viewer on specified target's home or root directory.
-l, --list
Print a list of containers and basic metrics.
-s, --symlink
Create a symbolic container.
-r, --remove
Delete a container(s) root filesystem.
DESKTOP OPTIONS
Create and manage desktop files to launch applications in pacwrap from your favourite applications menu.
-c, --create <CONTAINER> <APPLICATION>
Create desktop file associated with application at $HOME/.local/share/applications/ launching an
application in pacwrap.
-l, --list <CONTAINER>
List available desktop files in the container root located at /usr/share/applications/.
-r, --remove <APPLICATION>
Remove desktop file associated with application from $HOME/.local/share/applications/.
EDITOR OPTIONS
These options are associated with the --edit and --view utility command modules.
-c, --config <CONTAINER>
Edit specified container configuration located in the pacwrap data directory. Defaults to the primary configuration file: '$PACWRAP_CONFIG_DIR/pacwrap.yml' if no option is otherwise specified.
-d, --desktop <APPLICATION>
Edit specified desktop file associated with a pacwrap container.
-r, --repo
Edit repositories configuration file: $PACWRAP_CONFIG_DIR/repositories.conf.
-l, --log
View 'pacwrap.log'. This file contains transaction log iformation.
OPEN OPTIONS
These options are associated with the --open utility command module.
-h, --home <CONTAINER>
Specified container's home filesystem.
-r, --root <CONTAINER>
Specified container's root filesystem.
-t, --target <CONTAINER>
Target container to perform the operation.
LIST
These options are associated with the --list utility command module.
-t, --total
Display a total column.
-d, --on-disk
Display a size on disk column.
-s, --summary
Print out a summary table to STDOUT.
-b, --bytes
Toggle byte unit display for the proceeding item.
REMOVE OPTIONS
These options are associated with the --remove utility command module.
-t, --target <CONTAINER>
Target container to perform the operation.
--noconfirm
Peform the operation without confirmation.
--force
Disable sanity checks and force removal of conatiner filesystem.
SYMBOLIC
These options are associated with the --symlink utility command module.
Create a symbolic container of target at destination.
-n, --new
Create a fresh configuration rather than derive it from the target.
EXAMPLES
$ pacwrap -Uoh firefox
Open firefox's home directory in the default file manager.
$ pacwrap -Uvl
View **$PACWRAP_DATA_DIR**/pacwrap.log with $EDITOR.
$ pacwrap -Uec firefox
Edit $PACWRAP_CONFIG_DIR**/container/firefox.yml with $EDITOR.
$ pacwrap utils -dc firefox firefox
Create desktop file $HOME/.local/share/applications/pacwrap.firefox.desktop derived from
/usr/share/applications/firefox.desktop in the root of the firefox container.
$ pacwrap utils symlink java runelite
Create a symbolic container called runelite of java.
$ pacwrap -Uld
Print container tabulation out to STDOUT with two total columns, one listing the container name, and the other detailing the total size-on-disk consumption displayed with byteunits.
$ pacwrap utils -lbtbts
Print container tabulation to STDOUT with three total columns, first listing the container name, second the total amount of bytes, and the last showing the total with byteunits. Then print a summation of total, actual consumption below.
VERSION
-V, --version, --version=min
Sends version information to STDOUT with colourful ASCII art. The 'min' option provides a minimalistic output as is provided to non-colour terms.
HELP
-h, --help <TOPIC>
Print the specified topic to STDOUT.
-m, --more
When specifying a topic to display, show the default topic in addition to specified options.
-f, --format <FORMAT>
Change output format of help in STDOUT. Format options include: 'ansi', 'dumb', 'markdown', and 'man'. This option is for the express purposes of generating documentation at build time, and has little utility outside the context of package maintenance. 'man' option produces troff-formatted documents for man pages.
-a, --all, --help=all
Display all help topics.
ENVIRONMENT
Provided herein are environment variables of which can be used to configure pacwrap's runtime parameters. All environment variables listed are case sensitive.
Use with care: These variables if used improperly could result in undesired behaviour.
PACWRAP_CONFIG_DIR <DIR>
Set path of the configuration directory, overriding the default location.
PACWRAP_DATA_DIR <DIR>
Set path of the data directory, overriding the default location.
PACWRAP_CACHE_DIR <DIR>
Set path of the cache directory, overriding the default location.
PACWRAP_HOME <DIR>
Upon container invocation, mount the set path provided when engaging the home filesystem module.
PACWRAP_ROOT <DIR>
Upon container invocation, mount the set path provided when engaging the root filesystem module.
PACWRAP_VERBOSE <0 | 1>
Toggle verbose output during a transaction. Valid options are 1 for enablement and 0 for
disablement of verbosity.
DEFAULT
For the following environment variables, contained herein are default runtime values. Any variables not included here in this subsection are to be assumed to have inert values by default.
PACWRAP_CACHE_DIR
$HOME/.cache/pacwrap: Default cache directory.
PACWRAP_CONFIG_DIR
$HOME/.config/pacwrap: Default configuration directory.
PACWRAP_DATA_DIR
$HOME/.local/share/pacwrap: Default data directory.
AUTHOR
Copyright (C) 2023-2024 Xavier Moffett sapphirus@azorium.net
LICENSE
This program may be freely redistributed under the terms of the GNU General Public License v3 only.