Configuración¶

Esta página cubre las variables de entorno del contenedor, los montajes que provee la plantilla, la copia de VMs por SSH y la configuración externa. Las rutas de repositorio de copia se configuran dentro de la app (Ajustes, Almacenamiento, Rutas de copia), no mediante variables de entorno.

Variables de entorno¶

Variable	Requerida	Descripción
`APP_KEY`	Sí	Secreto hexadecimal de 32 bytes (64 caracteres hex) usado para derivar la contraseña del repo restic. Genera con `openssl rand -hex 32`. Mantenlo a salvo: perderlo hace que las copias cifradas queden irrecuperables.
`LIBVIRT_HOST`	Para VMs y conjuntos de datos ZFS	Host de Unraid alcanzado por SSH para la copia de VMs (por defecto `host.docker.internal`; la plantilla rellena de antemano un marcador de IP LAN). Usa la IP LAN de tu Unraid, requerida en una red `br0.x` personalizada. También lo usan las copias de conjuntos de datos ZFS (campo de plantilla Host SSH: Address); el marcador `192.168.x.x` cuenta como no definido.
`LIBVIRT_SSH_PORT`	No	Puerto SSH del host para la copia de VMs (por defecto `22`). Campo de plantilla Host SSH: Port, también para conjuntos de datos ZFS.
`LIBVIRT_SSH_USER`	No	Usuario SSH en el host para la copia de VMs (por defecto `root`). Campo de plantilla Host SSH: User, también para conjuntos de datos ZFS.
`LIBVIRT_URI`	No	URI de conexión libvirt completa, usada literalmente en lugar de construirla a partir de las tres variables `LIBVIRT_*` anteriores (que en ese caso se ignoran para la cadena de conexión). Por defecto, sin definir. Necesaria en TrueNAS Scale, cuyo libvirtd escucha en un socket no estándar que la forma construida no puede expresar: `qemu+ssh://<user>@<truenas-host>/system?socket=/run/truenas_libvirt/libvirt-sock`. Consulta la sección de TrueNAS Scale en docs/vm-backup-ssh-setup.md. Si es una URI `qemu+ssh://`, cada una de `LIBVIRT_HOST`, `LIBVIRT_SSH_USER` y `LIBVIRT_SSH_PORT` que no esté definida se toma de ella, también para los propios comandos SSH de BombVault (transferencia de NVRAM, conjuntos de datos ZFS).
`PORT`	No	Puerto HTTP (por defecto `3000`; solo se usa con `HTTP_ONLY=true`).
`HTTPS_PORT`	No	Puerto HTTPS (por defecto `3443`; la plantilla lo publica 1:1, de modo que la WebUI responde en `https://<ip>:3443`).
`HTTP_ONLY`	No	Establece `true` para deshabilitar el listener HTTPS autofirmado y servir solo HTTP en texto plano (para uso detrás de un proxy inverso que termina TLS).
`BIND_HOST`	No	Dirección en la que escucha la WebUI (por defecto `0.0.0.0`, todas las interfaces). Déjala sin definir en el contenedor, cuyos puertos publicados necesitan todas las interfaces; `127.0.0.1` sirve para ejecutarlo fuera de Docker. El healthcheck consulta la misma dirección.
`TRUSTED_PROXY`	No	Direcciones o rangos CIDR, separados por comas, del proxy inverso situado delante de BombVault (por ejemplo `192.168.20.11` o `10.0.0.0/8`). Solo desde esos saltos se cree la cabecera `X-Forwarded-For`, y el límite de intentos cuenta entonces los fallos por cliente real en lugar de meter a todos los que están detrás del proxy en el mismo saco. Sin definir (lo predeterminado) no se cree a nadie: una cabecera creída sin condiciones dejaría a cualquiera elegir su propio contador.
`HOST_SOURCE_ROOT`	No	La ruta del host montada como Host Data (por defecto `/mnt`). BombVault traduce los orígenes de bind-mount que reporta Docker a rutas bajo este montaje. Cámbialo solo si montaste una raíz de host distinta.
`DATA_ROOT_SEGMENTS`	No	Nombres de segmentos de ruta, separados por comas, que marcan un origen de bind-mount como datos de copia (por defecto `appdata`, siguiendo la convención de Unraid `/mnt/user/appdata/<container>`). El bind mount de un contenedor se selecciona automáticamente para la copia cuando CUALQUIER segmento indicado aparece como un segmento de ruta completo de su origen en el host; por ejemplo, `DATA_ROOT_SEGMENTS=appdata,config` también recoge un bind `.../config`. Consulta Detección de orígenes de copia para conocer las otras formas, siempre activas, en que se encuentra la carpeta de datos de un contenedor.
`PLATFORM`	No	Fuerza la plataforma en la que BombVault considera que se está ejecutando, en lugar de detectarla automáticamente: `unraid`, `generic` o `truenas` (sin definir por defecto: detecta Unraid automáticamente sondeando su marcador `dockerMan` bajo el montaje de flash, o usa `generic` en caso contrario; un valor no reconocido también recae en `generic`, y queda registrado). Establécela explícitamente en un host Docker genérico o en TrueNAS Scale, en lugar de depender del autosondeo exclusivo de Unraid: el archivo compose genérico ya lo hace así. Cambia la convención de resguardo de appdata, los destinos de restauración predeterminados entre instancias, y si se intentan o no los pasos de notificación/plugin complementario exclusivos de Unraid (consulta `internal/platform`).
`BOMBVAULT_SELF_CONTAINER`	No	El nombre del propio contenedor de BombVault, para que nunca se copie (y por tanto se detenga) a sí mismo.
`BACKUP_MAX_HOURS`	No	Máximas horas de reloj que una única ejecución de copia puede retener el bloqueo de su dominio antes de que se fuerce su cancelación (una salvaguarda para que una ejecución atascada no pueda bloquear el dominio para siempre). Vacío (el valor por defecto) usa `48`. Súbelo para copias en la nube muy grandes o lentas (una ejecución cancelada en el límite falla con `context deadline exceeded`). Establece `0` para desactivar el límite por completo.
`BACKUP_STALL_HOURS`	No	Horas que una copia puede pasar sin ningún progreso antes de cancelarse. Vacío (el valor por defecto) usa `2`; establece `0` para no cancelar nunca por un atasco. Es la más fina de las dos salvaguardas y normalmente la que salta: vigila si todavía ocurre algo en lugar de cuánto lleva la ejecución, de modo que una copia de varios terabytes lenta pero sana se deja en paz, mientras que una atascada en un recurso compartido que no responde se detiene en horas en lugar de días. Se registra un aviso tras 30 minutos de silencio, antes de cancelar nada. El escaneo cuenta como progreso: restic no escribe ningún byte mientras recorre un árbol grande, y esa fase se vigila mediante sus totales de archivos y bytes en lugar de mediante los bytes escritos. Las dos variables son independientes, y `BACKUP_MAX_HOURS` sigue acotando las fases posteriores a la copia en sí (retención, estadísticas, copia externa), donde no hay contadores que vigilar.
`DB_DUMP_MAX_HOURS`	No	Horas que un volcado automático de base de datos puede durar antes de detenerse. Vacío (el valor por defecto) usa `6`; se admiten valores de `1` a `48`, y el límite se mantiene una hora por debajo de `BACKUP_MAX_HOURS` (en la mitad cuando este es inferior a dos horas), para que un volcado largo lo corte su propio límite y se informe como tal en vez de arrastrar la copia con él. Un volcado que deja de avanzar se detiene antes, tras `BACKUP_STALL_HOURS`. Un volcado detenido falla por su cuenta y la copia del contenedor sigue. En Unraid, añade la variable al contenedor de BombVault con Add another Path, Port, Variable.
`TZ`	No	Zona horaria para el programador (por ejemplo `Europe/Berlin`). Si no se define, todas las programaciones se ejecutan en UTC: una programada a las 02:30 se inicia entonces a las 02:30 UTC y no en la hora local. En Unraid nunca lo configuras tú: el sistema pasa su propia zona horaria a cada contenedor. El registro de arranque indica qué zona se ha aplicado. Una zona con horario de verano se salta una ejecución en primavera y ejecuta una dos veces en otoño; UTC no hace ninguna de las dos cosas, pero se desfasa una hora respecto a tu reloj dos veces al año.

Montajes¶

Monta el socket de Docker, el flash (/boot) y la raíz de Host Data (/mnt) como se muestra en la plantilla de CA. Tanto los orígenes como los destinos de las copias viven bajo Host Data, y se monta como slave para que un recurso compartido remoto que se monte después de que arranque el contenedor (por ejemplo bajo /mnt/remotes) se vuelva visible sin reiniciar.

Las copias de conjuntos de datos ZFS también necesitan este modo: el host monta la instantánea de un conjunto solo después de que el contenedor haya arrancado. Consulta Conjuntos de datos ZFS.

Las rutas de repositorio de copia son por defecto /mnt/user/bombvault/{container,vms,flash,config,files,zfs}, creadas en la primera copia. Cambia la ubicación en cualquier momento en Ajustes, Almacenamiento, Rutas de copia. Cada campo de ruta tiene además un conmutador Local / Remoto integrado: una ruta puede ser un remoto de restic (s3:..., rest:..., sftp:..., rclone:...) en lugar de una carpeta local, y la copia va directamente allí, sin copia local aparte; consulta Repositorios primarios remotos.

Comprobación de integración con el host

Abre /spike en la interfaz web después de que arranque el contenedor. Sondea cada montaje y CLI (socket de Docker, libvirt, restic, qemu-img, rclone) e informa de cualquier pieza que falte.

Detección de las fuentes de copia¶

Para cada contenedor, BombVault elige por sí mismo qué montajes bind y volúmenes con nombre se copian. Una ruta se toma en cuanto se cumple alguno de estos puntos (el resultado siempre se puede corregir por contenedor en sus Carpetas a copiar):

Coincidencia de un segmento de raíz de datos: el origen en el host del bind contiene uno de los segmentos de DATA_ROOT_SEGMENTS como componente completo de ruta (por omisión solo appdata).
Los volúmenes Docker con nombre se incluyen siempre, porque no tienen equivalente desechable y por tanto no hay nada que filtrar, pero solo cuando la ruta real de almacenamiento del volumen en el host es accesible a través del montaje Host Data, igual que cualquier otra ruta de host que copia BombVault. El controlador local por omisión guarda un volumen bajo la raíz de datos del propio demonio, es decir /var/lib/docker/volumes/<nombre>/_data salvo que se haya personalizado (compruébalo con docker info -f '{{.DockerRootDir}}'). Ese lugar NO queda cubierto por el montaje Host Data estrecho, de un solo directorio, que el docker-compose.yml genérico usa por omisión. Un volumen inaccesible se omite en silencio, no es un error. Para copiar de verdad los volúmenes con nombre en un host genérico, apunta Host Data (y HOST_SOURCE_ROOT) a un ancestro común que cubra también la raíz de datos de Docker: mira el comentario Host Data del fichero compose para ver la contrapartida (Unraid lo evita montando todo /mnt, su propia convención universal de primer nivel, por la misma razón).
Directorio de proyecto de Docker Compose: si el contenedor lleva la etiqueta estándar com.docker.compose.project.working_dir (que docker compose up pone automáticamente), ese directorio se añade también, con independencia de que algún bind haya coincidido con un segmento de raíz de datos.
Anulación mediante la etiqueta bombvault.data: pon la etiqueta bombvault.data=true en un contenedor para incluir TODOS sus montajes bind, para una disposición que ninguna de las dos convenciones anteriores atrapa (por ejemplo un único bind /srv/plex/config sin proyecto Compose). Cualquier valor no vacío distinto de false cuenta como verdadero; una etiqueta ausente o bombvault.data=false no cambia nada.
Etiqueta bombvault.dbdump: pon bombvault.dbdump=false en un contenedor para apagar su volcado automático de base de datos (0, no y off hacen lo mismo), o nombra el motor (postgres, mysql, mariadb) para volcar un contenedor que BombVault no reconoce por sí solo. La etiqueta manda sobre el interruptor de la tarjeta del contenedor, que es la vía habitual en Unraid.

Modelo de seguridad¶

Control del host equivalente a root

A través del socket de Docker, BombVault puede detener, eliminar y recrear contenedores y leer/escribir appdata, y para la copia de VMs inicia sesión en el host por SSH (qemu+ssh://, root por defecto) para ejecutar virsh. Cualquiera que pueda alcanzar su interfaz web tiene, en la práctica, acceso root al host.

Protección por contraseña opcional (Ajustes, Seguridad): establece una contraseña para exigir inicio de sesión, bórrala para desactivarla. Desactivada por defecto para uso en una LAN de confianza. La contraseña se guarda con Argon2id sobre un valor con pimienta derivada de APP_KEY, así que un /config copiado no vale nada sin la clave y es lento de atacar con ella. Una contraseña nueva necesita al menos 12 caracteres; una más corta que ya exista sigue funcionando hasta que se cambie. Las sesiones están firmadas (HMAC derivado de APP_KEY) y cambiar la contraseña las invalida; los inicios de sesión se limitan a cinco fallos por minuto y cliente.
Autenticación en dos pasos (Ajustes): un código temporal de una aplicación de autenticación además de la contraseña, más ocho códigos de recuperación de un solo uso que se entregan una vez al activarla. El secreto compartido se guarda cifrado con APP_KEY, y desactivarla de nuevo exige un código actual.
Claves de acceso (WebAuthn): tienen su propia tarjeta en cuanto hay una contraseña definida, junto a la contraseña y nunca en su lugar, así que eliminar todas las claves de acceso no deja fuera a nadie. Necesitan un nombre de dominio real y un certificado en el que confíe el navegador. La dirección por defecto https://<ip>:3443 es justo lo que WebAuthn rechaza, y la tarjeta lo dice en lugar de ofrecer un botón que fallaría.
Los cambios requieren JSON. Una petición que cambia algo debe enviar Content-Type: application/json y el navegador no debe marcarla como procedente de otro sitio, para que una página de otro sitio no pueda hacer que tu navegador cambie ajustes en una dirección de la LAN. Un script que use la API envía esa cabecera; todo lo demás se rechaza con 415.
Como la protección es opcional, cuando no se define, toda la interfaz y la API (incluidas la configuración externa, las rutas de prueba de manipulación y el kit de recuperación) están al alcance de cualquiera que pueda llegar al puerto. Activa la protección en cuanto uses copias externas, inmutables o cifrado.
Ejecuta BombVault solo en una red de confianza y no expuesta. Para acceso remoto, ponlo detrás de un proxy inverso que añada autenticación y TLS. Las respuestas llevan cabeceras de seguridad básicas (CSP, nosniff, X-Frame-Options, Referrer-Policy).
Detrás de un proxy inverso cada petición lleva la dirección del proxy, así que sin TRUSTED_PROXY el límite de intentos cuenta a todos los clientes en el mismo contador y los fallos de un atacante te dejan fuera a ti también. Indica el proxy en TRUSTED_PROXY para recuperar el conteo por cliente.
Un proxy inverso delante de BombVault tiene que pasar la cabecera Authorization o X-API-Key a /mcp y no debe almacenar sus respuestas en búfer; si no, los asistentes no pueden conectarse. Ver Servidor MCP.
El endpoint MCP /mcp responde 404 mientras no exista ninguna clave ni esté activado el inicio de sesión mediante OAuth, y pide a cada cliente su clave o su token incluso con la contraseña de inicio de sesión desactivada; ninguna dirección está exenta, ni siquiera localhost. No tiene herramientas de restauración ni de borrado, y restaurar una copia de la configuración revoca todas las claves. Ver Servidor MCP.
Con HTTP_ONLY=true, la cookie de sesión pierde su marca Secure (tiene que hacerlo para funcionar por HTTP en texto plano), así que activa la contraseña detrás de un proxy que termina TLS solo si la confidencialidad importa.
La conexión SSH de la copia de VMs confía en la clave del host en la primera conexión (TOFU) y la fija a partir de entonces. Verifica la clave del host fuera de banda si tu ruta contenedor-a-host no es de confianza.
Las copias están cifradas por restic cuando el cifrado está habilitado (Ajustes; activado por defecto), con la clave derivada de APP_KEY.

Servidor MCP¶

El servidor MCP no necesita ninguna variable de entorno. Lo activas creando una clave en Ajustes, Integraciones, Servidor MCP, y responde en /mcp en el mismo puerto que la interfaz web (por ejemplo https://192.168.1.10:3443/mcp). Sin una clave activa, esa ruta responde 404. Los clientes, los certificados y los límites se describen en Servidor MCP.

Copia de VMs por SSH¶

BombVault copia las VMs KVM/libvirt sin montar ninguna ruta de libvirt. Ejecuta virsh en el host por SSH (qemu+ssh://), de modo que nunca puede afectar al VM Manager de tu host.

Montar el socket de libvirt del host dentro de un contenedor es frágil en Unraid: esas rutas pertenecen al VM Manager, y cambiar "Enable VMs" puede dejar libvirt sin poder arrancar. La clave SSH da acceso root al host, el mismo nivel de confianza que el socket de Docker que BombVault ya usa.

Configuración rápida:

Ajustes, Integraciones, SSH del host: copia la clave pública mostrada.
Añádela al /root/.ssh/authorized_keys de Unraid (también persistido al flash para que sobreviva a los reinicios).
Haz clic en Probar conexión.

La plantilla añade --add-host=host.docker.internal:host-gateway para que el contenedor pueda alcanzar el host. Establece LIBVIRT_HOST a la IP LAN de tu Unraid si ese nombre no resuelve (por ejemplo cuando el contenedor se ejecuta en una red br0.x personalizada). Si cambiaste el puerto SSH de Unraid, establece LIBVIRT_SSH_PORT para que coincida. Las instantáneas en vivo necesitan además el agente invitado de qemu en la VM y el disco en /mnt/cache (no en /mnt/user).

Guía completa de configuración de VMs y red

La guía paso a paso completa (habilitación de SSH, autorización persistente de claves, enrutamiento en redes personalizadas y VLAN, método por VM y resolución de problemas del lado del host) está en docs/vm-backup-ssh-setup.md en GitHub.

Configuración externa¶

Configura una réplica externa en la página Ajustes, Externo. Consulta Copia externa y recuperación para el flujo completo (inmutable/append-only, prueba de manipulación y ensayos de DR). En resumen:

Backends: SMB/CIFS y NFS (monta el recurso compartido y apunta una Ruta de copia a él), backends nativos de restic sin rclone (s3:..., rest:http://host:8000/repo, sftp:user@host:/repo), o cualquier remoto de rclone (rclone:<remote>:<bucket>/path). Backblaze B2 no tiene un backend nativo aquí: se accede a través de su punto de conexión S3 (s3:https://s3.<region>.backblazeb2.com/<bucket>/<path>), con el ID de clave y la clave de aplicación como credenciales de S3.
Las credenciales de nube compartidas se almacenan cifradas en Ajustes, Acceso a la nube, Credenciales de nube compartidas.
Los destinos SSH no requieren nada instalado en el otro extremo. sftp: solo necesita un servidor SSH. Añade la clave pública de Ajustes, Integraciones, SSH del host (también en /config/ssh/id_ed25519.pub) al ~/.ssh/authorized_keys del usuario de destino.
Copia externa: BombVault replica las nuevas instantáneas con restic copy en modo de mejor esfuerzo, además de un repositorio primario (normalmente local). Cada dominio tiene su propio calendario externo, más un botón Replicar ahora.
Varios destinos externos por dominio: cada dominio puede replicarse a varios destinos externos a la vez. Añade destinos adicionales en Ajustes, Externo, cada uno con su propio repositorio, clase de almacenamiento S3, marca append-only, retención y presupuesto de crecimiento; todos se replican según el calendario externo de ese dominio. Una configuración externa única existente se traslada como el primer destino.
Destinos: los destinos externos se configuran una sola vez en Ajustes, Externo, Destinos, con un asistente que enumera todos los servicios admitidos. Consulta Destinos.
Ubicación por elemento: cada contenedor, VM y conjunto de archivos enciende Local y los destinos que reciben sus copias de seguridad. Ajustes, Almacenamiento, Valores predeterminados de ubicación lo define por dominio para los elementos sin elección propia. Consulta Ubicación por elemento.
Retención por fuente: las políticas local y externa viven ambas en Ajustes, Retención (deja la externa toda a cero para no recortar nunca automáticamente las instantáneas externas). Las tarjetas Retención local y Retención externa tienen cada una Reglas de retención por origen, que dan a los contenedores, VM, flash, carpetas, ZFS o la autocopia sus propias reglas de retención, para sus copias locales y para su repo externo. Un origen sin ellas sigue las compartidas, y la retención tras cada copia, la copia externa, una purga manual y la vista previa de retención usan las reglas del origen con el que trabajan. Los destinos externos adicionales mantienen las reglas que tienen en Ajustes, Externo.
Límites de ancho de banda: limita la velocidad de subida/bajada de restic en Ajustes, Externo.
Primero el streaming: en Ajustes, Externo, elige los servidores multimedia (Plex, Jellyfin y Emby vienen preseleccionados por el nombre de la imagen), la tasa de envío a partir de la cual uno cuenta como en streaming, el límite de subida mientras dura y cuánto tiempo después vuelve el límite normal.
Clase de almacenamiento en frío y de archivo (S3): para un repo externo S3 nativo, elige un nivel legible para restauración (Standard, Standard-IA, One Zone-IA, Intelligent-Tiering, Glacier Instant Retrieval). Los remotos de rclone establecen su clase en la configuración de rclone.
Primario remoto en lugar de local: la Ruta de copia de un dominio puede ser ella misma uno de los backends anteriores, sin copia local ni paso de replicación; consulta Repositorios primarios remotos para el conmutador Local/Remoto integrado y sus ajustes de seguridad (ancho de banda, append-only, presupuesto de crecimiento).

Anomalías¶

La detección de anomalías se configura en la tarjeta Anomalías de Ajustes, Integridad. Cada control se guarda en cuanto lo cambias, y los tres que hay bajo el interruptor se ocultan mientras la detección está desactivada.

Ajuste	Predeterminado	Qué hace
Detectar anomalías	Activado	Compara cada copia con el historial propio del elemento. Desactivado, no se comprueba nada nuevo y la entrada Anomalías desaparece de la barra lateral; la tarjeta sigue enlazando con los hallazgos anteriores.
Sensibilidad	Equilibrada	Estricta avisa de cambios más pequeños, Permisiva solo de los grandes.
Enviar una notificación para	Solo hallazgos críticos	La gravedad mínima que envía un mensaje por los canales configurados en Notificaciones. Los fallos repetidos de copias y volcados y las comprobaciones de restauración programadas fallidas ya envían su propio mensaje y no se envían dos veces.
Conservar las copias antiguas cuando un origen se reduce mucho o se reescribe	Activado	Mientras un elemento tenga un hallazgo abierto por una fuente casi vacía, un encogimiento fuerte o la mayoría de sus datos guardados de nuevo, la retención y la limpieza no tocan sus copias antiguas. Confirma el hallazgo o márcalo como esperado para liberarlas.

Cada elemento puede tener su propia sensibilidad y su propio mínimo de notificación. Ajústalos en la página Anomalías, donde un elemento con hallazgos abiertos los tiene bajo Supervisión en su tarjeta y cualquier otro elemento los abre desde la tarjeta Nada abierto, o en el panel del propio elemento: la sección de carpetas de un contenedor y los ajustes de una VM (ambos en modo avanzado), el editor de carpetas de un conjunto de carpetas y las páginas Flash y Autocopia. En un elemento ZFS están en su editor de la página ZFS y valen para todos los conjuntos de datos de su árbol.

Ajustes portátiles (exportar e importar)¶

La tarjeta Exportar / importar ajustes en la página de Ajustes, Sistema escribe toda tu configuración de BombVault (ajustes de dominio, destinos externos, calendarios, retención, notificaciones) en un archivo JSON portátil que puedes importar en otra instancia, para que cambiar de máquina o clonar una instalación no signifique volver a introducirlo todo a mano. La importación muestra una vista previa y pide confirmación, y nunca toca tus datos de copia ni tu historial.

La exportación puede contener credenciales

Tú eliges si incluir las credenciales externas, de notificación y del broker MQTT en el archivo. Con las credenciales incluidas, la exportación es tan sensible como tu kit de recuperación, así que guárdala en un lugar seguro. Sin ellas, el archivo contiene solo ajustes no secretos.