PaganOS Luna 0.6.0
PL EN DE
← pag

Commit fe7c4ba

0
plików
+0
dodanych
-0
usuniętych
@@ -1,449 +1,449 @@
1 -# pag – PaganOS Package Manager
2 -
3 -[![Version](https://img.shields.io/badge/pag-3.3.20-blue)](https://git.paganlinux.eu/pag)
4 -[![Platform](https://img.shields.io/badge/PaganOS-Linux-success)](https://paganlinux.eu)
5 -
6 -Package manager for [PaganOS](https://paganlinux.eu). Atomic installation
7 -(staging → rename), GPG signature verification with fingerprint pinning,
8 -per-file SHA256, full transaction rollback, hooks and triggers, and support for
9 -immutable systems with deployments.
10 -
11 -Diagrams in this README are rendered with Mermaid – supported by the
12 -`git.paganlinux.eu` portal (and GitHub/Gitea).
13 -
14 -```bash
15 -pag --version # client version (e.g. pag 3.3.20)
16 -pag # full help (command list)
17 -pag --help # same as above
18 -```
19 -
20 -
21 -## Table of contents
22 -
23 -- [Quick start](#quick-start)
24 -- [How it works](#how-it-works)
25 - - [`pag install` flow](#pag-install-flow)
26 - - [Trust chain](#trust-chain)
27 - - [Immutable system](#immutable-system)
28 - - [Rollback](#rollback)
29 - - [Rolling – base baked into the ISO](#rolling--base-baked-into-the-iso)
30 -- [Commands](#commands)
31 -- [Environment variables](#environment-variables)
32 -- [Paths and files](#paths-and-files)
33 -- [Package format](#package-format)
34 -- [Hooks and triggers](#hooks-and-triggers)
35 -- [`/etc` configuration – `.pacnew` / `.pacsave`](#etc-configuration--pacnew--pacsave)
36 -- [Examples](#examples)
37 -- [Troubleshooting](#troubleshooting)
38 -- [Install and update](#install-and-update)
39 -- [License](#license)
40 -
41 -
42 -## Quick start
43 -
44 -```bash
45 -# Refresh repository indexes (and see what is pending an update)
46 -sudo pag sync
47 -
48 -# Install / remove
49 -sudo pag install firefox gimp
50 -sudo pag remove gimp
51 -
52 -# Update packages only…
53 -sudo pag update
54 -# …or the whole system: packages + kernel / initramfs / GRUB
55 -sudo pag upgrade
56 -
57 -# Base baked into the ISO vs. the repository (full rolling)
58 -pag base # what comes from the image, what pag manages
59 -sudo pag base adopt # adopt the base from the repo (--dry-run = preview)
60 -
61 -# Verify the integrity of all files
62 -sudo pag verify --deep
63 -```
64 -
65 -
66 -## How it works
67 -
68 -### `pag install` flow
69 -
70 -```mermaid
71 -graph TD
72 - A["pag install pkg"] --> B["Dependency resolution (DFS + provides)"]
73 - B --> C{"Missing dependencies?"}
74 - C -->|yes| C1["Error – abort"]
75 - C -->|no| D["ABI verification (so-name)"]
76 - D --> E["Pre-flight: free space + RW mount"]
77 - E --> F["flock + database snapshot"]
78 - F --> G["Parallel package download"]
79 - G --> H["GPG + package SHA256 verification"]
80 - H --> I["Staging: extract + per-file sums"]
81 - I --> J["Atomic rename of files into the system"]
82 - J --> K["pre/post-install hooks"]
83 - K --> L["Write to SQLite + transaction history"]
84 - L --> M{"PAG_IMMUTABLE=1?"}
85 - M -->|yes| N["New deployment + GRUB entries"]
86 - M -->|no| O["ldconfig + triggers"]
87 - H -->|error| R["Rollback of the whole transaction"]
88 - I -->|error| R
89 - J -->|error| R
90 - R --> S["Restore database and files"]
91 -```
92 -
93 -Key properties:
94 -
95 -- **Atomicity** – files first go to staging on the same partition as `/`, then
96 - are moved with `rename()` (no half-install).
97 -- **Transactionality** – if any package fails, the whole transaction is rolled
98 - back (`installed.json`, files, backups).
99 -- **File sharing** – a file owned by two packages is not removed when one of
100 - them is removed (only the database entry is removed).
101 -
102 -### Trust chain
103 -
104 -```mermaid
105 -graph TD
106 - A["repo.json + repo.json.asc"] --> B["GPG: VALIDSIG line"]
107 - B --> C["Repo fingerprint pinning (TOFU → pin)"]
108 - C --> D["Package index"]
109 - D --> E["package .pag + .asc"]
110 - E --> F["GPG: signature matches repo pin"]
111 - F --> G["Whole-package SHA256"]
112 - G --> H["Safe extraction (anti-traversal)"]
113 - H --> I["sums.json: per-file SHA256"]
114 - I --> J["Strip SUID bit"]
115 - J --> K["Install"]
116 - F -->|"missing / bad signature"| X["Reject package"]
117 - G -->|"SHA256 mismatch"| X
118 - H -->|"traversal / symlink escape"| X
119 -```
120 -
121 -- First use of a key = **TOFU**, afterwards the fingerprint is **pinned**
122 - (`pag key-trust` / `pag key-untrust`).
123 -- Verification is **fail-closed**: missing/bad signature = no installation
124 - (override only with `PAG_INSECURE=1`, build/dev only).
125 -- `pag self-update` goes through the same path: GPG → SHA256 → syntax check →
126 - atomic client replacement.
127 -
128 -### Immutable system
129 -
130 -With `PAG_IMMUTABLE=1`, installation does not mutate `/`; it creates a new
131 -deployment. Rollback is just switching the `active` symlink.
132 -
133 -```mermaid
134 -graph TD
135 - R["/"] --> D["/.deployments"]
136 - D --> A["active → 20260723T120000"]
137 - D --> D1["20260723T120000 (new)"]
138 - D --> D2["20260722T090000 (previous)"]
139 - D1 --> U["usr/ bin/ lib/ – system"]
140 - D1 --> S1["var → /var"]
141 - D1 --> S2["etc → /etc"]
142 - D1 --> S3["home → /home"]
143 - D1 --> S4["boot → /boot"]
144 - D2 -.->|"deploy-rollback"| A
145 -```
146 -
147 -- `/var`, `/etc`, `/home`, `/boot` (and other `SHARED_PATHS`) are **shared**
148 - between deployments – they are not duplicated.
149 -- `/boot` shares the kernel and initramfs, saving space per deployment.
150 -- Rollback from the bootloader: each deployment has its own GRUB entry
151 - (`pag grub-update`).
152 -
153 -### Rollback
154 -
155 -```mermaid
156 -graph TD
157 - T["Transaction"] --> OK{"Success?"}
158 - OK -->|yes| H["History + snapshot + file journal"]
159 - OK -->|no| RB["Automatic transaction rollback"]
160 - H --> R["pag rollback"]
161 - R --> R1["Restore installed.json from snapshot"]
162 - R --> R2["Remove new files from the journal"]
163 - R --> R3["Restore overwritten files from backup"]
164 - R --> R4["Clean up empty directories"]
165 - RB --> R1
166 - RB --> R2
167 - RB --> R3
168 -```
169 -
170 -`pag history` shows recent transactions (including executed hooks), and
171 -`pag rollback` reverts the **last successful** transaction with a snapshot.
172 -
173 -
174 -### Rolling – base baked into the ISO
175 -
176 -The PaganOS image is built **from sources** (glibc, gcc, GTK, XFCE, kernel…).
177 -`pag` did not install them, so they are not in its database
178 -(`/var/lib/pag/installed.json`) – and since it does not know them,
179 -`pag upgrade` will **not** update them. The image files are not untouchable
180 -though: `pag install <name>` overwrites them (a backup is kept for
181 -`pag rollback`).
182 -
183 -To make the system fully rolling, tell pag what the image base is:
184 -
185 -```bash
186 -pag base # report: how many image packages pag manages, how many can
187 - # be adopted from the repo, which stay at the image version
188 -sudo pag base adopt # adopt the base from the repo (--dry-run = preview only)
189 -```
190 -
191 -After `pag base adopt` the image packages become ordinary repo packages, so
192 -the next `sudo pag upgrade` updates the **whole** system. The list of base
193 -packages comes from a manifest baked into the image:
194 -`/usr/share/pag/base.json` (name + version; the builder appends an entry for
195 -every package it builds). Builder names are mapped onto repo names (e.g.
196 -`gtk` → `gtk3`, `libX11` → `xorg-libx11`); names with no repo counterpart are
197 -reported as staying at the image version.
198 -
199 -
200 -## Commands
201 -
202 -### BASICS
203 -
204 -| Command | Description |
205 -|---|---|
206 -| `pag install <pkg>...` | Install packages (together with dependencies) |
207 -| `pag install -f <pkg>...` | **Force reinstall** (even the same version) – restores files, empty directories and hooks |
208 -| `pag remove <pkg>...` | Remove packages |
209 -| `pag update` | Update **packages** to newer versions |
210 -| `pag sync` | Refresh repository indexes + show how many packages await update |
211 -| `pag upgrade` | **System** update: packages + kernel / initramfs / GRUB |
212 -| `pag list` | List packages available in the repository |
213 -| `pag list --installed` | List installed packages |
214 -| `pag search <query>` | Search packages in the repo (+ Flathub) |
215 -| `pag info <pkg>` | Package details (version, dependencies, size, signature) |
216 -| `pag files <pkg>` | List files owned by a package |
217 -| `pag verify` | Verify the integrity of installed files |
218 -| `pag verify --deep` | Full per-file SHA256 verification |
219 -| `pag clean` | Clear the download cache |
220 -| `pag stats` | System statistics (package count, size, cache…) |
221 -| `pag download <pkg>...` | Download packages to cache (offline mode) |
222 -
223 -**Smart search:** `pag <name>` (any unknown command) searches the repo and
224 -Flathub and suggests names – e.g. `pag firefox` will find the package.
225 -
226 -### SECURITY / GPG KEYS
227 -
228 -| Command | Description |
229 -|---|---|
230 -| `pag key-add <url\|file>` | Import a repository GPG key |
231 -| `pag key-list` | List trusted keys |
232 -| `pag key-remove <id>` | Remove a key |
233 -| `pag key-trust <repo>` | Pin the repo key fingerprint (TOFU disabled) |
234 -| `pag key-untrust <repo>` | Forget the fingerprint (back to TOFU) |
235 -| `pag key-trusted` | List pinned repo fingerprints |
236 -
237 -### ADVANCED
238 -
239 -| Command | Description |
240 -|---|---|
241 -| `pag why <pkg>` | Why a package is installed (who depends on it) |
242 -| `pag autoremove` | Remove orphaned dependencies |
243 -| `pag remove-orphans` | Remove orphaned dependencies (alias) |
244 -| `pag pin <pkg> [version]` | Pin a package to a version (block updates) |
245 -| `pag unpin <pkg>` | Unpin |
246 -| `pag pinned` | List pinned packages |
247 -| `pag history` | Transaction history |
248 -| `pag rollback` | Revert the **last** transaction (restore files from backup) |
249 -| `pag repo-add <url> [name]` | Add a repository (drop-in in `/etc/pag/repos/`) |
250 -| `pag repo-list` | List configured repositories |
251 -| `pag sbom export [spdx\|cyclonedx]` | Export an SBOM manifest of all installed components |
252 -| `pag self-update` | Update the `pag` client itself (GPG signature + SHA256 + syntax, atomically) |
253 -
254 -### ROLLING (BASE FROM THE IMAGE)
255 -
256 -| Command | Description |
257 -|---|---|
258 -| `pag base` | Report: image packages – managed by pag / adoptable from repo / no counterpart |
259 -| `pag base adopt` | Adopts the base packages from the repo (replaces image files, backup for `pag rollback`); `--dry-run` = preview |
260 -| `pag base adopt <pkg>...` | Adopts only the given base packages |
261 -
262 -### FLATPAK
263 -
264 -| Command | Description |
265 -|---|---|
266 -| `pag flatpak [<query>]` | Search and install from Flathub |
267 -| `pag flatpak search <query>` | Search Flathub |
268 -| `pag flatpak install <id>` | Install a flatpak |
269 -| `pag flatpak remove <id>` | Remove a flatpak |
270 -| `pag flatpak list` | List installed flatpaks |
271 -| `pag flatpak update` | Update all flatpaks |
272 -| `pag flatpak info <id>` | Flatpak details |
273 -
274 -> Installation as root forces the **system** scope (`--system`), so the
275 -> application is visible to all users, not just root.
276 -
277 -### IMMUTABLE SYSTEM (`PAG_IMMUTABLE=1`)
278 -
279 -| Command | Description |
280 -|---|---|
281 -| `pag deploy-list` | List deployments |
282 -| `pag deploy-rollback` | Switch to the previous deployment |
283 -| `pag deploy-cleanup [N]` | Remove old deployments (keep N, default 3) |
284 -| `pag initramfs-update` | Rebuild initramfs |
285 -| `pag grub-update` | Regenerate GRUB entries for all deployments |
286 -
287 -
288 -## Environment variables
289 -
290 -| Variable | Meaning |
291 -|---|---|
292 -| `PAG_ROOT` | Alternative operation root (tests/chroot); default `/` |
293 -| `PAG_IMMUTABLE=1` | Immutable mode – installation creates a new deployment |
294 -| `PAG_YES=1` | Automatic confirmation (same as `-y` / `--yes`) |
295 -| `PAG_INSECURE=1` | Disables the HTTPS requirement and fail-closed GPG (**build/dev only!**) |
296 -| `PAG_NO_HOOKS=1` | Skip hooks and triggers |
297 -| `PAG_HOOK_TIMEOUT` | Hook timeout in seconds (default `60`) |
298 -| `PAG_LANG_DIR` | Directory with translation files (`pl.json`, `en.json`) |
299 -| `PAG_LANG_NO_FILES=1` | Ignore translation files (export built-ins) |
300 -| `PAG_ROOT_DEVICE` / `PAG_GRUB_ROOT` | Explicit `root=` for GRUB (ISO/IMG build) |
301 -| `PAG_IN_CHROOT=1` | Force chroot mode when detecting the root device |
302 -
303 -
304 -## Paths and files
305 -
306 -| Path | Purpose |
307 -|---|---|
308 -| `/var/lib/pag/` | State database: `installed.json`, `files.db`, `world`, `pinned.json`, `history.json`, `pag.lock`, `hooks/` |
309 -| `/var/lib/pag/files.db` | SQLite: file owners + SHA256 sums |
310 -| `/var/cache/pag/` | Downloaded package cache |
311 -| `/var/cache/pag/repos/` | Repository index cache (JSON + ETag + timestamp) |
312 -| `/etc/pag/repos.conf` and `/etc/pag/repos/*.conf` | Repositories (drop-in) |
313 -| `/etc/pag/trusted.json` | Pinned repo key fingerprints |
314 -| `/etc/pag/gpg/` | Isolated GPG keyring |
315 -| `/etc/pag/triggers/*.json` | Custom triggers |
316 -| `/etc/pag/lang/`, `/usr/share/pag/lang/` | Translations (files override built-ins) |
317 -| `/var/log/pag/audit.log` | Audit: hooks, self-update |
318 -| `/.pag_staging` | Staging (same partition as `/` – no `EXDEV`) |
319 -| `/.deployments/` | Deployments (immutable mode) |
320 -
321 -
322 -## Package format
323 -
324 -A `.pag` package is an archive containing:
325 -
326 -```
327 -metadata.json – name, version, release, dependencies, provides/requires (so-name)
328 -data.tar.xz – system files + sums.json (per-file SHA256)
329 -hooks/ – optional: pre-install, post-install, pre-remove, post-remove
330 -```
331 -
332 -Installation is **verified per file** against `sums.json`, and extraction is
333 -protected against *directory traversal* and escape via malicious symlinks.
334 -
335 -
336 -## Hooks and triggers
337 -
338 -**Hooks** run as `root` (like apt/pacman), in a restricted environment:
339 -
340 -- `pre-install`, `post-install`, `pre-remove`, `post-remove`
341 -- clean env: `PATH`, `HOME=/root`, `LANG/LC_ALL=C.UTF-8`, `PKG_NAME`,
342 - `PKG_VERSION`, `PKG_ACTION`, `PKG_HOOK_API=1`
343 -- timeout (`PAG_HOOK_TIMEOUT`), optional disable (`PAG_NO_HOOKS=1`), entries in
344 - `/var/log/pag/audit.log` and in the transaction history
345 -
346 -You install code you trust – hooks have full privileges.
347 -
348 -**Triggers** run **once per transaction**, when matching paths were touched
349 -(only if the given binary exists):
350 -
351 -| Trigger | Paths | Command |
352 -|---|---|---|
353 -| `font-cache` | `/usr/share/fonts/`, `/usr/local/share/fonts/` | `fc-cache -fs` |
354 -| `glib-schemas` | `/usr/share/glib-2.0/schemas/` | `glib-compile-schemas …` |
355 -| `desktop-database` | `/usr/share/applications/` | `update-desktop-database -q …` |
356 -| `mime-database` | `/usr/share/mime/` | `update-mime-database …` |
357 -
358 -You can add your own triggers as `/etc/pag/triggers/*.json`.
359 -
360 -
361 -## `/etc` configuration – `.pacnew` / `.pacsave`
362 -
363 -The `/etc` directory is shared between deployments (it is not reverted by
364 -`deploy-rollback`). To avoid losing user changes:
365 -
366 -- **Updating** a configuration file that the user modified: the new version is
367 - written as `<file>.pacnew`, and the user's file **is kept**.
368 -- **Removing** a package with a modified configuration file: the file becomes
369 - `<file>.pacsave` instead of being deleted.
370 -
371 -The comparison uses the SHA256 sum recorded at install time.
372 -
373 -
374 -## Examples
375 -
376 -```bash
377 -# Install and updates
378 -sudo pag install firefox gimp
379 -sudo pag update # packages only
380 -sudo pag upgrade # packages + kernel/initramfs/GRUB
381 -sudo pag sync # refresh indexes + update info
382 -
383 -# Repair a package (missing files/directories, e.g. /etc/pulse/default.pa.d)
384 -sudo pag install -f pulseaudio
385 -
386 -# Application icons after installing an icon theme (cache built automatically)
387 -sudo pag install papirus-icon-theme
388 -
389 -# Security
390 -sudo pag key-add https://repo.paganlinux.eu/stable/paganos.asc
391 -sudo pag key-trust https://repo.paganlinux.eu/stable/
392 -sudo pag verify --deep
393 -
394 -# Dependencies and package provenance
395 -sudo pag why libjpeg-turbo
396 -sudo pag autoremove
397 -
398 -# SBOM for audit / compliance
399 -sudo pag sbom export cyclonedx > sbom.json
400 -
401 -# Revert the last transaction
402 -sudo pag rollback
403 -```
404 -
405 -
406 -## Troubleshooting
407 -
408 -| Symptom | Solution |
409 -|---|---|
410 -| "Another pag instance is running" | Another `pag` process is active (`flock` lock). Wait or check `pgrep -af pag`. |
411 -| "Cannot refresh the index" | The repo cache is read-only for a regular user – run as root: `sudo pag sync`. |
412 -| "Invalid signature / missing signature" | Import the key: `sudo pag key-add <url>`, then verify `sudo pag key-trusted`. |
413 -| Missing files/directories after install | `sudo pag install -f <pkg>` (restores files, empty directories and hooks). |
414 -| System does not boot after `grub-update` | Set the root device explicitly: `PAG_ROOT_DEVICE=/dev/sda2 sudo pag grub-update`. |
415 -| Flatpak app not visible in the menu | Add `/var/lib/flatpak/exports/share` to `XDG_DATA_DIRS` and log in again. |
416 -
417 -
418 -## Install and update
419 -
420 -```bash
421 -# On a running PaganOS, pag is in the base repository:
422 -sudo pag install pag # install from the repository
423 -sudo pag self-update # update the client itself (signed)
424 -
425 -# pag is also managed by the package manager – after a new version is
426 -# published in the repo:
427 -sudo pag update
428 -sudo pag upgrade
429 -```
430 -
431 -
432 -## License
433 -
434 -PaganOS / pag – an open source project. See the distribution repository for
435 -details.
1 +# pag – PaganOS Package Manager
2 +
3 +[![Version](https://img.shields.io/badge/pag-4.1.0-blue)](https://git.paganlinux.eu/pag)
4 +[![Platform](https://img.shields.io/badge/PaganOS-Linux-success)](https://paganlinux.eu)
5 +
6 +Package manager for [PaganOS](https://paganlinux.eu). Atomic installation
7 +(staging → rename), GPG signature verification with fingerprint pinning,
8 +per-file SHA256, full transaction rollback, hooks and triggers, and support for
9 +immutable systems with deployments.
10 +
11 +Diagrams in this README are rendered with Mermaid – supported by the
12 +`git.paganlinux.eu` portal (and GitHub/Gitea).
13 +
14 +```bash
15 +pag --version # client version (e.g. pag 3.3.20)
16 +pag # full help (command list)
17 +pag --help # same as above
18 +```
19 +
20 +---
21 +
22 +## Table of contents
23 +
24 +- [Quick start](#quick-start)
25 +- [How it works](#how-it-works)
26 + - [`pag install` flow](#pag-install-flow)
27 + - [Trust chain](#trust-chain)
28 + - [Immutable system](#immutable-system)
29 + - [Rollback](#rollback)
30 + - [Rolling – base baked into the ISO](#rolling--base-baked-into-the-iso)
31 +- [Commands](#commands)
32 +- [Environment variables](#environment-variables)
33 +- [Paths and files](#paths-and-files)
34 +- [Package format](#package-format)
35 +- [Hooks and triggers](#hooks-and-triggers)
36 +- [`/etc` configuration – `.pacnew` / `.pacsave`](#etc-configuration--pacnew--pacsave)
37 +- [Examples](#examples)
38 +- [Troubleshooting](#troubleshooting)
39 +- [Install and update](#install-and-update)
40 +- [License](#license)
41 +
42 +---
43 +
44 +## Quick start
45 +
46 +```bash
47 +# Refresh repository indexes (and see what is pending an update)
48 +sudo pag sync
49 +
50 +# Install / remove
51 +sudo pag install firefox gimp
52 +sudo pag remove gimp
53 +
54 +# Update packages only…
55 +sudo pag update
56 +# …or the whole system: packages + kernel / initramfs / GRUB
57 +sudo pag upgrade
58 +
59 +# Base baked into the ISO vs. the repository (full rolling)
60 +pag base # what comes from the image, what pag manages
61 +sudo pag base adopt # adopt the base from the repo (--dry-run = preview)
62 +
63 +# Verify the integrity of all files
64 +sudo pag verify --deep
65 +```
66 +
67 +---
68 +
69 +## How it works
70 +
71 +### `pag install` flow
72 +
73 +```mermaid
74 +graph TD
75 + A["pag install pkg"] --> B["Dependency resolution (DFS + provides)"]
76 + B --> C{"Missing dependencies?"}
77 + C -->|yes| C1["Error – abort"]
78 + C -->|no| D["ABI verification (so-name)"]
79 + D --> E["Pre-flight: free space + RW mount"]
80 + E --> F["flock + database snapshot"]
81 + F --> G["Parallel package download"]
82 + G --> H["GPG + package SHA256 verification"]
83 + H --> I["Staging: extract + per-file sums"]
84 + I --> J["Atomic rename of files into the system"]
85 + J --> K["pre/post-install hooks"]
86 + K --> L["Write to SQLite + transaction history"]
87 + L --> M{"PAG_IMMUTABLE=1?"}
88 + M -->|yes| N["New deployment + GRUB entries"]
89 + M -->|no| O["ldconfig + triggers"]
90 + H -->|error| R["Rollback of the whole transaction"]
91 + I -->|error| R
92 + J -->|error| R
93 + R --> S["Restore database and files"]
94 +```
95 +
96 +Key properties:
97 +
98 +- **Atomicity** – files first go to staging on the same partition as `/`, then
99 + are moved with `rename()` (no half-install).
100 +- **Transactionality** – if any package fails, the whole transaction is rolled
101 + back (`installed.json`, files, backups).
102 +- **File sharing** – a file owned by two packages is not removed when one of
103 + them is removed (only the database entry is removed).
104 +
105 +### Trust chain
106 +
107 +```mermaid
108 +graph TD
109 + A["repo.json + repo.json.asc"] --> B["GPG: VALIDSIG line"]
110 + B --> C["Repo fingerprint pinning (TOFU → pin)"]
111 + C --> D["Package index"]
112 + D --> E["package .pag + .asc"]
113 + E --> F["GPG: signature matches repo pin"]
114 + F --> G["Whole-package SHA256"]
115 + G --> H["Safe extraction (anti-traversal)"]
116 + H --> I["sums.json: per-file SHA256"]
117 + I --> J["Strip SUID bit"]
118 + J --> K["Install"]
119 + F -->|"missing / bad signature"| X["Reject package"]
120 + G -->|"SHA256 mismatch"| X
121 + H -->|"traversal / symlink escape"| X
122 +```
123 +
124 +- First use of a key = **TOFU**, afterwards the fingerprint is **pinned**
125 + (`pag key-trust` / `pag key-untrust`).
126 +- Verification is **fail-closed**: missing/bad signature = no installation
127 + (override only with `PAG_INSECURE=1`, build/dev only).
128 +- `pag self-update` goes through the same path: GPG → SHA256 → syntax check →
129 + atomic client replacement.
130 +
131 +### Immutable system
132 +
133 +With `PAG_IMMUTABLE=1`, installation does not mutate `/`; it creates a new
134 +deployment. Rollback is just switching the `active` symlink.
135 +
136 +```mermaid
137 +graph TD
138 + R["/"] --> D["/.deployments"]
139 + D --> A["active → 20260723T120000"]
140 + D --> D1["20260723T120000 (new)"]
141 + D --> D2["20260722T090000 (previous)"]
142 + D1 --> U["usr/ bin/ lib/ – system"]
143 + D1 --> S1["var → /var"]
144 + D1 --> S2["etc → /etc"]
145 + D1 --> S3["home → /home"]
146 + D1 --> S4["boot → /boot"]
147 + D2 -.->|"deploy-rollback"| A
148 +```
149 +
150 +- `/var`, `/etc`, `/home`, `/boot` (and other `SHARED_PATHS`) are **shared**
151 + between deployments – they are not duplicated.
152 +- `/boot` shares the kernel and initramfs, saving space per deployment.
153 +- Rollback from the bootloader: each deployment has its own GRUB entry
154 + (`pag grub-update`).
155 +
156 +### Rollback
157 +
158 +```mermaid
159 +graph TD
160 + T["Transaction"] --> OK{"Success?"}
161 + OK -->|yes| H["History + snapshot + file journal"]
162 + OK -->|no| RB["Automatic transaction rollback"]
163 + H --> R["pag rollback"]
164 + R --> R1["Restore installed.json from snapshot"]
165 + R --> R2["Remove new files from the journal"]
166 + R --> R3["Restore overwritten files from backup"]
167 + R --> R4["Clean up empty directories"]
168 + RB --> R1
169 + RB --> R2
170 + RB --> R3
171 +```
172 +
173 +`pag history` shows recent transactions (including executed hooks), and
174 +`pag rollback` reverts the **last successful** transaction with a snapshot.
175 +
176 +---
177 +
178 +### Rolling – base baked into the ISO
179 +
180 +The PaganOS image is built **from sources** (glibc, gcc, GTK, XFCE, kernel…).
181 +`pag` did not install them, so they are not in its database
182 +(`/var/lib/pag/installed.json`) – and since it does not know them,
183 +`pag upgrade` will **not** update them. The image files are not untouchable
184 +though: `pag install <name>` overwrites them (a backup is kept for
185 +`pag rollback`).
186 +
187 +To make the system fully rolling, tell pag what the image base is:
188 +
189 +```bash
190 +pag base # report: how many image packages pag manages, how many can
191 + # be adopted from the repo, which stay at the image version
192 +sudo pag base adopt # adopt the base from the repo (--dry-run = preview only)
193 +```
194 +
195 +After `pag base adopt` the image packages become ordinary repo packages, so
196 +the next `sudo pag upgrade` updates the **whole** system. The list of base
197 +packages comes from a manifest baked into the image:
198 +`/usr/share/pag/base.json` (name + version; the builder appends an entry for
199 +every package it builds). Builder names are mapped onto repo names (e.g.
200 +`gtk` → `gtk3`, `libX11` → `xorg-libx11`); names with no repo counterpart are
201 +reported as staying at the image version.
202 +
203 +---
204 +
205 +## Commands
206 +
207 +### BASICS
208 +
209 +| Command | Description |
210 +|---|---|
211 +| `pag install <pkg>...` | Install packages (together with dependencies) |
212 +| `pag install -f <pkg>...` | **Force reinstall** (even the same version) – restores files, empty directories and hooks |
213 +| `pag remove <pkg>...` | Remove packages |
214 +| `pag update` | Update **packages** to newer versions |
215 +| `pag sync` | Refresh repository indexes + show how many packages await update |
216 +| `pag upgrade` | **System** update: packages + kernel / initramfs / GRUB |
217 +| `pag list` | List packages available in the repository |
218 +| `pag list --installed` | List installed packages |
219 +| `pag search <query>` | Search packages in the repo (+ Flathub) |
220 +| `pag info <pkg>` | Package details (version, dependencies, size, signature) |
221 +| `pag files <pkg>` | List files owned by a package |
222 +| `pag verify` | Verify the integrity of installed files |
223 +| `pag verify --deep` | Full per-file SHA256 verification |
224 +| `pag clean` | Clear the download cache |
225 +| `pag stats` | System statistics (package count, size, cache…) |
226 +| `pag download <pkg>...` | Download packages to cache (offline mode) |
227 +
228 +**Smart search:** `pag <name>` (any unknown command) searches the repo and
229 +Flathub and suggests names – e.g. `pag firefox` will find the package.
230 +
231 +### SECURITY / GPG KEYS
232 +
233 +| Command | Description |
234 +|---|---|
235 +| `pag key-add <url\|file>` | Import a repository GPG key |
236 +| `pag key-list` | List trusted keys |
237 +| `pag key-remove <id>` | Remove a key |
238 +| `pag key-trust <repo>` | Pin the repo key fingerprint (TOFU disabled) |
239 +| `pag key-untrust <repo>` | Forget the fingerprint (back to TOFU) |
240 +| `pag key-trusted` | List pinned repo fingerprints |
241 +
242 +### ADVANCED
243 +
244 +| Command | Description |
245 +|---|---|
246 +| `pag why <pkg>` | Why a package is installed (who depends on it) |
247 +| `pag autoremove` | Remove orphaned dependencies |
248 +| `pag remove-orphans` | Remove orphaned dependencies (alias) |
249 +| `pag pin <pkg> [version]` | Pin a package to a version (block updates) |
250 +| `pag unpin <pkg>` | Unpin |
251 +| `pag pinned` | List pinned packages |
252 +| `pag history` | Transaction history |
253 +| `pag rollback` | Revert the **last** transaction (restore files from backup) |
254 +| `pag repo-add <url> [name]` | Add a repository (drop-in in `/etc/pag/repos/`) |
255 +| `pag repo-list` | List configured repositories |
256 +| `pag sbom export [spdx\|cyclonedx]` | Export an SBOM manifest of all installed components |
257 +| `pag self-update` | Update the `pag` client itself (GPG signature + SHA256 + syntax, atomically) |
258 +
259 +### ROLLING (BASE FROM THE IMAGE)
260 +
261 +| Command | Description |
262 +|---|---|
263 +| `pag base` | Report: image packages – managed by pag / adoptable from repo / no counterpart |
264 +| `pag base adopt` | Adopts the base packages from the repo (replaces image files, backup for `pag rollback`); `--dry-run` = preview |
265 +| `pag base adopt <pkg>...` | Adopts only the given base packages |
266 +
267 +### FLATPAK
268 +
269 +| Command | Description |
270 +|---|---|
271 +| `pag flatpak [<query>]` | Search and install from Flathub |
272 +| `pag flatpak search <query>` | Search Flathub |
273 +| `pag flatpak install <id>` | Install a flatpak |
274 +| `pag flatpak remove <id>` | Remove a flatpak |
275 +| `pag flatpak list` | List installed flatpaks |
276 +| `pag flatpak update` | Update all flatpaks |
277 +| `pag flatpak info <id>` | Flatpak details |
278 +
279 +> Installation as root forces the **system** scope (`--system`), so the
280 +> application is visible to all users, not just root.
281 +
282 +### IMMUTABLE SYSTEM (`PAG_IMMUTABLE=1`)
283 +
284 +| Command | Description |
285 +|---|---|
286 +| `pag deploy-list` | List deployments |
287 +| `pag deploy-rollback` | Switch to the previous deployment |
288 +| `pag deploy-cleanup [N]` | Remove old deployments (keep N, default 3) |
289 +| `pag initramfs-update` | Rebuild initramfs |
290 +| `pag grub-update` | Regenerate GRUB entries for all deployments |
291 +
292 +---
293 +
294 +## Environment variables
295 +
296 +| Variable | Meaning |
297 +|---|---|
298 +| `PAG_ROOT` | Alternative operation root (tests/chroot); default `/` |
299 +| `PAG_IMMUTABLE=1` | Immutable mode – installation creates a new deployment |
300 +| `PAG_YES=1` | Automatic confirmation (same as `-y` / `--yes`) |
301 +| `PAG_INSECURE=1` | Disables the HTTPS requirement and fail-closed GPG (**build/dev only!**) |
302 +| `PAG_NO_HOOKS=1` | Skip hooks and triggers |
303 +| `PAG_HOOK_TIMEOUT` | Hook timeout in seconds (default `60`) |
304 +| `PAG_LANG_DIR` | Directory with translation files (`pl.json`, `en.json`) |
305 +| `PAG_LANG_NO_FILES=1` | Ignore translation files (export built-ins) |
306 +| `PAG_ROOT_DEVICE` / `PAG_GRUB_ROOT` | Explicit `root=` for GRUB (ISO/IMG build) |
307 +| `PAG_IN_CHROOT=1` | Force chroot mode when detecting the root device |
308 +
309 +---
310 +
311 +## Paths and files
312 +
313 +| Path | Purpose |
314 +|---|---|
315 +| `/var/lib/pag/` | State database: `installed.json`, `files.db`, `world`, `pinned.json`, `history.json`, `pag.lock`, `hooks/` |
316 +| `/var/lib/pag/files.db` | SQLite: file owners + SHA256 sums |
317 +| `/var/cache/pag/` | Downloaded package cache |
318 +| `/var/cache/pag/repos/` | Repository index cache (JSON + ETag + timestamp) |
319 +| `/etc/pag/repos.conf` and `/etc/pag/repos/*.conf` | Repositories (drop-in) |
320 +| `/etc/pag/trusted.json` | Pinned repo key fingerprints |
321 +| `/etc/pag/gpg/` | Isolated GPG keyring |
322 +| `/etc/pag/triggers/*.json` | Custom triggers |
323 +| `/etc/pag/lang/`, `/usr/share/pag/lang/` | Translations (files override built-ins) |
324 +| `/var/log/pag/audit.log` | Audit: hooks, self-update |
325 +| `/.pag_staging` | Staging (same partition as `/` – no `EXDEV`) |
326 +| `/.deployments/` | Deployments (immutable mode) |
327 +
328 +---
329 +
330 +## Package format
331 +
332 +A `.pag` package is an archive containing:
333 +
334 +```
335 +metadata.json – name, version, release, dependencies, provides/requires (so-name)
336 +data.tar.xz – system files + sums.json (per-file SHA256)
337 +hooks/ – optional: pre-install, post-install, pre-remove, post-remove
338 +```
339 +
340 +Installation is **verified per file** against `sums.json`, and extraction is
341 +protected against *directory traversal* and escape via malicious symlinks.
342 +
343 +---
344 +
345 +## Hooks and triggers
346 +
347 +**Hooks** run as `root` (like apt/pacman), in a restricted environment:
348 +
349 +- `pre-install`, `post-install`, `pre-remove`, `post-remove`
350 +- clean env: `PATH`, `HOME=/root`, `LANG/LC_ALL=C.UTF-8`, `PKG_NAME`,
351 + `PKG_VERSION`, `PKG_ACTION`, `PKG_HOOK_API=1`
352 +- timeout (`PAG_HOOK_TIMEOUT`), optional disable (`PAG_NO_HOOKS=1`), entries in
353 + `/var/log/pag/audit.log` and in the transaction history
354 +
355 +You install code you trust – hooks have full privileges.
356 +
357 +**Triggers** run **once per transaction**, when matching paths were touched
358 +(only if the given binary exists):
359 +
360 +| Trigger | Paths | Command |
361 +|---|---|---|
362 +| `font-cache` | `/usr/share/fonts/`, `/usr/local/share/fonts/` | `fc-cache -fs` |
363 +| `glib-schemas` | `/usr/share/glib-2.0/schemas/` | `glib-compile-schemas …` |
364 +| `desktop-database` | `/usr/share/applications/` | `update-desktop-database -q …` |
365 +| `mime-database` | `/usr/share/mime/` | `update-mime-database …` |
366 +
367 +You can add your own triggers as `/etc/pag/triggers/*.json`.
368 +
369 +---
370 +
371 +## `/etc` configuration – `.pacnew` / `.pacsave`
372 +
373 +The `/etc` directory is shared between deployments (it is not reverted by
374 +`deploy-rollback`). To avoid losing user changes:
375 +
376 +- **Updating** a configuration file that the user modified: the new version is
377 + written as `<file>.pacnew`, and the user's file **is kept**.
378 +- **Removing** a package with a modified configuration file: the file becomes
379 + `<file>.pacsave` instead of being deleted.
380 +
381 +The comparison uses the SHA256 sum recorded at install time.
382 +
383 +---
384 +
385 +## Examples
386 +
387 +```bash
388 +# Install and updates
389 +sudo pag install firefox gimp
390 +sudo pag update # packages only
391 +sudo pag upgrade # packages + kernel/initramfs/GRUB
392 +sudo pag sync # refresh indexes + update info
393 +
394 +# Repair a package (missing files/directories, e.g. /etc/pulse/default.pa.d)
395 +sudo pag install -f pulseaudio
396 +
397 +# Application icons after installing an icon theme (cache built automatically)
398 +sudo pag install papirus-icon-theme
399 +
400 +# Security
401 +sudo pag key-add https://repo.paganlinux.eu/stable/paganos.asc
402 +sudo pag key-trust https://repo.paganlinux.eu/stable/
403 +sudo pag verify --deep
404 +
405 +# Dependencies and package provenance
406 +sudo pag why libjpeg-turbo
407 +sudo pag autoremove
408 +
409 +# SBOM for audit / compliance
410 +sudo pag sbom export cyclonedx > sbom.json
411 +
412 +# Revert the last transaction
413 +sudo pag rollback
414 +```
415 +
416 +---
417 +
418 +## Troubleshooting
419 +
420 +| Symptom | Solution |
421 +|---|---|
422 +| "Another pag instance is running" | Another `pag` process is active (`flock` lock). Wait or check `pgrep -af pag`. |
423 +| "Cannot refresh the index" | The repo cache is read-only for a regular user – run as root: `sudo pag sync`. |
424 +| "Invalid signature / missing signature" | Import the key: `sudo pag key-add <url>`, then verify `sudo pag key-trusted`. |
425 +| Missing files/directories after install | `sudo pag install -f <pkg>` (restores files, empty directories and hooks). |
426 +| System does not boot after `grub-update` | Set the root device explicitly: `PAG_ROOT_DEVICE=/dev/sda2 sudo pag grub-update`. |
427 +| Flatpak app not visible in the menu | Add `/var/lib/flatpak/exports/share` to `XDG_DATA_DIRS` and log in again. |
428 +
429 +---
430 +
431 +## Install and update
432 +
433 +```bash
434 +# On a running PaganOS, pag is in the base repository:
435 +sudo pag install pag # install from the repository
436 +sudo pag self-update # update the client itself (signed)
437 +
438 +# pag is also managed by the package manager – after a new version is
439 +# published in the repo:
440 +sudo pag update
441 +sudo pag upgrade
442 +```
443 +
444 +---
445 +
446 +## License
447 +
448 +PaganOS / pag – an open source project. See the distribution repository for
449 +details.