Configuração¶
Esta página cobre as variáveis de ambiente do container, as montagens que o template fornece, o modelo de segurança, o backup de VMs por SSH e a configuração do externo. O sítio para onde vão os backups define-se dentro da aplicação como destinos, não através de variáveis de ambiente.
Variáveis de ambiente¶
| Variável | Obrigatória | Descrição |
|---|---|---|
APP_KEY |
Sim | Segredo hexadecimal de 32 bytes (64 caracteres hex) usado para derivar a palavra-passe do repo restic. Gera com openssl rand -hex 32. Guarda-a em segurança: perdê-la torna os backups encriptados irrecuperáveis. |
LIBVIRT_HOST |
Para VMs e conjuntos de dados ZFS | Host do Unraid alcançado por SSH para o backup de VMs (predefinição host.docker.internal; o template pré-preenche um placeholder de IP LAN). Usa o IP LAN do seu Unraid, obrigatório numa rede br0.x personalizada. Também usado pelos backups de conjuntos de dados ZFS (campo do template Host SSH: Address); o marcador 192.168.x.x conta como não definido. Quando host.docker.internal não resolve, como numa app do TrueNAS, e LIBVIRT_URI também não indica um host, o BombVault usa o gateway predefinido do container, e o registo de arranque indica-o. |
LIBVIRT_SSH_PORT |
Não | Porta SSH do host para o backup de VMs (predefinição 22). Campo do template Host SSH: Port, também para conjuntos de dados ZFS. |
LIBVIRT_SSH_USER |
Não | Utilizador SSH no host para o backup de VMs (predefinição root). Campo do template Host SSH: User, também para conjuntos de dados ZFS. |
LIBVIRT_URI |
Não | URI de ligação libvirt completo, usado textualmente em vez de o construir a partir das três variáveis LIBVIRT_* acima (que são então ignoradas para a string de ligação). Não definido por predefinição. Necessário no TrueNAS Scale, cujo libvirtd escuta num socket não padrão que a forma construída não consegue exprimir: qemu+ssh://<user>@<truenas-host>/system?socket=/run/truenas_libvirt/libvirt-sock. Consulta o guia de backup de VMs. Se for um URI qemu+ssh://, cada uma de LIBVIRT_HOST, LIBVIRT_SSH_USER e LIBVIRT_SSH_PORT que não esteja definida é tirada dele, também para os próprios comandos SSH do BombVault (transferência de NVRAM, conjuntos de dados ZFS). |
PORT |
Não | Porta HTTP (predefinição 3000. Usada apenas com HTTP_ONLY=true). |
HTTPS_PORT |
Não | Porta HTTPS (predefinição 3443. O template publica-a 1:1, por isso a WebUI responde em https://<ip>:3443). |
HTTP_ONLY |
Não | Define true para desativar o listener HTTPS autoassinado e servir apenas HTTP simples (para uso por trás de um proxy reverso que termina o TLS). |
BIND_HOST |
Não | Endereço em que a WebUI escuta (predefinição 0.0.0.0, todas as interfaces). Deixa-o por definir no contentor, cujas portas publicadas precisam de todas as interfaces. 127.0.0.1 serve para uma execução fora do Docker. O healthcheck consulta o mesmo endereço. |
TRUSTED_PROXY |
Não | Endereços ou intervalos CIDR, separados por vírgulas, do proxy reverso à frente do BombVault (por exemplo 192.168.20.11 ou 10.0.0.0/8). Só a partir desses saltos o X-Forwarded-For é acreditado, e o travão de início de sessão passa a contar falhas por cliente real em vez de juntar todos os que estão atrás do proxy no mesmo balde. Por definir (o padrão) ninguém é acreditado: um cabeçalho acreditado sem condições deixaria qualquer chamador escolher o seu próprio balde. |
HOST_SOURCE_ROOT |
Não | O caminho do host montado como Host Data (predefinição /mnt). O BombVault traduz as origens de bind-mount que o Docker reporta em caminhos sob esta montagem. Altera apenas se montou uma raiz de host diferente. |
HOST_MOUNT_ROOT |
Não | Onde o Host Data é montado dentro do container (predefinição /host/user). No TrueNAS, o Host Data é montado no seu próprio caminho do host, por isso esta variável e HOST_SOURCE_ROOT indicam ambas esse caminho, por exemplo /mnt/tank (consulta TrueNAS SCALE). |
DATA_ROOT_SEGMENTS |
Não | Nomes de segmentos de caminho, separados por vírgula, que marcam uma origem de bind-mount como dados de backup (predefinição appdata, seguindo a convenção do Unraid /mnt/user/appdata/<container>). O bind-mount de um container é automaticamente selecionado para backup quando QUALQUER segmento listado aparece como um segmento de caminho completo da sua origem no host. Por exemplo DATA_ROOT_SEGMENTS=appdata,config também apanha um bind .../config. Consulta Deteção da origem de backup para as outras formas, sempre ativas, de encontrar a pasta de dados de um container. |
PLATFORM |
Não | Força a plataforma que o BombVault assume estar a correr, em vez de a detetar automaticamente: unraid, generic ou truenas (não definido por predefinição, deteta automaticamente o Unraid ao procurar o seu marcador dockerMan sob a montagem flash, caso contrário generic. Um valor não reconhecido também recai em generic, registado no log). Define-o explicitamente num host Docker genérico ou no TrueNAS Scale em vez de depender da autodeteção exclusiva do Unraid. O ficheiro compose genérico já faz isto. Altera a convenção de recurso de appdata, as predefinições de destino de restauro entre instâncias, e se os passos de notificação/plugin complementar exclusivos do Unraid sequer são tentados (ver internal/platform). |
BOMBVAULT_SELF_CONTAINER |
Não | O nome do próprio container BombVault, para que nunca faça backup (e assim pare) de si próprio. |
BACKUP_MAX_HOURS |
Não | Máximo de horas de relógio que uma única execução de backup pode reter o bloqueio da sua secção antes de ser forçada a cancelar (uma salvaguarda para que uma execução encravada não possa bloquear a secção para sempre). Vazio (a predefinição) usa 48. Aumenta-o para backups em nuvem muito grandes ou lentos (uma execução cancelada no limite falha com context deadline exceeded). Define 0 para desativar o limite por completo. Uma poda está sujeita ao mesmo limite, e uma verificação ou uma poda continua enquanto o restic for reportando progresso. |
BACKUP_STALL_HOURS |
Não | Horas que um backup pode passar sem qualquer progresso antes de ser cancelado. Vazio (a predefinição) usa 2. Define 0 para nunca cancelar por paragem. É a mais fina das duas salvaguardas e normalmente a que dispara: observa se ainda está a acontecer alguma coisa em vez de quanto tempo a execução já leva, por isso um backup de vários terabytes lento mas saudável é deixado em paz, enquanto um encravado numa partilha que não responde é parado em horas em vez de dias. É registado um aviso após 30 minutos de silêncio, antes de qualquer cancelamento. A análise conta como progresso: o restic não escreve bytes enquanto percorre uma árvore grande, e essa fase é vigiada através dos seus totais de ficheiros e bytes em vez dos bytes escritos. As duas variáveis são independentes, e BACKUP_MAX_HOURS continua a limitar as fases depois do backup propriamente dito (retenção, estatísticas, cópia externa), onde não há contadores para vigiar. |
DB_DUMP_MAX_HOURS |
Não | Horas que um dump automático de base de dados pode correr antes de ser parado. Vazio (a predefinição) usa 6. São aceites valores de 1 a 48, e o limite fica uma hora abaixo de BACKUP_MAX_HOURS (em metade dele quando este é inferior a duas horas), para que um dump longo seja cortado pelo seu próprio limite e relatado como tal, em vez de levar o backup atrás. Um dump que deixa de avançar é parado mais cedo, ao fim de BACKUP_STALL_HOURS. Um dump parado falha por si e o backup do container continua. No Unraid, acrescenta a variável ao container BombVault com Add another Path, Port, Variable. |
DATA_DIR |
Não | Onde o BombVault guarda a sua base de dados, chaves e caches (predefinição /config). Deixa-o em paz no container. Conta quando corres o binário fora do Docker. |
FLASH_DIR, FLASH_TEMPLATES_DIR |
Não | Onde a unidade flash e os seus templates Docker estão montados dentro do container (predefinições /host/boot e /host/boot/config/plugins/dockerMan/templates-user). Seguem a montagem /boot do template, por isso deixa-os por definir. |
MODE |
Não | full (a predefinição) corre a aplicação completa. node corre um nó: sem interface web e sem agendamentos próprios, só o que a sua instância base lhe diz. Qualquer outro valor interrompe o arranque com uma mensagem. A instância base preenche-o por ti no ficheiro compose do nó. |
NODE_HOME |
Num nó | A que instância base pertence o nó, com a chave e o relay da instância base, num único valor que começa por bvhome1.. A instância base escreve-o no ficheiro compose do nó. Sem ele, o nó arranca, mas nenhuma instância base chega até ele. Um nó que uma instância base já adotou recusa-se a arrancar quando o NODE_HOME indica outra, até a primeira o libertar. |
NODE_NAME |
Não | O nome do nó, tal como a instância base o preencheu a partir do nome que lhe deste. |
TZ |
Não | Fuso horário para o agendador (por exemplo Europe/Berlin). Se não for definido, todos os agendamentos são executados em UTC: um agendamento às 02:30 é então iniciado às 02:30 UTC e não na hora local. No Unraid nunca defines isto: o sistema passa o próprio fuso horário para cada contêiner. O registo de arranque indica que fuso foi aplicado. Um fuso com hora de verão salta uma execução na primavera e faz uma duas vezes no outono; o UTC não faz nenhuma das duas coisas, mas desvia-se uma hora face ao teu relógio duas vezes por ano. |
Montagens¶
Monta o socket Docker, o flash (/boot) e a raiz Host Data (/mnt) como mostrado no template CA. As origens e os destinos de backup vivem ambos sob Host Data, e é montada em slave para que uma partilha remota que montes depois de o container arrancar (por exemplo sob /mnt/remotes) fique visível sem um reinício.
No TrueNAS, o Host Data é o caminho de um conjunto de dados como /mnt/tank, nunca um ixVolume. Os dados que uma app guarda num ixVolume ficam fora dele e não entram no backup. Consulta TrueNAS SCALE.
Os backups de conjuntos de dados ZFS também precisam deste modo: o host só monta o instantâneo de um conjunto depois de o container ter arrancado. Vê Conjuntos de dados ZFS.
Os repositórios locais assumem por predefinição /mnt/user/bombvault/{container,vms,flash,config,files,zfs}, criados no primeiro backup. São as pastas próprias das secções e formam o destino Local. Na página desse destino, em Destinos, o cartão Ligação muda a pasta de cada secção.
A pasta própria de uma secção também pode ficar num destino que já tenhas, como um NAS ou um bucket S3: Usar como pasta própria na página desse destino muda-a para lá e diz primeiro o que acontece aos backups já feitos. Vê A pasta própria de uma secção.
As pastas dos repositórios locais ficam com os modos 0755 e 0644, para que um utilizador de sincronização sem root por SMB não fique de fora, e os repositórios são encriptados, por isso isto não expõe nada. As definições de recuperação vivem dentro de cada repositório, por isso uma pasta copiada está completa por si. O repositório do auto-backup continua legível só por root.
Verificação de integração com o host
O cartão Integração com o host na visão geral (adiciona-o em Personalizar) sonda cada montagem e CLI (socket Docker, libvirt, restic, qemu-img, rclone) e reporta quaisquer peças em falta.
Deteção das fontes de backup¶
Para cada contentor, o BombVault escolhe por si que bind mounts e volumes nomeados são copiados. Um caminho é aceite assim que um dos pontos seguintes se aplique (o resultado pode sempre ser corrigido no cartão Pastas a copiar do separador Definições do container):
- Correspondência de um segmento de raiz de dados: a origem no anfitrião do bind contém um dos segmentos de
DATA_ROOT_SEGMENTScomo componente completo do caminho (por omissão apenasappdata). - Os volumes Docker nomeados são sempre incluídos, porque não têm equivalente descartável e portanto não há nada a filtrar, mas só quando o caminho real de armazenamento do volume no anfitrião é alcançável através da montagem Host Data, tal como qualquer outro caminho do anfitrião que o BombVault copia. O controlador local por omissão guarda um volume sob a raiz de dados do próprio daemon, ou seja
/var/lib/docker/volumes/<nome>/_datasalvo personalização (confirma comdocker info -f '{{.DockerRootDir}}'). Esse local NÃO está coberto pela montagem Host Data estreita, de um único diretório, que odocker-compose.ymlgenérico usa por omissão. Um volume inalcançável é ignorado em silêncio, não é um erro. Para copiar mesmo os volumes nomeados num anfitrião genérico, aponta o Host Data (eHOST_SOURCE_ROOT) para um antecessor comum que cubra também a raiz de dados do Docker: vê o comentário Host Data no ficheiro compose para o compromisso (o Unraid contorna isto montando todo o/mnt, a sua própria convenção universal de topo, pela mesma razão). - Diretório de projeto do Docker Compose: se o contentor tiver a etiqueta padrão
com.docker.compose.project.working_dir(posta automaticamente pelodocker compose up), esse diretório é acrescentado também, independentemente de algum bind ter correspondido a um segmento de raiz de dados. - Substituição pela etiqueta
bombvault.data: põe a etiquetabombvault.data=truenum contentor para incluir todos os seus bind mounts, para uma disposição que nenhuma das duas convenções acima apanha (por exemplo um único bind/srv/plex/configsem projeto Compose). Qualquer valor não vazio diferente defalseconta como verdadeiro. Uma etiqueta ausente oubombvault.data=falsenão muda nada. - Etiqueta
bombvault.dbdump: põebombvault.dbdump=falsenum container para desligar o seu dump automático de base de dados (0,noeofffazem o mesmo), ou indica o motor (postgres,mysql,mariadb) para despejar um container que o BombVault não reconhece sozinho. A etiqueta manda sobre o interruptor no cartão Base de dados do separador Definições do container, que no Unraid é o caminho habitual.
Modelo de segurança¶
Controlo do host equivalente a root
Através do socket Docker, o BombVault pode parar, remover e recriar containers e ler/escrever appdata, e para o backup de VMs inicia sessão no host por SSH (qemu+ssh://, root por predefinição) para correr virsh. Qualquer pessoa que consiga alcançar a sua interface web tem, efetivamente, root no host.
Início de sessão¶
- Proteção por palavra-passe opcional (cartão Palavra-passe em Definições, Segurança): define uma palavra-passe para exigir início de sessão, limpa-a para desativar. Desativada por omissão para uso numa LAN de confiança. A palavra-passe é guardada com Argon2id sobre um valor apimentado com
APP_KEY, por isso um/configcopiado não vale nada sem a chave e é lento de atacar com ela. Uma palavra-passe nova precisa de pelo menos 12 caracteres. Uma mais curta já existente continua a funcionar até ser alterada. As sessões são assinadas (HMAC derivado deAPP_KEY) e alterar a palavra-passe invalida-as. Os inícios de sessão estão limitados a cinco falhas por minuto e por cliente. Alterar ou apagar a palavra-passe pede a Palavra-passe atual e, com a autenticação de dois fatores ligada, o código. - Algumas coisas exigem uma palavra-passe. Descarregar o kit de recuperação, o relatório de erros e o ZIP de um backup do flash, exportar um backup do flash ou um auto-backup, depositar a chave num guardião da chave, permitir que um depósito seja entregue, criar um novo código de desbloqueio, exportar definições com credenciais, a autenticação de dois fatores, as chaves de acesso, adicionar um nó, mostrar outra vez o ficheiro compose de um nó e abrir as entradas de um nó são recusados até estar definida uma palavra-passe de início de sessão, e exigem um início de sessão na própria instância. Apagar backups funciona sem palavra-passe. Com uma definida, também exige esse início de sessão.
- Um destino não mostra palavra-passe. Um destino pode conter um início de sessão, como em
rest:https://user:password@host/repo, e todas as páginas e respostas da API mostram-no comorest:https://[redacted]@host/repo, com ou sem palavra-passe de início de sessão. Se mudares o caminho por trás dele, a palavra-passe guardada fica. Para apontar o destino para outro servidor, escreve o destino inteiro com a palavra-passe, porque uma palavra-passe escondida fica com o seu servidor. - Autenticação de dois fatores (Definições, Segurança): um código temporal de uma aplicação de autenticação além da palavra-passe, mais oito códigos de recuperação de uso único entregues uma vez ao ativar. O segredo partilhado é guardado cifrado com
APP_KEY, e desligar o fator outra vez exige um código atual. - Chaves de acesso (WebAuthn): têm um cartão próprio assim que há uma palavra-passe definida, ao lado da palavra-passe e nunca em vez dela, por isso remover todas as chaves de acesso não deixa ninguém de fora. Precisam de um nome de domínio real e de um certificado em que o browser confie. O endereço predefinido
https://<ip>:3443é exatamente o que o WebAuthn recusa, e o cartão di-lo em vez de oferecer um botão que falharia. Com a autenticação de dois fatores ligada, uma chave de acesso tem de verificar o teu PIN, a tua impressão digital ou o teu rosto, senão o início de sessão pede também o código. - Uma reposição da configuração (Trazer de volta as definições no Assistente de emergência) termina todas as sessões, remove todas as chaves de acesso e revoga todos os tokens de API e chaves MCP, porque as definições repostas poderiam trazer de volta alguns que foram removidos depois de serem guardadas. Inicia sessão com a palavra-passe e volta a configurar as tuas chaves de acesso em Definições, Segurança.
- Uma palavra-passe esquecida é reposta na página de início de sessão. Esqueceste-te da palavra-passe? faz o BombVault escrever um código de 12 caracteres, em três grupos de quatro, no registo do seu container (no Unraid: separador Docker, ícone do BombVault, Logs). Esse código e uma palavra-passe nova iniciam-te a sessão. A reposição também desliga a autenticação de dois fatores, remove todas as chaves de acesso, revoga todos os tokens de API, chaves MCP e inícios de sessão OAuth, termina todas as outras sessões, termina a sessão de cada telemóvel emparelhado e desliga o emparelhamento de telemóveis. A página a seguir lista o que se foi. Um código é válido durante 10 minutos, e tentativas erradas não o gastam. Os tokens de widget e de métricas ficam, porque só leem.
- Quem consegue ler o registo do container consegue repor a palavra-passe. Isso é root no host, mas também um visualizador de registos como o Dozzle, qualquer container a quem seja dado o socket Docker (só de leitura chega) e um expedidor de registos que reencaminhe a saída dos containers. Dá isso apenas a pessoas em quem confiarias com a palavra-passe. Quem só chega à interface web nunca vê o código.
Telemóveis e membros do grupo¶
- Os telemóveis emparelhados chegam a uma lista de permitidos. Um telemóvel que conheça as doze palavras do grupo inicia sessão sem a palavra-passe, desde que Os telemóveis podem emparelhar com as doze palavras do grupo esteja ligado no cartão App Android em Definições, Segurança. A sessão dele só chega ao que a aplicação mostra: a visão geral, as execuções, os backups para ver, iniciar e restaurar, as anomalias para ler e a página Instâncias para ver. Os destinos e os comandos chegam-lhe sem os endereços e os segredos, e um restauro que substitui o original faz primeiro backup do estado atual. Um restauro para uma pasta só aceita uma pasta nova ou vazia dentro da pasta de restauro, e um telemóvel não consegue ver nenhuma outra pasta. Tudo o resto responde que precisa de um início de sessão na própria instância: chaves, o kit de recuperação, depósitos de chaves, definições, a eliminação de backups. Uma reposição da palavra-passe desliga o emparelhamento de telemóveis até o voltares a ligar. Um telemóvel removido da página Instâncias, ou com Consultar esta instância desligado nos seus detalhes, perde logo a sessão, e um telemóvel removido que volta a abrir a aplicação regressa desligado.
- Fora de casa, um telemóvel abre páginas através do relay. Cada pedido da página é selado com a chave do grupo, que o relay não consegue ler nem alterar, e assinado com uma chave própria do telemóvel, que o servidor fixa na primeira chamada do telemóvel e deixa entrar assim que alguém aprova o telemóvel na página de emparelhamento. O servidor executa um pedido uma só vez e apenas enquanto for recente. Só responde a um telemóvel que conste da página Instâncias, enquanto o emparelhamento de telemóveis estiver ligado, e só com uma sessão que tenha dado a esse telemóvel, pelo que terminar sessão em todo o lado e repor a palavra-passe também encerram estas páginas. O servidor assina cada resposta, e a aplicação verifica a assinatura com a chave que fixou para esse servidor e avisa quando a chave muda. Uma página assim chega à mesma lista de permitidos que um telemóvel emparelhado, com ou sem palavra-passe de início de sessão, e ainda ao estado do início de sessão que a página lê primeiro. O início e o fim de sessão, a reposição da palavra-passe e as transferências ficam no endereço do próprio servidor, e uma resposta está limitada a 16 MB.
- Os membros assinam o que pedem. Os pedidos de função e as respostas, as ofertas de armazenamento, a entrega de uma palavra-passe restic a um recetor ou a quem a vai buscar, os inícios de sessão de recetores e os depósitos de chaves são assinados com uma chave de cada membro, que uma instância fixa a primeira vez que vê esse membro. Uma chamada assinada com outra chave é recusada. Esquecer a chave nos detalhes de uma instância larga a chave fixada, para o caso de a que é conhecida aqui não ser a do próprio membro. Ao membro volta a ser pedida a chave na sua próxima chamada assinada. Os membros no BombVault 9.x não assinam e podem ser imitados por qualquer pessoa com as palavras, como no 9.9. Um pedido de função ou uma oferta de armazenamento de um membro na 10.4 ou anterior é recusado até esse membro ser atualizado.
- As doze palavras são uma palavra-passe. Quem as tem entra no grupo, vê o estado de proteção dos membros e pode pedir funções, que uma pessoa na outra instância ainda tem de permitir. Sem palavra-passe de início de sessão, qualquer pessoa que consiga abrir a interface web pode lê-las, e o cartão de emparelhamento di-lo até haver uma palavra-passe definida.
Chaves¶
- A APP_KEY faz duas coisas. Sela o que esta instalação guarda (palavras-passe, inícios de sessão, tokens) e é a chave dos backups: a palavra-passe restic deriva dela, e as definições de containers e VMs são seladas com ela.
- Uma chave assumida é mantida à parte. Quando o Assistente de emergência assume os backups de outro servidor, esta instalação continua a selar com a sua própria APP_KEY e guarda a chave do outro servidor como a sua chave dos backups, selada como todos os outros segredos. O kit de recuperação imprime então as duas. Se a APP_KEY for alterada depois, a chave dos backups já não se consegue abrir: o BombVault pára de fazer backups e di-lo em Precisa de atenção, em vez de escrever com a chave errada. Carrega o kit de recuperação outra vez em Restauração, Emergência, ou repõe a APP_KEY. Consulta Assistente de emergência.
- A encriptação vem ligada por predefinição (Encriptar backups no cartão Encriptação em Definições, Segurança). Os backups são encriptados pelo restic com a palavra-passe derivada da chave dos backups.
- Depósitos de chaves. Um guardião da chave no teu grupo guarda uma cópia selada do kit de recuperação deste servidor que ele próprio não consegue abrir. Só o código de desbloqueio de 20 caracteres a abre, e o guardião só a entrega depois de alguém aí carregar em Permitir. Consulta Guardião da chave.
Nós¶
Um nó é um BombVault sem interface web que recebe ordens de uma instância base.
- A instância base manda no nó. Um nó monta o socket Docker do seu servidor, que lá equivale a root, e a instância base controla o nó. Se alguém tomar a instância base, controla também todos os seus nós. Dá à instância base uma palavra-passe de início de sessão e mantém a sua interface web fora da internet.
- Um nó guarda pouco. Se alguém tomar um nó, não fica com nenhum grupo de emparelhamento, nenhuma fortaleza, nenhum outro nó nem nenhum outro repositório. O nó tem apenas uma ligação à sua instância base, um início de sessão próprio no servidor recetor e uma pasta própria num destino. No servidor recetor não consegue apagar o histórico, porque o servidor é append-only. Consegue encher o disco do servidor, porque o rest-server não define quotas, por isso dá espaço ao servidor recetor ou uma partilha só para ele. Num destino, as suas credenciais costumam conseguir apagar o que lá está. Os backups guardados no nó ficam nas mãos de quem o tomou, e é por isso que a instância base recolhe uma cópia deles.
- A ligação é privada e assinada. A instância base e o nó falam pelo relay através de uma ligação só deles, selada com um segredo derivado da
APP_KEYdo nó. Cada lado conhece a chave do outro antes da primeira chamada, por isso não há passo de aprovação. A instância base assina cada chamada com a sua própria chave e um contador, e o nó recusa uma chamada que não tenha sido assinada pela instância base ou que já tenha recebido antes. O nó não chama nada na instância base além do seu olá. - A instância base chega a uma lista fixa. Os pedidos que a instância base passa a um nó só correm numa lista fixa de rotas do nó, indicada em
GET /api/nodes/routes, e o nó só lhes responde com JSON. Nada na lista apaga nem chega às definições, ao armazenamento, às chaves, ao grupo ou aos tokens. Na instância base exigem um início de sessão com a palavra-passe: os telemóveis emparelhados, os tokens de API e as chaves MCP não chegam a nenhum nó. Os backups e restauros iniciados assim aparecem como iniciados pela instância base. - Os depósitos da chave levam as chaves dos nós. A instância base guarda a
APP_KEYde cada nó, e o kit de recuperação imprime-a no seu capítulo Nodes, por isso um depósito da chave também a leva. Um guardião da chave que obtenha o depósito e o código de desbloqueio consegue abrir os repositórios dos teus nós, mas não consegue dar ordens a nenhum nó, porque isso exige a assinatura da instância base. - Libertar é definitivo. Um nó libertado não aceita outra vez nenhuma instância base com a mesma
APP_KEY. Um nó que esteja ausente quando o libertas fica a saber pela instância base assim que voltar.
Rede¶
- As alterações exigem JSON. Um pedido que altera algo tem de enviar
Content-Type: application/jsone não pode ser marcado pelo browser como vindo de outro site, para que uma página de outro site não consiga pôr o teu browser a alterar definições num endereço da LAN. Um script que use a API envia esse cabeçalho. Tudo o resto é recusado com415. - Como o controlo é opcional, quando não está definido, toda a interface e API (incluindo os destinos, as rotas de teste de adulteração e as rotas de restauro) ficam acessíveis a quem alcançar a porta. Define uma palavra-passe de início de sessão assim que usares backups externos, append-only ou encriptação.
- Corre o BombVault apenas numa rede de confiança e não exposta. Para acesso remoto, coloca-o por trás de um proxy reverso que adicione autenticação e TLS. As respostas transportam cabeçalhos de segurança de base (CSP,
nosniff,X-Frame-Options,Referrer-Policy). - Atrás de um proxy reverso cada pedido traz o endereço do proxy, por isso sem
TRUSTED_PROXYo travão conta todos os clientes no mesmo balde e as falhas de um atacante também te trancam de fora. Indica o proxy emTRUSTED_PROXYpara voltar a contar por cliente. - Um proxy inverso à frente do BombVault tem de passar o cabeçalho
AuthorizationouX-API-Keypara/mcpe não pode reter as respostas em buffer; caso contrário os assistentes não conseguem ligar-se. Ver Servidor MCP. - O endpoint MCP
/mcpresponde404enquanto não existir nenhuma chave nem estiver ativado o início de sessão por OAuth, e pede a cada cliente a sua chave ou o seu token mesmo com a palavra-passe de início de sessão desligada. Nenhum endereço fica isento, nem sequerlocalhost. Não tem ferramentas de restauro nem de eliminação, e restaurar um backup da configuração revoga todas as chaves. Ver Servidor MCP. - Com
HTTP_ONLY=true, o cookie de sessão perde a sua flagSecure(tem de perder, para funcionar sobre HTTP simples), por isso ativa a palavra-passe por trás de um proxy que termina o TLS apenas se a confidencialidade importar. - A ligação SSH do backup de VMs confia na chave do host no primeiro contacto (TOFU) e fixa-a a partir daí. Verifica a chave do host fora de banda se o seu caminho container-para-host não for de confiança.
- As ligações não levam para fora da montagem. Um backup ou um restauro no lugar para com uma mensagem quando uma ligação acima do seu caminho leva para fora da montagem do anfitrião, porque um container que escreve na sua própria partilha poderia lá pôr uma. Um destino cujo anfitrião ou remoto rclone comece por um hífen é recusado da mesma forma, ao guardar e na execução seguinte, porque o
sshou orcloneo leriam como uma opção.
Servidor MCP¶
O servidor MCP não precisa de nenhuma variável de ambiente. Ativa-o criando uma chave em Definições, Integrações, Servidor MCP, e ele responde em /mcp na mesma porta da interface web (por exemplo https://192.168.1.10:3443/mcp). Sem uma chave ativa, esse caminho responde 404. Clientes, certificados e limites estão descritos em Servidor MCP.
Backup de VMs por SSH¶
O BombVault faz backup de VMs KVM/libvirt sem montar qualquer caminho de libvirt. Corre virsh no host por SSH (qemu+ssh://), por isso nunca pode afetar o VM Manager do seu host.
Montar o socket libvirt do host dentro de um container é frágil no Unraid: esses caminhos pertencem ao VM Manager, e alternar "Enable VMs" pode deixar o libvirt sem conseguir arrancar. A chave SSH dá acesso root ao host, o mesmo nível de confiança que o socket Docker que o BombVault já usa.
Configuração rápida:
- Definições, Integrações, SSH do anfitrião: copia a chave pública mostrada.
- Adiciona-a ao
/root/.ssh/authorized_keysdo Unraid (também persistida no flash para sobreviver a reinícios). - Clica em Testar ligação.
O template adiciona --add-host=host.docker.internal:host-gateway para que o container possa alcançar o host. Define LIBVIRT_HOST para o IP LAN do teu Unraid se esse nome não resolver (por exemplo quando o container corre numa rede br0.x personalizada). Se alteraste a porta SSH do Unraid, define LIBVIRT_SSH_PORT para corresponder. Os instantâneos a quente também precisam do agente convidado qemu na VM e do disco em /mnt/cache (não /mnt/user).
Guia completo de configuração e rede de VMs
O guia completo passo a passo (ativação de SSH, autorização persistente da chave, encaminhamento de rede personalizada e VLAN, método por VM e resolução de problemas no lado do host) é o guia de backup de VMs.
Configuração do externo¶
As cópias externas vão para destinos. Abre Destinos a partir do seu mosaico de definições (ou fixa-o à barra lateral) e escolhe Adicionar destino. Consulta Externo e recuperação para o fluxo de trabalho completo (proteção contra eliminação, teste de adulteração e simulacros de DR). Em resumo:
- Backends: SMB/CIFS e WebDAV através do rclone sem montagem no host, NFS (monta a exportação no host e usa-a como pasta local), backends restic nativos sem rclone (
s3:...,rest:http://host:8000/repo,sftp:user@host:/repo) ou qualquer remoto rclone (rclone:<remote>:<bucket>/path). O Backblaze B2 não tem backend nativo aqui: chega-se lá pelo seu ponto de acesso S3 (s3:https://s3.<region>.backblazeb2.com/<bucket>/<path>), com o ID da chave e a chave da aplicação como credenciais S3. - As credenciais são guardadas encriptadas, como uma lista de credenciais guardadas no cartão Credenciais em Definições, Destinos. Uma estrela marca a predefinida, usada onde não se escolhe nenhuma. A página de um destino escolhe a que usa no seu cartão Credenciais. Vê Credenciais.
- Os destinos SSH não precisam de nada instalado do outro lado. O
sftp:só precisa de um servidor SSH. Adiciona a chave pública de Definições, Integrações, SSH do anfitrião (também em/config/ssh/id_ed25519.pub) ao~/.ssh/authorized_keysdo utilizador de destino, ou deixa que Adicionar chave em Adicionar destino a coloque lá com a palavra-passe da conta. - rest-server com um certificado autoassinado: coloca o seu certificado, ou o da autoridade que o assinou, como ficheiro PEM na pasta
certsda pasta de dados do BombVault (/config/certsno container,appdata/bombvault/certsno Unraid). Os backups, as cópias e o teste da proteção contra eliminação confiam nele sem reiniciar. - Cópia externa: o BombVault copia novos backups com
restic copynuma base de melhor esforço, por cima de um primário (normalmente local). O cartão Copiar de um destino define se copia Depois de cada backup ou segundo um plano próprio, e Definições, Agendamento, Cópias externas por secção dá a uma secção o seu plano de cópia. Replicar agora está na linha da secção do cartão Cópias externas em Definições, Destinos. - Vários destinos por secção: o cartão Destinos por secção na página Destinos liga ou desliga cada linha de uma secção para um destino com um clique, Local incluído. Uma secção só com destinos externos faz backup diretamente para eles, e uma com todas as linhas desligadas não tem backup. As Regras por secção de um destino dão a uma secção o seu próprio repositório, retenção ou compressão aí.
- Localização por entrada: cada container, VM e conjunto de pastas acende Local e os destinos que recebem os seus backups, no cartão Agendamento e destino do separador Definições. As entradas sem escolha própria seguem a sua secção. Consulta Localização por entrada.
- Retenção: cada destino guarda os backups segundo o seu cartão Durante quanto tempo guardar, e uma secção pode ter aí valores próprios em Regras por secção. A cópia no campo externo de uma secção segue as regras do cartão Retenção externa em Definições, Destinos, que tem Regras de retenção por origem para secções individuais (deixa tudo a zero para nunca podar automaticamente os backups externos).
- Limites de largura de banda: limita a taxa de envio/receção do restic no cartão Largura de banda externa em Definições, Destinos, ou por destino no seu cartão Copiar. Escreves KiB/s, e o campo mostra a mesma taxa em MB/s e Mbit/s.
- Primeiro o streaming: no cartão Streaming da página Destinos, escolhe os servidores multimédia (Plex, Jellyfin e Emby vêm pré-selecionados pelo nome da imagem), a taxa de envio a partir da qual um conta como a fazer streaming, o limite de envio enquanto faz streaming e quanto tempo depois de um stream o limite normal volta.
- Classe de armazenamento fria e de arquivo (S3): para um destino S3, escolhe na sua página um nível legível no restauro (Standard, Standard-IA, One Zone-IA, Intelligent-Tiering, Glacier Instant Retrieval). Os remotos rclone definem a sua classe na configuração do rclone.
- Pasta própria num destino em vez de local: a pasta própria de uma secção pode ficar num dos destinos acima, sem cópia local e sem passo de cópia. Vê A pasta própria de uma secção.
Anomalias¶
A deteção de anomalias não precisa de nenhuma variável de ambiente. Configura-se no cartão Anomalias em Definições, Verificação, descrito em Anomalias.
Definições portáteis (exportar e importar)¶
O cartão Exportar / importar configurações em Definições, Sistema escreve toda a tua configuração BombVault (definições por secção, destinos, agendamentos, retenção, notificações) para um ficheiro JSON portátil que podes importar noutra instância, para que mudar para uma máquina nova ou clonar uma configuração não signifique reintroduzir tudo à mão. A importação mostra uma pré-visualização e pede confirmação, e nunca toca nos teus dados ou histórico de backup. As ligações no ficheiro a destinos ou repositórios que já não existem são deixadas de fora, e a pré-visualização nomeia-as. Enquanto uma réplica ZFS corre, uma importação é recusada antes de se escrever o que quer que seja.
A exportação pode conter credenciais
Escolhe se inclui as credenciais externas, de notificação e do broker MQTT no ficheiro. Com as credenciais incluídas, a exportação é tão sensível como o teu kit de recuperação, por isso guarda-a num local seguro. Sem elas, o ficheiro contém apenas definições não secretas.
A APP_KEY não viaja com o ficheiro
Os repositórios estão fechados com uma palavra-passe derivada da APP_KEY, e o ficheiro não a contém. Para uma mudança planeada, dá à máquina nova a APP_KEY antiga no seu template, ou assume a chave com o kit de recuperação em Emergência. Com outra chave, os repositórios respondem com palavra-passe errada. Não se perde nada, e definir a chave certa volta a abri-los.