PVE-Backup-Report/docs/fr/exploitation.md

Exploitation

English version

Execution avec Docker

Docker est le mode d'exploitation recommande. Le conteneur execute une commande ponctuelle, ecrit les logs sur stdout/stderr, genere le rapport PDF puis se termine.

Preparation

cp .env.example .env
mkdir -p reports

Dans .env, adapter les acces PVE/PBS et conserver en execution Docker :

REPORT_OUTPUT_DIR=/reports

Le service Docker Compose monte ./reports vers /reports, ce qui rend les PDF disponibles sur l'hote dans le repertoire reports/.

Construction de l'image

docker compose build

L'image installe les dependances Python et les bibliotheques systeme necessaires a WeasyPrint.

Verification de la configuration

docker compose run --rm pve-backup-report --check-config

Test de connexion API

docker compose run --rm pve-backup-report --check-api

Cette commande teste /nodes, /storage, /cluster et l'endpoint configure dans PVE_BACKUP_JOBS_ENDPOINT.

Si /cluster/backup retourne HTTP 403 - Permission check failed (/, Sys.Audit), le token fonctionne mais il lui manque le privilege Sys.Audit sur /.

Generation du rapport PDF

docker compose run --rm pve-backup-report --generate-pdf

Le rapport est cree dans REPORT_OUTPUT_DIR. Le nom contient un horodatage et n'ecrase pas les rapports precedents.

Exemple de fichier genere sur l'hote :

reports/rapport-sauvegardes-pve-2026-05-09-020000.pdf

Commandes de diagnostic Docker

Inventaire :

docker compose run --rm pve-backup-report --dump-inventory

Couverture :

docker compose run --rm pve-backup-report --dump-coverage

Donnees de rapport au format JSON :

docker compose run --rm pve-backup-report --dump-report-data

Cette sortie est une previsualisation technique du modele de rapport. Les champs bruts sensibles sont filtres, mais le JSON contient des informations d'exploitation comme les noms de VM/CT, VMID, notes PVE, serveurs, datastores, namespaces, utilisateurs PBS et metadonnees de sauvegarde. Il doit donc etre traite comme une donnee interne et ne pas etre partage hors du perimetre d'exploitation/audit autorise.

Espaces des datastores PBS :

docker compose run --rm pve-backup-report --dump-pbs-storage-usages

Utilisateurs PBS utilises par les stockages PVE :

docker compose run --rm pve-backup-report --dump-pbs-users

Diagnostic d'une derniere sauvegarde manquante :

docker compose run --rm pve-backup-report --debug-last-backup-vmid <VMID>

La commande docker compose run --rm pve-backup-report sans argument ne genere pas de PDF. Pour produire le rapport, utiliser explicitement --generate-pdf.

Execution directe en ligne de commande

Ce mode est utile pour le developpement ou le diagnostic hors conteneur.

Installation locale :

python3 -m venv .venv
. .venv/bin/activate
python -m ensurepip --upgrade
pip install -r requirements.txt
pip install -e .

La generation PDF utilise WeasyPrint. Hors Docker, l'hote doit fournir les bibliotheques systeme requises par WeasyPrint. Avec WeasyPrint 62.x, conserver la contrainte pydyf>=0.10,<0.11 pour eviter les erreurs de generation PDF liees a l'API interne de pydyf.

Commandes installees :

pve-backup-report --check-config
pve-backup-report --check-api
pve-backup-report --dump-inventory
pve-backup-report --dump-coverage
pve-backup-report --dump-report-data
pve-backup-report --dump-pbs-storage-usages
pve-backup-report --dump-pbs-users
pve-backup-report --generate-pdf

Sans installation editable :

PYTHONPATH=src python3 -m pve_backup_report --check-config
PYTHONPATH=src python3 -m pve_backup_report --check-api
PYTHONPATH=src python3 -m pve_backup_report --dump-inventory
PYTHONPATH=src python3 -m pve_backup_report --dump-coverage
PYTHONPATH=src python3 -m pve_backup_report --dump-report-data
PYTHONPATH=src python3 -m pve_backup_report --dump-pbs-storage-usages
PYTHONPATH=src python3 -m pve_backup_report --dump-pbs-users
PYTHONPATH=src python3 -m pve_backup_report --generate-pdf

En execution locale directe, REPORT_OUTPUT_DIR peut rester a reports/ ou pointer vers un autre repertoire accessible par l'utilisateur courant.

Le meme fichier .env peut etre utilise en Docker et en execution locale. La valeur Docker REPORT_OUTPUT_DIR=/reports reste valide dans le conteneur avec le montage ./reports:/reports. Hors Docker, si /reports n'est pas accessible, l'application utilise automatiquement le repertoire local reports/ et l'indique dans les logs.

Il reste possible de forcer explicitement un chemin local :

REPORT_OUTPUT_DIR=reports

Politique de retention PBS

Pour alimenter le tableau Politique de retention et les tableaux Retention des sauvegardes VM/CT, renseigner les variables API du PBS concerne :

PBS01_NAME=nom-affiche
PBS01_API_URL=https://backup.example.invalid:8007
PBS01_API_TOKEN_ID=
PBS01_API_TOKEN_SECRET=
PBS01_VERIFY_TLS=true

Pour plusieurs PBS, dupliquer ce bloc avec les prefixes PBS02_*, PBS03_*, PBS04_*, etc. Le rapport cree les sections de retention pour chaque PBS configure.

La collecte lit les prune jobs des PBS configures via /config/prune. Si un PBS est indisponible, si son token n'a pas les droits suffisants, ou si aucune politique n'est retournee, le rapport continue et ajoute une anomalie pbs_retention.

La collecte lit aussi les snapshots des datastores de chaque PBS configure. Les namespaces declarees dans les stockages PBS de PVE sont interrogees sur chaque PBS, y compris sur un PBS secondaire qui ne recoit pas directement les backups depuis PVE mais contient des sauvegardes synchronisees. Ces donnees alimentent les tableaux Retention des sauvegardes VM/CT <PBS>, y compris les VM/CT encore visibles sur PBS mais absentes de l'inventaire PVE. Elles sont marquees Non-active sur PVE dans le rapport. Si une namespace PVE n'existe pas sur un datastore PBS teste, l'eventuel HTTP 400 - Bad Request retourne par PBS est ignore pour cette namespace non racine afin d'eviter une anomalie attendue.

Les tableaux de retention sont separes par namespace et affichent aussi le datastore, car une meme namespace peut exister sur plusieurs datastores d'un meme PBS. Ils affichent aussi le nombre attendu de versions et un delta par rapport au nombre de snapshots visibles. Ce calcul depend d'une politique de retention active correspondant au meme serveur PBS, datastore et namespace.

Le rapport collecte aussi le statut des datastores de chaque PBS configure afin d'afficher l'espace total, l'espace consomme et l'espace libre. Le statut du garbage collector de chaque datastore PBS est aussi collecte. Si le garbage collector est en cours, un avertissement est affiche uniquement sous les tableaux de retention du PBS/datastore concerne.

Planification quotidienne

La planification recommandee sur Debian 13 peut etre faite avec systemd timer ou cron. Le conteneur et la CLI sont concus pour une execution ponctuelle : la commande genere le rapport puis se termine.

Cron avec Docker Compose

Exemple de crontab cote hote pour lancer le rapport tous les jours a 02:00 :

SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

0 2 * * * cd /srv/pve-backup-report && /usr/bin/flock -n /tmp/pve-backup-report.lock /usr/bin/docker compose run --rm pve-backup-report --generate-pdf >> /var/log/pve-backup-report.log 2>&1

Points importants :

• adapter /srv/pve-backup-report au chemin reel du depot ;
• conserver REPORT_OUTPUT_DIR=/reports dans .env pour Docker ;
• verifier que le repertoire hote reports/ existe et est accessible ;
• utiliser flock pour eviter deux generations simultanees si une execution dure plus longtemps que prevu ;
• rediriger stdout/stderr vers un fichier de log ou vers le systeme de supervision de l'hote.

Pour tester exactement la commande planifiee :

cd /srv/pve-backup-report
/usr/bin/flock -n /tmp/pve-backup-report.lock /usr/bin/docker compose run --rm pve-backup-report --generate-pdf

Cron en appel direct du script

Exemple avec l'environnement virtuel du projet :

SHELL=/bin/sh
PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

0 2 * * * cd /srv/pve-backup-report && /usr/bin/flock -n /tmp/pve-backup-report.lock /srv/pve-backup-report/.venv/bin/pve-backup-report --generate-pdf >> /var/log/pve-backup-report.log 2>&1

Dans ce mode :

• le cd vers le depot permet de charger le fichier .env par defaut ;
• REPORT_OUTPUT_DIR peut rester a /reports, a reports/, ou pointer vers un chemin absolu accessible par l'utilisateur cron ;
• l'utilisateur cron doit avoir les droits de lecture sur .env et d'ecriture dans le repertoire des rapports ;
• les bibliotheques systeme requises par WeasyPrint doivent etre installees sur l'hote.

Pour tester exactement la commande planifiee :

cd /srv/pve-backup-report
/usr/bin/flock -n /tmp/pve-backup-report.lock /srv/pve-backup-report/.venv/bin/pve-backup-report --generate-pdf

Adapter l'horaire pour eviter les periodes de forte charge ou les fenetres de maintenance.

Verification quotidienne

Apres execution, verifier :

• la presence d'un nouveau PDF ;
• le code retour de la commande ;
• les logs du conteneur ;
• la section des anomalies ;
• la liste des VM/CT sans sauvegarde.

Conservation des preuves

Pour un usage audit, conserver les rapports dans un emplacement sauvegarde.

Recommandations :

• stockage persistant hors conteneur ;
• droits d'ecriture limites ;
• lecture autorisee aux personnes habilitees ;
• retention alignee avec la politique interne ;
• horloge systeme synchronisee par NTP.

Codes de sortie recommandes

Code	Signification
0	Rapport genere sans erreur bloquante.
1	Erreur de configuration.
2	Authentification PVE impossible.
3	API PVE indisponible.
4	Erreur d'ecriture du PDF.
5	Erreur inattendue.

Une execution avec anomalies non bloquantes peut retourner 0 si le rapport est genere et que les anomalies sont visibles dans le PDF.

Supervision

Surveiller au minimum :

• absence de rapport du jour ;
• echec de commande ;
• augmentation du nombre de VM/CT non sauvegardes ;
• apparition d'anomalies recurrentes ;
• expiration ou revocation du token PVE.

Rotation des logs

Les logs doivent rester sur stdout/stderr pour s'integrer a Docker.

La rotation est geree par Docker ou par la plateforme d'exploitation.

Restauration et audit

Ce rapport prouve la configuration observee au moment de son execution.

Il ne prouve pas a lui seul qu'une restauration est possible.

Pour une preuve plus forte, completer ce projet avec :

• controle des dernieres executions de jobs ;
• verification des snapshots presents dans PBS ;
• tests periodiques de restauration ;
• signature ou stockage immuable des rapports.