PaganOS Luna 0.6.0
PL EN DE
🔒 Repozytorium w trybie tylko do odczytu – edycja plików jest wyłączona.

pag

git clone https://git.paganlinux.eu/pag.git
▶ Pliki (5) · main
5 / 5 1 4
Nazwa↕ Rozmiar↕ Ostatnia zmiana↕
pag-lang/ 7 dni temu
.gitignore 28 B 2 mies. temu
pag 0.4 KB 7 dni temu
README-EN.md 0.0 KB 7 dni temu
README.md 0.0 KB 7 dni temu
Brak pasujących plików
▶ README.md PL | EN

pag – PaganOS Package Manager

Wersja Platforma

Menedżer pakietów dla PaganOS. Instalacja atomowa (staging → rename), weryfikacja podpisów GPG z pinningiem fingerprintu, SHA256 per-plik, pełny rollback transakcji, hooki i triggery oraz wsparcie systemów immutable z wdrożeniami (deployments).

Diagramy w tym README renderuje Mermaid – obsługiwany przez portal git.paganlinux.eu (oraz GitHub/Gitea).

pag --version        # wersja klienta (np. pag 3.3.20)
pag                  # pełna pomoc (lista komend)
pag --help           # to samo co wyżej

Spis treści


Szybki start

# Odśwież indeksy repozytoriów (i zobacz, co czeka na aktualizację)
sudo pag sync

# Instaluj / usuwaj
sudo pag install firefox gimp
sudo pag remove gimp

# Aktualizuj same pakiety…
sudo pag update
# …albo cały system: pakiety + flatpaki + kernel / initramfs / GRUB
sudo pag upgrade

# Baza zbudowana w obrazie ISO a repozytorium (pełny rolling)
pag base                       # co jest z obrazu, a czym pag już zarządza
sudo pag base adopt            # dograj bazę z repo (--dry-run = podgląd)

# Sprawdź integralność wszystkich plików
sudo pag verify --deep

Jak to działa

Przepływ pag install

graph TD
    A["pag install pkg"] --> B["Rozwiązanie zależności (DFS + provides)"]
    B --> C{"Brakujące zależności?"}
    C -->|tak| C1["Błąd – przerwij"]
    C -->|nie| D["Weryfikacja ABI (so-name)"]
    D --> E["Pre-flight: wolne miejsce + montowanie RW"]
    E --> F["Blokada flock + migawka bazy"]
    F --> G["Równoległe pobieranie paczek"]
    G --> H["Weryfikacja GPG + SHA256 paczki"]
    H --> I["Staging: rozpakowanie + sumy per-plik"]
    I --> J["Atomowy rename plików do systemu"]
    J --> K["Hooki pre/post-install"]
    K --> L["Zapis do SQLite + historia transakcji"]
    L --> M{"PAG_IMMUTABLE=1?"}
    M -->|tak| N["Nowy deployment + wpisy GRUB"]
    M -->|nie| O["ldconfig + triggery"]
    H -->|błąd| R["Rollback całej transakcji"]
    I -->|błąd| R
    J -->|błąd| R
    R --> S["Przywrócenie bazy i plików"]

Kluczowe własności:

  • Atomowość – pliki trafiają najpierw do staging na tej samej partycji co /, potem są przenoszone rename() (bez pół-instalacji).
  • Transakcyjność – jeśli którykolwiek pakiet zawiedzie, cała transakcja jest cofana (installed.json, pliki, backupy).
  • Współdzielenie plików – plik należący do dwóch pakietów nie jest usuwany przy usunięciu jednego z nich (usuwany jest tylko wpis w bazie).

Pobieranie równoległe – status każdej paczki

Przy instalacji lub aktualizacji wielu pakietów pag pobiera je równolegle (do 4 wątków) i pokazuje osobny, animowany wiersz dla każdego aktywnego pobierania – z procentem, nazwą paczki, liczbą pobranych bajtów i ETA:

  ⏬ [▓▓▓▓▓█▓»~_~_~_~_~_~_] 7/12 (58%)
  ↓ [███»~~~~~~]  38% (mesa: 12.3/29.1 MB, ETA 8s)
  ↓ [█████»~~~~]  67% (glibc: 8.8/10.0 MB, ETA 3s)
  ↓ [▓▓▓▓▓▓▓▓»~]  91% (linux-firmware: 26.2/28.7 MB, ETA 2s)
  ✅ python-3.14.0 (30.1 MB, 14s)

Ukończone pobrania zostają w scrollbacku, a pasek zbiorczy pokazuje liczbę gotowych paczek. Poza TTY (logi instalatora, cron) pag nie używa sekwencji ANSI – wypisuje linię startu, kamienie milowe 25/50/75% i wynik.

Wygląd pasków można zmienić: PAG_NO_ANIM=1 (statyczny pasek), PAG_BAR_STYLE=snake|classic (domyślnie drakkar).

Łańcuch zaufania

graph TD
    A["repo.json + repo.json.asc"] --> B["GPG: linia VALIDSIG"]
    B --> C["Pinning fingerprintu repo (TOFU → pin)"]
    C --> D["Indeks pakietów"]
    D --> E["pakiet .pag + .asc"]
    E --> F["GPG: podpis zgodny z pinem repo"]
    F --> G["SHA256 całej paczki"]
    G --> H["Bezpieczne rozpakowanie (anty-traversal)"]
    H --> I["sums.json: SHA256 per plik"]
    I --> J["Zdjęcie bitu SUID"]
    J --> K["Instalacja"]
    F -->|"brak / zły podpis"| X["Odrzuć paczkę"]
    G -->|"niezgodny SHA256"| X
    H -->|"traversal / escape przez symlink"| X
  • Pierwsze użycie klucza = TOFU, potem fingerprint jest przypinany (pag key-trust / pag key-untrust).
  • Weryfikacja jest fail-closed: brak/zły podpis = brak instalacji (obejście tylko przez PAG_INSECURE=1, wyłącznie build/dev).
  • pag self-update przechodzi tę samą ścieżkę: GPG → SHA256 → kontrola składni → atomowa podmiana klienta.

System immutable

Przy PAG_IMMUTABLE=1 instalacja nie mutuje /, lecz tworzy nowy deployment; rollback to przełączenie symlinku active.

graph TD
    R["/"] --> D["/.deployments"]
    D --> A["active → 20260723T120000"]
    D --> D1["20260723T120000 (nowy)"]
    D --> D2["20260722T090000 (poprzedni)"]
    D1 --> U["usr/ bin/ lib/ – system"]
    D1 --> S1["var → /var"]
    D1 --> S2["etc → /etc"]
    D1 --> S3["home → /home"]
    D1 --> S4["boot → /boot"]
    D2 -.->|"deploy-rollback"| A
  • /var, /etc, /home, /boot (i inne z listy SHARED_PATHS) są współdzielone między deploymentami – nie duplikują się.
  • /boot współdzieli jądro i initramfs, oszczędzając miejsce na każdym deploymentcie.
  • Rollback z poziomu bootloadera: każdy deployment ma własny wpis GRUB (pag grub-update).

Rollback

graph TD
    T["Transakcja"] --> OK{"Sukces?"}
    OK -->|tak| H["Historia + migawka + journal plików"]
    OK -->|nie| RB["Automatyczny rollback transakcji"]
    H --> R["pag rollback"]
    R --> R1["Przywróć installed.json z migawki"]
    R --> R2["Usuń nowe pliki z journalu"]
    R --> R3["Przywróć nadpisane pliki z backupu"]
    R --> R4["Posprzątaj puste katalogi"]
    RB --> R1
    RB --> R2
    RB --> R3

pag history pokazuje ostatnie transakcje (wraz z wykonanymi hookami), a pag rollback cofa ostatnią udaną transakcję z migawką.


Rolling – baza z obrazu ISO

Obraz PaganOS jest zbudowany ze źródeł (glibc, gcc, GTK, XFCE, jądro…). pag ich nie instalował, więc nie ma ich w swojej bazie (/var/lib/pag/installed.json) – a skoro ich nie zna, to pag upgrade ich nie zaktualizuje. Pliki z obrazu nie są jednak nietykalne: pag install <nazwa> je nadpisze (z kopią zapasową dla pag rollback).

Żeby system był w pełni rolling, trzeba powiedzieć pagowi, co jest bazą obrazu:

pag base              # raport: ile pakietów z obrazu pag zarządza, ile da się
                      # zaadoptować z repo i co zostaje w wersji z obrazu
sudo pag base adopt   # dograj bazę z repo (--dry-run = podgląd, nic nie instaluje)

Po pag base adopt pakiety z obrazu stają się zwykłymi pakietami z repo, więc kolejne sudo pag upgrade aktualizuje cały system. Spis pakietów bazy pochodzi z manifestu wypalanego w obrazie: /usr/share/pag/base.json (nazwa + wersja; builder dopisuje wpis przy każdym budowanym pakiecie). Nazwy z buildera są mapowane na nazwy z repo (np. gtk → gtk3, libX11 → xorg-libx11); te bez odpowiednika w repo raport zostawia w wersji z obrazu i mówi o tym wprost.


Komendy

PODSTAWY

Komenda Opis
pag install <pkg>... Instaluje pakiety (razem z zależnościami)
pag install -f <pkg>... Wymusza reinstalację (nawet tej samej wersji) – odtwarza pliki, puste katalogi i hooki
pag remove <pkg>... Usuwa pakiety
pag update Aktualizuje pakiety + flatpaki systemowe
pag sync Odświeża indeksy repozytoriów + pokazuje, ile pakietów czeka na aktualizację (nic nie zmienia)
pag upgrade Aktualizacja systemu: pakiety + flatpaki + kernel / initramfs / GRUB
pag list Lista pakietów dostępnych w repozytorium
pag list --installed Lista zainstalowanych pakietów
pag search <query> Szukaj pakietów w repo (+ Flathub)
pag info <pkg> Szczegóły pakietu (wersja, zależności, rozmiar, podpis)
pag files <pkg> Lista plików należących do pakietu
pag verify Weryfikacja integralności zainstalowanych plików
pag verify --deep Pełna weryfikacja SHA256 per-plik
pag clean Czyści cache pobierania
pag stats Statystyki systemu (liczba pakietów, rozmiar, cache…)
pag download <pkg>... Pobiera pakiety do cache (tryb offline)

Smart search: pag <nazwa> (dowolna nieznana komenda) przeszukuje repo i Flathub oraz podpowiada nazwy – np. pag firefox znajdzie pakiet.

BEZPIECZEŃSTWO / KLUCZE GPG

Komenda Opis
pag key-add <url\|plik> Importuje klucz GPG repozytorium
pag key-list Lista zaufanych kluczy
pag key-remove <id> Usuwa klucz
pag key-trust <repo> Przypina fingerprint klucza repo (TOFU wyłączone)
pag key-untrust <repo> Zapomina fingerprint (powrót do TOFU)
pag key-trusted Lista przypiętych fingerprintów repo

ZAAWANSOWANE

Komenda Opis
pag why <pkg> Dlaczego pakiet jest zainstalowany (kto go zależy)
pag autoremove Usuwa osierocone zależności
pag remove-orphans Usuwa osierocone zależności (alias)
pag pin <pkg> [wersja] Przypina pakiet do wersji (blokada aktualizacji)
pag unpin <pkg> Zdejmuje przypięcie
pag pinned Lista przypiętych pakietów
pag history Historia transakcji
pag rollback Cofa ostatnią transakcję (przywraca pliki z backupu)
pag repo-add <url> [nazwa] Dodaje repozytorium (drop-in w /etc/pag/repos/)
pag repo-list Lista skonfigurowanych repozytoriów
pag sbom export [spdx\|cyclonedx] Eksportuje manifest SBOM wszystkich zainstalowanych komponentów
pag self-update Aktualizuje samego klienta pag (podpis GPG + SHA256 + składnia, atomowo)

ROLLING (BAZA Z OBRAZU)

Komenda Opis
pag base Raport: pakiety z obrazu ISO – zarządzane przez pag / do adoptowania z repo / bez odpowiednika
pag base adopt Dogrywa pakiety bazy z repo (zastępuje pliki z obrazu, kopie dla pag rollback); --dry-run = podgląd
pag base adopt <pkg>... Adoptuje tylko wskazane pakiety bazy

FLATPAK

Komenda Opis
pag flatpak [<query>] Szukaj i instaluj z Flathub
pag flatpak search <query> Szukaj na Flathub
pag flatpak install <id> Instaluje flatpak
pag flatpak remove <id> Usuwa flatpak
pag flatpak list Lista zainstalowanych flatpaków
pag flatpak update Aktualizuje wszystkie flatpaki
pag flatpak info <id> Szczegóły flatpaka
pag update / pag upgrade Aktualizują też flatpaki systemowe (pomiń: --no-flatpak)

Instalacja jako root wymusza zakres systemowy (--system), dzięki czemu aplikacja jest widoczna dla wszystkich użytkowników, a nie tylko dla roota.

pag update i pag upgrade aktualizują flatpaki systemowe razem z pakietami (pomiń: --no-flatpak). Instalacje --user aktualizuje pag flatpak update uruchomiony bez sudo.

SYSTEM IMMUTABLE (PAG_IMMUTABLE=1)

Komenda Opis
pag deploy-list Lista wdrożeń (deployments)
pag deploy-rollback Przełącza na poprzednie wdrożenie
pag deploy-cleanup [N] Usuwa stare wdrożenia (zachowuje N, domyślnie 3)
pag initramfs-update Przebudowuje initramfs
pag grub-update Regeneruje wpisy GRUB dla wszystkich wdrożeń

EASTER EGG

Komenda Opis
pag wroom Ukryty, animowany wyścig ASCII w stylu Commodore (3 pasy, kolizje, rekord sesji)

Sterowanie: ←/→ (lub A/D) zmiana pasa, ↑/↓ (lub W/S) gaz/hamulec, P pauza, R/SPACJA restart, Q wyjście. Gra działa tylko w terminalu, nie wymaga roota i nie jest pokazywana w pag --help.


Zmienne środowiskowe

Zmienna Znaczenie
PAG_ROOT Alternatywny root operacji (testy/chroot); domyślnie /
PAG_IMMUTABLE=1 Tryb immutable – instalacja tworzy nowy deployment
PAG_YES=1 Automatyczne potwierdzenie (to samo co -y / --yes)
PAG_INSECURE=1 Wyłącza wymóg HTTPS i fail-closed GPG (tylko build/dev!)
PAG_NO_HOOKS=1 Pomija hooki i triggery
PAG_HOOK_TIMEOUT Timeout hooka w sekundach (domyślnie 900)
PAG_LANG_DIR Katalog z plikami tłumaczeń (pl.json, en.json)
PAG_LANG_NO_FILES=1 Ignoruje pliki tłumaczeń (eksport wbudowanych)
PAG_NO_ANIM=1 Wyłącza animację pasków postępu (statyczny pasek)
PAG_BAR_STYLE Styl paska postępu: drakkar (domyślnie), snake, classic
PAG_ROOT_DEVICE / PAG_GRUB_ROOT Jawny root= dla GRUB (build ISO/IMG)
PAG_IN_CHROOT=1 Wymusza tryb chroot przy wykrywaniu urządzenia root

Ścieżki i pliki

Ścieżka Przeznaczenie
/var/lib/pag/ Baza stanu: installed.json, files.db, world, pinned.json, history.json, pag.lock, hooks/
/var/lib/pag/files.db SQLite: właściciele plików + sumy SHA256
/var/cache/pag/ Cache pobranych pakietów
/var/cache/pag/repos/ Cache indeksów repozytoriów (JSON + ETag + znacznik czasu)
/etc/pag/repos.conf i /etc/pag/repos/*.conf Repozytoria (drop-in)
/etc/pag/trusted.json Przypięte fingerprinty kluczy repo
/etc/pag/gpg/ Izolowany keyring GPG
/etc/pag/triggers/*.json Własne triggery
/etc/pag/lang/, /usr/share/pag/lang/ Tłumaczenia (pliki nadpisują wbudowane)
/var/log/pag/audit.log Audyt: hooki, self-update
/.pag_staging Staging (ta sama partycja co / – brak EXDEV)
/.deployments/ Wdrożenia (tryb immutable)

Format pakietu

Pakiet .pag to archiwum zawierające:

metadata.json   – nazwa, wersja, release, zależności, provides/requires (so-name)
data.tar.xz      – pliki systemu + sums.json (SHA256 per plik)
hooks/           – opcjonalne: pre-install, post-install, pre-remove, post-remove

Instalacja jest weryfikowana per-plik względem sums.json, a rozpakowanie chroni przed directory traversal i ucieczką przez złośliwe symlinki.


Hooki i triggery

Hooki uruchamiane są jako root (jak w apt/pacman), w ograniczonym środowisku:

  • pre-install, post-install, pre-remove, post-remove
  • czyste env: PATH, HOME=/root, LANG/LC_ALL=C.UTF-8, PKG_NAME, PKG_VERSION, PKG_ACTION, PKG_HOOK_API=1
  • timeout (PAG_HOOK_TIMEOUT, domyślnie 900 s – hooki jądra/NVIDIA budują moduły DKMS i initramfs), możliwość wyłączenia (PAG_NO_HOOKS=1), wpisy w /var/log/pag/audit.log i w historii transakcji

Instalujesz kod, któremu ufasz – hooki mają pełne uprawnienia.

Przy zmianie jądra lub sterowników (NVIDIA/VirtualBox) pag przebudowuje initramfs raz, po całej transakcji, w kolejności DKMS → depmod → initramfs → GRUB. depmod jest istotny, bo część pakietów jądra dostarcza własny, niepełny modules.dep (bez modułów doinstalowanych później, np. NVIDIA). Docelowo hooki pakietów powinny pominąć własną przebudowę, gdy działają pod lockiem pag (np. sprawdzając /var/lib/pag/pag.lock) – pozwala to uniknąć kilku kosztownych przebudów w jednej aktualizacji.

Triggery uruchamiane są raz na transakcję, gdy dotknięto pasujących ścieżek (tylko jeśli dana binarka istnieje):

Trigger Ścieżki Komenda
font-cache /usr/share/fonts/, /usr/local/share/fonts/ fc-cache -fs
glib-schemas /usr/share/glib-2.0/schemas/ glib-compile-schemas …
desktop-database /usr/share/applications/ update-desktop-database -q …
mime-database /usr/share/mime/ update-mime-database …

Własne triggery dodasz jako /etc/pag/triggers/*.json.


Konfiguracja /etc – .pacnew / .pacsave

Katalog /etc jest współdzielony między wdrożeniami (nie cofa się przy deploy-rollback). Aby nie tracić zmian użytkownika:

  • Aktualizacja pliku konfiguracyjnego, który użytkownik zmodyfikował: nowa wersja trafia jako <plik>.pacnew, a plik użytkownika zostaje.
  • Usunięcie pakietu ze zmodyfikowanym plikiem konfiguracyjnym: plik trafia jako <plik>.pacsave zamiast zostać skasowany.

Porównanie odbywa się względem sumy SHA256 z chwili instalacji.


Przykłady

# Instalacja i aktualizacje
sudo pag install firefox gimp
sudo pag update                # pakiety + flatpaki systemowe
sudo pag upgrade               # pakiety + flatpaki + kernel/initramfs/GRUB
sudo pag sync                  # odśwież indeksy + info o aktualizacjach

# Naprawa pakietu (brakujące pliki/katalogi, np. /etc/pulse/default.pa.d)
sudo pag install -f pulseaudio

# Ikony aplikacji po instalacji motywu (cache budowany automatycznie)
sudo pag install papirus-icon-theme

# Bezpieczeństwo
sudo pag key-add https://repo.paganlinux.eu/stable/paganos.asc
sudo pag key-trust https://repo.paganlinux.eu/stable/
sudo pag verify --deep

# Zależności i pochodzenie pakietów
sudo pag why libjpeg-turbo
sudo pag autoremove

# SBOM dla audytu / compliance
sudo pag sbom export cyclonedx > sbom.json

# Cofnij ostatnią transakcję
sudo pag rollback

Diagnostyka

Objaw Rozwiązanie
„Inna instancja pag jest uruchomiona” Działa inny proces pag (blokada flock). Poczekaj lub sprawdź pgrep -af pag.
„Nie można odświeżyć indeksu” Cache repo jest tylko-do-odczytu dla zwykłego usera – uruchom jako root: sudo pag sync.
„Nieprawidłowy podpis / brak podpisu” Zaimportuj klucz: sudo pag key-add <url>, potem zweryfikuj sudo pag key-trusted.
Brakujące pliki/katalogi po instalacji sudo pag install -f <pkg> (odtwarza pliki, puste katalogi i hooki).
System nie bootuje po grub-update Ustaw jawnie urządzenie root: PAG_ROOT_DEVICE=/dev/sda2 sudo pag grub-update.
Aplikacja z Flathuba niewidoczna w menu Dodaj /var/lib/flatpak/exports/share do XDG_DATA_DIRS i zaloguj się ponownie.

Instalacja i aktualizacja

# Na działającym PaganOS pag jest w repo bazowym:
sudo pag install pag          # instalacja z repozytorium
sudo pag self-update          # aktualizacja samego klienta (podpisana)

# pag jest też zarządzany przez menedżera pakietów – po publikacji nowej
# wersji w repo:
sudo pag update
sudo pag upgrade

Licencja

PaganOS / pag – projekt open source. Szczegóły w repozytorium dystrybucji.

O repozytorium

Pag manager
commitów77
gałęzi2
Kontrybutorzy8
Issues1
Domyślna gałąźmain
LicencjaBrak