구성¶
이 페이지는 컨테이너의 환경 변수, 템플릿이 제공하는 마운트, 보안 모델, SSH를 통한 VM 백업, 오프사이트 설정을 다룹니다. 백업이 가는 곳은 환경 변수가 아니라 앱 안에서 대상으로 설정합니다.
환경 변수¶
| 변수 | 필수 | 설명 |
|---|---|---|
APP_KEY |
예 | restic 저장소 비밀번호를 파생하는 데 쓰는 32바이트 16진수 비밀 값(16진수 64자)입니다. openssl rand -hex 32로 만드세요. 안전하게 보관하세요. 잃어버리면 암호화된 백업을 복구할 수 없습니다. |
LIBVIRT_HOST |
VM 및 ZFS 데이터세트용 | VM과 ZFS 데이터세트 백업을 위해 SSH로 접속하는 Unraid 호스트입니다(템플릿 필드 Host SSH: Address, 기본값 host.docker.internal). 템플릿은 자리 표시자 192.168.x.x를 미리 채워 두는데, 이는 설정하지 않은 것으로 봅니다. Unraid의 LAN IP를 쓰세요. 사용자 지정 br0.x 네트워크에서는 필수입니다. TrueNAS 앱처럼 host.docker.internal이 확인되지 않고 LIBVIRT_URI에도 호스트가 없으면, BombVault는 컨테이너의 기본 게이트웨이를 사용하며 부팅 로그에 그 주소를 남깁니다. |
LIBVIRT_SSH_PORT |
아니요 | VM과 ZFS 데이터세트 백업에 쓰는 호스트 SSH 포트입니다(템플릿 필드 Host SSH: Port, 기본값 22). |
LIBVIRT_SSH_USER |
아니요 | VM과 ZFS 데이터세트 백업에 쓰는 호스트의 SSH 사용자입니다(템플릿 필드 Host SSH: User, 기본값 root). |
LIBVIRT_URI |
아니요 | 전체 libvirt 연결 URI입니다. 위의 세 LIBVIRT_* 변수로 연결 문자열을 만드는 대신 이 값을 그대로 씁니다(이 경우 그 변수들은 연결 문자열에 쓰이지 않습니다). 기본값은 설정되지 않음입니다. TrueNAS Scale에서 필요합니다. 이곳의 libvirtd는 조합 방식으로 표현할 수 없는 비표준 소켓에서 대기합니다. 예: qemu+ssh://<user>@<truenas-host>/system?socket=/run/truenas_libvirt/libvirt-sock. VM 백업 가이드를 참고하세요. qemu+ssh:// URI이면 LIBVIRT_HOST, LIBVIRT_SSH_USER, LIBVIRT_SSH_PORT 중 설정하지 않은 것은 각각 여기서 가져오며, BombVault 자체의 SSH 명령(NVRAM 전송, ZFS 데이터세트)에도 적용됩니다. |
PORT |
아니요 | HTTP 포트입니다(기본값 3000. HTTP_ONLY=true일 때만 쓰입니다). |
HTTPS_PORT |
아니요 | HTTPS 포트입니다(기본값 3443. 템플릿이 1:1로 게시하므로 WebUI는 https://<ip>:3443에서 응답합니다). |
HTTP_ONLY |
아니요 | true로 설정하면 자체 서명 HTTPS 리스너를 끄고 일반 HTTP만 제공합니다(TLS를 종료하는 리버스 프록시 뒤에서 쓸 때). |
BIND_HOST |
아니요 | WebUI가 수신 대기하는 주소입니다(기본값 0.0.0.0, 모든 인터페이스). 컨테이너에서는 게시된 포트에 모든 인터페이스가 필요하므로 설정하지 마세요. 127.0.0.1은 Docker 밖에서 실행할 때 알맞습니다. 헬스체크도 같은 주소로 요청합니다. |
TRUSTED_PROXY |
아니요 | BombVault 앞에 있는 리버스 프록시의 주소 또는 CIDR 범위를 쉼표로 구분해 적습니다(예: 192.168.20.11 또는 10.0.0.0/8). 이 홉에서 온 요청만 X-Forwarded-For를 신뢰하며, 그러면 로그인 제한이 프록시 뒤의 모두를 한 통에 담는 대신 실제 클라이언트별로 실패를 셉니다. 설정하지 않으면(기본값) 아무도 신뢰하지 않습니다. 무조건 신뢰하는 헤더는 누구나 자기 계수기를 고를 수 있게 만들기 때문입니다. |
HOST_SOURCE_ROOT |
아니요 | Host Data로 마운트하는 호스트 경로입니다(기본값 /mnt). BombVault는 Docker가 알려 주는 바인드 마운트 원본을 이 마운트 아래의 경로로 바꿉니다. 다른 호스트 루트를 마운트했을 때만 바꾸세요. |
HOST_MOUNT_ROOT |
아니요 | 컨테이너 안에서 Host Data가 마운트되는 위치입니다(기본값 /host/user). TrueNAS에서는 Host Data가 호스트와 같은 경로에 마운트되므로, 이 변수와 HOST_SOURCE_ROOT 모두 그 경로(예: /mnt/tank)를 가리킵니다(TrueNAS SCALE 참고). |
DATA_ROOT_SEGMENTS |
아니요 | 바인드 마운트 원본을 백업 데이터로 표시하는 경로 구간 이름을 쉼표로 구분해 적습니다(기본값 appdata, Unraid의 /mnt/user/appdata/<container> 관례와 같습니다). 나열한 구간 중 하나라도 호스트 원본 경로의 온전한 구간으로 나타나면 그 컨테이너의 바인드 마운트가 백업 대상으로 자동 선택됩니다. 예를 들어 DATA_ROOT_SEGMENTS=appdata,config는 .../config 바인드도 함께 잡습니다. 대소문자는 구분하지 않으므로 기본값으로도 ZimaOS의 /DATA/AppData/<container>를 찾습니다. 컨테이너의 데이터 폴더를 찾는 그 밖의 상시 방식은 백업 원본 자동 판별을 참고하세요. |
PLATFORM |
아니요 | 자동 감지 대신 BombVault가 자신이 어느 플랫폼에서 돌아가는지 판단하는 값을 강제로 정합니다. unraid, generic, truenas 중 하나입니다(기본값은 설정되지 않음입니다. 플래시 마운트 아래의 dockerMan 표시를 찾아 Unraid를 자동 감지하고, 못 찾으면 generic으로 처리합니다. 인식하지 못하는 값도 generic으로 처리하며 이때 로그를 남깁니다). 일반 Docker 호스트나 TrueNAS Scale에서는 Unraid 전용 자동 감지에 맡기지 말고 직접 지정하세요. 일반용 compose 파일이 그렇게 되어 있습니다. 이 값은 appdata 대체 관례, 인스턴스 간 복원 대상의 기본값, Unraid 전용 알림과 컴패니언 플러그인 단계를 시도할지 여부를 바꿉니다(internal/platform 참고). |
BOMBVAULT_SELF_CONTAINER |
아니요 | BombVault 컨테이너 자신의 이름입니다. 자기 자신을 백업(그래서 중지)하지 않게 합니다. |
BACKUP_MAX_HOURS |
아니요 | 백업 한 번이 강제로 취소되기 전까지 섹션 잠금을 쥐고 있을 수 있는 최대 실제 경과 시간입니다(멈춘 실행이 섹션을 영원히 막지 못하게 하는 보호 장치). 비워 두면(기본값) 48을 씁니다. 아주 크거나 느린 클라우드 백업에는 값을 높이세요(상한에서 취소된 실행은 context deadline exceeded로 실패합니다). 0으로 두면 상한이 완전히 꺼집니다. 정리도 같은 상한을 따르고, 점검이나 정리는 restic이 진행 상황을 계속 알리는 한 계속 실행됩니다. |
BACKUP_STALL_HOURS |
아니요 | 백업이 전혀 진행되지 않는 상태로 취소되기 전까지 버틸 수 있는 시간입니다. 비워 두면(기본값) 2를 쓰고, 0으로 두면 정체를 이유로 취소하지 않습니다. 두 보호 장치 중 더 세밀한 쪽이고 보통 먼저 작동하는 것도 이쪽입니다. 실행이 얼마나 오래 걸렸는지가 아니라 아직 무언가 일어나고 있는지를 보기 때문에, 느리지만 정상인 수 테라바이트 백업은 그대로 두고, 응답하지 않는 공유에서 멈춘 백업은 며칠이 아니라 몇 시간 만에 멈춥니다. 무엇이든 취소하기 전에, 30분 동안 아무 움직임이 없으면 경고를 로그에 남깁니다. 스캔도 진행으로 칩니다. restic은 큰 트리를 훑는 동안 바이트를 쓰지 않으므로, 그 단계는 쓴 바이트가 아니라 파일과 바이트 합계로 지켜봅니다. 두 변수는 서로 독립적이며, BACKUP_MAX_HOURS는 백업 자체 이후의 단계(보존, 통계, 오프사이트 복사)에도 여전히 상한을 둡니다. 그 단계에는 지켜볼 카운터가 없기 때문입니다. |
DB_DUMP_MAX_HOURS |
아니요 | 자동 데이터베이스 덤프 한 번이 중단되기 전까지 실행될 수 있는 시간입니다. 비워 두면(기본값) 6을 씁니다. 허용 범위는 1부터 48까지이고, 이 한도는 BACKUP_MAX_HOURS보다 한 시간 낮게 유지됩니다(그 값이 두 시간 미만이면 절반). 긴 덤프가 백업 전체를 함께 무너뜨리지 않고 자기 한도에서 끊겨 그렇게 보고되도록 하기 위해서입니다. 진행이 없는 덤프는 BACKUP_STALL_HOURS가 지나면 그보다 일찍 중단됩니다. 중단된 덤프는 그것만 실패하고 컨테이너 백업은 계속됩니다. Unraid에서는 Add another Path, Port, Variable로 BombVault 컨테이너에 추가합니다. |
TZ |
아니요 | 스케줄러의 시간대입니다(예: Europe/Berlin). 설정하지 않으면 모든 일정이 UTC로 실행됩니다. 02:30으로 정한 일정은 현지 시간이 아니라 02:30 UTC에 시작됩니다. Unraid에서는 직접 설정할 필요가 없습니다. 시스템이 자신의 시간대를 모든 컨테이너에 넘겨 줍니다. 어떤 시간대로 정해졌는지는 부팅 로그에 나옵니다. 일광 절약 시간이 있는 시간대에서는 봄에 실행 한 번을 건너뛰고 가을에 한 번을 두 번 실행합니다. UTC는 둘 다 겪지 않지만 대신 일 년에 두 번 실제 시계와 한 시간씩 어긋납니다. |
DATA_DIR |
아니요 | BombVault가 데이터베이스, 키, 캐시를 두는 곳입니다(기본값 /config). 컨테이너에서는 건드리지 마세요. Docker 밖에서 바이너리를 실행할 때 의미가 있습니다. |
FLASH_DIR, FLASH_TEMPLATES_DIR |
아니요 | 플래시 드라이브와 그 Docker 템플릿이 컨테이너 안에 마운트되는 위치입니다(기본값 /host/boot와 /host/boot/config/plugins/dockerMan/templates-user). 템플릿의 /boot 마운트를 따르므로 설정하지 마세요. |
MODE |
아니요 | full(기본값)은 앱 전체를 실행합니다. node는 노드를 실행합니다. 웹 인터페이스도 자체 일정도 없이 홈 인스턴스가 지시하는 일만 합니다. 다른 값이면 메시지를 남기고 시작을 멈춥니다. 노드의 compose 파일에서는 홈 인스턴스가 대신 채워 줍니다. |
NODE_HOME |
노드용 | 노드가 어느 홈 인스턴스에 속하는지를 홈 인스턴스의 키와 릴레이와 함께 bvhome1.로 시작하는 값 하나로 나타냅니다. 홈 인스턴스가 노드의 compose 파일에 적어 줍니다. 없으면 노드는 시작하지만 어느 홈 인스턴스도 노드에 닿지 못합니다. 홈 인스턴스가 맡은 노드는 NODE_HOME이 다른 홈 인스턴스를 가리키면, 그 홈 인스턴스가 노드를 해제할 때까지 시작을 거부합니다. |
NODE_NAME |
아니요 | 노드의 이름으로, 노드에 붙인 이름을 바탕으로 홈 인스턴스가 채워 줍니다. |
마운트¶
CA 템플릿에 나온 대로 Docker 소켓, 플래시(/boot), Host Data 루트(/mnt)를 마운트하세요. 백업 원본과 대상은 모두 Host Data 아래에 있으며, slave로 마운트되므로 컨테이너가 시작된 뒤에 마운트되는 원격 공유(예: /mnt/remotes 아래)도 재시작 없이 보입니다.
TrueNAS에서 Host Data는 /mnt/tank 같은 데이터세트 경로이며 ixVolume이어서는 안 됩니다. 앱이 ixVolume에 두는 데이터는 그 바깥에 있어 백업되지 않습니다. TrueNAS SCALE을 참고하세요.
ZFS 데이터세트 백업에도 이 모드가 필요합니다. 호스트는 컨테이너가 시작된 뒤에야 데이터세트의 스냅샷을 마운트하기 때문입니다. ZFS 데이터세트를 참고하세요.
로컬 저장소는 기본적으로 /mnt/user/bombvault/{container,vms,flash,config,files,zfs}에 있으며 첫 백업 때 만들어집니다. 이들은 각 섹션의 전용 폴더이고 로컬 대상을 이룹니다. 그 페이지의 대상에서 연결 카드가 섹션별 폴더를 바꿉니다.
섹션의 전용 폴더는 NAS나 S3 버킷처럼 이미 있는 대상에 둘 수도 있습니다. 그 대상 페이지의 전용 폴더로 사용을 누르면 폴더가 그곳으로 옮겨지고, 그 전에 이미 만든 백업이 어떻게 되는지 먼저 알려 줍니다. 섹션의 전용 폴더를 참고하세요.
로컬 저장소 폴더는 모드 0755와 0644로 유지되므로 SMB로 접속하는 root가 아닌 동기화 사용자도 막히지 않으며, 저장소는 암호화되어 있어 이것이 아무것도 노출하지 않습니다. 복구 정의는 각 저장소 안에 들어 있어 복사한 폴더 하나만으로 완전합니다. 자체 백업 저장소는 root만 읽을 수 있게 유지됩니다.
호스트 통합 확인
개요의 호스트 통합 카드(사용자 지정에서 추가)는 모든 마운트와 CLI(Docker 소켓, libvirt, restic, qemu-img, rclone)를 검사하고 빠진 부분을 알려 줍니다.
백업 원본 자동 판별¶
컨테이너마다 어떤 바인드 마운트와 명명된 볼륨을 백업할지는 BombVault가 스스로 고릅니다. 다음 중 하나에 해당하면 경로가 채택됩니다(결과는 컨테이너의 설정 탭에 있는 백업 폴더 카드에서 언제든 바꿀 수 있습니다).
- 데이터 루트 구간 일치: 바인드의 호스트 원본이
DATA_ROOT_SEGMENTS의 구간 중 하나를 온전한 경로 요소로 포함하는 경우입니다(기본값은appdata뿐). - Docker의 명명된 볼륨은 걸러낼 것이 없고 버려도 되는 대응물도 없어서 항상 포함됩니다. 다만 그 볼륨의 실제 호스트 저장 경로 자체가 Host Data 마운트를 통해 닿을 수 있을 때만 해당하며, 이는 BombVault가 백업하는 다른 호스트 경로와 똑같은 조건입니다. Docker의 기본 로컬 볼륨 드라이버는 볼륨을 데몬 자신의 데이터 루트 아래, 바꾸지 않았다면
/var/lib/docker/volumes/<name>/_data에 둡니다(docker info -f '{{.DockerRootDir}}'로 확인하세요). 이 위치는 일반docker-compose.yml이 기본으로 쓰는 단일 디렉터리의 좁은 Host Data 마운트에 포함되지 않습니다. 닿을 수 없는 볼륨은 오류 없이 조용히 건너뜁니다. 일반 호스트에서 명명된 볼륨을 실제로 백업하려면 Host Data(그리고HOST_SOURCE_ROOT)를 Docker 데이터 루트까지 아우르는 공통 상위 경로로 지정하세요. 득실은 compose 파일의 Host Data 주석에 설명되어 있습니다(Unraid는 같은 이유로 자체 최상위 관례인/mnt전체를 마운트해 이 문제를 비껴갑니다). - Docker Compose 프로젝트 디렉터리: 컨테이너에 표준 레이블
com.docker.compose.project.working_dir(docker compose up이 자동으로 붙입니다)이 있으면, 어떤 바인드가 데이터 루트 구간에 맞았는지와 상관없이 그 디렉터리도 추가됩니다. - 레이블
bombvault.data로 덮어쓰기: 컨테이너에bombvault.data=true레이블을 붙이면 그 바인드 마운트를 모두 포함합니다. 위의 두 관례로 잡히지 않는 구성(예: Compose 프로젝트 없이/srv/plex/config바인드 하나만 있는 경우)을 위한 것입니다.false가 아닌 비어 있지 않은 값은 모두 참으로 칩니다. 레이블이 없거나bombvault.data=false이면 아무것도 달라지지 않습니다. - 레이블
bombvault.dbdump: 컨테이너에bombvault.dbdump=false를 붙이면 그 컨테이너의 자동 데이터베이스 덤프가 꺼집니다(0,no,off도 같습니다). 엔진 이름(postgres,mysql,mariadb)을 적으면 BombVault가 스스로 알아보지 못하는 컨테이너도 덤프합니다. 레이블은 컨테이너의 설정 탭에 있는 데이터베이스 카드의 스위치보다 우선하며, Unraid에서는 그 스위치를 쓰는 것이 방법입니다.
보안 모델¶
호스트에 대한 root에 준하는 제어 권한
Docker 소켓을 통해 BombVault는 컨테이너를 중지, 제거, 재생성할 수 있고 appdata를 읽고 쓸 수 있으며, VM 백업을 위해 SSH(qemu+ssh://, 기본값 root)로 호스트에 로그인해 virsh를 실행합니다. 웹 UI에 접근할 수 있는 사람은 사실상 호스트의 root 권한을 가진 것과 같습니다.
로그인¶
- 선택 사항인 비밀번호 보호(설정, 보안의 비밀번호 카드): 비밀번호를 설정하면 로그인이 필요해지고, 지우면 꺼집니다. 신뢰할 수 있는 LAN에서 쓰는 것을 전제로 기본값은 꺼짐입니다. 비밀번호는
APP_KEY로 후추를 친 값 위에 Argon2id로 저장되므로, 복사한/config는 키 없이는 쓸모가 없고 키가 있어도 공격이 느립니다. 새 비밀번호는 12자 이상이어야 합니다. 이미 있는 더 짧은 비밀번호는 바꿀 때까지 계속 쓸 수 있습니다. 세션은 서명되어 있으며(APP_KEY에서 파생한 HMAC) 비밀번호를 바꾸면 무효가 됩니다. 로그인은 클라이언트마다 분당 다섯 번의 실패로 제한됩니다. 비밀번호를 바꾸거나 지울 때는 현재 비밀번호를 묻고, 2단계 인증이 켜져 있으면 코드도 묻습니다. - 일부 기능은 비밀번호가 필요합니다. 복구 키트, 버그 보고서, 플래시 백업 ZIP 내려받기, 플래시 백업이나 셀프 백업 내보내기, 키 보관 측에 키 맡기기, 맡긴 키를 내줘도 된다고 허용하기, 새 수령 코드 만들기, 자격 증명을 포함한 설정 내보내기, 2단계 인증, 패스키, 노드 추가, 노드의 compose 파일 다시 보기, 노드의 항목 열기는 로그인 비밀번호를 설정하기 전에는 거부되며, 인스턴스 자체에서 로그인해야 합니다. 백업 삭제는 비밀번호 없이도 할 수 있습니다. 비밀번호를 설정했다면 삭제에도 이 로그인이 필요합니다.
- 대상에는 비밀번호가 보이지 않습니다. 대상에는
rest:https://user:password@host/repo처럼 자격 증명이 들어갈 수 있으며, 로그인 비밀번호가 있든 없든 모든 페이지와 API 응답은 이를rest:https://[redacted]@host/repo로 보여 줍니다. 그 뒤의 경로를 바꿔도 저장된 비밀번호는 그대로 남습니다. 대상을 다른 서버로 바꾸려면 비밀번호까지 포함해 대상 전체를 입력하세요. 숨겨진 비밀번호는 원래 서버에 묶여 있기 때문입니다. - 2단계 인증(설정, 보안): 비밀번호에 더해 인증 앱의 시간 기반 코드를 쓰며, 켤 때 한 번만 일회용 복구 코드 여덟 개를 받습니다. 공유 비밀은
APP_KEY로 암호화해 저장하고, 다시 끄려면 현재 코드가 필요합니다. - 패스키(WebAuthn)는 비밀번호를 설정하면 별도의 카드에 나타납니다. 비밀번호를 대신하지 않고 함께 쓰는 것이므로 패스키를 모두 지워도 아무도 잠기지 않습니다. 실제 도메인 이름과 브라우저가 신뢰하는 인증서가 필요합니다. 기본 주소
https://<ip>:3443은 WebAuthn이 거부하는 바로 그 형태라서, 카드는 실패할 버튼을 보여 주는 대신 그렇다고 알려 줍니다. 2단계 인증이 켜져 있으면 패스키가 PIN, 지문 또는 얼굴을 확인해야 하고, 그렇지 않으면 로그인할 때 코드도 묻습니다. - 구성 복원(긴급 마법사의 설정 되돌리기)은 모든 세션을 끝내고, 모든 패스키를 지우며, 모든 API 토큰과 MCP 키를 폐기합니다. 복원한 설정에는 저장한 뒤에 제거한 것들이 되살아나 있을 수 있기 때문입니다. 비밀번호로 로그인한 다음 설정, 보안에서 패스키를 다시 설정하세요.
- 잊어버린 비밀번호는 로그인 페이지에서 재설정합니다. 비밀번호를 잊으셨나요?를 누르면 BombVault가 네 글자씩 세 묶음, 12자로 된 코드를 컨테이너 로그에 기록합니다(Unraid에서는 Docker 탭에서 BombVault 아이콘을 누르고 Logs를 엽니다). 그 코드와 새 비밀번호로 로그인합니다. 재설정하면 2단계 인증이 꺼지고, 모든 패스키가 지워지며, 모든 API 토큰, MCP 키, OAuth 로그인이 폐기되고, 다른 세션은 모두 끝나며, 페어링한 휴대폰은 모두 로그아웃되고 휴대폰 페어링이 꺼집니다. 그다음 페이지에서 무엇이 없어졌는지 보여 줍니다. 코드는 10분 동안 유효하고, 잘못 입력해도 코드가 소진되지 않습니다. 위젯 토큰과 메트릭 토큰은 읽기만 하므로 그대로 남습니다.
- 컨테이너 로그를 읽을 수 있는 사람은 누구나 비밀번호를 재설정할 수 있습니다. 호스트의 root뿐 아니라 Dozzle 같은 로그 뷰어, Docker 소켓에 접근할 수 있는 모든 컨테이너(읽기 전용이어도 충분합니다), 컨테이너 출력을 전달하는 로그 수집기도 마찬가지입니다. 이런 권한은 비밀번호를 맡길 수 있는 사람에게만 주세요. 웹 인터페이스에만 접근할 수 있는 사람은 코드를 볼 수 없습니다.
휴대폰과 그룹 구성원¶
- 페어링한 휴대폰은 허용 목록 안에서만 움직입니다. 그룹의 12개 단어를 아는 휴대폰은 설정, 보안의 Android 앱 카드에서 그룹의 12개 단어로 휴대폰 페어링 허용이 켜져 있는 동안 비밀번호 없이 로그인합니다. 그 세션이 닿는 것은 앱이 보여 주는 것뿐입니다. 개요, 실행 기록, 보고 시작하고 복원할 백업, 읽을 이상 징후, 볼 인스턴스 페이지입니다. 대상과 명령은 주소와 비밀이 빠진 채 전달되고, 원본을 교체하는 복원은 먼저 현재 상태를 백업합니다. 폴더로 복원할 때는 복원 폴더 안의 새 폴더나 빈 폴더만 받으며, 휴대폰은 다른 폴더를 들여다볼 수 없습니다. 그 밖의 모든 것은 인스턴스 자체에서 로그인해야 한다고 응답합니다. 키, 복구 키트, 키 맡기기, 설정, 백업 삭제가 해당합니다. 비밀번호를 재설정하면 다시 켤 때까지 휴대폰 페어링이 꺼집니다. 인스턴스 페이지에서 제거했거나 세부 정보에서 이 인스턴스 조회를 끈 휴대폰은 세션을 바로 잃고, 제거된 휴대폰이 앱을 다시 열면 꺼진 상태로 돌아옵니다.
- 집 밖에서는 휴대폰이 릴레이를 통해 페이지를 엽니다. 페이지의 각 요청은 그룹의 키로 봉인되어 릴레이가 읽거나 바꿀 수 없고, 휴대폰의 첫 호출 때 서버가 고정하고 누군가 페어링 페이지에서 그 휴대폰을 승인하면 들여보내는 휴대폰 자신의 키로 서명됩니다. 서버는 요청을 한 번만, 그리고 최신인 동안에만 실행합니다. 휴대폰 페어링이 켜져 있는 동안 인스턴스 페이지에 올라 있는 휴대폰에만, 그리고 그 휴대폰에 내준 세션이 있을 때만 응답하므로, 모든 곳에서 로그아웃하거나 비밀번호를 재설정하면 이런 페이지도 끝납니다. 서버는 모든 응답에 서명하고, 앱은 그 서명을 해당 서버용으로 고정해 둔 키로 확인하며 키가 바뀌면 경고합니다. 이런 페이지는 로그인 비밀번호가 있든 없든 페어링한 휴대폰과 같은 허용 목록에 닿고, 페이지가 가장 먼저 읽는 로그인 상태에도 닿습니다. 로그인과 로그아웃, 비밀번호 재설정, 다운로드는 서버 자체 주소에서만 가능하며, 응답 하나는 16 MB로 제한됩니다.
- 구성원은 자신이 요청한 것에 서명합니다. 역할 요청과 그 응답, 스토리지 제안, 수신기나 가져오기 측에 restic 비밀번호를 내주는 일, 수신기 로그인, 키 맡기기는 각 구성원의 키로 서명되며, 인스턴스는 그 구성원을 처음 볼 때 키를 고정합니다. 다른 키로 서명한 호출은 거부됩니다. 인스턴스 세부 정보의 키 잊기는 여기서 아는 키가 구성원 자신의 것이 아닌 경우를 위해 고정한 키를 버립니다. 구성원은 다음 서명된 호출 때 키를 다시 요청받습니다. BombVault 9.x 구성원은 서명하지 않으며, 9.9에서처럼 단어를 아는 사람이라면 누구든 사칭할 수 있습니다. 10.4 이하 구성원의 역할 요청이나 스토리지 제안은 그 구성원이 업데이트될 때까지 거부됩니다.
- 12개 단어는 비밀번호입니다. 이를 가진 사람은 누구든 그룹에 합류하고, 구성원의 보호 상태를 보고, 역할을 요청할 수 있습니다. 역할은 상대 인스턴스의 사람이 여전히 허용해야 합니다. 로그인 비밀번호가 없으면 웹 인터페이스를 열 수 있는 누구나 이 단어를 읽을 수 있으며, 페어링 카드는 비밀번호를 설정할 때까지 그렇게 알려 줍니다.
키¶
- APP_KEY는 두 가지 일을 합니다. 이 설치가 저장하는 것(비밀번호, 로그인, 토큰)을 봉인하고, 백업의 키이기도 합니다. restic 비밀번호가 여기서 파생되고 컨테이너와 VM 정의도 이것으로 봉인됩니다.
- 인수한 키는 따로 보관됩니다. 긴급 마법사가 다른 서버의 백업을 인수하면, 이 설치는 자신의 APP_KEY로 계속 봉인하고 상대 서버의 키는 백업 키로, 다른 비밀과 똑같이 봉인해 저장합니다. 복구 키트에는 둘 다 인쇄됩니다. 이후 APP_KEY를 바꾸면 백업 키를 더 이상 열 수 없습니다. 이때 BombVault는 잘못된 키로 쓰는 대신 백업을 멈추고 조치 필요에 그렇게 알립니다. 복원, 긴급에서 복구 키트를 다시 올리거나 APP_KEY를 되돌리세요. 긴급 마법사를 참고하세요.
- 암호화는 기본으로 켜져 있습니다(설정, 보안의 암호화 카드에 있는 백업 암호화). 백업은 백업 키에서 파생한 비밀번호로 restic이 암호화합니다.
- 키 맡기기. 그룹의 키 보관 측은 이 서버의 복구 키트를 봉인한 사본으로 보관하며 스스로는 열 수 없습니다. 열 수 있는 것은 20자 수령 코드뿐이고, 보관 측은 그곳에서 누군가 허용을 누른 뒤에만 내줍니다. 키 보관 측을 참고하세요.
노드¶
노드는 웹 인터페이스가 없는 BombVault로, 홈 인스턴스의 지시를 받습니다.
- 홈 인스턴스가 노드를 쥐고 있습니다. 노드는 자기 서버의 Docker 소켓을 마운트하는데, 이는 그 서버에서 root와 같으며 홈 인스턴스가 노드를 제어합니다. 홈 인스턴스를 장악당하면 공격자는 홈 인스턴스의 모든 노드도 제어합니다. 홈 인스턴스에는 로그인 비밀번호를 설정하고, 홈 인스턴스의 웹 인터페이스를 인터넷에 내놓지 마세요.
- 노드가 가진 것은 적습니다. 노드를 장악당해도 공격자는 페어링 그룹, 요새, 다른 노드, 다른 저장소를 얻지 못합니다. 노드가 가진 것은 홈 인스턴스로 가는 연결 하나, 수신 서버의 자체 로그인, 대상에 있는 자기 폴더뿐입니다. 수신 서버는 append-only이므로 노드는 그곳의 기록을 삭제할 수 없습니다. 다만 rest-server에는 용량 제한이 없어 서버의 디스크를 채울 수는 있으니, 수신 서버에 넉넉한 공간이나 전용 공유를 마련해 두세요. 대상에서는 노드의 자격 증명으로 대개 그곳에 있는 것을 삭제할 수 있습니다. 노드에 보관한 백업은 공격자의 손에 들어가며, 그래서 홈 인스턴스가 그 사본을 가져옵니다.
- 연결은 비공개이며 서명됩니다. 홈 인스턴스와 노드는 노드의
APP_KEY에서 파생한 비밀로 봉인한 전용 연결로 릴레이를 거쳐 대화합니다. 양쪽 모두 첫 호출 전에 상대의 키를 알고 있으므로 승인 단계가 없습니다. 홈 인스턴스는 모든 호출에 자기 키와 카운터로 서명하고, 노드는 홈 인스턴스가 서명하지 않은 호출이나 이미 받은 호출을 거부합니다. 노드가 홈 인스턴스에서 부르는 것은 첫인사뿐입니다. - 홈 인스턴스는 정해진 목록에만 닿습니다. 홈 인스턴스가 노드로 전달하는 요청은
GET /api/nodes/routes에 나열된 노드 경로의 정해진 목록에서만 실행되고, 노드는 JSON으로만 답합니다. 목록에는 삭제하는 것도, 설정, 저장 공간, 키, 그룹, 토큰에 닿는 것도 없습니다. 홈 인스턴스에서는 비밀번호로 로그인해야 하며, 페어링한 휴대폰, API 토큰, MCP 키는 노드에 닿지 않습니다. 이렇게 시작한 백업과 복원은 홈 인스턴스가 시작한 것으로 표시됩니다. - 키 맡기기에는 노드의 키가 들어갑니다. 홈 인스턴스는 각 노드의
APP_KEY를 보관하고 복구 키트가 이를 노드 장에 출력하므로, 맡긴 키에도 들어갑니다. 보관본과 복구 코드를 받은 키 보관 측은 노드의 저장소를 열 수 있지만, 노드에 명령하려면 홈 인스턴스의 서명이 필요하므로 노드를 부릴 수는 없습니다. - 해제는 되돌릴 수 없습니다. 해제한 노드는 같은
APP_KEY로는 다시 홈 인스턴스를 가질 수 없습니다. 해제할 때 연결되어 있지 않던 노드는 돌아오면 홈 인스턴스로부터 그 사실을 듣습니다.
네트워크¶
- 변경에는 JSON이 필요합니다. 무언가를 바꾸는 요청은
Content-Type: application/json을 보내야 하고, 브라우저가 교차 사이트 요청으로 표시하지 않아야 합니다. 그래서 다른 사이트의 페이지가 여러분의 브라우저를 시켜 LAN 주소의 설정을 바꿀 수 없습니다. API를 다루는 스크립트는 이 헤더를 보냅니다. 그 밖의 요청은415로 거부됩니다. - 이 관문은 선택 사항이므로, 설정하지 않으면 전체 UI와 API(대상, 변조 테스트 경로, 복원 경로 포함)에 포트에 닿을 수 있는 누구나 접근할 수 있습니다. 오프사이트, 추가 전용 백업, 암호화를 쓰기 시작하면 로그인 비밀번호를 설정하세요.
- BombVault는 신뢰할 수 있고 외부에 노출되지 않은 네트워크에서만 실행하세요. 원격 접근에는 인증과 TLS를 더해 주는 리버스 프록시 뒤에 두세요. 응답에는 기본 보안 헤더(CSP,
nosniff,X-Frame-Options,Referrer-Policy)가 붙습니다. - 리버스 프록시 뒤에서는 모든 요청이 프록시의 주소를 달고 오므로,
TRUSTED_PROXY가 없으면 로그인 제한이 모든 클라이언트를 한 통에서 세고 공격자의 실패 때문에 여러분도 잠깁니다.TRUSTED_PROXY에 프록시를 적으면 클라이언트별 계수가 돌아옵니다. - BombVault 앞의 리버스 프록시는
Authorization또는X-API-Key헤더를/mcp로 그대로 넘겨야 하고 응답을 버퍼링하면 안 됩니다. 그렇지 않으면 어시스턴트가 연결할 수 없습니다. MCP 서버를 참고하세요. - MCP 엔드포인트
/mcp는 키가 생기거나 OAuth 로그인이 켜지기 전까지404로 응답하며, 로그인 비밀번호가 꺼져 있어도 모든 클라이언트에 키나 토큰을 요구합니다. 예외인 주소는 없고localhost도 마찬가지입니다. 복원이나 삭제 도구는 없으며, 구성 백업을 복원하면 모든 키가 폐기됩니다. MCP 서버를 참고하세요. HTTP_ONLY=true에서는 세션 쿠키에서Secure플래그가 빠지므로(일반 HTTP에서 동작하려면 그래야 합니다), 기밀성이 중요하다면 TLS를 종료하는 프록시 뒤에서만 비밀번호를 켜세요.- VM 백업의 SSH 연결은 첫 접속 때 호스트 키를 신뢰하고(TOFU) 이후에는 그 키를 고정합니다. 컨테이너에서 호스트까지의 경로를 믿을 수 없다면 호스트의 키를 다른 경로로 확인하세요.
- 링크로 마운트 밖에 나갈 수 없습니다. 경로 위쪽의 링크가 호스트 마운트 밖으로 이어지면, 백업이나 제자리 복원은 메시지를 남기고 멈춥니다. 자기 공유에 쓰는 컨테이너라면 그런 링크를 심어 둘 수 있기 때문입니다. 호스트나 rclone 리모트가
-로 시작하는 대상도 저장할 때와 다음 실행 때 같은 방식으로 거부됩니다.ssh나rclone이 그것을 옵션으로 읽기 때문입니다.
MCP 서버¶
MCP 서버에는 환경 변수가 필요 없습니다. 설정, 연동, MCP 서버에서 키를 만들면 켜지고, 웹 인터페이스와 같은 포트의 /mcp에서 응답합니다(예: https://192.168.1.10:3443/mcp). 활성 키가 없으면 이 경로는 404로 응답합니다. 클라이언트, 인증서, 제한은 MCP 서버에 설명되어 있습니다.
SSH를 통한 VM 백업¶
BombVault는 libvirt 경로를 하나도 마운트하지 않고 KVM/libvirt VM을 백업합니다. SSH(qemu+ssh://)로 호스트에서 virsh를 실행하므로 호스트의 VM Manager에 영향을 줄 일이 없습니다.
Unraid에서 호스트의 libvirt 소켓을 컨테이너에 마운트하는 방식은 깨지기 쉽습니다. 그 경로는 VM Manager가 관리하며, "Enable VMs"를 바꾸면 libvirt가 시작되지 못하는 상태가 될 수 있습니다. SSH 키는 호스트의 root 권한을 주는데, 이는 BombVault가 이미 쓰는 Docker 소켓과 같은 수준의 신뢰입니다.
빠른 설정:
- 설정, 연동, 호스트 SSH: 표시된 공개 키를 복사합니다.
- Unraid의
/root/.ssh/authorized_keys에 추가합니다(재부팅 후에도 남도록 플래시에도 저장됩니다). - 연결 테스트를 누릅니다.
템플릿은 컨테이너가 호스트에 닿을 수 있도록 --add-host=host.docker.internal:host-gateway를 추가합니다. 그 이름이 확인되지 않으면(예: 컨테이너가 사용자 지정 br0.x 네트워크에서 실행될 때) LIBVIRT_HOST를 Unraid의 LAN IP로 설정하세요. Unraid의 SSH 포트를 바꿨다면 LIBVIRT_SSH_PORT도 맞춰 설정하세요. 라이브 스냅샷에는 추가로 VM 안의 qemu 게스트 에이전트가 필요하고 디스크가 /mnt/cache(/mnt/user가 아님)에 있어야 합니다.
전체 VM 설정 및 네트워킹 가이드
SSH 활성화, 키 승인 유지, 사용자 지정 네트워크와 VLAN 라우팅, VM별 방식, 호스트 쪽 문제 해결까지 담은 전체 단계별 가이드는 VM 백업 가이드입니다.
오프사이트 설정¶
오프사이트 사본은 대상으로 갑니다. 설정 타일에서 대상을 열고(또는 사이드바에 고정하고) 대상 추가를 고르세요. 전체 흐름(삭제 방지, 변조 테스트, DR 훈련)은 오프사이트 및 복구를 참고하세요. 요약하면 다음과 같습니다.
- 백엔드: 호스트 마운트 없이 rclone으로 쓰는 SMB/CIFS와 WebDAV, NFS(호스트에 export를 마운트해 로컬 폴더로 사용), rclone 없이 쓰는 네이티브 restic 백엔드(
s3:...,rest:http://host:8000/repo,sftp:user@host:/repo), 또는 모든 rclone 리모트(rclone:<remote>:<bucket>/path). Backblaze B2에는 여기서 전용 네이티브 백엔드가 없습니다. S3 엔드포인트(s3:https://s3.<region>.backblazeb2.com/<bucket>/<path>)로 접근하고, 키 ID와 애플리케이션 키를 S3 자격 증명으로 쓰세요. - 자격 증명은 암호화되어 저장되며, 설정, 대상의 자격 증명 카드에 저장된 자격 증명 하나의 목록으로 관리됩니다. 별표는 기본값을 뜻하며, 자격 증명을 고르지 않은 곳에서 쓰입니다. 대상 자체 페이지의 자격 증명 카드에서 그 대상이 쓸 것을 고릅니다. 자격 증명을 참고하세요.
- SSH 대상은 상대편에 아무것도 설치할 필요가 없습니다.
sftp:는 SSH 서버만 있으면 됩니다. 설정, 연동, 호스트 SSH의 공개 키(/config/ssh/id_ed25519.pub에도 있습니다)를 대상 사용자의~/.ssh/authorized_keys에 추가하거나, 대상 추가의 키 추가로 계정 비밀번호를 써서 넣게 하세요. - 자체 서명 인증서를 쓰는 rest-server: 그 인증서나 그것에 서명한 인증 기관의 인증서를 PEM 파일로 BombVault 데이터 폴더의
certs폴더(컨테이너 안에서는/config/certs, Unraid에서는appdata/bombvault/certs)에 넣으세요. 백업, 복사, 삭제 방지 테스트가 재시작 없이 그 인증서를 신뢰합니다. - 오프사이트 복사: BombVault는 (보통 로컬인) 기본 저장소 위에
restic copy로 새 스냅샷을 최선을 다해 복사합니다. 대상의 복사 카드는 백업할 때마다 복사할지 자체 일정으로 복사할지를 정하고, 설정, 일정, 섹션별 오프사이트 복사에서는 섹션 하나에 자체 복사 일정을 줄 수 있습니다. 지금 복제는 설정, 대상의 오프사이트 복사본 카드에 있는 섹션 행에 있습니다. - 섹션당 여러 대상: 대상 페이지의 섹션별 대상 카드는 섹션에서 대상으로 가는 각 줄을 클릭 한 번으로 켜고 끕니다. 로컬도 포함됩니다. 오프사이트 대상만 있는 섹션은 그곳으로 바로 백업하고, 모든 줄이 꺼진 섹션은 백업되지 않습니다. 대상의 섹션별 규칙으로 섹션 하나에 그곳에서만 쓰는 저장소, 보존, 압축을 따로 줄 수 있습니다.
- 항목별 배치: 컨테이너, VM, 폴더 세트는 각자 설정 탭의 일정 및 대상 카드에서 로컬과 자신의 백업을 받을 대상을 켭니다. 따로 고르지 않은 항목은 섹션을 따릅니다. 항목별 배치를 참고하세요.
- 보존: 각 대상은 자신의 보존 기간 카드로 백업을 보존하며, 섹션은 섹션별 규칙에서 자기 값을 따로 둘 수 있습니다. 섹션의 오프사이트 필드에 있는 사본도 여기에 포함됩니다. 모두 0이면 대상의 스냅샷을 정리하지 않습니다.
- 대역폭 제한: restic의 업로드와 다운로드 속도는 설정, 대상의 오프사이트 대역폭 카드에서, 또는 대상별로 그 대상의 복사 카드에서 제한합니다. KiB/s로 입력하면 필드가 같은 속도를 MB/s와 Mbit/s로도 보여 줍니다.
- 스트리밍 우선: 대상 페이지의 스트리밍 카드에서 미디어 서버(Plex, Jellyfin, Emby는 이미지 이름으로 미리 선택됩니다), 스트리밍으로 보는 전송 속도 기준, 스트리밍 중의 업로드 한도, 스트림이 끝난 뒤 일반 한도로 돌아오기까지의 시간을 정합니다.
- 콜드 및 아카이브 스토리지 클래스(S3): S3 대상이라면 그 페이지에서 복원할 수 있는 등급(Standard, Standard-IA, One Zone-IA, Intelligent-Tiering, Glacier Instant Retrieval)을 고릅니다. rclone 리모트는 rclone 설정에서 클래스를 정합니다.
- 로컬 대신 대상 안의 전용 폴더: 섹션의 전용 폴더를 위의 대상 중 하나에 둘 수 있으며, 로컬 사본도 복사 단계도 없습니다. 섹션의 전용 폴더를 참고하세요.
이상 징후¶
이상 징후 감지에는 환경 변수가 필요 없습니다. 설정, 검증의 이상 징후 카드에서 설정하며, 이상 징후에 설명되어 있습니다.
휴대용 설정(내보내기와 가져오기)¶
설정, 시스템의 설정 내보내기 / 가져오기 카드는 BombVault 구성 전체(섹션 설정, 대상, 일정, 보존, 알림)를 휴대용 JSON 파일로 저장합니다. 다른 인스턴스에서 가져올 수 있으므로, 새 장비로 옮기거나 설정을 복제할 때 모든 것을 손으로 다시 입력하지 않아도 됩니다. 가져오기는 미리 보기를 보여 주고 확인을 받으며, 백업 데이터나 기록은 건드리지 않습니다. 더는 없는 대상이나 저장소로 이어지는 파일 속 링크는 빠지고, 미리 보기가 그 목록을 알려 줍니다. ZFS 복제본이 실행 중일 때는 아무것도 쓰기 전에 가져오기가 거부됩니다.
내보낸 파일에 자격 증명이 들어갈 수 있습니다
오프사이트, 알림, MQTT 브로커의 자격 증명을 파일에 넣을지 직접 고릅니다. 자격 증명을 포함하면 내보낸 파일은 복구 키트만큼 민감하므로 안전한 곳에 보관하세요. 포함하지 않으면 파일에는 비밀이 아닌 설정만 들어 있습니다.
APP_KEY는 파일과 함께 옮겨지지 않습니다
저장소는 APP_KEY에서 파생한 비밀번호로 잠겨 있으며, 파일에는 그 키가 들어 있지 않습니다. 계획된 이전이라면 새 장비의 템플릿에 이전 APP_KEY를 넣거나, 긴급에서 복구 키트로 키를 넘겨받으세요. 다른 키로는 저장소가 비밀번호가 틀렸다고 응답합니다. 잃어버린 것은 없으며, 올바른 키를 설정하면 다시 열립니다.