Gå til indholdet

API og integrationer

BombVault har et lille HTTP-API til scripts, dashboards og hjemmeautomatisering. Det læser det samme, som oversigten viser, og kan starte en sikkerhedskopi. Alt andet, som gendannelser, sletning af kopier, indstillinger og noder, bliver i brugerfladen.

Tokens

Hver forespørgsel skal have et API-token, også når der ikke er sat en adgangskode. Opret et under Indstillinger, Integrationer, API-tokens:

  1. Skriv et navn, der siger, hvor tokenet bruges, for eksempel "Home Assistant" eller "Uptime Kuma".
  2. Slå Tillad at starte sikkerhedskopier til, hvis tokenet skal kunne starte kopier. Uden det kan det kun læse.
  3. Klik på Opret token. Tokenet vises én gang. BombVault gemmer kun et fingeraftryk af det, så kopiér det nu.

Send tokenet i en header, enten Authorization: Bearer <token> eller X-API-Key: <token>. Et token starter med bvapi_. Det åbner kun API'et: en MCP-nøgle virker ikke her, og et token virker ikke til MCP.

Hvert token har en flise med navnet, om det må starte kopier, de sidste fire tegn, hvornår og hvorfra det sidst blev brugt, og dagens kald. På flisen kan du omdøbe det, ændre hvad det må, udskifte det eller tilbagekalde det. Log viser de kopier, det startede, og dets seneste kald. Gendanner du BombVaults konfiguration fra en kopi, tilbagekaldes alle tokens, fordi kopien kan indeholde tokens, du har tilbagekaldt siden.

Uden adgangskode kan alle, der kan åbne brugerfladen, også oprette et token. Åbner du BombVault under et navn, der ser offentligt ud, og er der ingen adgangskode, kan der ikke oprettes tokens fra den adresse, ligesom med MCP-nøglerne.

Endepunkter

Rute Hvad den returnerer eller gør Token
GET /api/v1/health Version, instansnavn, om en kopi kører, og hvad dette token må læse
GET /api/v1/status Beskyttelsesstatus pr. område: seneste vellykkede kopi, forventet interval, kontroller, næste planlagte kørsler læse
GET /api/v1/activity Hvad der kører lige nu, med fase og procent læse
GET /api/v1/items Hvert beskyttet element med tidsplan, hvad en kopi stopper, og seneste kopi. ?domain= for ét område læse
GET /api/v1/runs Kørselshistorik, nyeste først. Filtre limit, domain, item, status, kind, since læse
GET /api/v1/anomalies Afvigelser med et overblik over de åbne. Filtre state, severity, domain, limit læse
GET /api/v1/anomalies/{id} Én afvigelse læse
GET /api/v1/storage/{domain} Størrelseshistorik, vækst pr. uge og ledig plads for hvert repository i et område læse
POST /api/v1/backups Sikkerhedskopierer ét element ({"domain":"containers","item":"plex"}) eller et helt område ({"domain":"vms"}) starte
POST /api/v1/backups/everything Kører Fuld sikkerhedskopi starte
POST /api/v1/runs/{id}/cancel Afbryder en kørende kopi, som dette token startede starte

Områderne hedder containers, vms, files, zfs, flash og config. Tider er Unix-sekunder. Svarene er de samme som fra MCP-værktøjerne med samme navn, så de to følges ad.

En kopi, der startes her, er den samme, som brugerfladen starter: en kørende container stoppes, indtil dens kopi er færdig. Forespørgslen svarer med det samme, og /api/v1/activity og /api/v1/runs viser, hvordan det går.

Eksempler

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

# Sikkerhedskopiér én container nu.
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 selvsignerede certifikat tilføjer du --cacert bombvault-cert.pem (filen fra Hent certifikat på MCP-kortet) eller -k på et netværk, du stoler på.

Fejl og grænser

En fejl kommer tilbage som {"error": {"code": "...", "message": "..."}} med den tilsvarende status:

Status Koder Betydning
400 invalid_argument, ambiguous Et argument mangler eller er forkert
401 no_token, invalid_token Intet token, eller ikke et aktivt
403 not_permitted, forbidden_origin Tokenet må kun læse, eller det startede ikke kørslen, eller anmodningen kom fra en side med en anden oprindelse
404 not_found Intet sådant element, ingen sådan kørsel eller afvigelse
409 busy, domain_off, nothing_to_back_up, not_running Noget andet kører, området er slået fra, eller der er intet at gøre
429 throttled, rate_limited, cooldown, retention_guard En grænse holder forespørgslen tilbage. Retry-After siger, hvornår du kan prøve igen

Starter følger de samme grænser som starter via MCP: 12 i timen pr. token, 15 minutter mellem to starter af samme element, højst 4 starter af et element på 24 timer og opbevaringsbeskyttelsen. De sidste tre tæller starter via MCP, via API'et og fra Home Assistant sammen. Et token må lave 120 forespørgsler i minuttet. Fem mislykkede forsøg fra én adresse spærrer den i et minut.

OpenAPI

BombVault leverer en beskrivelse af disse ruter på /api/v1/openapi.json (OpenAPI 3.1). Den kræver intet token. Indlæs den i Swagger UI, Postman eller en kodegenerator.

Noder

Ruterne, der passer noder, hører til brugerfladen, ikke til token-API'et ovenfor. Med en login-adgangskode angivet kræver de en browsersession fra et login på denne instans. Et API-token eller en MCP-nøgle åbner ingen af dem, parrede telefoner når dem ikke, og /api/v1/openapi.json beskriver dem ikke. At tilføje en node, vise dens compose-fil igen og nå en nodes egne ruter afvises, indtil der er angivet en login-adgangskode. Et script, der ændrer noget, sender Content-Type: application/json, som overalt i brugerfladen.

Rute Hvad den gør
GET /api/nodes Hver node med, om den er online, dens version, hvor dens sikkerhedskopier går hen, planen for hvert område, dens seneste sikkerhedskopi, dens fejl og dens åbne afvigelser
POST /api/nodes Tilføjer 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-værdier igen, til Erstat
POST /api/nodes/{id}/placement Sender nodens sikkerhedskopier til en destination og svarer pr. område, om noden nåede sit repository, med en warning for en destination
PUT /api/nodes/{id}/schedule Sætter planerne, som {"containers":"daily 03:00","files":"off"}. Et område, der er udeladt, beholder sin plan
DELETE /api/nodes/{id} Frigiver noden. told siger, om den hørte det nu eller hører det, når den er tilbage
GET /api/nodes/routes Listen over nodens egne ruter, som hjemmeinstansen sender forespørgsler videre til
GET, POST, PATCH /api/nodes/{id}/api/{path} Sender forespørgslen videre til nodens rute /api/{path}, når den rute er på listen, og returnerer nodens JSON-svar
PUT /api/receiver/node-address Sætter modtageserverens Adresse til noder, som {"url":"https://backup.tower.example.org","caPem":""}. En tom url tager noderne af den

De tre destinationer:

{"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ørgsel til /api/nodes/{id}/api/... bærer højst 32 KiB. En rute, der ikke er på listen, svarer 403, en node, der ikke har svaret endnu eller er ved at blive frigivet, 409 med koden node-not-adopted, og en node, der er væk, 502 med koden node-away. For eksempel returnerer GET /api/nodes/{id}/api/runs?limit=20 nodens 20 seneste kørsler, og POST /api/nodes/{id}/api/containers/nextcloud/backup tager sikkerhedskopi af dens container nextcloud.

Home Assistant

BombVault kan vises i Home Assistant som en enhed via MQTT-discovery. Home Assistant skal bruge sin MQTT-integration og en broker, for eksempel Mosquitto-tilføjelsen. Der skal ikke installeres nogen egen komponent.

  1. Åbn Indstillinger, Integrationer i BombVault og slå Home Assistant til i kortet Tjenester. Felterne til brokeren kommer frem under den.
  2. Skriv brokerens adresse og port, og brugernavn og adgangskode, hvis den beder om dem. Slå Brug TLS til, hvis brokeren taler TLS, som regel på port 8883. Dens certifikat skal være gyldigt for den adresse, du skrev. Ændrer du adressen, porten eller brugernavnet, skal du indtaste adgangskoden igen: BombVault giver ikke den gemte videre til en anden broker eller bruger.
  3. Klik på Gem. Rækken viser, når forbindelsen er oppe.

Enheden hedder BombVault, eller BombVault med instansnavnet i parentes, og har disse entiteter:

Entitet Hvad den viser
Status ok, warning, overdue, failed eller off, det værste af de områder, der er slået til. Et område, der venter på sin første backup, tæller først, når den backup var planlagt, og kun et aktuelt område giver status ok. overdue betyder som i oversigten, at et områdes seneste backup er ældre end to intervaller
Running job Hvad der kører nu, eller idle
Open anomalies Hvor mange anomalier der er åbne
Next scheduled backup Hvornår den næste planlagte kopi starter
Område last backup Hvornår områdets seneste vellykkede kopi kørte
Område last result Hvordan dets seneste kopi endte
Område repository free space Ledig plads der, hvor dets primære repository ligger, hvis BombVault kan læse den
Back up område En knap, der sikkerhedskopierer hele området

Entiteternes navne er på engelsk, fordi Home Assistant overtager dem, som BombVault sender dem. Hvert område, der er slået til, får sine egne entiteter, og et område, du slår fra, mister dem. Knapperne dukker op, når du slår Knapper starter sikkerhedskopier til. En ny installation har det slået fra. De følger de samme grænser som starter via API'et. Derudover tager BombVault kun imod ét tryk ad gangen pr. område og højst seks i minuttet, og ser bort fra et tryk, som brokeren har gemt som retained-besked. Alle, der kan udgive på brokeren, kan trykke på dem, så giv brokeren en adgangskode.

BombVault læser sin status hvert 15. sekund og udgiver den, når noget har ændret sig, som JSON under <præfiks>/<node>/state. Præfikset er bombvault, så længe du ikke ændrer det, og noden er et kort id, som BombVault vælger én gang. Discovery-beskederne går til Home Assistants standardpræfiks homeassistant. Begge gemmes (retained). En last will markerer enheden som utilgængelig, hvis BombVault stopper uden at melde fra. Slår du forbindelsen fra, fjerner BombVault enheden og dens entiteter fra Home Assistant.

Eksempel: et kort og en alarm

Home Assistant laver entitets-id'erne ud fra navnene, så enheden BombVault får id'er som sensor.bombvault_status. Med et instansnavn i parentes bærer id'erne også det, så tjek dem først under Developer Tools, States. Et kort til dashboardet:

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

En automation, der giver din telefon besked, når status skifter til 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 Indstillinger, Integrationer leverer sikkerhedskopistatus, størrelser og tidsstempler til Prometheus, Grafana eller Uptime Kuma på /metrics på webgrænsefladens port. Det er slået fra som standard. Scrape-token (valgfrit) får scraperen til at sende et bearer-token. Labelsene indeholder ingen hemmeligheder og ingen stier.

Dashboard-widget

Kortet Dashboard-widget under Indstillinger, Integrationer laver et skrivebeskyttet token og giver dig en adresse til ethvert dashboard, der viser en iframe, for eksempel Homepage, Organizr eller Heimdall. Adressen åbner en lille side på /widget med kun den levende aktivitetslog. Tokenet giver adgang til den log og intet andet, og Deaktivér tilbagekalder det med det samme. Den indlejrede side er kun på engelsk.

Find BombVault på netværket

BombVault annoncerer sin brugerflade på det lokale netværk via mDNS, protokollen bag Bonjour og Avahi. En browser når den så som https://bombvault.local:3443, eller http://bombvault.local:3000 med HTTP_ONLY, og tjenestebrowsere viser den som webtjeneste med undertypen _bombvault. TXT-posterne indeholder versionen og stien. Kontakten er Find på netværket i kortet Tjenester under Indstillinger, Integrationer og er slået til fra start. Bruger en anden enhed allerede navnet, tager BombVault bombvault-2.local og så videre, og kortet viser den adresse, den fik. Når BombVault stopper, eller du slår annonceringen fra, melder den fra på netværket, så browsere fjerner posten med det samme.

Om annonceringen når dit netværk, afhænger af, hvordan containeren er forbundet:

  • bridge, standarden i Unraid-skabelonen: annonceringen bliver i Dockers netværk, og ingen på LAN'et ser den. Åbn BombVault på værtens adresse som før.
  • br0 eller et andet macvlan- eller ipvlan-netværk: containeren har sin egen adresse på LAN'et, og annonceringen når det.
  • host: annonceringen går ud over værtens interfaces ved siden af Unraids egen. Docker- og libvirt-broerne springes over.

Kun IPv4-adresser annonceres.