Commit ad99b97
0
plików
+0
dodanych
-0
usuniętych
@@ -0,0 +1,410 @@
1
+# pag – PaganOS Package Manager
2
+
3
+[](https://git.paganlinux.eu/pag)
4
+[](https://paganlinux.eu)
5
+
6
+Menedżer pakietów dla [PaganOS](https://paganlinux.eu). Instalacja atomowa
7
+(staging → rename), weryfikacja podpisów GPG z pinningiem fingerprintu, SHA256
8
+per-plik, pełny rollback transakcji, hooki i triggery oraz wsparcie systemów
9
+immutable z wdrożeniami (deployments).
10
+
11
+Diagramy w tym README renderuje Mermaid – obsługiwany przez portal
12
+`git.paganlinux.eu` (oraz GitHub/Gitea).
13
+
14
+```bash
15
+pag --version # wersja klienta (np. pag 3.3.20)
16
+pag # pełna pomoc (lista komend)
17
+pag --help # to samo co wyżej
18
+```
19
+
20
+---
21
+
22
+## Spis treści
23
+
24
+- [Szybki start](#szybki-start)
25
+- [Jak to działa](#jak-to-działa)
26
+ - [Przepływ `pag install`](#przepływ-pag-install)
27
+ - [Łańcuch zaufania](#łańcuch-zaufania)
28
+ - [System immutable](#system-immutable)
29
+ - [Rollback](#rollback)
30
+- [Komendy](#komendy)
31
+- [Zmienne środowiskowe](#zmienne-środowiskowe)
32
+- [Ścieżki i pliki](#ścieżki-i-pliki)
33
+- [Format pakietu](#format-pakietu)
34
+- [Hooki i triggery](#hooki-i-triggery)
35
+- [Konfiguracja `/etc` – `.pacnew` / `.pacsave`](#konfiguracja-etc--pacnew--pacsave)
36
+- [Przykłady](#przykłady)
37
+- [Diagnostyka](#diagnostyka)
38
+- [Instalacja i aktualizacja](#instalacja-i-aktualizacja)
39
+- [Licencja](#licencja)
40
+
41
+---
42
+
43
+## Szybki start
44
+
45
+```bash
46
+# Odśwież indeksy repozytoriów (i zobacz, co czeka na aktualizację)
47
+sudo pag sync
48
+
49
+# Instaluj / usuwaj
50
+sudo pag install firefox gimp
51
+sudo pag remove gimp
52
+
53
+# Aktualizuj same pakiety…
54
+sudo pag update
55
+# …albo cały system: pakiety + kernel / initramfs / GRUB
56
+sudo pag upgrade
57
+
58
+# Sprawdź integralność wszystkich plików
59
+sudo pag verify --deep
60
+```
61
+
62
+---
63
+
64
+## Jak to działa
65
+
66
+### Przepływ `pag install`
67
+
68
+```mermaid
69
+graph TD
70
+ A["pag install pkg"] --> B["Rozwiązanie zależności (DFS + provides)"]
71
+ B --> C{"Brakujące zależności?"}
72
+ C -->|tak| C1["Błąd – przerwij"]
73
+ C -->|nie| D["Weryfikacja ABI (so-name)"]
74
+ D --> E["Pre-flight: wolne miejsce + montowanie RW"]
75
+ E --> F["Blokada flock + migawka bazy"]
76
+ F --> G["Równoległe pobieranie paczek"]
77
+ G --> H["Weryfikacja GPG + SHA256 paczki"]
78
+ H --> I["Staging: rozpakowanie + sumy per-plik"]
79
+ I --> J["Atomowy rename plików do systemu"]
80
+ J --> K["Hooki pre/post-install"]
81
+ K --> L["Zapis do SQLite + historia transakcji"]
82
+ L --> M{"PAG_IMMUTABLE=1?"}
83
+ M -->|tak| N["Nowy deployment + wpisy GRUB"]
84
+ M -->|nie| O["ldconfig + triggery"]
85
+ H -->|błąd| R["Rollback całej transakcji"]
86
+ I -->|błąd| R
87
+ J -->|błąd| R
88
+ R --> S["Przywrócenie bazy i plików"]
89
+```
90
+
91
+Kluczowe własności:
92
+
93
+- **Atomowość** – pliki trafiają najpierw do staging na tej samej partycji co
94
+ `/`, potem są przenoszone `rename()` (bez pół-instalacji).
95
+- **Transakcyjność** – jeśli którykolwiek pakiet zawiedzie, cała transakcja jest
96
+ cofana (`installed.json`, pliki, backupy).
97
+- **Współdzielenie plików** – plik należący do dwóch pakietów nie jest usuwany
98
+ przy usunięciu jednego z nich (usuwany jest tylko wpis w bazie).
99
+
100
+### Łańcuch zaufania
101
+
102
+```mermaid
103
+graph TD
104
+ A["repo.json + repo.json.asc"] --> B["GPG: linia VALIDSIG"]
105
+ B --> C["Pinning fingerprintu repo (TOFU → pin)"]
106
+ C --> D["Indeks pakietów"]
107
+ D --> E["pakiet .pag + .asc"]
108
+ E --> F["GPG: podpis zgodny z pinem repo"]
109
+ F --> G["SHA256 całej paczki"]
110
+ G --> H["Bezpieczne rozpakowanie (anty-traversal)"]
111
+ H --> I["sums.json: SHA256 per plik"]
112
+ I --> J["Zdjęcie bitu SUID"]
113
+ J --> K["Instalacja"]
114
+ F -->|"brak / zły podpis"| X["Odrzuć paczkę"]
115
+ G -->|"niezgodny SHA256"| X
116
+ H -->|"traversal / escape przez symlink"| X
117
+```
118
+
119
+- Pierwsze użycie klucza = **TOFU**, potem fingerprint jest **przypinany**
120
+ (`pag key-trust` / `pag key-untrust`).
121
+- Weryfikacja jest **fail-closed**: brak/zły podpis = brak instalacji
122
+ (obejście tylko przez `PAG_INSECURE=1`, wyłącznie build/dev).
123
+- `pag self-update` przechodzi tę samą ścieżkę: GPG → SHA256 → kontrola
124
+ składni → atomowa podmiana klienta.
125
+
126
+### System immutable
127
+
128
+Przy `PAG_IMMUTABLE=1` instalacja nie mutuje `/`, lecz tworzy nowy deployment;
129
+rollback to przełączenie symlinku `active`.
130
+
131
+```mermaid
132
+graph TD
133
+ R["/"] --> D["/.deployments"]
134
+ D --> A["active → 20260723T120000"]
135
+ D --> D1["20260723T120000 (nowy)"]
136
+ D --> D2["20260722T090000 (poprzedni)"]
137
+ D1 --> U["usr/ bin/ lib/ – system"]
138
+ D1 --> S1["var → /var"]
139
+ D1 --> S2["etc → /etc"]
140
+ D1 --> S3["home → /home"]
141
+ D1 --> S4["boot → /boot"]
142
+ D2 -.->|"deploy-rollback"| A
143
+```
144
+
145
+- `/var`, `/etc`, `/home`, `/boot` (i inne z listy `SHARED_PATHS`) są
146
+ **współdzielone** między deploymentami – nie duplikują się.
147
+- `/boot` współdzieli jądro i initramfs, oszczędzając miejsce na każdym
148
+ deploymentcie.
149
+- Rollback z poziomu bootloadera: każdy deployment ma własny wpis GRUB
150
+ (`pag grub-update`).
151
+
152
+### Rollback
153
+
154
+```mermaid
155
+graph TD
156
+ T["Transakcja"] --> OK{"Sukces?"}
157
+ OK -->|tak| H["Historia + migawka + journal plików"]
158
+ OK -->|nie| RB["Automatyczny rollback transakcji"]
159
+ H --> R["pag rollback"]
160
+ R --> R1["Przywróć installed.json z migawki"]
161
+ R --> R2["Usuń nowe pliki z journalu"]
162
+ R --> R3["Przywróć nadpisane pliki z backupu"]
163
+ R --> R4["Posprzątaj puste katalogi"]
164
+ RB --> R1
165
+ RB --> R2
166
+ RB --> R3
167
+```
168
+
169
+`pag history` pokazuje ostatnie transakcje (wraz z wykonanymi hookami), a
170
+`pag rollback` cofa **ostatnią udaną** transakcję z migawką.
171
+
172
+---
173
+
174
+## Komendy
175
+
176
+### PODSTAWY
177
+
178
+| Komenda | Opis |
179
+|---|---|
180
+| `pag install <pkg>...` | Instaluje pakiety (razem z zależnościami) |
181
+| `pag install -f <pkg>...` | **Wymusza reinstalację** (nawet tej samej wersji) – odtwarza pliki, puste katalogi i hooki |
182
+| `pag remove <pkg>...` | Usuwa pakiety |
183
+| `pag update` | Aktualizuje **pakiety** do nowszych wersji |
184
+| `pag sync` | Odświeża indeksy repozytoriów + pokazuje, ile pakietów czeka na aktualizację |
185
+| `pag upgrade` | Aktualizacja **systemu**: pakiety + kernel / initramfs / GRUB |
186
+| `pag list` | Lista pakietów dostępnych w repozytorium |
187
+| `pag list --installed` | Lista zainstalowanych pakietów |
188
+| `pag search <query>` | Szukaj pakietów w repo (+ Flathub) |
189
+| `pag info <pkg>` | Szczegóły pakietu (wersja, zależności, rozmiar, podpis) |
190
+| `pag files <pkg>` | Lista plików należących do pakietu |
191
+| `pag verify` | Weryfikacja integralności zainstalowanych plików |
192
+| `pag verify --deep` | Pełna weryfikacja SHA256 per-plik |
193
+| `pag clean` | Czyści cache pobierania |
194
+| `pag stats` | Statystyki systemu (liczba pakietów, rozmiar, cache…) |
195
+| `pag download <pkg>...` | Pobiera pakiety do cache (tryb offline) |
196
+
197
+**Smart search:** `pag <nazwa>` (dowolna nieznana komenda) przeszukuje repo
198
+i Flathub oraz podpowiada nazwy – np. `pag firefox` znajdzie pakiet.
199
+
200
+### BEZPIECZEŃSTWO / KLUCZE GPG
201
+
202
+| Komenda | Opis |
203
+|---|---|
204
+| `pag key-add <url\|plik>` | Importuje klucz GPG repozytorium |
205
+| `pag key-list` | Lista zaufanych kluczy |
206
+| `pag key-remove <id>` | Usuwa klucz |
207
+| `pag key-trust <repo>` | Przypina fingerprint klucza repo (TOFU wyłączone) |
208
+| `pag key-untrust <repo>` | Zapomina fingerprint (powrót do TOFU) |
209
+| `pag key-trusted` | Lista przypiętych fingerprintów repo |
210
+
211
+### ZAAWANSOWANE
212
+
213
+| Komenda | Opis |
214
+|---|---|
215
+| `pag why <pkg>` | Dlaczego pakiet jest zainstalowany (kto go zależy) |
216
+| `pag autoremove` | Usuwa osierocone zależności |
217
+| `pag remove-orphans` | Usuwa osierocone zależności (alias) |
218
+| `pag pin <pkg> [wersja]` | Przypina pakiet do wersji (blokada aktualizacji) |
219
+| `pag unpin <pkg>` | Zdejmuje przypięcie |
220
+| `pag pinned` | Lista przypiętych pakietów |
221
+| `pag history` | Historia transakcji |
222
+| `pag rollback` | Cofa **ostatnią** transakcję (przywraca pliki z backupu) |
223
+| `pag repo-add <url> [nazwa]` | Dodaje repozytorium (drop-in w `/etc/pag/repos/`) |
224
+| `pag repo-list` | Lista skonfigurowanych repozytoriów |
225
+| `pag sbom export [spdx\|cyclonedx]` | Eksportuje manifest SBOM wszystkich zainstalowanych komponentów |
226
+| `pag self-update` | Aktualizuje samego klienta `pag` (podpis GPG + SHA256 + składnia, atomowo) |
227
+
228
+### FLATPAK
229
+
230
+| Komenda | Opis |
231
+|---|---|
232
+| `pag flatpak [<query>]` | Szukaj i instaluj z Flathub |
233
+| `pag flatpak search <query>` | Szukaj na Flathub |
234
+| `pag flatpak install <id>` | Instaluje flatpak |
235
+| `pag flatpak remove <id>` | Usuwa flatpak |
236
+| `pag flatpak list` | Lista zainstalowanych flatpaków |
237
+| `pag flatpak update` | Aktualizuje wszystkie flatpaki |
238
+| `pag flatpak info <id>` | Szczegóły flatpaka |
239
+
240
+> Instalacja jako root wymusza zakres **systemowy** (`--system`), dzięki czemu
241
+> aplikacja jest widoczna dla wszystkich użytkowników, a nie tylko dla roota.
242
+
243
+### SYSTEM IMMUTABLE (`PAG_IMMUTABLE=1`)
244
+
245
+| Komenda | Opis |
246
+|---|---|
247
+| `pag deploy-list` | Lista wdrożeń (deployments) |
248
+| `pag deploy-rollback` | Przełącza na poprzednie wdrożenie |
249
+| `pag deploy-cleanup [N]` | Usuwa stare wdrożenia (zachowuje N, domyślnie 3) |
250
+| `pag initramfs-update` | Przebudowuje initramfs |
251
+| `pag grub-update` | Regeneruje wpisy GRUB dla wszystkich wdrożeń |
252
+
253
+---
254
+
255
+## Zmienne środowiskowe
256
+
257
+| Zmienna | Znaczenie |
258
+|---|---|
259
+| `PAG_ROOT` | Alternatywny root operacji (testy/chroot); domyślnie `/` |
260
+| `PAG_IMMUTABLE=1` | Tryb immutable – instalacja tworzy nowy deployment |
261
+| `PAG_YES=1` | Automatyczne potwierdzenie (to samo co `-y` / `--yes`) |
262
+| `PAG_INSECURE=1` | Wyłącza wymóg HTTPS i fail-closed GPG (**tylko build/dev!**) |
263
+| `PAG_NO_HOOKS=1` | Pomija hooki i triggery |
264
+| `PAG_HOOK_TIMEOUT` | Timeout hooka w sekundach (domyślnie `60`) |
265
+| `PAG_LANG_DIR` | Katalog z plikami tłumaczeń (`pl.json`, `en.json`) |
266
+| `PAG_LANG_NO_FILES=1` | Ignoruje pliki tłumaczeń (eksport wbudowanych) |
267
+| `PAG_ROOT_DEVICE` / `PAG_GRUB_ROOT` | Jawny `root=` dla GRUB (build ISO/IMG) |
268
+| `PAG_IN_CHROOT=1` | Wymusza tryb chroot przy wykrywaniu urządzenia root |
269
+
270
+---
271
+
272
+## Ścieżki i pliki
273
+
274
+| Ścieżka | Przeznaczenie |
275
+|---|---|
276
+| `/var/lib/pag/` | Baza stanu: `installed.json`, `files.db`, `world`, `pinned.json`, `history.json`, `pag.lock`, `hooks/` |
277
+| `/var/lib/pag/files.db` | SQLite: właściciele plików + sumy SHA256 |
278
+| `/var/cache/pag/` | Cache pobranych pakietów |
279
+| `/var/cache/pag/repos/` | Cache indeksów repozytoriów (JSON + ETag + znacznik czasu) |
280
+| `/etc/pag/repos.conf` i `/etc/pag/repos/*.conf` | Repozytoria (drop-in) |
281
+| `/etc/pag/trusted.json` | Przypięte fingerprinty kluczy repo |
282
+| `/etc/pag/gpg/` | Izolowany keyring GPG |
283
+| `/etc/pag/triggers/*.json` | Własne triggery |
284
+| `/etc/pag/lang/`, `/usr/share/pag/lang/` | Tłumaczenia (pliki nadpisują wbudowane) |
285
+| `/var/log/pag/audit.log` | Audyt: hooki, self-update |
286
+| `/.pag_staging` | Staging (ta sama partycja co `/` – brak `EXDEV`) |
287
+| `/.deployments/` | Wdrożenia (tryb immutable) |
288
+
289
+---
290
+
291
+## Format pakietu
292
+
293
+Pakiet `.pag` to archiwum zawierające:
294
+
295
+```
296
+metadata.json – nazwa, wersja, release, zależności, provides/requires (so-name)
297
+data.tar.xz – pliki systemu + sums.json (SHA256 per plik)
298
+hooks/ – opcjonalne: pre-install, post-install, pre-remove, post-remove
299
+```
300
+
301
+Instalacja jest **weryfikowana per-plik** względem `sums.json`, a rozpakowanie
302
+chroni przed *directory traversal* i ucieczką przez złośliwe symlinki.
303
+
304
+---
305
+
306
+## Hooki i triggery
307
+
308
+**Hooki** uruchamiane są jako `root` (jak w apt/pacman), w ograniczonym
309
+środowisku:
310
+
311
+- `pre-install`, `post-install`, `pre-remove`, `post-remove`
312
+- czyste env: `PATH`, `HOME=/root`, `LANG/LC_ALL=C.UTF-8`, `PKG_NAME`,
313
+ `PKG_VERSION`, `PKG_ACTION`, `PKG_HOOK_API=1`
314
+- timeout (`PAG_HOOK_TIMEOUT`), możliwość wyłączenia (`PAG_NO_HOOKS=1`),
315
+ wpisy w `/var/log/pag/audit.log` i w historii transakcji
316
+
317
+Instalujesz kod, któremu ufasz – hooki mają pełne uprawnienia.
318
+
319
+**Triggery** uruchamiane są **raz na transakcję**, gdy dotknięto pasujących
320
+ścieżek (tylko jeśli dana binarka istnieje):
321
+
322
+| Trigger | Ścieżki | Komenda |
323
+|---|---|---|
324
+| `font-cache` | `/usr/share/fonts/`, `/usr/local/share/fonts/` | `fc-cache -fs` |
325
+| `glib-schemas` | `/usr/share/glib-2.0/schemas/` | `glib-compile-schemas …` |
326
+| `desktop-database` | `/usr/share/applications/` | `update-desktop-database -q …` |
327
+| `mime-database` | `/usr/share/mime/` | `update-mime-database …` |
328
+
329
+Własne triggery dodasz jako `/etc/pag/triggers/*.json`.
330
+
331
+---
332
+
333
+## Konfiguracja `/etc` – `.pacnew` / `.pacsave`
334
+
335
+Katalog `/etc` jest współdzielony między wdrożeniami (nie cofa się przy
336
+`deploy-rollback`). Aby nie tracić zmian użytkownika:
337
+
338
+- **Aktualizacja** pliku konfiguracyjnego, który użytkownik zmodyfikował:
339
+ nowa wersja trafia jako `<plik>.pacnew`, a plik użytkownika **zostaje**.
340
+- **Usunięcie** pakietu ze zmodyfikowanym plikiem konfiguracyjnym: plik trafia
341
+ jako `<plik>.pacsave` zamiast zostać skasowany.
342
+
343
+Porównanie odbywa się względem sumy SHA256 z chwili instalacji.
344
+
345
+---
346
+
347
+## Przykłady
348
+
349
+```bash
350
+# Instalacja i aktualizacje
351
+sudo pag install firefox gimp
352
+sudo pag update # same pakiety
353
+sudo pag upgrade # pakiety + kernel/initramfs/GRUB
354
+sudo pag sync # odśwież indeksy + info o aktualizacjach
355
+
356
+# Naprawa pakietu (brakujące pliki/katalogi, np. /etc/pulse/default.pa.d)
357
+sudo pag install -f pulseaudio
358
+
359
+# Ikony aplikacji po instalacji motywu (cache budowany automatycznie)
360
+sudo pag install papirus-icon-theme
361
+
362
+# Bezpieczeństwo
363
+sudo pag key-add https://repo.paganlinux.eu/stable/paganos.asc
364
+sudo pag key-trust https://repo.paganlinux.eu/stable/
365
+sudo pag verify --deep
366
+
367
+# Zależności i pochodzenie pakietów
368
+sudo pag why libjpeg-turbo
369
+sudo pag autoremove
370
+
371
+# SBOM dla audytu / compliance
372
+sudo pag sbom export cyclonedx > sbom.json
373
+
374
+# Cofnij ostatnią transakcję
375
+sudo pag rollback
376
+```
377
+
378
+---
379
+
380
+## Diagnostyka
381
+
382
+| Objaw | Rozwiązanie |
383
+|---|---|
384
+| „Inna instancja pag jest uruchomiona” | Działa inny proces `pag` (blokada `flock`). Poczekaj lub sprawdź `pgrep -af pag`. |
385
+| „Nie można odświeżyć indeksu” | Cache repo jest tylko-do-odczytu dla zwykłego usera – uruchom jako root: `sudo pag sync`. |
386
+| „Nieprawidłowy podpis / brak podpisu” | Zaimportuj klucz: `sudo pag key-add <url>`, potem zweryfikuj `sudo pag key-trusted`. |
387
+| Brakujące pliki/katalogi po instalacji | `sudo pag install -f <pkg>` (odtwarza pliki, puste katalogi i hooki). |
388
+| System nie bootuje po `grub-update` | Ustaw jawnie urządzenie root: `PAG_ROOT_DEVICE=/dev/sda2 sudo pag grub-update`. |
389
+| Aplikacja z Flathuba niewidoczna w menu | Dodaj `/var/lib/flatpak/exports/share` do `XDG_DATA_DIRS` i zaloguj się ponownie. |
390
+
391
+---
392
+
393
+## Instalacja i aktualizacja
394
+
395
+```bash
396
+# Na działającym PaganOS pag jest w repo bazowym:
397
+sudo pag install pag # instalacja z repozytorium
398
+sudo pag self-update # aktualizacja samego klienta (podpisana)
399
+
400
+# pag jest też zarządzany przez menedżera pakietów – po publikacji nowej
401
+# wersji w repo:
402
+sudo pag update
403
+sudo pag upgrade
404
+```
405
+
406
+---
407
+
408
+## Licencja
409
+
410
+PaganOS / pag – projekt open source. Szczegóły w repozytorium dystrybucji.