Aller au contenu principal

Intégration domotique Proxmox Backup Server, gratuite et open source

Intégration Proxmox Backup Server pour Gladys Assistant

Supervision en lecture seule des datastores et tâches de maintenance Proxmox Backup Server.

Voir sur GitHubToutes les intégrations

Cette intégration interroge uniquement les routes GET de l'API PBS. Elle ne lance, ne modifie et ne supprime aucun backup ou job.

Droits exacts (lecture seule)​

Le rôle intégré DatastoreAudit contient Datastore.Audit : métriques, configuration et liste du contenu, sans accès aux données sauvegardées. Le rôle intégré Audit sur /system fournit Sys.Audit, nécessaire pour lire l'historique des tâches du nœud. N'accordez surtout pas DatastoreAdmin, DatastoreBackup, DatastorePowerUser, Datastore.Prune, Datastore.Modify ou Datastore.Verify.

Sur PBS, exécutez en tant que root (remplacez le mot de passe et conservez le secret affiché par generate-token) :

proxmox-backup-manager user create gladys@pbs --password 'UN_MOT_DE_PASSE_LONG_ET_UNIQUE'
proxmox-backup-manager user generate-token gladys@pbs monitoring
proxmox-backup-manager acl update /datastore DatastoreAudit --auth-id gladys@pbs --propagate true
proxmox-backup-manager acl update /datastore DatastoreAudit --auth-id 'gladys@pbs!monitoring' --propagate true
proxmox-backup-manager acl update /system Audit --auth-id gladys@pbs --propagate true
proxmox-backup-manager acl update /system Audit --auth-id 'gladys@pbs!monitoring' --propagate true

La séparation des privilèges des jetons API est native dans PBS : generate-token n'accepte pas d'option --privsep. PBS utilise l'intersection des ACL de l'utilisateur et du jeton. Ces quatre ACL identiques sont donc intentionnelles. Pour limiter la supervision à un seul datastore, remplacez /datastore par /datastore/NOM dans les deux commandes correspondantes. Vérifiez avec :

proxmox-backup-manager user permissions 'gladys@pbs!monitoring'

Paramètres Gladys​

  1. URL : https://pbs.example.com:8007.
  2. Identifiant du jeton : gladys@pbs!monitoring.
  3. Secret : la valeur affichée une seule fois à la création du jeton.
  4. Nœud : généralement localhost; indiquez le nom retourné par PBS si nécessaire.
  5. Pour un certificat autosigné, renseignez son empreinte SHA-256 dans Empreinte du certificat TLS (voir ci-dessous) et gardez la vérification TLS activée.
  6. L'intervalle de rafraîchissement est de 15 minutes par défaut. Il ne peut pas être inférieur à 5 minutes afin de limiter la croissance de la base Gladys, et peut être augmenté jusqu'à 24 heures.
  7. La liste déroulante générale Format de date s'applique à toutes les dates des tâches. Elle propose les formats ISO 8601, jour/mois/année, année-mois-jour et mois/jour/année.
  8. Le champ Fuseau horaire fixe le fuseau d'affichage des dates, sous forme de nom IANA comme Europe/Paris (heures d'été et d'hiver gérées). Il vaut UTC par défaut ; une valeur vide ou inconnue revient aussi à UTC. En ISO 8601, un fuseau autre que UTC ajoute son décalage, par exemple 2026-09-23T23:30:01+02:00.

Après avoir modifié et sauvegardé le format de date ou le fuseau horaire, ouvrez l'appareil PBS concerné dans Gladys et sauvegardez-le de nouveau pour appliquer le changement.

Le jeton est envoyé avec l'en-tête natif Authorization: PBSAPIToken=...; aucun mot de passe n'est envoyé à chaque requête.

TLS et le certificat autosigné de PBS​

Utilisez une URL https://. Une URL http:// est acceptée, mais le jeton API circule alors en clair sur le réseau à chaque rafraîchissement : quiconque peut lire ce trafic peut le réutiliser.

PBS est livré avec un certificat autosigné, que le conteneur ne reconnaît pas. De la meilleure option à la moins bonne :

  1. Épingler l'empreinte (recommandé). Collez l'empreinte SHA-256 du serveur dans le champ Empreinte du certificat TLS. Seul un serveur présentant exactement ce certificat est accepté, et l'empreinte est vérifiée avant l'envoi du jeton : un serveur qui se ferait passer pour PBS ne le reçoit jamais. L'empreinte s'affiche dans l'interface web de PBS (Tableau de bord → Afficher l'empreinte) ou dans un shell sur PBS :

    proxmox-backup-manager cert info | grep -i fingerprint

    Les séparateurs et la casse sont indifférents (AA:BB:… ou aabb…). L'empreinte change quand le certificat est renouvelé ou remplacé : mettez alors le champ à jour. Une empreinte épinglée exige une URL https:// et prime sur Vérifier le certificat TLS.

  2. Un certificat signé par une autorité reconnue (par exemple ACME / Let's Encrypt configuré sur PBS) : laissez l'empreinte vide et gardez Vérifier le certificat TLS activé.

  3. Désactiver Vérifier le certificat TLS, en dernier recours et sur un réseau de confiance uniquement : la connexion reste chiffrée, mais rien ne prouve l'identité du serveur, et le jeton est envoyé à celui qui répond.

Fonctionnalités exposées​

Chaque datastore PBS est représenté par un appareil Gladys comportant les fonctionnalités en lecture seule suivantes :

Les trois valeurs de capacité (Usage, Total size et Used space) sont rattachées à la fonctionnalité Gladys data/size, tout en conservant leur unité en pourcentage ou en gigaoctets.

FonctionnalitéValeurDescription
UsagePourcentageEspace utilisé, arrondi à deux décimales.
Total sizeGigaoctetsCapacité totale du datastore, arrondie à deux décimales.
Used spaceGigaoctetsEspace utilisé, arrondi à deux décimales.
Snapshot countEntierNombre de snapshots stockés, cumulé sur les groupes de sauvegarde.
Last verify statusTexteDernier statut de vérification, par exemple OK.
Last verify dateTexteDate de la dernière vérification, au format configuré.
Last garbage collection statusTexteDernier statut du garbage collection, par exemple OK.
Last garbage collection dateTexteDate du dernier garbage collection, au format configuré.
Last prune statusTexteDernier statut du prune, par exemple OK.
Last prune dateTexteDate du dernier prune, au format configuré.
Backup stale (> 26 h)0 ou 11 lorsqu'aucun snapshot n'existe ou que le plus récent date de plus de 26 heures.

Widgets, déclencheurs et actions de scène (Gladys 5.1)​

Ces fonctions demandent Gladys 5.1.0 ou plus récent. Elles lisent PBS uniquement : aucun bouton, déclencheur ou action ne peut lancer, modifier ou supprimer quoi que ce soit sur le serveur.

Widgets du tableau de bord​

Ajoutez-les depuis l'édition du tableau de bord, dans la liste des widgets de cette intégration.

WidgetRéglagesContenu
Datastore PBSUn datastore, afficher les tuiles (activé par défaut)Jauge d'utilisation, espace libre, nombre de snapshots, une carte par tâche vérification/GC/prune (date et badge de résultat), dernière sauvegarde, espace utilisé / total, bouton Actualiser.
Sauvegardes PBSAucunUtilisation du datastore le plus plein, sauvegardes en retard, tâches en échec, une ligne d'état par datastore (10 au maximum), bouton Actualiser.

La tuile snapshots suit l'état de l'appareil en direct. Les autres tuiles, les cartes des tâches et les lignes d'état sont mises à jour après chaque rafraîchissement. Le bouton Actualiser relit PBS tout de suite. Désactivez Afficher les tuiles utilisation, espace libre et snapshots pour masquer les trois tuiles.

Déclencheurs de scène​

Ils apparaissent dans l'éditeur de scène, dans la catégorie « Intégrations ». Chaque filtre est facultatif : laissez-le vide pour accepter toutes les valeurs.

DéclencheurSe déclenche quandFiltresVariables
Tâche de maintenance PBS terminéeUne tâche de vérification, de garbage collection ou de prune est finie.Datastore, type de tâche, résultatdatastore_name, task_type, result, status, date
Nouvelle sauvegarde PBSUn snapshot plus récent est apparu sur le datastore.Datastoredatastore_name, last_backup, snapshot_count
Sauvegarde PBS trop ancienneLe snapshot le plus récent vient de dépasser 26 heures.Datastoredatastore_name, last_backup, hours_since_backup
PBS injoignableUne lecture de datastore a échoué (une fois par panne).Datastoredatastore_name, error
PBS de nouveau joignableUne lecture de datastore a réussi après un échec.Datastoredatastore_name

result vaut ok, warning ou error ; status est le statut brut de PBS, par exemple OK, WARNINGS: 2 ou le texte de l'erreur.

  • Un déclencheur part une seule fois par changement, jamais à chaque rafraîchissement. Exemple : une sauvegarde qui reste trop ancienne ne déclenche Sauvegarde PBS trop ancienne qu'une fois.
  • Les changements sont détectés par le rafraîchissement planifié (l'intervalle de rafraîchissement). Une lecture demandée par un widget ou une action de scène ne déclenche jamais rien elle-même ; le rafraîchissement planifié suivant signale le changement.
  • Le premier rafraîchissement après un démarrage ou un changement de configuration ne déclenche rien : il sert de point de départ.
  • Si plusieurs tâches du même type se terminent entre deux rafraîchissements, seule la plus récente est signalée.

Actions de scène​

ActionChampsSorties
Lire l'état d'un datastore PBSDatastore (obligatoire), Lire PBS maintenant (désactivé par défaut)datastore_name, usage_percent, used_gb, total_gb, snapshot_count, backup_stale, last_backup, hours_since_backup, last_verify_status, last_verify_date, last_gc_status, last_gc_date, last_prune_status, last_prune_date
Obtenir le rapport des sauvegardes PBSLire PBS maintenant (désactivé par défaut), langue du rapport (en/fr/de/es)datastore_count, stale_count, failed_task_count, unreachable_count, max_usage_percent, all_ok, summary
  • Sans Lire PBS maintenant, l'action répond avec les valeurs du dernier rafraîchissement et ne sollicite pas PBS.
  • summary est un texte prêt à envoyer, une ligne par datastore. Exemple de rapport quotidien : « Tous les jours à 8 h » → « Obtenir le rapport des sauvegardes PBS » (langue fr) → « Envoyer un message » avec la sortie summary.
  • Exemple d'alerte : « Tâche de maintenance PBS terminée » filtrée sur le résultat Erreur → « Envoyer un message » : Échec de {{triggerEvent.data.task_type}} sur {{triggerEvent.data.datastore_name}} : {{triggerEvent.data.status}}.

Détails de fonctionnement​

  • Le nombre de snapshots et la fraîcheur des sauvegardes sont lus depuis les groupes de sauvegarde du datastore (backup-count et last-backup) : un datastore contenant des milliers de snapshots ne coûte qu'une petite réponse par rafraîchissement. Si une version de PBS n'expose pas ces compteurs, l'intégration revient à la liste complète des snapshots.
  • L'historique des tâches est lu avec une requête filtrée par type de tâche (vérification, garbage collection, prune) : sur un datastore très actif, elles ne disparaissent pas de la fenêtre consultée et ne repassent pas à Never run, et un type de tâche jamais lancé ne coûte qu'une réponse vide. Une version de PBS qui refuse ce filtre est lue page par page (jusqu'à 2000 tâches).
  • La capacité de tous les datastores provient d'une seule lecture de /status/datastore-usage, partagée par les datastores rafraîchis dans la même minute.
  • Un datastore hors ligne ou non monté ne renvoie aucune capacité ; l'intégration ne publie alors rien pour l'usage, la taille totale et l'espace utilisé (les dernières valeurs réelles restent affichées), plutôt qu'un 0 qui ferait croire à un datastore vidé. Les widgets affichent la capacité comme indisponible.
  • Chaque requête vers PBS se termine en 15 secondes au plus, y compris une réponse coupée ou bloquée en cours de route, et une réponse de plus de 8 Mo est refusée. L'état de connexion nomme la cause : jeton refusé (HTTP 401), rôle manquant (HTTP 403), certificat, réseau ou délai dépassé.
  • Un rafraîchissement en échec (erreur réseau, délai dépassé, redémarrage de PBS) est retenté au tick Gladys suivant, sans attendre un intervalle complet. Au démarrage, la connexion est retentée quatre fois avec un délai exponentiel avant que l'intégration ne se déclare déconnectée.
  • Un rafraîchissement auquel PBS a répondu mais que Gladys n'a pas pu enregistrer (Gladys en cours de redémarrage, par exemple) est lui aussi retenté au tick suivant ; il n'est pas signalé comme PBS injoignable.
  • Un datastore supprimé ou renommé sur PBS est retiré de la supervision dès que PBS ne le liste plus, sans événement PBS injoignable, et ne laisse plus l'état de connexion au rouge. Son appareil resté dans Gladys est recherché de nouveau après un intervalle de rafraîchissement, puis deux fois plus tard à chaque fois, jusqu'à une fois par jour.
  • Un appareil que vous venez d'ajouter depuis l'onglet Découverte est lu immédiatement, sans attendre le prochain rafraîchissement.

Vérifier la route d'inventaire utilisée​

L'intégration privilégie la route économique groups et se rabat sur la liste complète des snapshots ; ce repli est tracé en avertissement dans les logs du conteneur (Falling back to the snapshot list for datastore ..., avec l'erreur PBS qui l'a déclenché).

Pour le vérifier sur votre serveur sans rien installer dans Gladys, lancez le diagnostic en lecture seule depuis un clone de ce dépôt :

PBS_URL=https://pbs.example.com:8007 \
PBS_TOKEN_ID='gladys@pbs!monitoring' \
PBS_TOKEN_SECRET='le-secret-du-jeton' \
npm run check:pbs

Il affiche, pour chaque datastore, la route réellement utilisée, le temps de réponse de chaque route et les dernières tâches verify/GC/prune. Il recoupe également le nombre de snapshots et la date du plus récent avec la liste complète des snapshots, et se termine avec le code 1 en cas de divergence. Ajoutez PBS_NODE=... pour un nœud autre que localhost, et PBS_FINGERPRINT=AA:BB:... pour un certificat autosigné (ou PBS_VERIFY_TLS=false sur un réseau de confiance).

Les mêmes routes se vérifient à la main :

curl -sSf -H "Authorization: PBSAPIToken=gladys@pbs!monitoring:SECRET" \
  'https://pbs.example.com:8007/api2/json/admin/datastore/NOM/groups' | head -c 400

Un HTTP 403 signale une ACL sans Datastore.Audit sur ce datastore ; un HTTP 404 signifie que cette version de PBS ne sert pas la route et que le repli sur les snapshots est normal.

Paramètres de configuration​

Voici les paramètres demandés par Proxmox Backup Server dans son écran de configuration dans Gladys.

ParamètreTypeObligatoireDescription
Connexion à Proxmox Backup ServersectionNonCréez un jeton API dédié avec les rôles de lecture seule DatastoreAudit et Audit. Consultez la documentation pour les commandes exactes.
URL du serveurstringOuiPar exemple : https://pbs.example.com:8007. Évitez http:// : le jeton API circule alors en clair.
Identifiant du jeton APIstringOuiIdentifiant complet, par exemple gladys@pbs!monitoring
Secret du jeton APIsecretOui
Nom du nœud PBSstringNon
Intervalle de rafraîchissement (secondes)numberNon
Empreinte du certificat TLSstringNonRecommandé avec le certificat auto-signé de PBS : son empreinte SHA-256 (Tableau de bord > Afficher l'empreinte). Le jeton n'est envoyé qu'à un serveur qui la présente. Laissez vide pour un certificat signé par une AC reconnue.
Vérifier le certificat TLSbooleanNonIgnoré quand une empreinte est épinglée. À désactiver en dernier recours, sur un réseau de confiance : la connexion reste chiffrée mais rien ne prouve l'identité du serveur.
Format de dateselectNonSélectionnez le format d'affichage des dates des tâches, dans le fuseau horaire indiqué ci-dessous.
Fuseau horairestringNonNom IANA utilisé pour afficher les dates, par exemple Europe/Paris. Vide ou inconnu : UTC.

Comment installer Proxmox Backup Server dans Gladys​

  1. Dans Gladys, ouvrez Intégrations : Proxmox Backup Server apparaît dans le catalogue, aux côtés des intégrations natives, avec un badge communautaire.
  2. Cliquez sur Installer. Gladys télécharge l'image Docker (ghcr.io/prohand/gladys-proxmox-backup-server:2.6.1), la démarre dans un bac à sable isolé du cœur, et génère l'interface de l'intégration (appareils, découverte et configuration).
  3. Ouvrez l'écran Configuration de l'intégration, remplissez les paramètres, puis enregistrez.
  4. Vous pouvez aussi l'installer directement depuis l'URL de son dépôt : https://github.com/prohand/gladys-proxmox-backup-server.

Proxmox Backup Server nécessite Gladys >=5.1.0. Le catalogue dans Gladys se rafraîchit toutes les heures : une nouvelle version est donc disponible au plus tard une heure après sa sortie.

Vous n'utilisez pas encore Gladys ? C'est gratuit et open source : suivez le guide d'installation pour démarrer.

À propos des intégrations externes​

Proxmox Backup Server est une intégration externe : une intégration communautaire empaquetée dans un conteneur Docker et publiée sur GitHub, que Gladys installe en un clic et exécute dans un bac à sable isolé de son cœur. Elle est publiée et maintenue par prohand, et non par l'équipe cœur de Gladys.

Inscrivez-vous à la newsletter Gladys Assistant

Quelques emails par mois sur les nouveautés et l'actualité du projet. Envoyés par Pierre-Gilles Leymarie, le fondateur du projet. Désinscription possible à tout moment 🙂
Dernière mise à jour le