Guide complet — Installer PINCE depuis zéro sur Bazzite

Permet d'attacher PINCE à un processus Wine/Proton (ex. SOTTR.exe), ce qui échoue avec un setup distrobox standard à cause de l'isolation user namespace de rootless podman.

Pourquoi distrobox rootful ?

Le distrobox classique tourne en rootless podman → user namespace isolé → même avec CAP_SYS_PTRACE, le kernel refuse le ptrace sur les processus du host (« Operation not permitted »).

Seule solution propre : un distrobox rootful, qui place le container dans le namespace racine du host. Les capabilities sont alors réellement effectives.

Architecture choisie

Container : tout l'environnement PINCE (Fedora + deps + code PINCE lui-même dans /opt/PINCE)
Host : aucune installation. Le $HOME reste propre — il sera juste monté en lecture/écriture dans le container par distrobox pour que PINCE puisse stocker ses configs dans ~/.config/PINCE.

→ Pour réinstaller à neuf : distrobox rm du container, et on recommence. Aucune pollution sur le host.

0. Vérifications host (Bazzite)

# ptrace_scope doit être à 0 pour le ptrace same-UID
cat /proc/sys/kernel/yama/ptrace_scope
# Si != 0 :
echo 0 | sudo tee /proc/sys/kernel/yama/ptrace_scope

# SELinux (à savoir, pas forcément à changer)
getenforce

Rendre ptrace_scope=0 persistant :

sudo tee /etc/sysctl.d/10-ptrace.conf <<< "kernel.yama.ptrace_scope = 0"
sudo sysctl --system

1. Créer le distrobox rootful (image Fedora vanilla)

# ⚠️ PAS de sudo devant — distrobox refuse, le flag --root gère l'élévation
distrobox create --root \
  --name pince \
  --image registry.fedoraproject.org/fedora-toolbox:latest \
  --additional-flags "--cap-add=SYS_PTRACE --security-opt seccomp=unconfined" \
  --yes

Distrobox demandera le mot de passe sudo en interne pour utiliser podman en mode root.

Flags clés :

--root → podman rootful, container dans le namespace racine du host
--cap-add=SYS_PTRACE → permet à GDB / PINCE d'attacher
--security-opt seccomp=unconfined → désactive le filtre seccomp par défaut qui peut bloquer certains syscalls (process_vm_readv, etc.)
--image fedora-toolbox:latest → image officielle Fedora optimisée pour les containers de dev (peut être omis, c'est la valeur par défaut)

2. Entrer dans le container

# ⚠️ Toujours sans sudo, le --root suffit
distrobox enter --root pince

Vous êtes maintenant dans le container. Le prompt change.

3. Installer les dépendances et PINCE (DANS le container)

# Deps système (gdb + libs natives Qt6 pour PyQt6 + outils pour install.sh)
sudo dnf install -y python3-pip python3-devel python3-virtualenv gdb gcc git \
  qt6-qtbase-gui curl tar

# Préparer /opt/PINCE avec la bonne ownership AVANT le clone
# (install.sh refuse de tourner en root, donc le dossier doit appartenir à l'user)
sudo mkdir -p /opt/PINCE
sudo chown -R $USER:$USER /opt/PINCE

# Clone SANS sudo
git clone https://github.com/korcankaraokcu/PINCE.git /opt/PINCE
cd /opt/PINCE

# Lancer le script d'install officiel SANS sudo
# Il s'occupe de tout : venv + pip install requirements + git submodule libmemscan
# + download Zig 0.16.0 + compile libmemscan + compile traductions Qt
./install.sh

À la fin, vous aurez :

/opt/PINCE/.venv/ → venv Python avec PyQt6, capstone, keystone-engine, etc.
/opt/PINCE/libpince/libmemscan/memscan.so → module C++ compilé
/opt/PINCE/i18n/qm/*.qm → fichiers de traduction compilés

Pourquoi /opt/PINCE et pas ~/PINCE : distrobox monte votre $HOME host dans le container, donc ~/PINCE polluerait le host. /opt est purement container-local. On utilise chown pour donner la propriété à l'user puisque install.sh refuse de tourner en root.

Pourquoi install.sh et pas un pip manuel : PINCE intègre libmemscan, un module C++ pour les scans mémoire performants. C'est un git submodule compilé avec Zig (pas gcc/make). Le script crée un venv Python, installe les requirements dedans, télécharge Zig 0.16.0 dans libmemscan/, build le module natif, et compile les traductions Qt. Sans cette étape : ModuleNotFoundError: No module named 'libpince.libmemscan'.

Pourquoi un venv et pas le Python système : install.sh isole PINCE dans .venv — propre, reproductible, pas de conflit avec d'autres outils Python du container. Conséquence : il faut lancer PINCE avec .venv/bin/python, pas avec python3 directement.

4. Validation — tester gdb AVANT de lancer PINCE

Le test qui ne ment pas : si gdb n'arrive pas à s'attacher, PINCE non plus.

Lancez votre jeu (Steam / Proton). Puis dans le container :

PID=$(pgrep -f SOTTR.exe)   # adapter au nom du process cible
echo "PID = $PID"
sudo gdb -p $PID

Sortie attendue :

Attaching to process 24729
[New LWP 24730]
...
(gdb)

Sortie qui veut dire que ça ne marche pas :

ptrace: Operation not permitted.
(gdb)

Si ça marche → detach puis quit pour libérer le process. Sinon, voir la section Dépannage.

5. Lancer PINCE

PINCE doit tourner avec le Python du venv créé par install.sh, et sudo reste nécessaire pour les privilèges ptrace.

Ne pas utiliser sh PINCE.sh : ce wrapper utilise pkexec pour l'élévation GUI via polkit/D-Bus, ce qui n'est pas dispo dans un container distrobox (erreur Error getting authority). On utilise sudo à la place.

Depuis l'intérieur du container

cd /opt/PINCE
sudo .venv/bin/python PINCE.py

Depuis le host en une seule commande

distrobox enter --root pince -- bash -c "cd /opt/PINCE && sudo .venv/bin/python PINCE.py"

6. Lanceur pratique (optionnel)

Option A — alias bash

Dans ~/.bashrc ou ~/.bash_aliases :

alias pince='distrobox enter --root pince -- bash -c "cd /opt/PINCE && sudo .venv/bin/python PINCE.py"'

Option B — fichier `.desktop`

Créer ~/.local/share/applications/pince.desktop :

[Desktop Entry]
Name=PINCE
Comment=Memory scanner / debugger (rootful distrobox)
Exec=distrobox enter --root pince -- bash -c "cd /opt/PINCE && sudo .venv/bin/python PINCE.py"
Terminal=true
Type=Application
Categories=Development;Debugger;

Puis :

chmod +x ~/.local/share/applications/pince.desktop
update-desktop-database ~/.local/share/applications

Icône (à exécuter dans le container, une fois) :

mkdir -p ~/.local/share/icons/
cp /opt/PINCE/media/logo/ozgurozbek/pince_appimage.png ~/.local/share/icons/pince.png

Le ~/.local/share/icons/ étant sur le host via le mount du $HOME, le fichier y apparaît immédiatement. Pointer le .desktop dessus avec un chemin absolu :

Icon=/home/sub/.local/share/icons/pince.png

Note Bazzite : sur une Fedora atomic, /home est un symlink vers /var/home. Le path /home/sub/... fonctionne donc partout, pas besoin d'utiliser /var/home/sub/....

Dépannage

`ptrace: Operation not permitted` persiste

Vérification	Commande	Attendu
Container bien rootful ?	`distrobox ls --root`	Doit lister `pince`
Cap effectivement présente ?	Dans le container : `sudo grep CapBnd /proc/self/status` puis `capsh --decode=<hex>`	Doit contenir `cap_sys_ptrace`
SELinux qui bloque ?	`getenforce` côté host	Essayer `sudo setenforce 0`
ptrace_scope OK ?	`cat /proc/sys/kernel/yama/ptrace_scope`	Doit être `0`
Bon PID ?	`pgrep -af <nom_process>`	Le jeu peut avoir plusieurs sous-processus

Erreur `No module named 'PyQt6'` au lancement

Vous lancez probablement avec python3 au lieu du Python du venv créé par install.sh. Bonne commande :

cd /opt/PINCE
sudo .venv/bin/python PINCE.py

Si le venv n'existe pas (ls .venv/bin/python échoue) → relancer ./install.sh (sans sudo).

Erreur `libGL.so.1: cannot open shared object file` au lancement

Les libs natives Qt6 manquent dans l'image fedora-toolbox minimale. PyQt6-pip embarque ses propres binaires Qt mais a besoin de libs système OpenGL/X11. Fix :

sudo dnf install -y qt6-qtbase-gui

Cette commande tire en cascade toutes les deps nécessaires (mesa, xcb-*, fontconfig, dbus, etc.). Variante manuelle si vous voulez le strict minimum :

sudo dnf install -y mesa-libGL libxkbcommon-x11 dbus-libs fontconfig \
  xcb-util-cursor xcb-util-keysyms xcb-util-image xcb-util-renderutil xcb-util-wm

Erreur `Error getting authority: Error initializing authority` quand vous lancez `sh PINCE.sh`

PINCE.sh utilise pkexec (élévation GUI via polkit/D-Bus), pas dispo dans un container distrobox. Ne pas l'utiliser. Lancer via :

sudo .venv/bin/python PINCE.py

Erreur `No module named 'libpince.libmemscan'` au lancement

libmemscan (scan mémoire C++ via Zig) n'a pas été compilé. install.sh n'a pas été lancé ou a échoué avant l'étape de build. Relancer (sans sudo) :

cd /opt/PINCE
./install.sh

En cas d'échec du download Zig (curl 404, etc.), vérifier la version Zig pinnée dans install.sh et adapter si la 0.16.0 n'est plus dispo.

Erreur `Permission denied: '/opt/PINCE/.venv'` durant install.sh

Le dossier /opt/PINCE appartient à root (clone fait avec sudo par erreur). install.sh refuse de tourner en root et ne peut pas écrire dans le dossier. Fix :

sudo chown -R $USER:$USER /opt/PINCE
cd /opt/PINCE
./install.sh

Erreur `please do not run this script as root`

install.sh doit tourner en user, pas en root. Relancer sans sudo. Si l'ownership de /opt/PINCE est mauvaise, voir le point précédent.

Erreur SELinux dans `dmesg` ou `journalctl`

sudo ausearch -m AVC -ts recent

Si des AVC liés à ptrace apparaissent, laisser SELinux en Permissive pour les sessions PINCE (sudo setenforce 0).

Notes annexes

Règle distrobox : --root et sudo sont mutuellement exclusifs. Pour les commandes distrobox (create, enter, stop, rm), ne jamais mettre sudo devant quand on utilise --root — distrobox demandera lui-même l'élévation. Le seul sudo légitime dans la chaîne est celui à l'intérieur du container devant python3 PINCE.py (PINCE vérifie qu'il tourne en root au démarrage).
gdb-gef n'existe pas dans les dépôts Fedora — c'est un script tiers, inutile pour PINCE qui embarque ses propres extensions GDB dans gdb_python_scripts/.
PyQt5 n'est plus packagé sur Fedora 44+ → PINCE moderne (≥ 2025) utilise PyQt6.
Module keyboard nécessite root pour accéder à /dev/input/* → OK puisque PINCE tourne déjà en sudo.
Configs PINCE stockées dans ~/.config/PINCE (host, via le mount distrobox du $HOME) → survivent à un distrobox rm.
Code PINCE dans /opt/PINCE (container-only) → disparaît si vous détruisez le container. À re-cloner lors d'une recréation.

Désinstaller / recommencer à zéro

distrobox stop pince --root --yes
distrobox rm pince --root --yes
# Si vous voulez aussi virer les configs PINCE :
rm -rf ~/.config/PINCE

TL;DR

Couche	Action
Host kernel	`ptrace_scope = 0` (persistant via `/etc/sysctl.d/`)
Container	distrobox rootful (`--root`) + `--cap-add=SYS_PTRACE` + `seccomp=unconfined`
Code & deps	Clone dans `/opt/PINCE` (chown user) puis `./install.sh` (sans sudo) gère tout : venv, pip, libmemscan C++ via Zig, traductions Qt
Lancement	`distrobox enter --root pince ...` (pas de sudo devant), puis `sudo .venv/bin/python PINCE.py` dans le container

→ La clé : pour qu'un container puisse ptrace un processus du host, il faut être dans le même user namespace que le host → distrobox rootful obligatoire.

brahimmachkouri/pince-installation-bazzite-from-scratch.md

Select an option

No results found

Select an option

No results found

Guide complet — Installer PINCE depuis zéro sur Bazzite

Pourquoi distrobox rootful ?

Architecture choisie

0. Vérifications host (Bazzite)

1. Créer le distrobox rootful (image Fedora vanilla)

2. Entrer dans le container

3. Installer les dépendances et PINCE (DANS le container)

4. Validation — tester gdb AVANT de lancer PINCE

5. Lancer PINCE

Depuis l'intérieur du container

Depuis le host en une seule commande

6. Lanceur pratique (optionnel)

Option A — alias bash

Option B — fichier `.desktop`

Dépannage

`ptrace: Operation not permitted` persiste

Erreur `No module named 'PyQt6'` au lancement

Erreur `libGL.so.1: cannot open shared object file` au lancement

Erreur `Error getting authority: Error initializing authority` quand vous lancez `sh PINCE.sh`

Erreur `No module named 'libpince.libmemscan'` au lancement

Erreur `Permission denied: '/opt/PINCE/.venv'` durant install.sh

Erreur `please do not run this script as root`

Erreur SELinux dans `dmesg` ou `journalctl`

Notes annexes

Désinstaller / recommencer à zéro

TL;DR

brahimmachkouri/pince-installation-bazzite-from-scratch.md

Guide complet — Installer PINCE depuis zéro sur Bazzite

Pourquoi distrobox rootful ?

Architecture choisie

0. Vérifications host (Bazzite)

1. Créer le distrobox rootful (image Fedora vanilla)

2. Entrer dans le container

3. Installer les dépendances et PINCE (DANS le container)

4. Validation — tester gdb AVANT de lancer PINCE

5. Lancer PINCE

Depuis l'intérieur du container

Depuis le host en une seule commande

6. Lanceur pratique (optionnel)

Option A — alias bash

Option B — fichier .desktop

Dépannage

ptrace: Operation not permitted persiste

Erreur No module named 'PyQt6' au lancement

Erreur libGL.so.1: cannot open shared object file au lancement

Erreur Error getting authority: Error initializing authority quand vous lancez sh PINCE.sh

Erreur No module named 'libpince.libmemscan' au lancement

Erreur Permission denied: '/opt/PINCE/.venv' durant install.sh

Erreur please do not run this script as root

Erreur SELinux dans dmesg ou journalctl

Notes annexes

Désinstaller / recommencer à zéro

TL;DR

Option B — fichier `.desktop`

`ptrace: Operation not permitted` persiste

Erreur `No module named 'PyQt6'` au lancement

Erreur `libGL.so.1: cannot open shared object file` au lancement

Erreur `Error getting authority: Error initializing authority` quand vous lancez `sh PINCE.sh`

Erreur `No module named 'libpince.libmemscan'` au lancement

Erreur `Permission denied: '/opt/PINCE/.venv'` durant install.sh

Erreur `please do not run this script as root`

Erreur SELinux dans `dmesg` ou `journalctl`