Résoudre l’erreur « Authentication Failed » de Proxmox PBS : jetons, autorisations et empreintes

Playbook de diagnostic rapide

Quand l’authentification PBS casse, vous voulez le chemin le plus court vers la vérité. Ne commencez pas par tout faire tourner.
Commencez par décider s’il s’agit (a) du mauvais secret, (b) des mauvaises permissions, ou (c) de la mauvaise identité serveur (empreinte/certificat).
Tout le reste est de la garniture.

Première étape : identifier où l’échec se produit (côté PVE vs côté PBS)

• Si PVE ne peut pas atteindre PBS du tout : c’est le réseau, le DNS, le firewall, ou le service API PBS.
• Si PVE atteint PBS mais reçoit 401/403 : c’est le jeton/utilisateur/realm/ACL.
• Si PVE se plaint de l’empreinte/certificat : c’est une discordance d’identité TLS.

Deuxième étape : classer le comportement HTTP-ish

• 401 Unauthorized : identifiants/jeton non acceptés (mauvais jeton, mauvais utilisateur, mauvais realm, jeton expiré/désactivé).
• 403 Forbidden : identité acceptée, permissions refusées (ACL manquante, mauvais chemin, privilège incorrect).
• Erreur de handshake/fingerprint TLS : vous parlez au mauvais serveur ou le serveur a changé d’identité.

Troisième étape : choisir une action sûre

• Pour 401 : validez que le jeton est envoyé, qu’il appartient à l’utilisateur attendu et qu’il n’est pas restreint d’une façon oubliée.
• Pour 403 : mappez les privilèges requis au chemin PBS exact (datastore, namespace, groupe de sauvegarde).
• Pour les erreurs d’empreinte : vérifiez le certificat du serveur sur PBS, puis mettez à jour l’empreinte sur PVE. Ne « cliquez pas simplement accepter » sur un LAN de production sans avoir vérifié que vous n’êtes pas redirigé.

Une citation à garder sur votre mur :
Idée paraphrasée (Werner Vogels) : vous concevez des systèmes en supposant que des pannes arrivent, puis vous faites en sorte qu’ils récupèrent rapidement et en sécurité.

Modèle mental : qui s’authentifie auprès de quoi

Proxmox VE (PVE) ne « se connecte » pas à PBS comme un humain avec un navigateur. Il utilise l’API HTTP de PBS.
Cet appel API inclut une identité d’authentification (utilisateur ou jeton), et PBS évalue cette identité par rapport à ses ACL.
Séparément, PVE épingle une empreinte TLS pour que « pbs01 » soit effectivement votre PBS et non ce qui a répondu à cette IP aujourd’hui.

Donc « authentication failed » peut signifier que n’importe laquelle de ces couches a cassé :

1. Nom et atteignabilité : DNS et routage vers l’hôte PBS et le port.
2. Identité TLS : discordance d’empreinte de certificat ou échec de confiance.
3. Authentification : utilisateur/mot de passe, ou format d’en-tête de jeton, realm, état du jeton.
4. Autorisation : ACL PBS et privilèges pour le datastore, le namespace, les opérations de maintenance.
5. Incompatibilité de capacités : PVE attend une fonctionnalité (namespace, vérification de propriété, chiffrement) que la config PBS interdit ou ne fournit pas.

La bonne nouvelle : PBS et PVE sont bruyants dans les logs une fois que vous regardez au bon endroit. La mauvaise nouvelle : la bulle d’erreur GUI est inutile.
Considérez cela comme une invitation à arrêter de cliquer et à commencer à lire les logs comme un adulte.

Faits et contexte intéressants (pourquoi c’est délicat)

• Fait 1 : PBS utilise un modèle ACL basé sur les chemins. Les permissions peuvent être accordées à « / » ou à un sous-arbre spécifique au datastore, et l’héritage compte.
• Fait 2 : PVE épingle l’empreinte du certificat serveur PBS pour la définition du stockage. C’est un choix anti-MITM délibéré ; ce n’est pas juste être pointilleux.
• Fait 3 : Les jetons API dans l’écosystème Proxmox sont des identités séparées avec leurs propres privilèges et restrictions optionnelles. Ce ne sont pas de simples « mots de passe sans MFA ».
• Fait 4 : La distinction 401 vs 403 a une valeur opérationnelle énorme. 401 signifie « qui êtes-vous ? » et 403 signifie « je sais qui vous êtes et non ».
• Fait 5 : Quand vous restaurez des sauvegardes, PBS peut appliquer les vérifications de propriété et les contrôles de permissions différemment que pour les sauvegardes. Vous pouvez être autorisé à écrire des sauvegardes mais pas à les lire/restaurer.
• Fait 6 : L’API PBS écoute par défaut sur le port 8007. Les gens pointent encore par erreur PVE vers 8006 par habitude, parce que Proxmox vous habitue à 8006 comme « le port Proxmox ».
• Fait 7 : Les changements d’empreinte concordent souvent avec une réinstallation, un remplacement d’hôte, une régénération de certificat, ou « quelqu’un a nettoyé /etc/proxmox-backup » sans comprendre les conséquences.
• Fait 8 : Le support des namespaces dans PBS a introduit un contrôle plus fin, et aussi plus de manières de refuser l’accès par erreur (un cadeau pour la conformité, une plaisanterie pour les opérations).
• Fait 9 : La vérification des sauvegardes, le pruning et le garbage collection sont des opérations privilégiées. Un jeton qui peut lancer des sauvegardes peut quand même échouer sur les tâches de maintenance ensuite.

Ce que « authentication failed » signifie réellement

1) Mauvais realm ou mauvais format d’identité

Les identités Proxmox sont user@realm. Si vous avez créé backup@pbs et puis configuré backup@pam,
vous obtiendrez une erreur qui ressemble à une faute de frappe de mot de passe. Ce n’en est pas une.

2) Le jeton existe, mais vous avez utilisé le mauvais ID ou secret

Les jetons ont deux parties : l’identifiant du jeton (comme un suffixe d’utilisateur) et le secret du jeton (la chaîne affichée une seule fois).
Il est facile de coller le mauvais dans un champ mot de passe et de jurer que PBS est cassé.

3) Le jeton authentifie, l’ACL refuse (403), la GUI masque la nuance

Le problème le plus courant « ça marche à un endroit mais pas à un autre » : le jeton peut lister les datastores, mais ne peut pas écrire de snapshots,
ou peut écrire mais pas prune, ou peut sauvegarder des VMs mais pas des containers (type de contenu différent côté PVE, appels API différents).

4) Discordance d’empreinte après reconstruction ou réaffectation d’IP

Si le certificat du serveur PBS a changé, PVE refusera la connexion à moins que vous ne mettiez à jour l’empreinte épinglée.
C’est le comportement correct. Traitez les discordances d’empreinte comme les changements de clé SSH : vérifiez d’abord, puis mettez à jour.

5) Dérive horaire provoquant des bizarreries de ticket/jeton

PBS et PVE sont sensibles au temps pour les sessions et validations. Si un hôte a dérivé parce que NTP est tombé en panne en silence,
vous pouvez obtenir des échecs qui disparaissent après un redémarrage (ce qui n’est pas une solution ; c’est un coup de dés).

Blague #1 : Les sauvegardes sont comme des parachutes — si vous en avez besoin et qu’il ne s’ouvre pas, vous n’êtes pas en train « d’apprendre », vous tombez.

Tâches pratiques (commandes, sens des sorties, décisions)

Voici les tâches que j’exécute réellement quand l’auth PBS casse. Chacune inclut ce que la sortie implique et quelle décision prendre ensuite.
Exécutez les commandes sur l’hôte approprié (PVE ou PBS). N’improvisez pas ; suivez les indices.

Task 1: Confirmer que vous atteignez le port API PBS (PVE)

cr0x@pve01:~$ nc -vz pbs01 8007
Connection to pbs01 8007 port [tcp/*] succeeded!

Signification : Le chemin réseau et le port sont accessibles.
Décision : Montez dans la pile vers TLS et auth. Si ça échoue, corrigez DNS/routage/firewall/service avant de toucher aux jetons.

Task 2: Vérifier la santé du service API PBS (PBS)

cr0x@pbs01:~$ systemctl status proxmox-backup-proxy
● proxmox-backup-proxy.service - Proxmox Backup Server Proxy
     Loaded: loaded (/lib/systemd/system/proxmox-backup-proxy.service; enabled)
     Active: active (running) since Fri 2025-12-26 00:11:04 UTC; 2h 9min ago

Signification : Le proxy fonctionne ; PBS devrait accepter les connexions API.
Décision : S’il est arrêté, redémarrez et vérifiez les logs avant d’accuser l’authentification.

Task 3: Suivre les logs du proxy PBS pendant une tentative échouée (PBS)

cr0x@pbs01:~$ journalctl -u proxmox-backup-proxy -f
Dec 26 02:13:21 pbs01 proxmox-backup-proxy[1872]: authentication failure; rhost=10.10.20.11 user=backup@pbs msg=invalid credentials
Dec 26 02:13:21 pbs01 proxmox-backup-proxy[1872]: failed login attempt: backup@pbs from 10.10.20.11

Signification : PBS a reçu la requête et a rejeté les identifiants (probablement 401).
Décision : Concentrez-vous sur le format d’identité, le realm, le secret du jeton, et si PVE utilise un jeton ou un mot de passe.

Task 4: Vérifier « permission denied » vs « invalid credentials » (PBS)

cr0x@pbs01:~$ journalctl -u proxmox-backup-proxy --since "30 minutes ago" | tail -n 20
Dec 26 02:18:09 pbs01 proxmox-backup-proxy[1872]: user 'backup@pbs' failed to access /datastore/vmstore: permission check failed
Dec 26 02:18:09 pbs01 proxmox-backup-proxy[1872]: api request failed: 403 Forbidden

Signification : L’identité est valide ; l’autorisation a échoué (403).
Décision : Corrigez les ACL sur le chemin datastore/namespace ; ne faites pas tourner les jetons.

Task 5: Vérifier la synchronisation NTP/heure des deux côtés (PVE et PBS)

cr0x@pve01:~$ timedatectl
               Local time: Fri 2025-12-26 02:20:31 UTC
           Universal time: Fri 2025-12-26 02:20:31 UTC
                 RTC time: Fri 2025-12-26 02:20:31
                Time zone: Etc/UTC (UTC, +0000)
System clock synchronized: yes
              NTP service: active

Signification : L’heure est correcte ici.
Décision : Si System clock synchronized: no sur l’un des hôtes, corrigez NTP d’abord. La dérive horaire crée de faux problèmes « auth ».

Task 6: Confirmer l’empreinte épinglée par PVE (PVE)

cr0x@pve01:~$ grep -R "fingerprint" /etc/pve/storage.cfg
pbs: pbs-vmstore
        server pbs01
        datastore vmstore
        username backup@pbs
        fingerprint 8A:12:6F:9C:AA:6E:9D:5A:5B:22:1C:77:41:9A:0E:1F:74:54:2B:11

Signification : PVE ne fera confiance qu’à un PBS présentant cette empreinte.
Décision : Si le certificat PBS a changé, mettez à jour cette empreinte après avoir vérifié la nouvelle sur PBS.

Task 7: Obtenir l’empreinte actuelle du certificat PBS (PBS)

cr0x@pbs01:~$ openssl x509 -in /etc/proxmox-backup/proxy.pem -noout -fingerprint -sha1
sha1 Fingerprint=8A:12:6F:9C:AA:6E:9D:5A:5B:22:1C:77:41:9A:0E:1F:74:54:2B:11

Signification : C’est ce que PVE devrait épingler.
Décision : Si cela diffère de storage.cfg, mettez à jour la définition de stockage PVE (et demandez pourquoi le cert a changé).

Task 8: Vérifier que vous ne touchez pas le mauvais hôte (PVE)

cr0x@pve01:~$ getent hosts pbs01
10.10.20.50   pbs01

Signification : DNS résout pbs01 vers une IP.
Décision : Si cette IP a récemment changé, confirmez que le nouvel hôte est bien PBS et non une adresse recyclée ou un load balancer.

Task 9: Vérifier l’identité TLS sur le wire (PVE)

cr0x@pve01:~$ echo | openssl s_client -connect pbs01:8007 -servername pbs01 2>/dev/null | openssl x509 -noout -subject -fingerprint -sha1
subject=CN = pbs01
sha1 Fingerprint=8A:12:6F:9C:AA:6E:9D:5A:5B:22:1C:77:41:9A:0E:1F:74:54:2B:11

Signification : Le serveur contacté présente un cert avec le CN et l’empreinte affichés.
Décision : Si l’empreinte diffère de ce que PBS rapporte localement, vous êtes redirigé ou il y a un proxy entre les deux.

Task 10: Confirmer que l’utilisateur PBS existe et est activé (PBS)

cr0x@pbs01:~$ proxmox-backup-manager user list
┌─────────────┬───────┬───────────┬────────┐
│ userid      │ enable│ expire    │ comment│
╞═════════════╪═══════╪═══════════╪════════╡
│ root@pam    │ true  │           │        │
│ backup@pbs  │ true  │           │ PVE jobs│
└─────────────┴────────────┴───────────┴────────┘

Signification : L’utilisateur existe et est activé.
Décision : S’il est désactivé/expiré, corrigez cela. Si l’utilisateur n’existe pas, arrêtez-vous : vous vous authentifiez sur une identité imaginaire.

Task 11: Confirmer que le jeton existe et est activé (PBS)

cr0x@pbs01:~$ proxmox-backup-manager user token list backup@pbs
┌───────────────┬────────┬─────────┬──────────────┐
│ tokenid       │ enable │ expire  │ comment      │
╞═══════════════╪════════╪═════════╪══════════════╡
│ pve01         │ true   │         │ PVE node token│
└────────────────┴────────┴─────────┴──────────────┘

Signification : Le jeton backup@pbs!pve01 existe et est activé.
Décision : Si le jeton est manquant/désactivé/expiré, réémettez un jeton et mettez à jour PVE. Ne devinez pas les secrets.

Task 12: Inspecter les ACL pertinentes au datastore (PBS)

cr0x@pbs01:~$ proxmox-backup-manager acl list
┌──────────────────────┬─────────────┬───────────┬─────────┐
│ path                 │ ugid        │ role      │ propagate│
╞══════════════════════╪═════════════╪═══════════╪═════════╡
│ /datastore/vmstore   │ backup@pbs  │ DatastoreBackup │ true │
│ /datastore/vmstore   │ backup@pbs!pve01 │ DatastoreBackup │ true │
└──────────────────────┴─────────────┴───────────┴─────────┘

Signification : L’identité a un rôle assigné sur le chemin du datastore.
Décision : Si l’ACL est absente ou pointe vers un mauvais chemin, ajoutez-la. Si vous n’avez accordé qu’à « / » mais désactivé la propagation, vous vous êtes peut-être coupé.

Task 13: Confirmer que le datastore existe et est sain (PBS)

cr0x@pbs01:~$ proxmox-backup-manager datastore list
┌───────────┬───────────────┬──────────┬────────┐
│ name      │ path          │ comment  │ state  │
╞═══════════╪═══════════════╪══════════╪════════╡
│ vmstore   │ /mnt/pbs/vmstore │         │ ok     │
└───────────┴───────────────┴──────────┴────────┘

Signification : Le datastore existe et PBS le juge OK.
Décision : S’il est manquant ou en erreur, corrigez le mount/les permissions du datastore d’abord ; les erreurs d’auth peuvent être du bruit secondaire.

Task 14: Tester la connexion à l’API PBS avec un jeton depuis un nœud (PVE)

cr0x@pve01:~$ curl -sk -H "Authorization: PBSAPIToken=backup@pbs!pve01:REDACTED" https://pbs01:8007/api2/json/version
{"data":{"version":"3.2-1","release":"bookworm"}} 

Signification : Le jeton est valide pour l’accès API et TLS fonctionne (parce que vous avez obtenu une réponse).
Décision : Si cela échoue avec 401, votre jeton/secret/realm est incorrect. Si cela échoue avec des erreurs TLS, corrigez l’empreinte/la confiance du certificat.

Task 15: Repérer les échecs 403 avec un appel API ciblé (PVE)

cr0x@pve01:~$ curl -sk -H "Authorization: PBSAPIToken=backup@pbs!pve01:REDACTED" https://pbs01:8007/api2/json/admin/datastore/vmstore/status
{"errors":"permission check failed"} 

Signification : Le jeton s’authentifie mais manque de privilèges pour cet endpoint/chemin.
Décision : Ajustez les rôles/ACL pour le jeton (préféré) ou pour l’utilisateur (moins recommandé) sur le datastore correct.

Task 16: Vérifier la correction de la config de stockage PVE (PVE)

cr0x@pve01:~$ pvesm status
Name        Type     Status           Total            Used       Available        %
local        dir     active        19684264         6021132        13012000   30.59%
pbs-vmstore  pbs     active               0               0               0    0.00%

Signification : PVE voit le stockage PBS comme actif. S’il est inactif, vérifiez auth/empreinte.
Décision : S’il est actif mais que les jobs échouent, concentrez-vous sur les permissions des jobs de sauvegarde (snapshot/upload/prune) plutôt que sur la connectivité de base.

Task 17: Valider quelle identité PVE utilise pour le stockage PBS (PVE)

cr0x@pve01:~$ awk '/^pbs: /{f=1} f{print} /^$/{f=0}' /etc/pve/storage.cfg
pbs: pbs-vmstore
        datastore vmstore
        server pbs01
        username backup@pbs
        fingerprint 8A:12:6F:9C:AA:6E:9D:5A:5B:22:1C:77:41:9A:0E:1F:74:54:2B:11

Signification : Vous pouvez vérifier l’intégrité du realm utilisateur ici.
Décision : Si username est d’un mauvais realm (pam vs pbs) ou contient une faute, corrigez-le et retestez avant de toucher aux ACL.

Task 18: Rechercher les échecs de connexion au niveau du backend d’auth (PBS)

cr0x@pbs01:~$ journalctl --since "1 hour ago" | grep -E "failed login|authentication failure" | tail -n 10
Dec 26 02:13:21 pbs01 proxmox-backup-proxy[1872]: authentication failure; rhost=10.10.20.11 user=backup@pbs msg=invalid credentials

Signification : Confirme des tentatives répétées et l’utilisateur que PBS voit.
Décision : Si les logs PBS montrent un utilisateur différent de celui attendu, vous avez mal configuré PVE (ou vous testez depuis le mauvais hôte).

Jetons et ACL : la pile de permissions qui pose problème

Utilisateur vs jeton : choisir les jetons pour les machines

Utilisez des jetons API pour les nœuds PVE et l’automatisation. Utilisez des mots de passe pour les humains. Les jetons réduisent le rayon d’impact et éliminent la
surprise « quelqu’un a fait tourner le mot de passe root@pam pour satisfaire une politique ».

Un modèle propre typique ressemble à ceci :

• Créer un utilisateur PBS dédié : backup@pbs (realm pbs, pas pam).
• Créer un jeton par nœud PVE : backup@pbs!pve01, backup@pbs!pve02, etc.
• Accorder des rôles ACL sur le datastore spécifique (et le namespace si utilisé), pas à « / ».
• N’accorder que ce dont le nœud a besoin : backup, peut-être verify, peut-être prune — décidez consciemment.

Les rôles ne sont pas décoratifs ; ce sont des contrats

Si vous voulez que les sauvegardes s’exécutent mais que vous ne voulez pas qu’un nœud compromis supprime l’historique, ne lui donnez pas de larges rôles admin.
L’approche correcte est d’accorder explicitement un rôle de sauvegarde et de garder prune/GC restreint à une identité de maintenance séparée.
Cette séparation est ennuyeuse. L’ennui, c’est bien.

Où les gens se blessent : ils testent avec root, ça marche, puis « resserrent les permissions plus tard », et le plus tard arrive sous forme d’un 403
en pleine nuit.

Pièges liés aux namespaces et à la propriété

PBS peut segmenter les données avec des namespaces. Idéal pour des environnements multi-tenant, ou pour séparer prod et dev sans datastores supplémentaires.
Mais c’est aussi très facile de créer un jeton qui s’authentifie mais ne voit rien.

Si votre job cible un namespace, votre ACL doit correspondre à ce chemin namespace. Accorder des droits à la racine du datastore peut ne pas suffire
selon la structure et si la propagation est activée.

Empreintes et TLS : quand la sécurité fait son travail

Les erreurs d’empreinte ressemblent à de la bureaucratie jusqu’à ce que vous vous rappeliez l’alternative : envoyer silencieusement vos sauvegardes vers la machine d’un attaquant
parce que quelqu’un a ARP-spoofé votre VLAN ou parce qu’une IP a été réutilisée. PVE épingle l’empreinte du cert PBS pour détecter « ce n’est pas le même serveur ».
Ce n’est pas de la paranoïa. C’est du pragmatisme.

Raisons légitimes pour lesquelles les empreintes changent

• PBS a été réinstallé ou remplacé.
• Le certificat a été régénéré volontairement.
• Le fichier proxy.pem a été remplacé lors d’une restauration/migration.
• Quelqu’un a restauré un ancien snapshot du filesystem de /etc/proxmox-backup.
• Vous avez déplacé PBS derrière un reverse proxy terminant TLS (généralement une mauvaise idée pour ce cas).

Mauvaises raisons pour lesquelles les empreintes changent

• « On a nettoyé les certificats pour la sécurité. »
• « On a redéployé la VM depuis un template en supposant que ce serait identique. »
• « On a changé le hostname et on n’a pas pensé que ça importait. »

Le bon workflow est ennuyeux :
vérifier l’empreinte sur PBS localement, comparer à ce que PVE épingle, puis mettre à jour la définition de stockage
si le changement est légitime. Si vous ne pouvez pas expliquer le changement, arrêtez et enquêtez. Les sauvegardes sont une frontière de sécurité.

Blague #2 : Les empreintes TLS sont comme la sécurité aéroportuaire — agaçantes jusqu’au jour où vous êtes content que quelqu’un ait posé des questions.

Trois mini-récits d’entreprise depuis les tranchées des sauvegardes

Incident #1 (mauvaise hypothèse) : « C’est sur le même VLAN, donc ça va »

Une entreprise de taille moyenne gérait des clusters PVE et une unique VM PBS. Elle était sur un VLAN d’infrastructure « de confiance ». L’équipe a supposé que personne n’usurperait PBS,
donc l’avertissement d’empreinte dans PVE était traité comme une nuisance.

Lors d’un nettoyage réseau, une adresse IP utilisée par PBS a été brièvement réassignée à un autre hôte. Cet hôte n’était pas malveillant ; il était simplement là en premier
quand le DNS s’est mis à jour. PVE a commencé à générer des erreurs d’authentification et d’empreinte. Quelqu’un, sous pression, a mis à jour l’empreinte pour « rendre les sauvegardes vertes »
sans vérifier le certificat côté PBS.

Les sauvegardes ont recommencé à « fonctionner » — sauf qu’elles étaient envoyées vers la mauvaise machine qui n’avait aucun datastore monté, donc les uploads échouaient en cours,
et les jobs retentaient indéfiniment. Le monitoring était calé sur « job démarré », pas sur « sauvegarde terminée », donc le tableau de bord restait agréablement optimiste.

La correction a été simple mais humiliante : remettre l’empreinte précédente, corriger le DNS/IP, et traiter les invites d’empreinte comme des changements de clé SSH :
vérifier hors bande, puis accepter. Ils ont aussi modifié le monitoring pour alerter sur la fin effective des sauvegardes et la croissance du datastore.

Incident #2 (optimisation qui se retourne contre eux) : « Un jeton pour tout le cluster »

Une autre équipe voulait réduire la dispersion de configuration. Ils ont créé un jeton PBS unique et l’ont collé dans la config de stockage de chaque nœud PVE.
Ça a marché, et c’était rapide. Mais cela signifiait que chaque nœud partageait la même identité effective.

Plus tard, ils ont essayé de restreindre les permissions en limitant le jeton. Mais ils avaient besoin de permissions différentes pour différents nœuds :
un nœud gérait des workloads soumis à conformité et nécessitait des permissions verify ; un autre nœud était jetable pour le dev où prune n’était pas autorisé.
Avec un jeton partagé, les changements de permissions sont devenus politiques et lents.

Puis un nœud a été décommissionné. Personne n’a pensé à faire tourner le jeton partagé, parce que « ce ne sont que des sauvegardes ». Le disque du nœud a été vendu,
et le secret du jeton est resté dans une sauvegarde de configuration oubliée. Des mois plus tard, lors d’un audit, ils ont réalisé qu’ils n’avaient aucun moyen propre de prouver que le secret avait disparu.

L’optimisation contre-productive était l’identité partagée. La correction : un jeton par nœud, ACL limitées par jeton, et une pratique de rotation liée au cycle de vie du nœud.
Un peu plus de saisie ; beaucoup moins d’angoisse existentielle.

Incident #3 (pratique ennuyeuse mais correcte) : la checklist qui a sauvé la journée

Un environnement régulé a subi une défaillance matérielle PBS. Ils ont restauré PBS depuis une procédure de récupération connue : réinstaller l’OS,
rattacher le stockage, restaurer la config PBS, valider l’empreinte du certificat, valider l’inventaire utilisateurs/jetons, puis réactiver les jobs PVE.
C’était un runbook terne, rempli de sorties de commandes et de « valeurs attendues ».

Pendant la restauration, le certificat PBS a été régénéré. C’est normal. Le runbook disait explicitement :
« Avant de mettre à jour les empreintes sur PVE, obtenir l’empreinte depuis /etc/proxmox-backup/proxy.pem et valider l’accès console. »
Ils l’ont fait. Pas de devinettes. Pas de clics aveugles.

Ils ont mis à jour les empreintes sur les nœuds PVE, puis testé avec une seule VM, puis étendu au parc entier.
La panne entière a été contenue dans une fenêtre prévisible. Le meilleur : le postmortem a presque manqué de drame, parce que le processus avait déjà répondu aux questions.

C’est pour ça qu’on rédige des runbooks. Pas parce qu’on adore la paperasse, mais parce que votre futur vous est occupé, fatigué, et qu’une mauvaise décision suffit à transformer une récupération en incident.

Erreurs courantes : symptôme → cause → correction

1) Symptom: « authentication failed » immédiatement lors de l’ajout du stockage PBS

Cause : Mauvais realm (@pam vs @pbs) ou mauvais format de nom d’utilisateur.

Correction : Vérifiez que l’utilisateur existe sur PBS (proxmox-backup-manager user list) et définissez username backup@pbs en conséquence.

2) Symptom: 401 Unauthorized dans les logs du proxy PBS

Cause : Secret du jeton erroné, jeton désactivé/expiré, ou ID de jeton incorrect.

Correction : Listez les jetons (proxmox-backup-manager user token list backup@pbs), réémettez si nécessaire, mettez à jour PVE, puis testez via curl.

3) Symptom: 403 Forbidden / permission check failed

Cause : ACL manquante sur /datastore/<name> ou mauvais namespace/propagation.

Correction : Ajoutez une ACL sur le chemin exact avec le rôle approprié et la propagation ; confirmez via proxmox-backup-manager acl list.

4) Symptom: Invite de discordance d’empreinte après reboot/reinstall de PBS

Cause : Le certificat PBS a changé ou PVE atteint un hôte différent.

Correction : Obtenez l’empreinte depuis PBS localement avec openssl x509 -in /etc/proxmox-backup/proxy.pem ..., validez DNS/IP, mettez à jour l’empreinte PVE seulement après vérification.

5) Symptom: Le stockage apparaît actif, mais les jobs échouent pendant prune ou verify

Cause : Le jeton peut écrire des sauvegardes mais n’a pas les privilèges de maintenance.

Correction : Séparez les identités : un jeton pour l’écriture des backups, un autre pour prune/verify, ou accordez explicitement les rôles nécessaires pour les endpoints de maintenance.

6) Symptom: Ça marche depuis un nœud PVE, échoue depuis un autre

Cause : Différences de jetons par nœud, ou entrées storage.cfg différentes, ou règles firewall selon l’IP source.

Correction : Comparez /etc/pve/storage.cfg entre nœuds ; testez curl depuis chaque nœud ; vérifiez les logs PBS pour rhost et user/token.

7) Symptom: Après activation du 2FA pour un utilisateur, les sauvegardes échouent

Cause : Vous avez utilisé un compte humain pour l’automatisation. Le 2FA casse les flux non interactifs à moins d’utiliser l’auth par jeton.

Correction : Passez PVE aux jetons API PBS pour l’accès machine. Gardez le 2FA pour les humains.

8) Symptom: « permission denied » lors du listing de snapshots/contents

Cause : L’ACL autorise l’écriture mais interdit la lecture/le listing ou le parcours sur le chemin/namespace concerné.

Correction : Assurez-vous que les rôles couvrent les opérations nécessaires (backup, read/list, restore). Testez via des appels API qui listent groups/snapshots.

9) Symptom: Tout a cassé après un « durcissement de sécurité »

Cause : Régénération de certs ou insertion d’un reverse proxy sans mise à jour des empreintes, ou ACL durcies à « / » sans propagation.

Correction : Annulez le proxy, ré-épingler les empreintes, et réappliquez les ACL au scope du datastore avec propagate activé intentionnellement.

Checklists / plan étape par étape

Plan A : réparer vite sans empirer (recommandé)

1. Confirmer l’atteignabilité : nc -vz pbs01 8007 depuis le nœud PVE en échec.
2. Lire les logs PBS en reproduisant : journalctl -u proxmox-backup-proxy -f.
3. Classer l’échec :
   • invalid credentials / 401 → jeton/utilisateur/realm.
   • permission check failed / 403 → chemin/role/propagation ACL.
   • fingerprint mismatch → vérifier cert et mettre à jour le pin PVE.
4. Vérifier l’inventaire d’identités sur PBS :
   • proxmox-backup-manager user list
   • proxmox-backup-manager user token list backup@pbs
5. Vérifier l’ACL sur PBS : proxmox-backup-manager acl list et confirmer le chemin du datastore correct.
6. Vérifier l’empreinte :
   • PBS local : openssl x509 -in /etc/proxmox-backup/proxy.pem -noout -fingerprint -sha1
   • PVE épinglé : grep storage.cfg
7. Tester via curl depuis PVE en utilisant l’en-tête du jeton pour isoler les problèmes de GUI.
8. Corriger exactement une chose, retester, puis avancer. Pas de « tout faire tourner et espérer ».

Plan B : reconstruire proprement les credentials (quand vous avez perdu le fil)

1. Créer (ou recréer) un utilisateur PBS dédié pour les jobs PVE (backup@pbs), activé, sans expiration.
2. Créer un nouveau jeton par nœud ; enregistrer le secret une seule fois ; le stocker dans votre gestionnaire de secrets.
3. Assigner l’ACL sur /datastore/<name> directement à l’identité du jeton.
4. Mettre à jour la config de stockage PVE pour utiliser le jeton et l’empreinte correcte.
5. Lancer un test de sauvegarde d’une VM ; confirmer que les logs PBS indiquent le jeton/utilisateur correct et aucun 403.
6. Ensuite seulement réactiver le planning complet des sauvegardes.

Plan C : réponse à un changement d’empreinte (traitez-le comme un incident)

1. Arrêtez-vous et vérifiez le mapping DNS/IP (getent hosts pbs01).
2. Vérifiez l’empreinte localement sur PBS via accès console.
3. Comparez à ce que PVE épingle ; si différent, documentez pourquoi.
4. Mettre à jour l’empreinte PVE et retester la connectivité.
5. Si vous ne pouvez pas expliquer le changement, supposez compromission ou mauvais routage jusqu’à preuve du contraire.

FAQ

1) Est-ce que « authentication failed » signifie toujours mauvais mot de passe ou mauvais jeton ?

Non. Cela peut être une discordance d’empreinte TLS, un mauvais realm, ou même un refus de permission qui a été aplani dans un message GUI générique.
Vérifiez toujours les logs du proxy PBS pour savoir s’il s’agit d’un 401 ou d’un 403.

2) Quelle est la différence entre utilisateur/mot de passe et auth par jeton API pour PBS ?

L’utilisateur/mot de passe est adapté à l’interaction humaine. Les jetons API sont destinés à l’automatisation, peuvent être révoqués indépendamment,
et sont plus sûrs à restreindre via les ACL. Pour PVE→PBS, utilisez des jetons.

3) Pourquoi PVE se préoccupe de l’empreinte PBS ? Nous sommes sur un réseau interne.

Les réseaux internes sont le lieu où la plupart des erreurs de confiance se produisent : réutilisation d’IP, dérive DNS, VM de test branchée, ou hôte compromis.
L’épinglage d’empreinte empêche d’envoyer silencieusement vos sauvegardes au mauvais endpoint.

4) J’ai mis à jour l’empreinte et maintenant ça marche. Sommes-nous quittes ?

Seulement si vous pouvez expliquer pourquoi elle a changé. Si elle a changé parce que PBS a été reconstruit, OK. Si le changement est « mystérieux », enquêtez DNS, ARP, proxies,
et si l’hôte PBS a été remplacé ou restauré depuis un snapshot.

5) Pourquoi ai-je un 403 quand les sauvegardes s’exécutent mais que prune échoue ?

L’upload de sauvegarde et prune/GC/verify sont des opérations différentes. Votre jeton peut avoir des privilèges d’écriture mais pas de maintenance.
Séparez les responsabilités : jeton backup pour les écritures, jeton maintenance pour prune/verify.

6) Puis-je utiliser root@pam partout pour éviter les problèmes de permissions ?

Vous le pouvez, et vous le regretterez. Root est une excellente identité de dépannage et une horrible identité d’automatisation à long terme.
Utilisez le principe du moindre privilège avec des jetons et des ACL scoppés par datastore.

7) Quelle est la façon la plus rapide de confirmer qu’un jeton fonctionne en dehors de la GUI ?

Utilisez curl contre /api2/json/version avec l’en-tête PBSAPIToken=.... Si cela retourne du JSON, l’auth et TLS sont OK.
Si ça échoue, le message d’erreur est plus explicite que la GUI.

8) Mon utilisateur PBS existe, mon jeton existe, l’ACL semble correcte, mais j’ai toujours un 403. Et maintenant ?

Confirmez que le chemin ACL correspond à la cible réelle : nom du datastore correct, namespace, et si la propagation est activée.
Confirmez aussi que vous accordez au bon identity : backup@pbs vs backup@pbs!pve01.

9) La dérive horaire cause vraiment des erreurs d’auth ici ?

Oui, en particulier autour de la validation de tickets/sessions et pour tout ce qui a une sémantique d’expiration. Si vous voyez des échecs intermittents après des reboots,
vérifiez timedatectl sur les deux côtés avant d’accuser les jetons.

10) Dois-je mettre PBS derrière un reverse proxy avec mon propre certificat ?

En général non. Cela introduit des composants supplémentaires et casse le modèle mental « PVE épingle l’identité du cert PBS ».
Si vous devez le faire, traitez-le comme un changement d’architecture et planifiez la gestion des empreintes délibérément.

Conclusion : étapes suivantes pour éviter d’être réveillé la nuit

Corriger le « authentication failed » de PBS n’est pas une question d’héroïsme. C’est refuser de deviner. Commencez par les logs, classez 401 vs 403 vs TLS,
et seulement alors touchez aux jetons, ACL ou empreintes.

Étapes pratiques :

• Créer un utilisateur PBS dédié et un jeton par nœud PVE. Supprimez les jetons partagés sauf si vous aimez faire tourner des secrets en masse.
• Accorder des ACL scoppées au datastore avec propagation volontaire. Évitez les grants à « / » qui deviennent des super-pouvoirs accidentels.
• Documenter et monitorer les changements d’empreinte comme des changements de clé SSH : vérifier, puis mettre à jour, et toujours enregistrer la raison.
• Séparer les responsabilités : jeton write-backup vs jeton prune/verify. Le moindre privilège n’est pas une religion ; c’est une stratégie de confinement.
• Ajouter du monitoring sur la réussite effective des sauvegardes et sur la croissance du datastore, pas seulement sur « job lancé ».

Quand les sauvegardes sont saines, elles sont ennuyeuses. Visez l’ennui. La production aime l’ennui.