Gå til innhold

API og integrasjoner

BombVault har et lite HTTP-API for skript, dashbord og hjemmeautomasjon. Det leser det samme som oversikten viser, og kan starte en sikkerhetskopi. Alt annet, som gjenoppretting, sletting av kopier, innstillinger og noder, blir i nettgrensesnittet.

Tokener

Hver forespørsel trenger et API-token, også når det ikke er satt noe innloggingspassord. Lag et under Innstillinger, Integrasjoner, API-tokener:

  1. Skriv et navn som sier hvor tokenet brukes, for eksempel «Home Assistant» eller «Uptime Kuma».
  2. Slå på Tillat å starte sikkerhetskopier hvis tokenet skal kunne starte kopier. Uten det kan det bare lese.
  3. Klikk Lag token. Tokenet vises én gang. BombVault tar bare vare på et fingeravtrykk av det, så kopier det nå.

Send tokenet i en header, enten Authorization: Bearer <token> eller X-API-Key: <token>. Et token begynner med bvapi_. Det åpner bare API-et: en MCP-nøkkel virker ikke her, og et token virker ikke for MCP.

Hvert token har en flis med navnet, om det kan starte kopier, de fire siste tegnene, når og hvorfra det sist ble brukt, og dagens kall. På flisen kan du gi det nytt navn, endre hva det får gjøre, bytte det eller tilbakekalle det. Logg viser kopiene det startet og de siste kallene. Gjenoppretter du BombVaults konfigurasjon fra en kopi, blir alle tokener tilbakekalt, fordi kopien kan inneholde tokener du har tilbakekalt senere.

Uten innloggingspassord kan alle som kan åpne nettgrensesnittet, også lage et token. Åpner du BombVault under et navn som ser offentlig ut, og det ikke er satt noe passord, kan det ikke lages tokener fra den adressen, samme regel som for MCP-nøklene.

Endepunkter

Rute Hva den returnerer eller gjør Token
GET /api/v1/health Versjon, instansnavn, om en kopi kjører, og hva dette tokenet får gjøre lese
GET /api/v1/status Beskyttelsesstatus per område: siste vellykkede kopi, forventet intervall, kontroller, neste planlagte kjøringer lese
GET /api/v1/activity Hva som kjører akkurat nå, med fase og prosent lese
GET /api/v1/items Hvert beskyttet element med tidsplan, hva en kopi stopper og siste kopi. ?domain= for ett område lese
GET /api/v1/runs Kjørehistorikk, nyeste først. Filtre limit, domain, item, status, kind, since lese
GET /api/v1/anomalies Anomalier med en oversikt over de åpne. Filtre state, severity, domain, limit lese
GET /api/v1/anomalies/{id} Én anomali lese
GET /api/v1/storage/{domain} Størrelseshistorikk, vekst per uke og ledig plass for hvert repository i et område lese
POST /api/v1/backups Tar kopi av ett element ({"domain":"containers","item":"plex"}) eller et helt område ({"domain":"vms"}) starte
POST /api/v1/backups/everything Kjører Full sikkerhetskopi starte
POST /api/v1/runs/{id}/cancel Avbryter en kjørende kopi som dette tokenet startet starte

Områdene heter containers, vms, files, zfs, flash og config. Tider er Unix-sekunder. Svarene er de samme som fra MCP-verktøyene med samme navn, så de to følger hverandre.

En kopi som startes her, er den samme som nettgrensesnittet starter: en container som kjører, stoppes til kopien er ferdig. Forespørselen svarer med en gang, og /api/v1/activity og /api/v1/runs viser hvordan det går.

Eksempler

# Hvordan står det til med sikkerhetskopiene?
curl -s -H "Authorization: Bearer $BOMBVAULT_TOKEN" https://tower:3443/api/v1/status

# Ta kopi av én container nå.
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

Med BombVaults eget selvsignerte sertifikat legger du til --cacert bombvault-cert.pem (filen fra Last ned sertifikat på MCP-kortet) eller -k på et nettverk du stoler på.

Feil og grenser

En feil kommer tilbake som {"error": {"code": "...", "message": "..."}} med tilhørende status:

Status Koder Betydning
400 invalid_argument, ambiguous Et argument mangler eller er feil
401 no_token, invalid_token Intet token, eller ikke et aktivt
403 not_permitted, forbidden_origin Tokenet kan bare lese, eller det startet ikke kjøringen, eller forespørselen kom fra en side med en annen opprinnelse
404 not_found Ikke noe slikt element, kjøring eller anomali
409 busy, domain_off, nothing_to_back_up, not_running Noe annet kjører, området er slått av, eller det er ingenting å gjøre
429 throttled, rate_limited, cooldown, retention_guard En grense holder forespørselen tilbake. Retry-After sier når du kan prøve igjen

Starter følger de samme grensene som starter via MCP: 12 i timen per token, 15 minutter mellom to starter av samme element, høyst 4 starter av ett element på 24 timer, og oppbevaringsvernet. De tre siste teller starter via MCP, via API-et og fra Home Assistant sammen. Et token kan gjøre 120 forespørsler i minuttet. Fem mislykkede forsøk fra én adresse sperrer den i ett minutt.

OpenAPI

BombVault leverer en beskrivelse av disse rutene på /api/v1/openapi.json (OpenAPI 3.1). Den krever ikke noe token. Last den inn i Swagger UI, Postman eller en kodegenerator.

Noder

Rutene som styrer noder, hører til nettgrensesnittet, ikke til token-API-et ovenfor. Med et påloggingspassord satt krever de en nettleserøkt fra en pålogging på denne instansen. Et API-token eller en MCP-nøkkel åpner ingen av dem, parede telefoner når dem ikke, og /api/v1/openapi.json beskriver dem ikke. Å legge til en node, vise compose-filen dens på nytt og nå nodens egne ruter avvises til et påloggingspassord er satt. Et skript som endrer noe, sender Content-Type: application/json, som overalt i nettgrensesnittet.

Rute Hva den gjør
GET /api/nodes Hver node med om den er tilkoblet, versjonen, hvor sikkerhetskopiene går, planen for hvert område, den siste sikkerhetskopien, feilene og de åpne avvikene
POST /api/nodes Legger til en node, som {"name":"vps-helsinki"}, og returnerer den med compose: MODE, APP_KEY, NODE_HOME og NODE_NAME
POST /api/nodes/{id}/compose Returnerer de samme compose-verdiene på nytt, for Erstatt
POST /api/nodes/{id}/placement Sender sikkerhetskopiene til noden til et mål og svarer per område om noden nådde repositoryet sitt, med en warning for et mål
PUT /api/nodes/{id}/schedule Setter planene, som {"containers":"daily 03:00","files":"off"}. Et område som er utelatt, beholder planen sin
DELETE /api/nodes/{id} Frigir noden. told sier om den fikk vite det nå eller får vite det når den er tilbake
GET /api/nodes/routes Listen over nodens egne ruter som hjemmeinstansen sender forespørsler videre til
GET, POST, PATCH /api/nodes/{id}/api/{path} Sender forespørselen videre til nodens rute /api/{path} når den ruten står på listen, og returnerer JSON-svaret fra noden
PUT /api/receiver/node-address Setter Adresse for noder for mottaksserveren, som {"url":"https://backup.tower.example.org","caPem":""}. En tom url tar nodene av den

De tre målene:

{"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"}

En forespørsel til /api/nodes/{id}/api/... bærer høyst 32 KiB. En rute som ikke står på listen, svarer 403, en node som ikke har svart ennå eller holder på å bli frigitt, 409 med koden node-not-adopted, og en node som er borte, 502 med koden node-away. For eksempel returnerer GET /api/nodes/{id}/api/runs?limit=20 de 20 siste kjøringene til noden, og POST /api/nodes/{id}/api/containers/nextcloud/backup tar sikkerhetskopi av containeren nextcloud på noden.

Home Assistant

BombVault kan dukke opp i Home Assistant som en enhet, via MQTT-discovery. Home Assistant trenger MQTT-integrasjonen sin og en megler, for eksempel Mosquitto-tillegget. Ingen egen komponent trengs.

  1. Åpne Innstillinger, Integrasjoner i BombVault og slå på Home Assistant i kortet Tjenester. Feltene for megleren vises under.
  2. Skriv inn adressen og porten til megleren, og brukernavn og passord hvis den ber om det. Slå på Bruk TLS hvis megleren bruker TLS, som regel på port 8883. Sertifikatet må være gyldig for adressen du skrev inn. Endrer du adressen, porten eller brukernavnet, må du skrive inn passordet på nytt: BombVault gir ikke det lagrede videre til en annen megler eller bruker.
  3. Klikk Lagre. Raden viser når tilkoblingen er oppe.

Enheten heter BombVault, eller BombVault med instansnavnet i parentes, og har disse entitetene:

Entitet Hva den viser
Status ok, warning, overdue, failed eller off, det verste av områdene som er slått på. Et område som venter på sin første sikkerhetskopi, teller først når den skulle ha kjørt, og bare et oppdatert område gir statusen ok. overdue betyr, som i oversikten, at den siste sikkerhetskopien av et område er eldre enn to intervaller
Running job Hva som kjører nå, eller idle
Open anomalies Hvor mange anomalier som er åpne
Next scheduled backup Når neste planlagte kopi starter
Område last backup Når den siste vellykkede kopien av området kjørte
Område last result Hvordan den siste kopien endte
Område repository free space Ledig plass der det primære repositoryet ligger, hvis BombVault kan lese den
Back up område En knapp som tar kopi av hele området

Navnene på entitetene er på engelsk, fordi Home Assistant tar dem slik BombVault sender dem. Hvert område som er slått på, får egne entiteter, og et område du slår av, mister dem. Knappene dukker opp når du slår på Knapper starter sikkerhetskopier. Den er av i en ny installasjon. De følger de samme grensene som starter via API-et. I tillegg tar BombVault imot ett trykk om gangen per område og høyst seks i minuttet, og ser bort fra et trykk som megleren har lagret som retained-melding. Alle som kan publisere på megleren, kan trykke på dem, så gi megleren et passord.

BombVault leser statusen sin hvert 15. sekund og publiserer den når noe har endret seg, som JSON under <prefiks>/<node>/state. Prefikset er bombvault så lenge du ikke endrer det, og noden er en kort id BombVault velger én gang. Discovery-meldingene går til standardprefikset homeassistant i Home Assistant. Begge beholdes (retained). En last will merker enheten som utilgjengelig hvis BombVault stopper uten å si fra. Slår du forbindelsen av, fjerner BombVault enheten og entitetene fra Home Assistant.

Eksempel: et kort og en varsling

Home Assistant lager entitets-id-ene av navnene, så enheten BombVault får id-er som sensor.bombvault_status. Med et instansnavn i parentes følger det også med i id-ene, så sjekk dem først under Developer Tools, States. Et kort til dashbordet:

type: entities
title: Backups
entities:
  - sensor.bombvault_status
  - sensor.bombvault_running_job
  - sensor.bombvault_open_anomalies
  - sensor.bombvault_next_scheduled_backup

En automasjon som sier fra til telefonen når statusen blir failed eller 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

Eksponer /metrics i kortet Tjenester under Innstillinger, Integrasjoner leverer kopistatus, størrelser og tidsstempler til Prometheus, Grafana eller Uptime Kuma, på /metrics på porten til nettgrensesnittet. Den er av fra start. Scrape-token (valgfritt) får skraperen til å sende et bearer-token. Etikettene inneholder ingen hemmeligheter og ingen stier.

Dashbord-widget

Kortet Dashbord-widget under Innstillinger, Integrasjoner lager et skrivebeskyttet token og gir deg en adresse til et hvilket som helst dashbord som viser en iframe, for eksempel Homepage, Organizr eller Heimdall. Adressen åpner en liten side på /widget med bare den levende aktivitetsloggen. Tokenet gir tilgang til loggen og ingenting annet, og Deaktiver tilbakekaller det med en gang. Den innebygde siden er bare på engelsk.

Finn BombVault på nettverket

BombVault kunngjør nettgrensesnittet sitt på det lokale nettverket via mDNS, protokollen bak Bonjour og Avahi. En nettleser når den da som https://bombvault.local:3443, eller http://bombvault.local:3000 med HTTP_ONLY, og tjenestelesere viser den som nettjeneste med undertypen _bombvault. TXT-postene inneholder versjonen og stien. Bryteren er Finn på nettverket i kortet Tjenester under Innstillinger, Integrasjoner og er slått på fra start. Bruker en annen enhet allerede navnet, tar BombVault bombvault-2.local og så videre, og kortet viser adressen den fikk. Når BombVault stopper eller du slår kunngjøringen av, sier den fra på nettverket, og nettlesere fjerner oppføringen med en gang.

Om kunngjøringen når nettverket ditt, avhenger av hvordan containeren er koblet til:

  • bridge, standarden i Unraid-malen: kunngjøringen blir i Dockers nettverk, og ingen på LAN-et ser den. Åpne BombVault på vertens adresse som før.
  • br0 eller et annet macvlan- eller ipvlan-nettverk: containeren har sin egen adresse på LAN-et, og kunngjøringen når det.
  • host: kunngjøringen går ut over vertens grensesnitt, ved siden av Unraids egen. Broene til Docker og libvirt holdes utenfor.

Bare IPv4-adresser kunngjøres.