PVE-Backup-Report/docs/api-pbs.md

API Proxmox Backup Server

English version

Ce document decrit la collecte PBS utilisee par le rapport.

Objectif

La collecte PBS sert a completer le rapport PVE avec les politiques de retention configurees et les versions de sauvegarde visibles sur les serveurs Proxmox Backup Server renseignes.

L'application peut interroger un ou plusieurs serveurs PBS. Chaque serveur est collecte uniquement si son URL API, son token ID et son token secret sont fournis.

Cette etape ne prouve pas les synchronisations entre serveurs PBS. Elle collecte les prune jobs et les snapshots visibles sur chaque PBS configure.

Authentification

Le client PBS utilise un token API PBS.

Le header HTTP est :

Authorization: PBSAPIToken=TOKENID:TOKENSECRET

Exemple de configuration d'un serveur PBS :

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

Pour collecter plusieurs PBS, dupliquer ce bloc avec les prefixes PBS02_*, PBS03_*, PBS04_*, etc. Tous les blocs PBS<number>_* complets sont detectes automatiquement.

Le secret du token ne doit jamais etre journalise ni apparaitre dans le rapport.

Endpoint utilise

Donnee	Endpoint PBS
Prune jobs	/config/prune
Datastores PBS	/config/datastore
Statut d'un datastore	/admin/datastore/{datastore}/status
Statut garbage collector d'un datastore	/admin/datastore/{datastore}/gc
Namespaces d'un datastore	/admin/datastore/{datastore}/namespace
Snapshots d'un datastore/namespace	/admin/datastore/{datastore}/snapshots?ns={namespace}
Utilisateurs PBS	/access/users
Permissions effectives	/access/permissions?auth-id={auth-id}&path={path}

Le client ajoute automatiquement /api2/json a l'URL PBS si ce suffixe n'est pas deja present.

Donnees normalisees

Chaque prune job PBS est transforme en politique de retention avec les champs suivants :

• identifiant du job ;
• serveur PBS ;
• datastore ;
• namespace ;
• planification ;
• etat actif/inactif ;
• keep-last ;
• keep-hourly ;
• keep-daily ;
• keep-weekly ;
• keep-monthly ;
• keep-yearly ;
• max-depth ;
• commentaire.

Si le champ ns est absent, la namespace est consideree comme la racine /. Le rapport calcule le nombre attendu de versions d'une VM/CT depuis la politique de retention active qui correspond au meme serveur PBS, datastore et namespace que les snapshots. Ce nombre est la somme des valeurs keep-last, keep-hourly, keep-daily, keep-weekly, keep-monthly et keep-yearly renseignees. Le delta affiche nombre de snapshots visibles - nombre attendu.

Chaque snapshot PBS est agrege par datastore, namespace, type de sauvegarde et VMID afin de produire :

• nombre de versions de sauvegarde ;
• date de la plus ancienne sauvegarde ;
• date de la plus recente sauvegarde ;
• taille de la sauvegarde la plus recente lorsque PBS expose cette information.

Les snapshots restant visibles sur PBS alors que la VM/CT n'existe plus dans l'inventaire PVE sont conserves pour le tableau de retention et marques Non-active sur PVE. Les snapshots dont le namespace ne figure pas dans les namespaces declares sur PVE sont exclus de ces tableaux de retention.

Le statut de chaque datastore PBS configure est collecte afin d'afficher l'espace total, l'espace consomme et l'espace libre dans le rapport.

Utilisateurs PBS declares cote PVE

La commande de diagnostic --dump-pbs-users collecte les stockages PBS declares dans PVE via /storage, puis rapproche leur champ username des utilisateurs visibles sur chaque PBS configure via /access/users.

Pour chaque stockage PBS PVE ayant un username, le diagnostic interroge les permissions effectives de cet auth-id sur le chemin PBS cible :

/datastore/{datastore}
/datastore/{datastore}/{namespace}

Le second format est utilise lorsqu'une namespace non racine est declaree cote PVE.

Les informations collectees alimentent le tableau Utilisateurs PBS - Audit des accès du rapport et la commande de diagnostic. Elles servent a verifier quel compte PBS est utilise par PVE, si le compte est actif lorsque PBS expose cette information, et quels privileges effectifs sont disponibles sur le datastore/namespace cible.

Si le username PVE est un token PBS de type user@realm!token, le rapprochement avec /access/users se fait sur le user parent user@realm; les permissions sont demandees avec l'auth-id complet.

Les types PBS vm et ct sont rapproches des types PVE qemu et lxc.

La collecte des snapshots interroge les datastores exposes par chaque PBS configure. Pour chaque datastore, elle ajoute aussi l'ensemble des namespaces declarees dans les stockages PBS de PVE, meme si le PBS concerne ne recoit pas directement les backups des VM/CT depuis PVE. Cela permet de retrouver des sauvegardes synchronisees sur un PBS secondaire, par exemple dans les namespaces serveurs-internes ou Serveurs-PVELAB.

Les namespaces retournees par l'API du PBS cible restent collectees egalement. Les snapshots sont ensuite rapproches des VM/CT par type et VMID.

Comme ces serveurs additionnels peuvent contenir des sauvegardes directes et synchronisees, certains appels /snapshots peuvent etre plus longs. Augmenter le timeout du bloc PBS concerne si le timeout par defaut est insuffisant.

Gestion des erreurs

Si aucun PBS n'est configure, la collecte PBS est ignoree.

Si un PBS configure est indisponible, le rapport continue et une anomalie pbs_retention est ajoutee pour le serveur concerne.

Si un PBS configure est indisponible pour la collecte des snapshots, le rapport continue et une anomalie pbs_snapshots est ajoutee pour le serveur concerne.

Lorsqu'une namespace declaree dans PVE est testee sur un datastore PBS ou elle n'existe pas, PBS peut repondre HTTP 400 - Bad Request sur l'endpoint /snapshots. Pour une namespace non racine, cette reponse est interpretee comme une absence de namespace sur ce datastore et n'est pas remontee comme anomalie. Les autres erreurs, y compris un 400 sur la racine /, restent visibles.

Si la reponse /config/prune n'est pas une liste, le rapport continue et ajoute une anomalie.

Si /config/prune repond avec une liste vide alors qu'un PBS est configure, une anomalie warning est ajoutee afin de verifier soit l'absence reelle de prune jobs, soit les droits effectifs du token PBS.

Limites

La collecte ne verifie pas encore :

• les synchronisations entre serveurs PBS ;
• l'etat d'execution des prune jobs ;
• le resultat effectif d'un prune sur les snapshots.

Ces points pourront etre ajoutes dans une etape dediee.