Backup

The Backup & Restore tab backs up the console, keeps its last seven backups, and restores the console from one of them or from a backup file you upload.

Where: Settings > Backup & Restore

What a Backup Contains

A backup is a .tar.gz archive that contains:

• The database — a dump of the console's PostgreSQL database.
• The settings and the encryption key — the settings file, whose stored credentials are encrypted, and the key that decrypts them.
• Logs — the console's logs, including rotated ones, the agent dashboard history, and the agents' logs.
• A manifest — backup-manifest.json, which lists every file in the archive.

A backup does not contain ClickHouse data, which includes the audit events. On the VMware appliance, back up the whole virtual machine with your VM backup software to protect that data too.

warning

The archive is not encrypted. It holds both the encrypted credentials and the key that decrypts them, so anyone who has the file can read the credentials. Store backups as securely as any other file of passwords.

Create a Backup

Click Create Backup Now. The console first asks every online agent to send its current logs, so the backup includes them. The Collecting agent logs before create backup panel lists each agent, with a 60-second countdown.

Agent status	Meaning
pending heartbeat	The agent has not picked up the request yet. It does so on its next heartbeat.
waiting	The agent's logs have not arrived yet.
received	The agent's logs have arrived.
offline — skipped	The agent is offline, so the backup does not wait for it.

The backup then proceeds in one of three ways:

• Continue — create backup appears once every online agent has sent its logs. The backup includes the newest log package from each agent.
• Skip & Continue Now creates the backup immediately. It includes every agent log package the console holds, not only the newest one from each agent.
• When the countdown runs out, the backup is created anyway, with the newest log package the console holds from each agent.

When the backup is done, the tab shows Backup created with the file name, and the backup appears at the top of Stored Backups.

• Only one backup runs at a time. Starting another while one runs is refused.
• Dumping a large database can take several minutes. The backup fails if the dump takes more than 30 minutes.
• On the VMware appliance, the page stops waiting after 10 minutes, but the backup carries on. Refresh Stored Backups later instead of starting another.

Stored Backups

Backups are kept on the console's data volume and are named with the date and time they were made. The heading shows how many are stored out of seven, for example Stored Backups (3 / 7). Creating a backup when seven exist deletes the oldest. The newest backup is marked Latest.

Each backup has these actions:

• Download — saves the archive to your computer. Keep a copy off the console, because a backup kept only on the console is lost with the console.
• Restore — restores the console from the backup. See Restore.
• Delete — deletes the backup from the console after you confirm. This cannot be undone.

Restore

A restore replaces the console's database, settings, and encryption key with the ones in a backup. You can restore from either source:

• A stored backup — click Restore on its row in Stored Backups.
• A file — under Restore from File, drop a .tar.gz backup onto the box, or click the box to browse. You can upload files up to 512 MB, or 100 MB on Kubernetes, where the ingress limits uploads. Restore a larger backup from Stored Backups.

Confirm Restore shows the file name and warns that the current data will be permanently replaced. Click Restore to continue. The Restore Log panel then shows each step as it runs. Download Log saves the log.

1. Extract the archive.
2. Check that it holds the database dump, the settings, and the encryption key.
3. Cancel all running and pending jobs.
4. Let in-flight database writes finish.
5. Close the console's database connections.
6. Load the backup's database dump into PostgreSQL, which replaces the current database.
7. Install the backup's settings and encryption key.
8. Restart the console with the restored state. The console is unavailable until it is back.

While the restore runs, the box reads Restore in progress — do not close this page. When the console answers again, the page shows Restore complete — backend restarted successfully. If the console is not back within 90 seconds, the log says so. Refresh the page once the console is back.

A restore does not change ClickHouse, and it does not put back the logs in the archive. The logs are there for troubleshooting.

Audit ingest resumes from the positions stored in the backup's database. Restoring a backup that is older than the newest audit data can ingest some events again and duplicate them in ClickHouse.

Restore a backup on the console that made it. The backup's settings include that console's database connection, so restoring it on another console also replaces that console's database connection settings.

Restore Attempt History

Every restore attempt, including failed ones, is saved as a log file on the console. The list shows when each attempt ran, the log's size, and its file name. Download saves the log.

The history is kept across restarts, so it still shows what happened after the console restarted or the page was closed.

Workflows

Create a backup before an upgrade

1. Open Settings > Backup & Restore.
2. Click Create Backup Now.
3. Wait for every online agent to show received, then click Continue — create backup. Click Skip & Continue Now if an agent does not respond.
4. When Backup created appears, click Download on the new backup.
5. Save the archive in a safe location outside the console.

Restore from a backup

1. Open Settings > Backup & Restore.
2. Click Restore on a stored backup, or drop a .tar.gz archive onto Restore from File.
3. In Confirm Restore, check the file name and click Restore.
4. Wait for Restore complete — backend restarted successfully.
5. Verify that your settings and agent registrations are present.

Troubleshooting

• A backup fails after 30 minutes — the database dump did not finish in time, for example because a table was locked. The partial file is deleted. Try again.
• An agent never reaches received — the agent has not checked in since the request, or cannot reach the console. Click Skip & Continue Now to back up without its newest logs, and check the agent in Live Agents.
• A restore fails — the Restore Log or Restore Attempt History shows the step that failed. A failure in step 1 or 2 changes nothing. After a failure in a later step, restart the console before you use it, and then restore again.
  • On the VMware appliance, run sudo systemctl restart aisec-console-app.
  • On Kubernetes, restart the console pod.

Best Practices

• Create a backup before and after configuration changes and before an upgrade.
• Keep a copy of each backup off the console.