Skip to content

Backups Updates and Maintenance

Jump to bottom
Tyler Hatfield edited this page Nov 12, 2026 · 2 revisions

Unified Encrypted Backups, Key Escrow, Disaster Recovery & Self-Updater (v2.5.1)

Vitrine RMM includes a built-in encrypted backup engine (backend/src/services/backup/index.ts) and release channel self-updater (backend/src/services/updater/index.ts) managed under Settings -> Backups & Updates.

1. Unified AES-256-GCM Self-Backup Engine (VRMMENC1)

Every manual, scheduled, or pre-update backup (POST /api/backups) produces a self-contained, authenticated .vrmm-backup.gz archive:

  1. Hot Atomic SQLite Snapshot: Uses better-sqlite3's native online SQLite Backup API (db.backup(...)) so WAL transactions are captured atomically without locking or corrupting live fleet telemetry.
  2. Complete Recovery Bundle: Packages vitrine.db (Schema v16), .vault-key.json (so AES-256-GCM LAPS, BitLocker, and secret Custom Field values remain decryptable on a brand-new server), custom white-label branding/ assets, and a JSON manifest (appVersion, schemaVersion, sha256, createdAt).
  3. Authenticated VRMMENC1 Envelope: Compresses the bundle with gzip and encrypts it with AES-256-GCM using the 8-byte magic header VRMMENC1, random salt/IV, and 16-byte GCM authentication tag.
  4. Reboot-Resilient Scheduled Backups & Pruning: The background scheduler triggers daily/weekly snapshots whenever now >= todayTarget and elapsedMs >= minIntervalMs (catching up cleanly even if the server was rebooted or offline during the exact scheduled minute) and prunes expired archives beyond backup_retention_count.

2. Backup Encryption Key Recovery & Escrow Reminders

To guarantee you can always decrypt .vrmm-backup.gz archives during bare-metal disaster recovery when the original server is lost:

  • Step-Up MFA Reveal & .txt Export (POST /api/backups/recovery-key): Super Admins can reveal, copy to clipboard, or download a timestamped .txt recovery kit of the active backup encryption passphrase (or fallback master vault key hex) at any time under Settings -> Backups -> Reveal / Export Backup Recovery Key.
  • Onboarding & Persistent Settings Reminder (POST /api/backups/acknowledge-key): Both the First-Run Setup Wizard (Step 6) and Settings -> Backups display a prominent Backup Key Escrow reminder banner until a Super Admin confirms the recovery key has been stored in an external password manager.

3. S3-Compatible Offsite Replication (AWS Signature V4)

Without requiring external CLI binaries, Vitrine RMM includes a pure Node crypto AWS Signature V4 (AWS4-HMAC-SHA256) client (protected by validateOutboundHostSafety) supporting Amazon S3, Cloudflare R2, Backblaze B2 (S3 API), and MinIO.

4. Schema-Aware Live Atomic Restore & Vault Cache Reload

Administrators can restore from a local snapshot (POST /api/backups/:id/restore) or upload an external .vrmm-backup.gz bundle (POST /api/backups/upload-restore):

  1. Verifies the VRMMENC1 header and GCM authentication tag before touching disk.
  2. Validates SQLite header magic and checks schemaVersion:
    • Older Schema Backups (backupSchema < 16): Restores atomically and automatically runs forward idempotent schema migrations (ensureSchemaUpgrades()) up to v2.5.1 (Schema v16).
    • Newer Schema Backups (backupSchema > 16): Safely blocks restore with instructions to update Vitrine RMM first.
  3. Atomically swaps the live SQLite connection, restores .vault-key.json and branding/, and immediately invokes reloadVaultMasterKey() so secrets encrypted on a different source machine decrypt seamlessly without requiring a process restart.

5. Full Bare-Metal Git Self-Updater & Automatic Rollback

Under Settings -> System Updates (GET /api/updater/status, POST /api/updater/check, POST /api/updater/apply):

  • Release Channels: Choose stable (tagged production GitHub Releases only, recommended) or alpha (pre-release / preview tags).
  • Full Bare-Metal Update Pipeline (enabled automatically by install.sh via VITRINE_ENABLE_GIT_SELF_PULL=true):
    1. Creates a pre-update VRMMENC1 encrypted backup and records preHeadSha.
    2. Executes git fetch --tags --force origin and checks out/fast-forwards to the target release tag.
    3. Runs npm install + npm run build in both frontend and backend, followed by forward SQLite schema upgrades.
    4. Full Automatic Rollback: If any fetch, dependency, build, or migration step fails, updater/index.ts automatically executes git reset --hard <preHeadSha>, rebuilds the known-good commit, and restores the pre-update VRMMENC1 database snapshot so the server is never stranded.
  • Docker Container Detection: When VITRINE_DOCKER=true (or /.dockerenv is present), Vitrine cleanly disables in-place git mutation and presents exact multi-arch docker compose pull && docker compose up -d commands.

Clone this wiki locally