Ga naar inhoud

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:

  1. Typ een naam die zegt waar het token gebruikt wordt, bijvoorbeeld "Home Assistant" of "Uptime Kuma".
  2. Zet Back-ups laten starten aan als het token back-ups moet kunnen starten. Zonder die schakelaar kan het token alleen lezen.
  3. 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.

  1. Open in BombVault Instellingen, Integraties en zet in de kaart Diensten Home Assistant aan. De velden voor de broker verschijnen eronder.
  2. 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.
  3. 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.