Appliance Backup & Restore

The Athena virtual appliance can back itself up completely: the database, the certificate authority your agents trust, the install's secrets and keys, the saved settings and the licence. Everything goes into one archive encrypted with a passphrase you choose. Take a backup on demand or on a schedule, copy it automatically to an SMB share, a WebDAV folder or an S3-compatible bucket, and restore it later onto the same appliance or a fresh one. After a restore, enrolled agents keep working because the same CA comes back.

Everything on this page is under Settings → Appliance, in the Backup, Backup destinations and Restore sections. The same actions are available over the REST API and in the PowerShell module.

What a full backup contains#

A full backup is a different thing from the database-only backup under Settings → Database:

Not included: the large content under /data/storage (uploaded agent installers, deployment packages, session recordings), log files, and earlier backups. Keep separate copies of anything there that you can't upload again. See Data Directories & Backup for what lives where.

Who can use it#

Both are held by the built-in Admin role only by default. Users with appliance.view but not appliance.manage see the sections read-only, with the note “Read-only: changing this needs the appliance.manage permission.” See Permission Model & Role Bundles.

Backing up now#

1. Open Settings → Appliance and scroll to Backup.
2. Type a Passphrase of at least 12 characters, then type it again in Repeat the passphrase. Backup now stays disabled until the two match and the passphrase is long enough.
3. Click Backup now. Athena writes the archive and then copies it to every enabled destination. Under the button you see “Written: file (size)” and one line per destination with its result.

Only one backup runs at a time. If a scheduled backup is already running, a second request is refused with “A backup is already running”.

How the archive is protected#

The archive is encrypted with AES-256-GCM. The key comes from your passphrase through PBKDF2-HMAC-SHA256 with 600,000 iterations and a random salt for every archive. Every part of the file is authenticated, so a changed, reordered, cut-short or extended archive is rejected when it is checked for restore, the same way a wrong passphrase is. Archives are written to the appliance's backup folder (/data/athena/backups) readable only by the Athena service.

Backups on this appliance#

The Backups on this appliance table lists every full backup, newest first, with its File name, Size and Created time. With appliance.manage, the download button on a row saves that encrypted archive through your browser. Every download is audited. If there are none yet, the table reads “No full backups yet.”

Retention and schedule#

Click Save to apply. The schedule appears in the Scheduler as the job Appliance full backup.

Retention only ever deletes files named like a full backup (athena_full_<date>_<time>.athbak). Other files in the same share, folder or bucket prefix are never touched.

Backup destinations (off-box copies)#

Backups on the appliance share a disk with the live data, so for real disaster recovery copy them somewhere else. Under Backup destinations, click Add destination. Every backup, manual or scheduled, is then uploaded to each enabled destination. If one destination fails, the others still get their copy. If there are no destinations, the section reads “No destinations: backups stay on this appliance only.”

Athena checks the whole destination when you save it, including the URL scheme, the share path and the required fields. It rejects an incomplete one with a message, for example “The WebDAV URL must be an https:// URL” or “The S3 bucket is required”. The Type of an existing destination can't be changed; add a new destination instead. Clear Upload backups here to pause a destination without deleting it. The table then shows it as (off).

Passwords, bearer tokens and secret keys are stored encrypted and are never shown again, not in the console and not through the API. When you edit a destination, leave the secret empty to keep the stored one. For WebDAV, tick Remove the stored CA to drop an extra CA you added earlier.

Testing a destination#

Use the Test connection button on a destination's row before the first real backup. Athena writes a small test file, checks that it appears in the listing, and deletes it again. On success it reports “Connected: write, list and delete work”. The result is also recorded in the destination's Last result column, as is every real upload: an OK or Failed badge, the time, and the message (for example “Uploaded; 2 older copies removed (keeping 7)”). A destination that has not been used yet reads “Not used yet”.

Removing a destination (Remove destination → Remove) only stops future copies. Backups already copied there are left in place.

Restoring a backup#

Use Restore to bring an appliance back to a backup's state. This can be the same appliance after a bad change, or a freshly deployed appliance that replaces one you lost. Because the backup carries the CA, a fresh appliance restored from it is trusted by the agents that were enrolled with the old one.

1. In Settings → Appliance → Restore, click Upload backup and choose the .athbak file. A progress bar shows the upload; archives of any size are accepted.
2. Enter the Backup passphrase and click Check backup. Athena decrypts the archive and verifies every file. Nothing changes yet.
3. Review what the backup brings back:
   • Backup taken: the date and the machine it was taken on.
   • Athena build: the backup's build, next to the build installed now.
   • CA thumbprint: marked same CA as now or replaces the current CA.
   • Contents: the number of files and their total size.
4. Type RESTORE in the confirmation box and click Restore, or Cancel to discard the checked copy.
5. Athena restarts. The page shows “The appliance is restarting. The web console is unavailable for a few minutes; this page reloads itself when the server is back.”

Automatic rollback#

The swap happens while Athena starts, before it opens the database or the CA. The previous state is set aside first and kept on the appliance. If the restored server does not finish starting, the next start puts the previous state back by itself. The Restore section then reports the outcome of the last restore:

When a restore is refused#

• Wrong passphrase, or a modified or damaged archive. The check fails and the upload is discarded. Upload the file again and retry with the right passphrase.
• A backup from a newer Athena build. “The archive is from a newer Athena build (…) than this one (…): update this appliance first.” Apply the matching appliance update, then restore. Backups from the same or an older build are accepted.
• The appliance runs on PostgreSQL. “This appliance runs on PostgreSQL: switch it back to SQLite at the console first, restore, then migrate again.” See PostgreSQL Database.

A backup taken while the appliance ran on PostgreSQL restores onto SQLite. Migrate to PostgreSQL again afterwards if you want to keep using it.

Audit trail#

Every backup and restore action is written to the audit log. Secrets and passphrases never appear in it.

See the Audit Event Types Reference for every event type.

REST API#

All endpoints are under api/appliance/backup, return the usual { success, message, data } envelope (except the download, which is the file itself), and answer 404 off the appliance.

To authenticate scripts, see API Tokens and the API Reference.

PowerShell#

The Athena PowerShell module wraps the same API. Passphrases and secrets are taken as SecureString.

# Nightly backup at 02:00 appliance time, keep 14
Set-AthenaApplianceBackupSettings -Retention 14 -ScheduleEnabled $true -Cron '0 2 * * *' `
  -Passphrase (Read-Host -AsSecureString 'Backup passphrase')

# Copy every backup to a Windows file share, then test it
New-AthenaBackupDestination -Name nas -Type smb -Location '\\nas01\backups\athena' `
  -Domain CORP -Username svc-backup -Secret (Read-Host -AsSecureString)
Get-AthenaBackupDestination | Test-AthenaBackupDestination

# Download the newest archive
Get-AthenaApplianceBackup | Select-Object -First 1 | Save-AthenaApplianceBackup -Path D:\Backups

# Check an archive without restoring it
Restore-AthenaApplianceBackup -Path .\athena_full_20261014_020000.athbak -Passphrase $p -ValidateOnly

Troubleshooting#

Related#

• Database Restore & Recovery: when to restore and how to verify the server afterwards.
• Database Backup & Maintenance: database-only backups.
• Data Directories & Backup: what lives where on the appliance.
• Certificates & PKI: the Root CA and why it matters for agents.
• Scheduled Jobs: where the Appliance full backup job appears.
• Downloads: appliance images and updates.