Backup & Restore

Backup & Restore

uControl Insight includes an integrated backup and restore system accessible from the UI, REST API, and CLI scripts. Backups are encrypted and portable — they work across on-premises and cloud deployments.

What Is Backed Up

What Is NOT Backed Up

• Worker agent data — Each worker has its own H2 database and worker.key. Back these up separately from the worker host (./data/ directory).
• Application WAR file — The application binary is not included. Deploy the same version WAR before restoring.
• Tomcat / reverse proxy configuration — Infrastructure config outside the application.

Creating a Backup (UI)

1. Log in as an administrator.
2. Sidebar → Settings → Backup & Restore tab.
3. In the Create a backup card, choose options:
   • Backup password (minimum 8 characters). Used to encrypt the bundled master key with PBKDF2 + AES-256-GCM. Remember this password — restore needs it.
   • Include flow data — ticks the flow_raw partitions in (can be very large; off by default).
   • Include audit log — on by default.
4. Click Create Backup. The request blocks while mysqldump + archive assembly + master-key encryption complete (typically tens of seconds for a moderate database).
5. When complete, the backup appears in the Backup History table with size, SHA-256, and Download / Delete actions. Download to copy the archive off-host.

Restoring from Backup (UI)

1. Sidebar → Settings → Backup & Restore.
2. Scroll to the red-bordered Restore from backup card at the bottom.
3. Choose the backup archive (.tar.gz) to upload.
4. Enter the backup password that was used at create time.
5. Tick Also restore flow data only if you want to overwrite flow_raw with the backup's snapshot.
6. Type RESTORE in the confirmation field.
7. Click Restore (replaces live database).

The restore performs three safety checks before any database write:

1. Archive integrity — manifest.json, master_key.enc and database.sql must all be present.
2. Password — the bundled master key is decrypted with the supplied password. Wrong password aborts before any DB change.
3. Master-key match — the decrypted master key must equal this server's UCONTROL_MASTER_KEY. If it doesn't, the restore aborts with a clear error message; restoring across master keys would make every encrypted secret (LDAP password, OIDC client secret, AI keys, Teams shared secret) unreadable.

After a successful restore: sudo systemctl restart ucontrolinsight on the server. This clears in-memory caches and reloads schema/config from the restored database. An in-UI restart button is on the roadmap.

CLI Backup Script

For automated/cron backups without the UI:

# Create backup
./scripts/backup.sh --password "mySecurePass" --output /backups/

# Include flow data
./scripts/backup.sh --password "mySecurePass" --output /backups/ --include-flows

# Custom database connection
./scripts/backup.sh --password "mySecurePass" \
  --db-host dbserver --db-port 3306 \
  --db-name ucontrolinsight --db-user admin --db-pass dbpass \
  --master-key "$(echo $UCONTROL_MASTER_KEY)"

CLI Restore Script

# Restore from backup
./scripts/restore.sh --file ucontrol-backup-2026-04-29-020000.zip --password "mySecurePass"

# Skip confirmation prompt
./scripts/restore.sh --file backup.zip --password "mySecurePass" --yes

The restore script will display the decrypted UCONTROL_MASTER_KEY — update the environment variable before restarting.

Scheduled Automatic Backups

Enable daily automated backups by setting these properties in application.yml or environment variables:

ucontrol:
  backup:
    directory: /var/backups/ucontrol
    scheduled:
      enabled: true
      password: your-backup-password
      retention: 7          # keep last 7 backups
      include-flows: false
      cron: "0 0 2 * * *"   # daily at 2:00 AM

Old backups beyond the retention count are automatically purged. Backup success/failure is logged to the audit trail.

Backup Archive Contents

The .zip backup file contains:

Backup Sizing Guide

Worker Agent Backup

Worker agents store data independently. To back up a worker:

1. Stop the worker agent service
2. Copy the ./data/ directory (contains H2 database and worker.key)
3. Restart the worker agent

The worker.key file is critical — without it, the worker cannot decrypt its locally stored credentials.