134 lines
6.5 KiB
Markdown
134 lines
6.5 KiB
Markdown
# API Proxmox Backup Server
|
|
|
|
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 :
|
|
|
|
```text
|
|
Authorization: PBSAPIToken=TOKENID:TOKENSECRET
|
|
```
|
|
|
|
Exemple de configuration d'un serveur PBS :
|
|
|
|
```env
|
|
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 :
|
|
|
|
```text
|
|
/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.
|