API et intégrations¶
BombVault propose une petite API HTTP pour les scripts, les tableaux de bord et la domotique. Elle lit ce que montre l'aperçu et peut lancer une sauvegarde. Tout le reste, comme les restaurations, la suppression de sauvegardes, les réglages et les nœuds, reste dans l'interface web.
Jetons¶
Chaque requête demande un jeton d'API, même sans mot de passe de connexion. Créez-le sous Paramètres, Intégrations, Jetons d'API :
- Saisissez un nom qui dit où le jeton sert, par exemple « Home Assistant » ou « Uptime Kuma ».
- Activez Autoriser le lancement de sauvegardes si le jeton doit pouvoir lancer des sauvegardes. Sans cela, il peut seulement lire.
- Cliquez sur Créer le jeton. Le jeton s'affiche une seule fois. BombVault n'en garde qu'une empreinte, alors copiez-le maintenant.
Envoyez le jeton dans un en-tête, soit Authorization: Bearer <token>, soit X-API-Key: <token>. Un jeton commence par bvapi_. Il n'ouvre que l'API : une clé MCP ne fonctionne pas ici, et un jeton ne fonctionne pas pour MCP.
Chaque jeton a une tuile avec son nom, s'il peut lancer des sauvegardes, ses quatre derniers caractères, quand et d'où il a servi la dernière fois, et ses appels du jour. Sur la tuile, vous pouvez le renommer, changer ce qu'il peut faire, le remplacer ou le révoquer. Journal montre les sauvegardes qu'il a lancées et ses derniers appels. Restaurer la configuration de BombVault depuis une sauvegarde révoque tous les jetons, car la sauvegarde peut contenir des jetons que vous avez révoqués depuis.
Sans mot de passe de connexion, toute personne qui peut ouvrir l'interface web peut aussi créer un jeton. Si vous ouvrez BombVault sous un nom d'apparence publique sans mot de passe, aucun jeton ne peut être créé depuis cette adresse, comme pour les clés MCP.
Points d'accès¶
| Route | Ce qu'elle renvoie ou fait | Jeton |
|---|---|---|
GET /api/v1/health |
Version, nom de l'instance, si une sauvegarde tourne et ce que ce jeton peut faire | lecture |
GET /api/v1/status |
État de protection par section : dernière sauvegarde réussie, intervalle attendu, vérifications, prochains lancements prévus | lecture |
GET /api/v1/activity |
Ce qui tourne en ce moment, avec phase et pourcentage | lecture |
GET /api/v1/items |
Chaque élément protégé avec son planning, ce qu'une sauvegarde arrête et sa dernière sauvegarde. ?domain= pour une section |
lecture |
GET /api/v1/runs |
Historique des exécutions, les plus récentes d'abord. Filtres limit, domain, item, status, kind, since |
lecture |
GET /api/v1/anomalies |
Anomalies avec un résumé de ce qui est ouvert. Filtres state, severity, domain, limit |
lecture |
GET /api/v1/anomalies/{id} |
Une anomalie | lecture |
GET /api/v1/storage/{domain} |
Historique de taille, croissance par semaine et espace libre de chaque dépôt d'une section | lecture |
POST /api/v1/backups |
Sauvegarde un élément ({"domain":"containers","item":"plex"}) ou une section entière ({"domain":"vms"}) |
lancement |
POST /api/v1/backups/everything |
Lance la sauvegarde complète | lancement |
POST /api/v1/runs/{id}/cancel |
Annule une sauvegarde en cours lancée par ce jeton | lancement |
Les sections sont containers, vms, files, zfs, flash et config. Les heures sont des secondes Unix. Les réponses sont celles des outils MCP du même nom, les deux restent donc alignés.
Une sauvegarde lancée ici est la même que celle de l'interface web : un conteneur en marche est arrêté jusqu'à la fin de sa sauvegarde. La requête revient tout de suite, et /api/v1/activity et /api/v1/runs montrent la suite.
Exemples¶
# How are the backups doing?
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status
# Back up one container now.
curl -s -X POST -H "Authorization: Bearer $BOMBVAULT_TOKEN" \
-H "Content-Type: application/json" -d '{"domain":"containers","item":"plex"}' \
https://tower:3443/api/v1/backups
Avec le certificat autosigné de BombVault, ajoutez --cacert bombvault-cert.pem (le fichier que donne Télécharger le certificat sur la carte MCP) ou -k sur un réseau de confiance.
Erreurs et limites¶
Une erreur revient sous la forme {"error": {"code": "...", "message": "..."}} avec le statut correspondant :
| Statut | Codes | Sens |
|---|---|---|
| 400 | invalid_argument, ambiguous |
Un argument manque ou est faux |
| 401 | no_token, invalid_token |
Pas de jeton, ou pas un jeton actif |
| 403 | not_permitted, forbidden_origin |
Le jeton peut seulement lire, ce n'est pas lui qui a lancé l'exécution, ou la requête vient d'une page d'une autre origine |
| 404 | not_found |
Élément, exécution ou anomalie introuvable |
| 409 | busy, domain_off, nothing_to_back_up, not_running |
Autre chose tourne, la section est désactivée, ou il n'y a rien à faire |
| 429 | throttled, rate_limited, cooldown, retention_guard |
Une limite retient la requête. Retry-After dit quand réessayer |
Les lancements suivent les mêmes limites que les lancements via MCP : 12 par heure et par jeton, 15 minutes entre deux lancements du même élément, au plus 4 lancements d'un élément en 24 heures, et la protection de rétention. Les trois dernières comptent ensemble les lancements via MCP, via l'API et depuis Home Assistant. Un jeton peut faire 120 requêtes par minute. Après cinq échecs depuis une même adresse, elle est bloquée une minute.
OpenAPI¶
BombVault sert une description de ces routes sous /api/v1/openapi.json (OpenAPI 3.1). Aucun jeton n'est nécessaire. Chargez-la dans Swagger UI, Postman ou un générateur de code.
Nœuds¶
Les routes qui gèrent les nœuds appartiennent à l'interface web, pas à l'API à jeton décrite plus haut. Avec un mot de passe de connexion défini, elles demandent une session de navigateur issue d'une connexion sur cette instance. Un jeton d'API ou une clé MCP n'en ouvre aucune, les téléphones appairés ne les atteignent pas, et /api/v1/openapi.json ne les décrit pas. Ajouter un nœud, afficher de nouveau son fichier compose et atteindre les routes d'un nœud sont refusés tant qu'aucun mot de passe de connexion n'est défini. Un script qui modifie quelque chose envoie Content-Type: application/json, comme partout dans l'interface web.
| Route | Ce qu'elle fait |
|---|---|
GET /api/nodes |
Chaque nœud, avec s'il est en ligne, sa version, la destination de ses sauvegardes, le planning de chaque section, sa dernière sauvegarde, ses erreurs et ses anomalies ouvertes |
POST /api/nodes |
Ajoute un nœud, par exemple {"name":"vps-helsinki"}, et le renvoie avec compose : MODE, APP_KEY, NODE_HOME et NODE_NAME |
POST /api/nodes/{id}/compose |
Renvoie de nouveau les mêmes valeurs compose, pour Remplacer |
POST /api/nodes/{id}/placement |
Envoie les sauvegardes du nœud vers une destination et répond par section si le nœud a atteint son dépôt, avec un warning pour une destination |
PUT /api/nodes/{id}/schedule |
Règle les plannings, par exemple {"containers":"daily 03:00","files":"off"}. Une section omise garde son planning |
DELETE /api/nodes/{id} |
Libère le nœud. told indique s'il l'a appris tout de suite ou s'il l'apprendra à son retour |
GET /api/nodes/routes |
La liste des routes du nœud vers lesquelles l'instance d'attache transmet les requêtes |
GET, POST, PATCH /api/nodes/{id}/api/{path} |
Transmet la requête à la route /api/{path} du nœud quand cette route figure sur la liste, et renvoie la réponse JSON du nœud |
PUT /api/receiver/node-address |
Règle l'Adresse pour les nœuds du serveur récepteur, par exemple {"url":"https://backup.tower.example.org","caPem":""}. Une url vide retire les nœuds du serveur |
Les trois destinations :
{"kind": "receiver"}
{"kind": "location", "location": "<storage location id>", "signIn": "<sign-in id made for the node>"}
{"kind": "node", "address": "https://203.0.113.7:8443"}
Une requête vers /api/nodes/{id}/api/... transporte au plus 32 KiB. Une route absente de la liste répond 403, un nœud qui n'a pas encore répondu ou qui est en cours de libération 409 avec le code node-not-adopted, et un nœud absent 502 avec le code node-away. Par exemple, GET /api/nodes/{id}/api/runs?limit=20 renvoie les 20 dernières exécutions du nœud, et POST /api/nodes/{id}/api/containers/nextcloud/backup sauvegarde son conteneur nextcloud.
Home Assistant¶
BombVault peut apparaître dans Home Assistant comme un appareil, grâce à la découverte MQTT. Home Assistant a besoin de son intégration MQTT et d'un broker, par exemple le module complémentaire Mosquitto. Aucun composant personnalisé n'est nécessaire.
- Dans BombVault, ouvrez Paramètres, Intégrations et activez Home Assistant dans la carte Services. Les champs du broker apparaissent en dessous.
- Saisissez l'adresse et le port du broker, ainsi que le nom d'utilisateur et le mot de passe s'il en demande. Activez Utiliser TLS si le broker accepte TLS, en général sur le port 8883. Son certificat doit être valide pour l'adresse saisie. Si vous changez l'adresse, le port ou le nom d'utilisateur, saisissez de nouveau le mot de passe : BombVault ne transmet pas celui qui est enregistré à un autre broker ou utilisateur.
- Cliquez sur Enregistrer. La ligne indique quand la connexion est établie.
L'appareil s'appelle BombVault, ou BombVault avec le nom de l'instance entre parenthèses, et possède ces entités :
| Entité | Ce qu'elle affiche |
|---|---|
| Status | ok, warning, overdue, failed ou off, le pire parmi les sections activées. Une section qui attend sa première sauvegarde ne compte qu'une fois cette sauvegarde due, et seule une section à jour donne le statut ok. overdue signifie, comme dans la vue d'ensemble, que la dernière sauvegarde d'une section date de plus de deux intervalles |
| Running job | Ce qui tourne maintenant, ou idle |
| Open anomalies | Le nombre d'anomalies ouvertes |
| Next scheduled backup | Quand démarre la prochaine sauvegarde planifiée |
| Section last backup | Quand a eu lieu la dernière sauvegarde réussie de la section |
| Section last result | Comment s'est terminée sa dernière sauvegarde |
| Section repository free space | L'espace libre là où se trouve son dépôt principal, si BombVault peut le lire |
| Back up section | Un bouton qui sauvegarde toute la section |
Chaque section activée a ses propres entités, et une section désactivée les perd. Les boutons apparaissent dès que vous activez Les boutons lancent des sauvegardes. Une nouvelle installation l'a désactivé. Ils suivent les mêmes limites que les lancements via l'API. En plus, BombVault ne traite qu'un appui à la fois par section et au plus six par minute, et ignore un appui que le broker a gardé comme message retenu. Toute personne qui peut publier sur le broker peut appuyer dessus, protégez donc le broker par un mot de passe.
BombVault lit son état toutes les 15 secondes et le publie quand quelque chose a changé, en JSON sous <prefix>/<node>/state. Le préfixe est bombvault tant que vous ne le changez pas, et le nœud est un court identifiant que BombVault choisit une fois. Les messages de découverte vont au préfixe par défaut de Home Assistant, homeassistant. Les deux sont retenus. Un dernier message (last will) marque l'appareil comme indisponible si BombVault s'arrête sans prévenir. Désactiver la liaison retire l'appareil et ses entités de Home Assistant.
Exemple : une carte et une alerte¶
Home Assistant fabrique les identifiants d'entités à partir des noms, l'appareil BombVault reçoit donc des identifiants comme sensor.bombvault_status. Avec un nom d'instance entre parenthèses, les identifiants le portent aussi, vérifiez-les donc d'abord sous Developer Tools, States. Une carte pour le tableau de bord :
type: entities
title: Backups
entities:
- sensor.bombvault_status
- sensor.bombvault_running_job
- sensor.bombvault_open_anomalies
- sensor.bombvault_next_scheduled_backup
Une automatisation qui prévient votre téléphone quand l'état passe à failed ou overdue :
alias: BombVault needs you
trigger:
- platform: state
entity_id: sensor.bombvault_status
to:
- failed
- overdue
action:
- service: notify.mobile_app_my_phone
data:
message: "BombVault status: {{ trigger.to_state.state }}. Open the overview."
Prometheus¶
Exposer /metrics dans la carte Services sous Paramètres, Intégrations sert l'état des sauvegardes, les tailles et les horodatages pour Prometheus, Grafana ou Uptime Kuma, sur /metrics au port de l'interface web. C'est désactivé par défaut. Jeton de scrape (facultatif) fait envoyer un jeton bearer par le scraper. Les étiquettes ne contiennent ni secrets ni chemins.
Widget de tableau de bord¶
La carte Widget de tableau de bord sous Paramètres, Intégrations génère un jeton en lecture seule et vous donne une adresse pour tout tableau de bord qui affiche une iframe, comme Homepage, Organizr ou Heimdall. L'adresse ouvre une petite page sur /widget avec seulement le journal d'activité en direct. Le jeton donne accès à ce journal et à rien d'autre, et Désactiver le révoque aussitôt. La page intégrée n'existe qu'en anglais.
Trouver BombVault sur le réseau¶
BombVault annonce son interface web sur le réseau local via mDNS, le protocole derrière Bonjour et Avahi. Un navigateur l'atteint alors sous https://bombvault.local:3443, ou http://bombvault.local:3000 avec HTTP_ONLY, et les explorateurs de services le listent comme service web avec le sous-type _bombvault. Ses enregistrements TXT portent la version et le chemin. Le réglage est Trouver sur le réseau, dans la carte Services sous Paramètres, Intégrations, et il est activé par défaut. Si un autre appareil utilise déjà le nom, BombVault prend bombvault-2.local et ainsi de suite, et la carte affiche l'adresse obtenue. Quand BombVault s'arrête ou que vous désactivez l'annonce, il le signale au réseau, et les navigateurs retirent l'entrée aussitôt.
L'annonce atteint ou non votre réseau selon la façon dont le conteneur est connecté :
- bridge, le réglage par défaut du modèle Unraid : l'annonce reste dans le réseau de Docker et personne sur le réseau local ne la voit. Ouvrez BombVault par l'adresse de l'hôte, comme avant.
- br0 ou un autre réseau macvlan ou ipvlan : le conteneur a sa propre adresse sur le réseau local, et l'annonce l'atteint.
- host : l'annonce sort par les interfaces de l'hôte, à côté de celle d'Unraid. Les ponts de Docker et de libvirt sont laissés de côté.
Seules les adresses IPv4 sont annoncées.