433 lines
15 KiB
Markdown
433 lines
15 KiB
Markdown
# 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=<MODULE>**
|
|
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=<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.
|
|
|
|
#### **<TARGET> <DEST>**
|
|
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.
|
|
|