15 KiB
Pacwrap User Manual
This document was generated by the pacwrap binary with version 0.7.2-91b5c79-RELEASE (30/03/2024) of the program.
NAME
pacwrap
SYNOPSIS
pacwrap [OPERATION | COMMAND MODULE] [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.
OPERATIONS
-S, --sync
Synchronize package databases and update packages in target containers.
-R, --remove
Remove packages from target containers.
-Q, --query
Query package information from target container.
-C, --compose
Compose a container from configuration.
-P, --process
Manage and show status of running container processes.
-E, --execute
Executes application in target container using bubblewrap.
-L, --list
List of available containers managed by pacwrap.
-U, --utils
Invoke miscellaneous utilities to manage containers.
-h, --help=
Invoke a printout of this manual to STDOUT.
-V, --version
Display version and copyright information in STDOUT.
EXECUTE
-r, --root
Execute operation with fakeroot and fakechroot. Facilitates a command with faked privileges.
-s, --shell
Invoke a bash shell
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= followed by a list of packages to specify package targets. Packages applicable to a target must only be specified after the target operand.
-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, filesystem slices 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.
-c, --create
Create a container with the first specified target. A container type argument is also required.
-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=TARGET
Specify a target container for the specified operation.
-d, --dep=DEPEND
Specify a dependent container for the specified operation.
-p, --preview
Perform a dryrun operation on existing containers to preview changes applicable or otherwise specified. Only applicable to
-o, --target-only
Apply specified operation on the specified target(s) only.
--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 this container's package database.
--dbonly
Transact on resident containers with a database-only transaction.
--noconfirm
Override confirmation prompts and confirm all operations.
EXAMPLES
$ pacwrap -Syucbt base
Create a base container named base with no additional packages
$ pacwrap -Syucbt firefox firefox --dep=base,common,nvidia
Create aggregate container named firefox with firefox installed.
$ pacwrap -Syut electron element-desktop -t mozilla firefox thunderbird
Synchronize package databases and upgrade all containers, as well as install element-desktop in the target electron, and install firefox and thunderbird in the target mozilla.
$ pacwrap -Syucst common gtk3 qt6-base --dep=base -cst nvidia nvidia-utils --dep=base,common
Create two sliced containers, one named common with the packages gtk3, qt6-base, and another named nvidia with the package nvidia-utils.
$ 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=TARGET
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.
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.
Reinitialize container
-t, --target=TARGET
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.
--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.
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 available containers as configured in '$PACWRAP_CONFIG_DIR/container/'.
QUERY
Query package list on target container. This module presently is not complete.
-q, --quiet
Quiet the output by truncating the package string.
-t, --target=TARGET
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 being executed by pacwrap.
-k, --kill
Kill target containers and their associated processes.
-a, --all
Enumerate all processes associated with running containers.
-d, --depth
Enumerate all processes at the specified depth associated with running containers.
-t, --target=TARGET
Specify a target container for the specified operation.
--noconfirm
Override confirmation prompts and confirm all operations.
EXAMPLE
$ pacwrap -Psaxc
Print table enumerating all container processes to STDOUT with process arguments and execution path split into separate columns.
UTILITIES
Miscellaneous utilities which provide helpful auxiliary functionality to aid in configuration and maintenance of operate containers.
-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.
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 information.
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
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 -Ulbtbts
Print table listing containers out to STDOUT with two total columns, one showing the total amount of bytes. Then print a summary calculation of total consumption below.
$ pacwrap -Uvl
View '$PACWRAP_DATA_DIR/pacwrap.log' with $EDITOR.
LIST
List all initialized containers presently managed by pacwrap.
This command module is a shortcut to -Ul.
-t, --total
Display a total column.
-o, --on-disk
Display a size on disk column.
-b, --bytes
Toggle byte unit display.
EXAMPLE
$ pacwrap ls -btbts
Print table listing containers out to STDOUT with two total columns, one showing the total amount of bytes. Then print a summary calculation of total consumption below.
HELP
-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 VARIABLES
Provided herein are environment variables of which can be used to configure pacwrap's runtime parameters. Use with care: These variables if used improperly could result in undesired behaviour.
PACWRAP_CONFIG_DIR
Set the configuration directory. This environment variable overrides the default, XDG Directory Specification compliant path.
PACWRAP_DATA_DIR
Set the data directory. This environment variable overrides the default, XDG Directory Specification compliant path.
PACWRAP_CACHE_DIR
Set the cache directory. This environment variable overrides the default, XDG Directory Specification compliant path.
PACWRAP_VERBOSE=[0|1]
Toggle verbose output during a transaction. This option may be removed or otherwise differ in functionality in future.
PACWRAP_HOME
Upon execution, mount the set path provided when engaging the 'home' module.
PACWRAP_ROOT
Upon execution, Mount the set path provided when engaging the 'root' module.
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.
COPYRIGHT
Copyright (C) 2023-2024 Xavier R.M.
This program may be freely redistributed under the terms of the GNU General Public License v3 only.