302 lines
11 KiB
Markdown
302 lines
11 KiB
Markdown
# Exploitation
|
|
|
|
[English version](en/exploitation.md)
|
|
|
|
## 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
|
|
|
|
```sh
|
|
cp .env.example .env
|
|
mkdir -p reports
|
|
```
|
|
|
|
Dans `.env`, adapter les acces PVE/PBS et conserver en execution Docker :
|
|
|
|
```env
|
|
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
|
|
|
|
```sh
|
|
docker compose build
|
|
```
|
|
|
|
L'image installe les dependances Python et les bibliotheques systeme necessaires a WeasyPrint.
|
|
|
|
### Verification de la configuration
|
|
|
|
```sh
|
|
docker compose run --rm pve-backup-report --check-config
|
|
```
|
|
|
|
### Test de connexion API
|
|
|
|
```sh
|
|
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
|
|
|
|
```sh
|
|
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 :
|
|
|
|
```text
|
|
reports/rapport-sauvegardes-pve-2026-05-09-020000.pdf
|
|
```
|
|
|
|
### Commandes de diagnostic Docker
|
|
|
|
Inventaire :
|
|
|
|
```sh
|
|
docker compose run --rm pve-backup-report --dump-inventory
|
|
```
|
|
|
|
Couverture :
|
|
|
|
```sh
|
|
docker compose run --rm pve-backup-report --dump-coverage
|
|
```
|
|
|
|
Donnees de rapport au format JSON :
|
|
|
|
```sh
|
|
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 :
|
|
|
|
```sh
|
|
docker compose run --rm pve-backup-report --dump-pbs-storage-usages
|
|
```
|
|
|
|
Utilisateurs PBS utilises par les stockages PVE :
|
|
|
|
```sh
|
|
docker compose run --rm pve-backup-report --dump-pbs-users
|
|
```
|
|
|
|
Diagnostic d'une derniere sauvegarde manquante :
|
|
|
|
```sh
|
|
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 :
|
|
|
|
```sh
|
|
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 :
|
|
|
|
```sh
|
|
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 :
|
|
|
|
```sh
|
|
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 :
|
|
|
|
```env
|
|
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 :
|
|
|
|
```env
|
|
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 :
|
|
|
|
```cron
|
|
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 :
|
|
|
|
```sh
|
|
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 :
|
|
|
|
```cron
|
|
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 :
|
|
|
|
```sh
|
|
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.
|