API en integraties¶
BombVault heeft een kleine HTTP-API voor scripts, dashboards en domotica. Die leest hetzelfde als wat het overzicht toont en kan een back-up starten. Al het andere, zoals herstellen, back-ups verwijderen, instellingen en nodes, blijft in de webinterface.
Tokens¶
Elke aanvraag heeft een API-token nodig, ook als er geen inlogwachtwoord is. Maak er een aan onder Instellingen, Integraties, API-tokens:
- Typ een naam die zegt waar het token gebruikt wordt, bijvoorbeeld "Home Assistant" of "Uptime Kuma".
- Zet Back-ups laten starten aan als het token back-ups moet kunnen starten. Zonder die schakelaar kan het token alleen lezen.
- Klik op Token aanmaken. Het token wordt één keer getoond. BombVault bewaart er alleen een vingerafdruk van, dus kopieer het nu.
Stuur het token mee in een header, als Authorization: Bearer <token> of als X-API-Key: <token>. Een token begint met bvapi_. Het opent alleen de API: een MCP-sleutel werkt hier niet, en een token werkt niet voor MCP.
Elk token heeft een tegel met zijn naam, of het back-ups mag starten, de laatste vier tekens, wanneer en vanwaar het voor het laatst is gebruikt en zijn aanroepen van vandaag. Op de tegel kun je het hernoemen, wijzigen wat het mag, vervangen of intrekken. Logboek toont de back-ups die het startte en zijn recente aanroepen. Als je de configuratie van BombVault uit een back-up herstelt, worden alle tokens ingetrokken, want de back-up kan tokens bevatten die je later hebt ingetrokken.
Zonder inlogwachtwoord kan iedereen die de webinterface kan openen ook een token aanmaken. Open je BombVault onder een naam die publiek lijkt en is er geen wachtwoord ingesteld, dan kunnen er vanaf dat adres geen tokens worden aangemaakt. Dat is dezelfde regel als bij MCP-sleutels.
Eindpunten¶
| Route | Wat het teruggeeft of doet | Token |
|---|---|---|
GET /api/v1/health |
Versie, instantienaam, of er een back-up loopt en wat dit token mag | lezen |
GET /api/v1/status |
Beschermingsstatus per onderdeel: laatste geslaagde back-up, verwacht interval, controles, volgende geplande runs | lezen |
GET /api/v1/activity |
Wat er nu loopt, met fase en percentage | lezen |
GET /api/v1/items |
Elk beschermd item met zijn planning, wat een back-up stillegt en zijn laatste back-up. ?domain= voor één onderdeel |
lezen |
GET /api/v1/runs |
Uitvoeringsgeschiedenis, nieuwste eerst. Filters limit, domain, item, status, kind, since |
lezen |
GET /api/v1/anomalies |
Anomalieën met een samenvatting van wat openstaat. Filters state, severity, domain, limit |
lezen |
GET /api/v1/anomalies/{id} |
Eén anomalie | lezen |
GET /api/v1/storage/{domain} |
Groottegeschiedenis, groei per week en vrije ruimte van elk repository van een onderdeel | lezen |
POST /api/v1/backups |
Maakt een back-up van één item ({"domain":"containers","item":"plex"}) of van een heel onderdeel ({"domain":"vms"}) |
starten |
POST /api/v1/backups/everything |
Start de ronde Nu alles back-uppen | starten |
POST /api/v1/runs/{id}/cancel |
Breekt een lopende back-up af die dit token startte | starten |
De onderdelen zijn containers, vms, files, zfs, flash en config. Tijden zijn Unix-seconden. De antwoorden zijn dezelfde als die van de MCP-tools met dezelfde naam, zodat beide gelijk blijven.
Een gestarte back-up is dezelfde back-up als die de webinterface start: een draaiende container wordt stilgelegd tot zijn back-up klaar is. De aanvraag komt meteen terug, en /api/v1/activity en /api/v1/runs laten zien hoe het gaat.
Voorbeelden¶
# 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
Heb je het eigen zelfondertekende certificaat van BombVault, voeg dan --cacert bombvault-cert.pem toe (het bestand dat Certificaat downloaden op de MCP-kaart geeft) of gebruik -k op een netwerk dat je vertrouwt.
Fouten en grenzen¶
Een fout komt terug als {"error": {"code": "...", "message": "..."}} met de bijbehorende status:
| Status | Codes | Betekenis |
|---|---|---|
| 400 | invalid_argument, ambiguous |
Een argument ontbreekt of klopt niet |
| 401 | no_token, invalid_token |
Geen token, of geen actief token |
| 403 | not_permitted, forbidden_origin |
Het token mag alleen lezen, de run is niet door dit token gestart, of het verzoek kwam van een pagina met een andere oorsprong |
| 404 | not_found |
Zo'n item, run of anomalie bestaat niet |
| 409 | busy, domain_off, nothing_to_back_up, not_running |
Er loopt al iets anders, het onderdeel staat uit, of er is niets te doen |
| 429 | throttled, rate_limited, cooldown, retention_guard |
Een limiet houdt de aanvraag tegen. Retry-After zegt wanneer je het opnieuw kunt proberen |
Starts volgen dezelfde limieten als starts via MCP: 12 per uur per token, 15 minuten tussen twee starts van hetzelfde item, hoogstens 4 starts van een item in 24 uur, en de bewaarbescherming. De laatste drie tellen starts via MCP, de API en Home Assistant samen. Een token mag 120 aanvragen per minuut doen. Na vijf mislukte pogingen vanaf één adres is dat adres een minuut geblokkeerd.
OpenAPI¶
BombVault levert een beschrijving van deze routes op /api/v1/openapi.json (OpenAPI 3.1). Daar is geen token voor nodig. Laad hem in Swagger UI, Postman of een codegenerator.
Nodes¶
De routes waarmee je nodes beheert, horen bij de webinterface, niet bij de token-API hierboven. Met een inlogwachtwoord ingesteld vragen ze een browsersessie uit een aanmelding op deze instantie. Een API-token of een MCP-sleutel opent er geen enkele, gekoppelde telefoons bereiken ze niet, en /api/v1/openapi.json beschrijft ze niet. Een node toevoegen, zijn compose-bestand opnieuw tonen en de eigen routes van een node bereiken worden geweigerd tot er een inlogwachtwoord is ingesteld. Een script dat iets wijzigt, stuurt Content-Type: application/json, zoals overal in de webinterface.
| Route | Wat het doet |
|---|---|
GET /api/nodes |
Elke node, met of hij online is, zijn versie, waar zijn back-ups heen gaan, de planning van elk onderdeel, zijn laatste back-up, zijn fouten en zijn openstaande anomalieën |
POST /api/nodes |
Voegt een node toe, zoals {"name":"vps-helsinki"}, en geeft hem terug met compose: MODE, APP_KEY, NODE_HOME en NODE_NAME |
POST /api/nodes/{id}/compose |
Geeft dezelfde compose-waarden opnieuw terug, voor Vervangen |
POST /api/nodes/{id}/placement |
Stuurt de back-ups van de node naar een bestemming en zegt per onderdeel of de node zijn repository bereikte, met een warning bij een bestemming |
PUT /api/nodes/{id}/schedule |
Stelt de planningen in, zoals {"containers":"daily 03:00","files":"off"}. Een onderdeel dat ontbreekt, houdt zijn planning |
DELETE /api/nodes/{id} |
Geeft de node vrij. told zegt of hij het nu hoorde of het hoort zodra hij terug is |
GET /api/nodes/routes |
De lijst met eigen routes van de node waaraan de thuisinstantie verzoeken doorgeeft |
GET, POST, PATCH /api/nodes/{id}/api/{path} |
Geeft het verzoek door aan de route /api/{path} van de node als die route op de lijst staat, en geeft het JSON-antwoord van de node terug |
PUT /api/receiver/node-address |
Stelt het Adres voor nodes van de ontvangserver in, zoals {"url":"https://backup.tower.example.org","caPem":""}. Een lege url haalt de nodes van de server af |
De drie bestemmingen:
{"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"}
Een verzoek aan /api/nodes/{id}/api/... draagt hoogstens 32 KiB. Een route die niet op de lijst staat, antwoordt 403, een node die nog niet heeft geantwoord of die wordt vrijgegeven 409 met de code node-not-adopted, en een node die weg is 502 met de code node-away. Zo geeft GET /api/nodes/{id}/api/runs?limit=20 de laatste 20 runs van de node terug, en maakt POST /api/nodes/{id}/api/containers/nextcloud/backup een back-up van zijn container nextcloud.
Home Assistant¶
BombVault kan in Home Assistant als apparaat verschijnen, via MQTT-discovery. Home Assistant heeft daarvoor zijn MQTT-integratie en een broker nodig, bijvoorbeeld de Mosquitto-add-on. Een eigen component is niet nodig.
- Open in BombVault Instellingen, Integraties en zet in de kaart Diensten Home Assistant aan. De velden voor de broker verschijnen eronder.
- Vul het adres en de poort van de broker in, en gebruikersnaam en wachtwoord als hij daarom vraagt. Zet TLS gebruiken aan als de broker TLS spreekt, meestal op poort 8883. Zijn certificaat moet geldig zijn voor het adres dat je invulde. Verander je het adres, de poort of de gebruikersnaam, voer dan het wachtwoord opnieuw in: BombVault geeft het opgeslagen wachtwoord niet door aan een andere broker of gebruiker.
- Klik op Opslaan. De rij laat zien wanneer de verbinding staat.
Het apparaat heet BombVault, of BombVault met de instantienaam tussen haakjes, en heeft deze entiteiten:
| Entiteit | Wat die toont |
|---|---|
| Status | ok, warning, overdue, failed of off, de slechtste van de ingeschakelde onderdelen. Een onderdeel dat op zijn eerste back-up wacht, telt pas mee zodra die back-up aan de beurt was, en alleen een actueel onderdeel maakt de status ok. overdue betekent, net als in het overzicht, dat de laatste back-up van een onderdeel ouder is dan twee intervallen |
| Running job | Wat er nu loopt, of idle |
| Open anomalies | Hoeveel anomalieën openstaan |
| Next scheduled backup | Wanneer de volgende geplande back-up start |
| Domain last backup | Wanneer de laatste geslaagde back-up van het onderdeel liep |
| Domain last result | Hoe zijn laatste back-up afliep |
| Domain repository free space | De vrije ruimte waar zijn primaire repository staat, als BombVault die kan lezen |
| Back up domain | Een knop die het hele onderdeel back-upt |
Elk ingeschakeld onderdeel krijgt eigen entiteiten, en een onderdeel dat je uitzet, verliest ze. De knoppen verschijnen zodra je Knoppen starten back-ups inschakelt. Op een nieuwe installatie staat dat uit. Ze volgen dezelfde limieten als starts via de API. Daarnaast verwerkt BombVault per onderdeel één druk tegelijk en hoogstens zes per minuut, en negeert het een druk die de broker als retained bericht heeft bewaard. Iedereen die op de broker mag publiceren, kan op de knoppen drukken, dus geef de broker een wachtwoord.
BombVault leest zijn status elke 15 seconden en publiceert die als er iets is veranderd, als JSON onder <prefix>/<node>/state. De prefix is bombvault zolang je hem niet wijzigt, en de node is een korte id die BombVault eenmalig kiest. De discovery-berichten gaan naar de standaardprefix homeassistant van Home Assistant. Beide worden bewaard (retained). Een last will markeert het apparaat als niet beschikbaar als BombVault stopt zonder zich af te melden. Zet je de koppeling uit, dan verwijdert BombVault het apparaat en zijn entiteiten uit Home Assistant.
Voorbeeld: een kaart en een melding¶
Home Assistant maakt de entiteit-id's van de namen, dus het apparaat van BombVault krijgt id's zoals sensor.bombvault_status. Staat er een instantienaam tussen haakjes, dan zit die ook in de id's. Controleer ze dus eerst onder Developer Tools, States. Een kaart voor het dashboard:
type: entities
title: Backups
entities:
- sensor.bombvault_status
- sensor.bombvault_running_job
- sensor.bombvault_open_anomalies
- sensor.bombvault_next_scheduled_backup
Een automatisering die je telefoon een bericht stuurt als de status op failed of overdue springt:
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¶
/metrics beschikbaar maken in de kaart Diensten onder Instellingen, Integraties levert back-upstatus, groottes en tijdstempels voor Prometheus, Grafana of Uptime Kuma, op /metrics op de poort van de webinterface. Het staat standaard uit. Met Scrape-token (optioneel) moet de scraper een bearer-token meesturen. De labels bevatten geen geheimen en geen paden.
Dashboardwidget¶
De kaart Dashboardwidget onder Instellingen, Integraties maakt een token om alleen te lezen en geeft je een adres voor elk dashboard dat een iframe toont, zoals Homepage, Organizr of Heimdall. Het adres opent een kleine pagina op /widget met alleen het live activiteitenlogboek. Het token geeft toegang tot dat logboek en tot niets anders, en Uitschakelen trekt het meteen in. De ingebedde pagina is alleen in het Engels beschikbaar.
BombVault vinden op het netwerk¶
BombVault maakt zijn webinterface via mDNS bekend op het lokale netwerk, het protocol achter Bonjour en Avahi. Een browser bereikt het dan als https://bombvault.local:3443, of als http://bombvault.local:3000 met HTTP_ONLY, en servicebrowsers tonen het als webdienst met het subtype _bombvault. De TXT-records bevatten de versie en het pad. De schakelaar is Vinden op het netwerk in de kaart Diensten onder Instellingen, Integraties en staat standaard aan. Gebruikt een ander apparaat de naam al, dan neemt BombVault bombvault-2.local enzovoort, en de kaart toont het adres dat het kreeg. Stopt BombVault of zet je de aankondiging uit, dan meldt het zich af op het netwerk en halen browsers de vermelding meteen weg.
Of de aankondiging je netwerk bereikt, hangt af van hoe de container is verbonden:
- bridge, de standaard in de Unraid-template: de aankondiging blijft binnen het Docker-netwerk en niemand op het LAN ziet haar. Open BombVault zoals voorheen via het adres van de host.
- br0 of een ander macvlan- of ipvlan-netwerk: de container heeft een eigen adres op het LAN en de aankondiging bereikt het.
- host: de aankondiging gaat via de interfaces van de host naar buiten, naast die van Unraid zelf. De bridges van Docker en libvirt slaat ze over.
Alleen IPv4-adressen worden bekendgemaakt.