Configurazione

Questa pagina copre le variabili d'ambiente del container, i mount forniti dal template, il backup delle VM via SSH e la configurazione off-site. I percorsi dei repository di backup si configurano dentro l'app (Impostazioni, Archiviazione, Percorsi di backup), non tramite variabili d'ambiente.

Variabili d'ambiente

Variabile	Richiesta	Descrizione
APP_KEY	Sì	Segreto esadecimale di 32 byte (64 caratteri esadecimali) usato per derivare la password del repo restic. Genera con openssl rand -hex 32. Tienilo al sicuro: perderlo rende i backup cifrati irrecuperabili.
LIBVIRT_HOST	Per le VM e i dataset ZFS	Host Unraid raggiunto via SSH per il backup delle VM (predefinito host.docker.internal; il template precompila un placeholder di IP LAN). Usa l'IP LAN del tuo Unraid, richiesto su una rete br0.x personalizzata. Usato anche per i backup dei dataset ZFS (campo del template Host SSH: Address); il segnaposto 192.168.x.x conta come non impostato.
LIBVIRT_SSH_PORT	No	Porta SSH dell'host per il backup delle VM (predefinita 22). Campo del template Host SSH: Port, anche per i dataset ZFS.
LIBVIRT_SSH_USER	No	Utente SSH sull'host per il backup delle VM (predefinito root). Campo del template Host SSH: User, anche per i dataset ZFS.
LIBVIRT_URI	No	URI di connessione libvirt completo, usato testualmente al posto di comporne uno dalle tre variabili LIBVIRT_* sopra (che a quel punto vengono ignorate per la stringa di connessione). Predefinito non impostato. Necessario su TrueNAS Scale, il cui libvirtd resta in ascolto su un socket non standard che il formato costruito automaticamente non può esprimere: qemu+ssh://<user>@<truenas-host>/system?socket=/run/truenas_libvirt/libvirt-sock. Vedi la sezione TrueNAS Scale di docs/vm-backup-ssh-setup.md. Se è un URI qemu+ssh://, ognuna tra LIBVIRT_HOST, LIBVIRT_SSH_USER e LIBVIRT_SSH_PORT non impostata viene presa da lì, anche per i comandi SSH di BombVault stesso (trasferimento NVRAM, dataset ZFS).
PORT	No	Porta HTTP (predefinita 3000; usata solo con HTTP_ONLY=true).
HTTPS_PORT	No	Porta HTTPS (predefinita 3443; il template la pubblica 1:1, così la WebUI risponde su https://<ip>:3443).
HTTP_ONLY	No	Imposta true per disabilitare il listener HTTPS autofirmato e servire solo HTTP in chiaro (per l'uso dietro un reverse proxy che termina il TLS).
BIND_HOST	No	Indirizzo su cui ascolta la WebUI (predefinito 0.0.0.0, tutte le interfacce). Lascialo non impostato nel container, le cui porte pubblicate richiedono tutte le interfacce; 127.0.0.1 va bene per un'esecuzione fuori da Docker. L'healthcheck interroga lo stesso indirizzo.
TRUSTED_PROXY	No	Indirizzi o intervalli CIDR, separati da virgole, del reverse proxy davanti a BombVault (per esempio 192.168.20.11 o 10.0.0.0/8). Solo da questi hop l'intestazione X-Forwarded-For viene creduta, e il freno agli accessi conta allora i fallimenti per client reale invece di mettere tutti quelli dietro il proxy nello stesso secchio. Non impostato (predefinito) significa non fidarsi di nessuno: un'intestazione creduta senza condizioni lascerebbe a chiunque la scelta del proprio secchio.
HOST_SOURCE_ROOT	No	Il percorso host montato come Host Data (predefinito /mnt). BombVault traduce le origini dei bind-mount riportate da Docker in percorsi sotto questo mount. Cambia solo se hai montato una radice host diversa.
DATA_ROOT_SEGMENTS	No	Nomi di segmenti di percorso separati da virgola che contrassegnano una sorgente di bind-mount come dati di backup (predefinito appdata, in linea con la convenzione di Unraid /mnt/user/appdata/<container>). Il bind-mount di un container viene selezionato automaticamente per il backup quando QUALSIASI segmento elencato compare come segmento di percorso completo nella sua sorgente host: per esempio DATA_ROOT_SEGMENTS=appdata,config include anche un bind .../config. Vedi Rilevamento della sorgente di backup per gli altri modi, sempre attivi, con cui viene trovata la cartella dati di un container.
PLATFORM	No	Forza la piattaforma su cui BombVault si considera in esecuzione, invece di rilevarla automaticamente: unraid, generic o truenas (predefinito non impostato: rileva automaticamente Unraid cercando il suo marcatore dockerMan sotto il mount flash, altrimenti generic; anche un valore non riconosciuto ricade su generic, e viene registrato nei log). Impostala esplicitamente su un host Docker generico o su TrueNAS Scale invece di affidarti alla sonda automatica valida solo per Unraid (il compose file generico lo fa già). Cambia la convenzione di fallback di appdata, i valori predefiniti della destinazione di ripristino tra istanze diverse, e se vengono anche solo tentati i passaggi di notifica e del plugin companion disponibili solo su Unraid (vedi internal/platform).
BOMBVAULT_SELF_CONTAINER	No	Il nome del container BombVault stesso, così non esegue mai il backup (e quindi non ferma mai) se stesso.
BACKUP_MAX_HOURS	No	Numero massimo di ore reali per cui una singola esecuzione di backup può tenere il lock del suo dominio prima di essere forzatamente annullata (una salvaguardia così che un'esecuzione bloccata non possa bloccare il dominio per sempre). Vuoto (il predefinito) usa 48. Aumentalo per backup cloud molto grandi o lenti (un'esecuzione annullata al limite fallisce con context deadline exceeded). Imposta 0 per disabilitare del tutto il limite.
BACKUP_STALL_HOURS	No	Ore per cui un backup può restare senza alcun progresso prima di essere annullato. Vuoto (il predefinito) usa 2; imposta 0 per non annullare mai per uno stallo. È la più fine delle due salvaguardie e di solito quella che scatta: guarda se succede ancora qualcosa invece di quanto dura l'esecuzione, così un backup di più terabyte lento ma sano viene lasciato in pace, mentre uno bloccato su una condivisione che non risponde viene fermato in ore invece che in giorni. Dopo 30 minuti di silenzio viene scritto un avviso nel log, prima che venga annullato qualcosa. La scansione conta come progresso: restic non scrive byte mentre percorre un albero grande, e quella fase viene sorvegliata tramite i suoi totali di file e byte invece che tramite i byte scritti. Le due variabili sono indipendenti, e BACKUP_MAX_HOURS continua a limitare le fasi dopo il backup vero e proprio (conservazione, statistiche, copia off-site), dove non ci sono contatori da sorvegliare.
DB_DUMP_MAX_HOURS	No	Ore per cui un dump automatico di database può girare prima di essere fermato. Vuoto (il valore predefinito) usa 6; sono ammessi valori da 1 a 48, e il limite resta un'ora sotto BACKUP_MAX_HOURS (alla metà, quando questo è inferiore a due ore), così un dump lungo viene tagliato dal proprio limite e segnalato come tale invece di trascinarsi dietro il backup. Un dump che non avanza più viene fermato prima, dopo BACKUP_STALL_HOURS. Un dump fermato fallisce per conto suo e il backup del container prosegue. Su Unraid aggiungi la variabile al container BombVault con Add another Path, Port, Variable.
TZ	No	Fuso orario per lo scheduler (per esempio Europe/Berlin). Se non è impostato, tutte le pianificazioni vengono eseguite in UTC: una pianificazione alle 02:30 parte quindi alle 02:30 UTC e non secondo l'ora locale. Su Unraid non lo imposti mai tu: il sistema passa il proprio fuso orario a ogni container. Il log di avvio indica quale fuso è stato applicato. Un fuso con l'ora legale salta un'esecuzione in primavera e ne esegue una due volte in autunno; UTC non fa né l'una né l'altra cosa, ma due volte l'anno si sposta di un'ora rispetto al tuo orologio.

Mount

Monta il socket Docker, il flash (/boot) e la radice Host Data (/mnt) come mostrato nel template CA. Le origini e le destinazioni dei backup risiedono entrambe sotto Host Data, ed è montato slave così una condivisione remota che si monta dopo l'avvio del container (per esempio sotto /mnt/remotes) diventa visibile senza un riavvio.

Anche i backup dei dataset ZFS hanno bisogno di questa modalità: l'host monta lo snapshot di un dataset solo dopo l'avvio del container. Vedi Dataset ZFS.

I percorsi dei repository di backup hanno come predefinito /mnt/user/bombvault/{container,vms,flash,config,files,zfs}, creati al primo backup. Cambia la posizione in qualsiasi momento in Impostazioni, Archiviazione, Percorsi di backup. Ogni campo percorso ha anche un interruttore Locale / Remoto integrato: un percorso può essere un remote restic (s3:..., rest:..., sftp:..., rclone:...) invece di una cartella locale, e il backup va direttamente lì, senza una copia locale separata; vedi Repository primari remoti.

Verifica integrazione host

Apri /spike nell'interfaccia web dopo l'avvio del container. Sonda ogni mount e CLI (socket Docker, libvirt, restic, qemu-img, rclone) e segnala eventuali pezzi mancanti.

Rilevamento delle sorgenti di backup

Per ogni contenitore, BombVault sceglie da sé quali bind mount e volumi con nome salvare. Un percorso viene preso non appena vale uno dei punti seguenti (il risultato si può sempre correggere per singolo contenitore nelle sue Cartelle da salvare):

• Corrispondenza di un segmento di radice dati: l'origine host del bind contiene uno dei segmenti di DATA_ROOT_SEGMENTS come componente completa del percorso (per impostazione predefinita solo appdata).
• I volumi Docker con nome sono sempre inclusi, perché non hanno un equivalente usa e getta e quindi non c'è nulla da filtrare, ma soltanto quando il percorso di archiviazione reale del volume sull'host è raggiungibile attraverso il mount Host Data, esattamente come ogni altro percorso host salvato da BombVault. Il driver locale predefinito colloca un volume sotto la radice dati del demone, cioè /var/lib/docker/volumes/<nome>/_data salvo personalizzazioni (verificalo con docker info -f '{{.DockerRootDir}}'). Quel punto NON rientra nel mount Host Data stretto, a directory singola, che il docker-compose.yml generico usa per impostazione predefinita. Un volume irraggiungibile viene saltato in silenzio, non è un errore. Per salvare davvero i volumi con nome su un host generico, punta Host Data (e HOST_SOURCE_ROOT) a un antenato comune che copra anche la radice dati di Docker: vedi il commento Host Data nel file compose per il compromesso (Unraid aggira la cosa montando tutto /mnt, la sua convenzione universale di primo livello, per lo stesso motivo).
• Directory di progetto Docker Compose: se il contenitore porta l'etichetta standard com.docker.compose.project.working_dir (impostata automaticamente da docker compose up), anche quella directory viene aggiunta, indipendentemente dal fatto che un bind abbia corrisposto a un segmento di radice dati.
• Forzatura tramite l'etichetta bombvault.data: metti l'etichetta bombvault.data=true su un contenitore per includere TUTTI i suoi bind mount, per una disposizione che nessuna delle due convenzioni sopra intercetta (per esempio un unico bind /srv/plex/config senza progetto Compose). Qualsiasi valore non vuoto diverso da false conta come vero; un'etichetta assente o bombvault.data=false non cambia nulla.
• Etichetta bombvault.dbdump: metti bombvault.dbdump=false su un container per spegnere il suo dump automatico del database (0, no e off fanno lo stesso), oppure indica il motore (postgres, mysql, mariadb) per dumpare un container che BombVault non riconosce da solo. L'etichetta ha la meglio sull'interruttore nella scheda del container, che su Unraid è la via abituale.

Modello di sicurezza

Controllo dell'host equivalente a root

Tramite il socket Docker BombVault può fermare, rimuovere e ricreare container e leggere/scrivere appdata, e per il backup delle VM accede all'host via SSH (qemu+ssh://, root di default) per eseguire virsh. Chiunque possa raggiungere la sua interfaccia web ha di fatto accesso root sull'host.

• Protezione con password opzionale (Impostazioni, Sicurezza): imposta una password per richiedere l'accesso, cancellala per disattivarla. Disattivata di default per l'uso su una LAN fidata. La password è memorizzata con Argon2id su un valore pepato con APP_KEY, quindi un /config copiato non vale nulla senza la chiave ed è lento da attaccare con essa. Una password nuova richiede almeno 12 caratteri; una più corta già presente continua a funzionare finché non viene cambiata. Le sessioni sono firmate (HMAC derivato da APP_KEY) e cambiare la password le invalida; gli accessi sono limitati a cinque fallimenti al minuto per client.
• Autenticazione a due fattori (Impostazioni): un codice temporale da un'app di autenticazione oltre alla password, più otto codici di recupero monouso consegnati una sola volta all'attivazione. Il segreto condiviso è memorizzato cifrato con APP_KEY, e disattivare il fattore richiede un codice attuale.
• Passkey (WebAuthn): hanno una scheda propria non appena è impostata una password, accanto alla password e mai al suo posto, quindi rimuovere tutte le passkey non lascia fuori nessuno. Richiedono un vero nome di dominio e un certificato di cui il browser si fidi. L'indirizzo predefinito https://<ip>:3443 è proprio ciò che WebAuthn rifiuta, e la scheda lo dice invece di offrire un pulsante destinato a fallire.
• Le modifiche richiedono JSON. Una richiesta che modifica qualcosa deve inviare Content-Type: application/json e non deve essere contrassegnata dal browser come cross-site, così una pagina di un altro sito non può far modificare al tuo browser le impostazioni su un indirizzo della LAN. Uno script che usa l'API invia quell'intestazione; tutto il resto viene rifiutato con 415.
• Poiché il gate è opt-in, quando non impostato l'intera interfaccia e API (inclusi la configurazione off-site, le route del tamper-test e il kit di ripristino) sono raggiungibili da chiunque possa raggiungere la porta. Abilita il gate una volta che sono in uso backup off-site, immutabili o la cifratura.
• Esegui BombVault solo su una rete affidabile e non esposta. Per l'accesso remoto mettilo dietro un reverse proxy che aggiunga autenticazione e TLS. Le risposte portano header di sicurezza di base (CSP, nosniff, X-Frame-Options, Referrer-Policy).
• Dietro un reverse proxy ogni richiesta porta l'indirizzo del proxy, quindi senza TRUSTED_PROXY il freno conta tutti i client in un unico secchio e i fallimenti di un attaccante bloccano fuori anche te. Indica il proxy in TRUSTED_PROXY per riavere il conteggio per client.
• Un reverse proxy davanti a BombVault deve passare l'intestazione Authorization o X-API-Key a /mcp e non deve bufferizzarne le risposte, altrimenti gli assistenti non riescono a collegarsi. Vedi Server MCP.
• L'endpoint MCP /mcp risponde 404 finché non esiste una chiave e l'accesso tramite OAuth non è attivato, e chiede a ogni client la sua chiave o il suo token anche con la password di accesso disattivata; nessun indirizzo è esente, nemmeno localhost. Non ha strumenti di ripristino né di eliminazione, e ripristinare un backup della configurazione revoca tutte le chiavi. Vedi Server MCP.
• Con HTTP_ONLY=true il cookie di sessione perde il suo flag Secure (deve, per funzionare su HTTP in chiaro), quindi abilita la password dietro un proxy che termina il TLS solo se la riservatezza è importante.
• La connessione SSH del backup VM si fida della chiave host al primo collegamento (TOFU) e la fissa in seguito. Verifica la chiave dell'host fuori banda se il tuo percorso container-verso-host non è affidabile.
• I backup vengono cifrati da restic quando la cifratura è abilitata (Impostazioni; attivata di default), con la chiave derivata da APP_KEY.

Server MCP

Il server MCP non richiede alcuna variabile d'ambiente. Lo attivi creando una chiave in Impostazioni, Integrazioni, Server MCP, e risponde su /mcp sulla stessa porta dell'interfaccia web (per esempio https://192.168.1.10:3443/mcp). Senza una chiave attiva quel percorso risponde 404. Client, certificati e limiti sono descritti in Server MCP.

Backup delle VM via SSH

BombVault esegue il backup delle VM KVM/libvirt senza montare alcun percorso libvirt. Esegue virsh sull'host via SSH (qemu+ssh://), così non può mai influire sul VM Manager del tuo host.

Montare il socket libvirt dell'host in un container è fragile su Unraid: quei percorsi appartengono al VM Manager, e cambiare "Enable VMs" può lasciare libvirt impossibilitato ad avviarsi. La chiave SSH concede l'accesso root all'host, lo stesso livello di fiducia del socket Docker che BombVault usa già.

Configurazione rapida:

1. Impostazioni, Integrazioni, SSH dell'host: copia la chiave pubblica mostrata.
2. Aggiungila a /root/.ssh/authorized_keys di Unraid (anche persistita sul flash così sopravvive ai riavvii).
3. Clicca Prova connessione.

Il template aggiunge --add-host=host.docker.internal:host-gateway così il container può raggiungere l'host. Imposta LIBVIRT_HOST sull'IP LAN del tuo Unraid se quel nome non si risolve (per esempio quando il container gira su una rete br0.x personalizzata). Se hai cambiato la porta SSH di Unraid, imposta LIBVIRT_SSH_PORT di conseguenza. Gli snapshot a caldo necessitano inoltre del qemu guest agent nella VM e del disco su /mnt/cache (non /mnt/user).

Guida completa alla configurazione delle VM e alla rete

La guida completa passo passo (abilitazione SSH, autorizzazione persistente della chiave, routing su rete personalizzata e VLAN, metodo per VM e risoluzione dei problemi lato host) si trova in docs/vm-backup-ssh-setup.md su GitHub.

Configurazione off-site

Configura una replica off-site nella pagina Impostazioni, Off-site. Vedi Off-site e ripristino per il flusso di lavoro completo (immutabile/append-only, tamper testing ed esercitazioni DR). In breve:

• Backend: SMB/CIFS e NFS (monta la condivisione e puntaci un Percorso di backup), backend restic nativi senza rclone (s3:..., rest:http://host:8000/repo, sftp:user@host:/repo), o qualsiasi remote rclone (rclone:<remote>:<bucket>/path). Backblaze B2 qui non ha un backend nativo: si raggiunge tramite il suo endpoint S3 (s3:https://s3.<region>.backblazeb2.com/<bucket>/<path>), con l'ID chiave e la chiave applicativa come credenziali S3.
• Le credenziali cloud condivise vengono memorizzate cifrate sotto Impostazioni, Accesso cloud, Credenziali cloud condivise.
• Le destinazioni SSH non richiedono nulla di installato sull'altro lato. sftp: necessita solo di un server SSH. Aggiungi la chiave pubblica da Impostazioni, Integrazioni, SSH dell'host (anche in /config/ssh/id_ed25519.pub) al file ~/.ssh/authorized_keys dell'utente di destinazione.
• Copia off-site: BombVault replica i nuovi snapshot con restic copy su base best-effort, in aggiunta a un repository primario (di solito locale). Ogni dominio ha il proprio calendario off-site, più un pulsante Replica ora.
• Più destinazioni off-site per dominio: ogni dominio può replicare verso più destinazioni off-site contemporaneamente. Aggiungi destinazioni extra in Impostazioni, Off-site, ciascuna con il proprio repository, classe di archiviazione S3, flag append-only, conservazione e budget di crescita; replicano tutte secondo il calendario off-site di quel dominio. Una configurazione off-site singola esistente viene riportata come prima destinazione.
• Destinazioni: le destinazioni off-site si impostano una sola volta in Impostazioni, Off-site, Destinazioni, con una procedura guidata che elenca ogni servizio supportato. Vedi Destinazioni.
• Collocazione per elemento: ogni container, VM e set di file accende Locale e le destinazioni che ricevono i suoi backup. Impostazioni, Archiviazione, Collocazioni predefinite lo imposta per dominio per gli elementi senza una scelta propria. Vedi Collocazione per elemento.
• Conservazione per sorgente: le policy locale e off-site risiedono entrambe su Impostazioni, Conservazione (lascia quella off-site tutta a zero per non tagliare mai automaticamente gli snapshot off-site). Le schede Conservazione locale e Conservazione off-site hanno ciascuna Regole di conservazione per origine, che dà a container, VM, flash, cartelle, ZFS o all'autobackup regole di conservazione proprie, per i backup locali e per il loro repo off-site. Un'origine senza regole proprie segue quelle comuni, e la conservazione dopo ogni backup, la copia off-site, una pulizia manuale e l'anteprima della conservazione usano tutte le regole dell'origine su cui lavorano. Le destinazioni off-site aggiuntive mantengono le regole impostate per loro in Impostazioni, Off-site.
• Limiti di banda: limita la velocità di upload/download di restic sotto Impostazioni, Off-site.
• Prima lo streaming: in Impostazioni, Off-site scegli i media server (Plex, Jellyfin ed Emby sono preselezionati in base al nome dell'immagine), la velocità di invio oltre la quale uno conta come in streaming, il limite di upload durante lo streaming e dopo quanto tempo da uno stream torna il limite normale.
• Classe di archiviazione fredda e d'archivio (S3): per un repo off-site S3 nativo, scegli un livello leggibile in ripristino (Standard, Standard-IA, One Zone-IA, Intelligent-Tiering, Glacier Instant Retrieval). I remote rclone impostano la loro classe nella configurazione rclone.
• Primario remoto invece che locale: il Percorso di backup di un dominio può essere esso stesso uno dei backend sopra, senza copia locale né passaggio di replica; vedi Repository primari remoti per l'interruttore Locale/Remoto integrato e le sue impostazioni di sicurezza (banda, append-only, budget di crescita).

Anomalie

Il rilevamento delle anomalie si imposta nella scheda Anomalie di Impostazioni, Integrità. Ogni controllo salva appena lo cambi, e i tre sotto l'interruttore sono nascosti finché il rilevamento è spento.

Impostazione	Predefinito	Cosa fa
Rileva le anomalie	Attivo	Confronta ogni backup con la cronologia propria dell'elemento. Spento, non si controlla più nulla di nuovo e la voce Anomalie esce dalla barra laterale; la scheda continua a rimandare ai rilevamenti precedenti.
Sensibilità	Equilibrata	Rigorosa segnala cambiamenti più piccoli, Permissiva solo quelli grandi.
Invia una notifica per	Solo riscontri critici	La gravità minima che invia un messaggio tramite i canali configurati in Notifiche. Gli errori ripetuti di backup e dump e i controlli di ripristino pianificati falliti inviano già un proprio messaggio e non vengono inviati due volte.
Conserva i backup vecchi quando una sorgente si riduce molto o viene riscritta	Attivo	Finché un elemento ha un rilevamento aperto per una sorgente quasi vuota, una forte riduzione o la maggior parte dei dati salvata di nuovo, la conservazione e la pulizia lasciano stare i suoi vecchi backup. Conferma il rilevamento o segnalo come previsto per liberarli.

Ogni elemento può avere una propria sensibilità e un proprio minimo di notifica. Impostali nella pagina Anomalie, dove un elemento con rilevamenti aperti li ha sotto Monitoraggio nella sua scheda e ogni altro elemento li apre dalla scheda Niente di aperto, oppure nel pannello dell'elemento stesso: la sezione cartelle di un container e le impostazioni di una VM (entrambe in modalità avanzata), l'editor delle cartelle di un set di cartelle e le pagine Flash e Auto-backup. Per un elemento ZFS si trovano nel suo editor nella pagina ZFS e valgono per ogni dataset del suo albero.

Impostazioni portatili (esporta e importa)

La scheda Esporta / importa impostazioni nella pagina Impostazioni, Sistema scrive l'intera configurazione BombVault (impostazioni di dominio, destinazioni off-site, calendari, conservazione, notifiche) in un file JSON portatile che puoi importare su un'altra istanza, così passare a una nuova macchina o clonare una configurazione non significa reinserire tutto a mano. L'importazione mostra un'anteprima e chiede conferma, e non tocca mai i tuoi dati di backup o la cronologia.

L'esportazione può contenere credenziali

Scegli tu se includere le credenziali off-site, di notifica e del broker MQTT nel file. Con le credenziali incluse, l'esportazione è sensibile quanto il tuo kit di ripristino, quindi conservala in un luogo sicuro. Senza di esse, il file contiene solo impostazioni non segrete.