2024-10-06 21:12:13 -04:00
# pacwrap [](https://git.sapphirus.org/pacwrap/pacwrap/actions?workflow=build.yml)
2024-04-03 17:15:23 -04:00
# <p align=center>[](https://aur.archlinux.org/packages/pacwrap/)[](https://aur.archlinux.org/packages/pacwrap-git/)[](https://spdx.org/licenses/GPL-3.0-only.html)</p>
2023-10-25 02:15:45 -04:00
2024-10-30 23:55:52 -04:00
< img align = "left" src = "https://github.com/pacwrap/pacwrap/raw/master/assets/logo.svg" >
2024-03-30 22:43:21 -04:00
2024-02-10 01:25:25 -05:00
A package management front-end which utilises libalpm to facilitate the creation of unprivileged, userspace containers with parallelised, filesystem-agnostic deduplication. These containers are constructed via bubblewrap to execute package transactions and launch applications.
2023-10-25 02:15:45 -04:00
2023-12-01 13:36:13 -05:00
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.
Goal of this project is to provide a distribution-backed alternative to flatpak with easily configurable security parameters.
\* Some CLI-based applications, such as ncspot, require disabling termios isolation. This could allow an attacker to overtake the terminal and thus breakout of the container.
2023-10-25 02:15:45 -04:00
## Example usage
2024-01-14 21:04:46 -05:00
To create a base container, execute the following command:
2023-10-25 02:15:45 -04:00
```
$ pacwrap -Syucb --target=base
```
Then to launch a shell inside of this container to configure it:
```
$ pacwrap -Es base
```
2024-02-12 22:35:55 -05:00
And finally, to install ```neovim``` inside of a fresh, aggregated container called ```editor```:
2023-10-25 02:15:45 -04:00
```
2024-02-10 01:25:25 -05:00
$ pacwrap -Syucat editor --dep=base neovim
2023-10-25 02:15:45 -04:00
```
2024-03-30 21:36:06 -04:00
To update these containers just created in aggregate:
```
$ pacwrap -Syu
```
2023-10-25 02:15:45 -04:00
More advanced examples along with further documentation of configuration can be found further
2024-10-30 23:55:52 -04:00
elaborated upon ** [here ](https://github.com/pacwrap/pacwrap/blob/master/docs/ )**.
2024-02-10 01:25:25 -05:00
## Features
2024-02-12 22:35:55 -05:00
Since this project is a work in progress, not everything is yet completed. Please refer to the matrix below for further detail.
2024-02-10 01:25:25 -05:00
If a feature you see here is not completed, feel free to submit a PR; or submit an issue regarding a feature not listed herein for triage.
| Feature | Description | Status |
| :--- | :--- | :----: |
| Aggregate Transactions | Aggregate package transactions across containers | ✅ |
| Transaction Agent | Transact within a sandboxed runtime environment | ✅ |
| Transaction CLI | Functional | ✅ |
| Global Configuration | Functional | ✅ |
2024-03-30 22:43:21 -04:00
| Package Dependency Resolution | Utilizes a recursive depth-first search algorithm; resilient to cycling | ✅ |
2024-02-10 01:25:25 -05:00
| Foreign Database Resolution | Populates foreign package database in aggregate containers | ✅ |
| Foreign Database Resolution (Lazy) | Not yet implemented | ❌ |
| Conflict Resolution | Not yet implemented | ❌ |
| Package Installation | Functional | ✅ |
2024-02-11 17:33:13 -05:00
| Package Removal | Functional | ✅ |
2024-03-10 00:20:31 -05:00
| Desktop Entry Creation | Functional | ✅ |
2024-02-10 01:25:25 -05:00
| Container Execution | Functional | ✅ |
| Launch within existing namespace | Not yet implemented | ❌ |
| Container Configuration | Functional | ✅ |
| Container Creation | Functional | ✅ |
2024-03-09 23:56:06 -05:00
| Container Composition | Functional | ✅ |
2024-02-10 01:25:25 -05:00
| Container Runtime | Embedded runtime environment | ✅ |
2024-02-11 17:33:13 -05:00
| Container Schema | Container filesystem schema with version tracking | ✅ |
2024-02-10 01:25:25 -05:00
| Filesystem Deduplication | Retains filesystem state across containers with hardlinks | ✅ |
| Seccomp Filters | Application of seccomp filters to instances via libseccomp bindings | ✅ |
2024-02-11 17:33:13 -05:00
| Dbus Isolation | Functional - provided by xdg-dbus-proxy | ✅ |
2024-02-10 01:25:25 -05:00
| Networking Isolation | Not yet implemented | ❌ |
2024-03-09 23:56:06 -05:00
| Port to Rust | Completed | ✅ |
| Config CLI (user friendly) | Not yet implemented | ❌ |
2024-02-10 01:25:25 -05:00
| Process API | Container process enumeration | ✅ |
| Process CLI | Functional | ✅ |
2024-03-09 23:56:06 -05:00
| Utility CLI | Functional | ✅ |
2024-02-10 01:25:25 -05:00
| Localization | Not yet implemented | ❌ |
2023-10-25 02:15:45 -04:00
## Manual
2024-10-30 23:55:52 -04:00
An online version of the user manual is viewable ** [here ](https://github.com/pacwrap/pacwrap/blob/master/docs/manual.md )**.
2023-10-25 02:15:45 -04:00
## Build requirements
2024-02-10 01:25:25 -05:00
A minimum version of Rust 1.72 is required to build with the following libraries fulfilled by your distribution:
```
2024-09-26 16:38:38 -04:00
libalpm=15, libseccomp, libzstd
2024-02-10 01:25:25 -05:00
```
## Packaging requirements
The following Arch Linux packages (or your distribution's equivalent) are required for build-time artefacts:
```
bash, busybox, coreutils, fakeroot, fakechroot
```
2023-10-25 02:15:45 -04:00
## Distribution support
2024-02-10 01:25:25 -05:00
Although this project aims to be distribution agnostic, at present only Arch-based distributions are supported. This project does aim, however, to be distribution agnostic, so in future it should be possible to support other distributions.