PVE-Backup-Report/docs/configuration.md

Configuration

Variables d'environnement

Configuration minimale recommandee :

PVE_API_URL=https://pve.example.invalid:8006
PVE_API_TOKEN_ID=
PVE_API_TOKEN_SECRET=
REPORT_OUTPUT_DIR=/reports
REPORT_TIMEZONE=Europe/Paris

Un fichier .env.example est fourni comme modele. Le fichier .env reel ne doit pas etre commite.

Configuration optionnelle :

PVE_VERIFY_TLS=false
PVE_CA_BUNDLE=
PVE_TIMEOUT_SECONDS=30
PVE_BACKUP_JOBS_ENDPOINT=/cluster/backup
PVE_TASK_HISTORY_LIMIT=500
PBS_HOSTNAMES=backup.example.invalid=nom-affiche
LOG_LEVEL=INFO
REPORT_FILENAME_PREFIX=rapport-sauvegardes-pve

Description des variables

Variable	Obligatoire	Description
PVE_API_URL	Oui	URL de l'API Proxmox VE, avec schema et port.
PVE_API_TOKEN_ID	Oui	Identifiant complet du token API PVE.
PVE_API_TOKEN_SECRET	Oui	Secret du token API PVE.
REPORT_OUTPUT_DIR	Non	Repertoire de sortie des rapports PDF. Defaut applicatif : reports/. En Docker Compose, utiliser /reports.
REPORT_TIMEZONE	Non	Fuseau horaire utilise pour les dates du rapport. Defaut : Europe/Paris.
PVE_VERIFY_TLS	Non	Active la verification TLS. Defaut : true.
PVE_CA_BUNDLE	Non	Chemin vers une CA interne montee dans le conteneur.
PVE_TIMEOUT_SECONDS	Non	Timeout HTTP. Defaut : 30.
PVE_BACKUP_JOBS_ENDPOINT	Non	Endpoint qui liste les jobs de sauvegarde planifies. Defaut : /cluster/backup. A conserver sauf cas particulier.
PVE_TASK_HISTORY_LIMIT	Non	Nombre de taches PVE recentes inspectees pour trouver la derniere sauvegarde. Defaut : 500.
PVE_TASK_LOG_LIMIT	Non	Nombre de lignes recuperees par log de tache vzdump. Defaut : 5000.
PBS_HOSTNAMES	Non	Mapping manuel IP/DNS PBS vers nom d'hote affiche dans le rapport.
PBS<number>_NAME	Non	Nom affiche du serveur PBS configure, par exemple PBS01_NAME. Defaut : le prefixe PBS<number>.
PBS<number>_API_URL	Non	URL API du serveur PBS, par exemple https://backup.example.invalid:8007. Active la collecte si le token est aussi renseigne.
PBS<number>_API_TOKEN_ID	Non	Identifiant complet du token API PBS.
PBS<number>_API_TOKEN_SECRET	Non	Secret du token API PBS.
PBS<number>_VERIFY_TLS	Non	Active la verification TLS pour ce serveur PBS. Defaut : valeur de PVE_VERIFY_TLS.
PBS<number>_CA_BUNDLE	Non	Chemin vers une CA interne pour ce serveur PBS.
PBS<number>_TIMEOUT_SECONDS	Non	Timeout HTTP pour ce serveur PBS. Defaut : valeur de PVE_TIMEOUT_SECONDS ou 30.
LOG_LEVEL	Non	Niveau de log. Defaut : INFO.
REPORT_FILENAME_PREFIX	Non	Prefixe du fichier PDF.

Exemple Docker Compose

services:
  pve-backup-report:
    build: .
    env_file:
      - .env
    volumes:
      - ./reports:/reports
    restart: "no"

Avec ce montage, la configuration Docker doit contenir :

REPORT_OUTPUT_DIR=/reports

Les rapports sont alors ecrits dans ./reports/ sur l'hote.

Mapping des noms PBS

Le champ PBS_HOSTNAMES permet d'afficher le nom d'hote entre parentheses dans la colonne Serveur PBS.

Format :

PBS_HOSTNAMES=backup.example.invalid=nom-affiche

Rendu dans le rapport :

backup.example.invalid (nom-affiche)

Collecte PBS

La collecte PBS est optionnelle. Pour chaque serveur PBS, elle est active uniquement si les trois variables API URL, token ID et token secret sont renseignees.

Un bloc PBS suit le motif PBS<number>_*. L'ordre de collecte et d'affichage suit l'ordre numerique des prefixes : PBS01, PBS02, PBS10, etc.

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

Pour ajouter d'autres serveurs PBS, dupliquer le bloc et incrementer le numero du prefixe :

PBS02_NAME=nom-affiche-secondaire
PBS02_API_URL=https://backup-secondary.example.invalid:8007
PBS02_API_TOKEN_ID=
PBS02_API_TOKEN_SECRET=

PBS10_NAME=nom-affiche-dixieme
PBS10_API_URL=https://backup-extra.example.invalid:8007
PBS10_API_TOKEN_ID=
PBS10_API_TOKEN_SECRET=

Le token PBS est transmis avec le schema d'authentification PBSAPIToken sous la forme TOKENID:TOKENSECRET.

La collecte d'un PBS est active uniquement lorsque l'URL, le token ID et le token secret sont tous renseignes. Une URL seule ne bloque pas le demarrage, mais aucune collecte n'est lancee pour ce PBS.

Le service Docker lance la commande pve-backup-report. Pour produire un rapport, passer explicitement l'argument --generate-pdf.

Pour tester la connexion API :

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

Pour generer le PDF :

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

Permissions du token PVE

Le token doit etre limite a la lecture.

Permissions attendues selon l'implementation :

• lecture de la configuration du cluster ;
• lecture des stockages ;
• lecture des ressources VM/CT ;
• lecture des jobs de sauvegarde.

Pour le test de l'endpoint des jobs de sauvegarde, PVE peut exiger le privilege Sys.Audit sur le chemin /.

Si --check-api retourne :

<endpoint>: HTTP 403 - Permission check failed (/, Sys.Audit)

ajouter ce privilege au role du token utilise, ou utiliser un role de lecture existant qui le contient.

Dans l'etat observe du projet, /cluster/backup existe bien et l'erreur attendue en cas de droit insuffisant est un 403, pas un 404.

Diagnostic des droits effectifs du token

Un token PVE peut etre en mode privileges separes. Dans ce mode, les droits effectifs du token sont l'intersection des droits de l'utilisateur et des ACL propres au token.

Verifier d'abord le token :

pveum user token permissions <user@realm> <tokenid> --path /

Exemple :

pveum user token permissions backup-report@pve report --path /

Verifier ensuite les ACL :

pveum acl list

Pour ajouter explicitement PVEAuditor au token sur / :

pveum acl modify / --tokens 'backup-report@pve!report' --roles PVEAuditor --propagate 1

Si le token est en privileges separes, l'utilisateur parent doit aussi avoir un droit compatible :

pveum acl modify / --users backup-report@pve --roles PVEAuditor --propagate 1

Autre option, moins restrictive : creer ou modifier le token en privileges complets (privsep=0). Dans ce cas, le token reprend les droits de son utilisateur parent. Cette option est moins fine et doit etre choisie volontairement.

Eviter les privileges d'administration globaux.

TLS

La verification TLS peut etre desactivee explicitement pour les connexions locales :

PVE_VERIFY_TLS=false
PVE_CA_BUNDLE=

Lorsque PVE_VERIFY_TLS=false, PVE_CA_BUNDLE est ignore meme s'il est renseigne.

Quand cette option est utilisee explicitement, l'application journalise un avertissement unique et masque les avertissements repetes de urllib3 pour conserver des logs lisibles.

Si la CA interne n'est pas reconnue par le conteneur, preferer un volume monte et renseigner PVE_CA_BUNDLE.

Exemple :

volumes:
  - ./reports:/reports
  - /etc/ssl/local/pve-ca.pem:/etc/ssl/local/pve-ca.pem:ro

Puis :

PVE_CA_BUNDLE=/etc/ssl/local/pve-ca.pem

Repertoire de sortie

Le repertoire de sortie doit etre persistant.

Dans Docker, monter un volume hote :

volumes:
  - /srv/pve-backup-report/reports:/reports

Et configurer :

REPORT_OUTPUT_DIR=/reports

Le conteneur doit avoir le droit d'ecrire dans ce repertoire.

Les rapports ne doivent pas etre produits dans un chemin ephemere si leur conservation est requise pour l'audit.