Backup

This tab handles creating and restoring a full backup of the application's persistent data, including settings, the application database, and collected logs.

warning

A backup is sensitive. It contains the settings file (settings.json) and the encryption keystore (.keystore), so a backup is equivalent to all stored credentials in clear. Store and transfer backups accordingly.

Overview

A backup captures the complete operational state of the AirGap for ObjectScale console at a point in time.

It does not back up ClickHouse audit event data. That data is retained according to the retention policy configured on the Database tab.

A backup is useful for:

• Migrating the application to a new deployment host.
• Recovering from accidental configuration changes.
• Archiving a known-good state before a major upgrade.

Before the archive is created, the system asks all online copy agents to push their local log files to the backend. This puts agent-side logs in the archive. A countdown panel tracks which agents have responded.

Backup

Click Create Backup Now to start the process.

1. The system sends a log-push request to all registered online agents.
2. It waits for responses or for the countdown to expire.
3. When all agents have responded or you skip the wait, the backend assembles a .tar.gz archive.

The archive contains:

• The settings JSON file with all configuration. Credentials are encrypted inside the file.
• The encryption keystore (.keystore) needed to decrypt the settings file.
• The application database, as a pg_dump export of PostgreSQL.
• The system health snapshot log (application.log and rolled archives), for ingest and job state history.
• The console backend log: the live backend.log and the last 7 days of rolled .gz files.
• The frontend server log: the live frontend.log and rolled archives.
• The agent-fleet snapshot log (agentdashboard.jsonl), with per-agent ClickHouse connectivity, spool and buffer depth, and host CPU history.
• Any agent log archives pushed during log collection.
• Support analyzer reports, if any were generated in Setup & Settings > Support Log Parsing.
• Restore operation logs, if a restore has been run on this appliance.
• Database migration logs, if a database-to-database migration has been run.
• JVM heap dump files, present only if the application has hit an out-of-memory condition.

info

Optional log and dump items are included only when they exist on the console. A clean appliance that has never had a restore, migration, out-of-memory event, or support report does not contain those directories. They are skipped silently.

Stored backups

The finished archive is stored on the console and listed under Stored Backups. The list shows Filename, Size, and Created. The newest backup is marked Latest.

• Up to 7 backups are kept. The oldest is removed automatically.
• The filename includes a timestamp, so backups never overwrite each other.
• Each row has Download, Restore, and Delete buttons. Download saves the archive to your machine.

Backup retention

The backup archive size depends on how much completed-job diagnostic detail is included in the SQL dump.

Two PostgreSQL tables collect large compressed payloads over time and dominate the dump size on long-running systems:

• jobs.result_summary holds per-job execution summaries.
• job_steps holds per-step log lines.

The Backup Retention setting tells the system how many days of these payloads to include.

info

This setting never modifies the live database. Filtering happens only while the dump is written, using a read-only PostgreSQL COPY (SELECT … WHERE …) TO STDOUT query.

Rows outside the retention window stay in the live database. They are only left out of the backup file. You can change the retention window at any time without losing operational data.

Retain detail for (days)

The default is 30.

• Backups always contain every jobs row (id, type, state, agent, and timing fields).
• Backups contain every job_steps row for jobs that completed within the retention window or are still in progress.
• For jobs that completed longer ago than the retention window, the jobs row is included but its result_summary is empty (NULL) in the dump. Its job_steps rows are not included at all.
• After you restore such a backup, those older jobs appear in the Job History list with no expandable step-log detail.

Value	Behavior
7 or more	Used as entered.
Below 7	Treated as 7. The backend enforces a minimum of 7 days to prevent an accidental near-wipe of recent diagnostics.
0	Disables filtering. Every row of every table is dumped. Use it only on small systems or when you need full history, because backups can grow very large.

Excluded preview cache

The cv_window_preview_cache table is a derived preview cache filled by the Data Sync Wizard. Its row data is always excluded from the backup, whatever the retention setting. It has no troubleshooting value and rebuilds on demand after a restore.

Retention manifest

Every backup archive includes a small backup-retention.json file that documents what was filtered:

{
  "retentionDays": 30,
  "jobsRowsRetained":           13843,
  "jobsResultSummaryNullified": 11205,
  "jobStepsRowsRetained":       12380,
  "jobStepsRowsExcluded":       41832,
  "prunedAt": "2026-05-23T08:42:00Z",
  "note": "Live database was NOT modified — filtering is dump-time only."
}

To confirm the filtering, inspect the file:

tar -xzOf <backup-file>.tar.gz backup-retention.json

Log Collection panel

The Log Collection panel appears automatically when a backup starts. It shows the status of each registered agent's log push.

Element	Description
Per-agent status	received ✓ means the agent has pushed its logs to the backend. waiting… or pending heartbeat… means the agent has not responded yet. offline — skipped means the agent is offline and is not waited for.
Countdown timer	Shows how many seconds remain before the system proceeds with the backup, whichever agents have responded. It gives agents time to transfer logs over slow network links.
Skip & Continue Now	Cancels the remaining wait and creates the archive with the logs received so far.

When every online agent has responded, Skip & Continue Now changes to Continue — create backup.

Agents that have not responded when you skip do not have their logs in the archive. Use Skip & Continue Now when an agent is offline or unresponsive and you do not want to wait for the full timeout.

Restore

You can start a restore in two ways:

• On a Stored Backups row, click Restore.
• Under Restore from File, drop a previously downloaded .tar.gz backup archive on the drop zone, or click browse to pick it. The file is uploaded to the backend.

A Confirm Restore dialog then appears. Confirming replaces the current database, encryption key, and settings with the contents of the archive. The backend restarts automatically to pick up the restored state.

The Restore Log shows progress live, and you can save it with Download Log. Restore Attempt History lists earlier restores.

Restoring a backup does not restore ClickHouse data. If audit event data was lost from ClickHouse, you must re-ingest it from the source devices.

Workflows

Create a backup before an upgrade

1. Navigate to Setup & Settings > Backup & Restore.
2. Click Create Backup Now.
3. In the Log Collection panel, wait for all online agents to show received ✓. If agents are not responding, click Skip & Continue Now.
4. Find the new archive at the top of Stored Backups, marked Latest. Click Download on that row.
5. Store the archive in a safe location outside the deployment host.

Restore from a backup

1. Navigate to Setup & Settings > Backup & Restore.
2. Click Restore on a Stored Backups row, or drop the backup .tar.gz file on Restore from File.
3. Confirm that the file name shown matches the expected backup.
4. Click Restore in the Confirm Restore dialog.
5. Wait for the backend to restart. The UI briefly shows a connection-lost indicator, then reloads.
6. Verify that settings and agent registrations are present after the restore.

Include all agent logs in a backup

1. Confirm that all agents are online in Cyber Vault > Agent Fleet Management.
2. Click Create Backup Now.
3. Do not click Skip & Continue Now. Let the countdown run fully.
4. Wait until all agents show received ✓ before the timer expires.
5. Download the resulting archive from Stored Backups.

Tips

warning

The restore operation overwrites the live database immediately and cannot be undone. If you are unsure, create a new backup of the current state before you restore an older one.

• Schedule regular backups before and after configuration changes. The archive is small and fast to create.
• The backup archive contains encrypted credentials and the key to decrypt them. Protect it as you would any secrets file.
• Restoring a backup that is much older than the current ClickHouse data may cause offset mismatches. The system re-ingests log data from the last known offset, which may produce duplicate events in ClickHouse.
• The backup includes a pg_dump export, and restoring it imports the dump into the configured PostgreSQL server. If applicable, make sure the pg_dump path override in the Database settings matches the server version.
• If an agent keeps failing to push logs before the timer expires, check that the agent's network path to the backend is open and that the agent process is healthy.