Documentation Backup and restore

Backup and restore

A recoverable Asura backup includes a consistent database backup, the configuration used to open it, and any external secrets or files referenced by that configuration. Use a database backup for disaster recovery and rollback. Use the JSON export in Settings to transfer portable configuration between installations.

Back up the database and configuration

For the default SQLite backend:

  1. Find the database file from database.path in your active configuration. For Docker, use the persistent data volume, not the container’s disposable filesystem.
  2. Create a consistent database snapshot with SQLite’s backup command, or stop Asura cleanly before copying its database files.
  3. Save config.yaml, environment or secret files, and any referenced TLS certificates or keys. Preserve database.encryption_key when configured: restoring the database without the matching key will not recover encrypted credentials.
  4. Record the Asura version and keep a compatible binary or container image reference with the backup.

With the SQLite CLI installed, this example creates a snapshot while Asura is running. Replace both paths with your actual database and backup destination:

sqlite3 /path/to/asura.db ".backup '/backup/asura.db'"

SQLite’s online backup mechanism produces a consistent snapshot; the CLI reference documents .backup. An ordinary copy of a live database file can miss changes in its WAL. For an offline file copy, stop Asura and preserve any remaining database companion files together with the database.

PostgreSQL backups

The optional PostgreSQL build uses PostgreSQL backup tooling. SQLite file-copy, WAL and checkpoint instructions do not apply to it. Preserve the same YAML, encryption key, referenced files and matching Asura binary alongside the database backup.

Use your database operator’s backup and recovery policy. For a logical snapshot, PostgreSQL’s pg_dump can capture a consistent database while it is running. This example uses a preconfigured connection service so credentials stay out of command arguments:

pg_dump --dbname=service=asura-backup --format=custom --file=/backup/asura.dump

Provision a separate empty restore database and its owner role. With Asura stopped for that destination, restore the archive as the intended owner:

pg_restore --dbname=service=asura-restore --single-transaction --no-owner --no-privileges /backup/asura.dump

Review the pg_restore options, backup command exit status and diagnostics. A single-database dump does not provision cluster roles. Test the restored database with its matching key and application version in an isolated environment before using it for recovery. Do not point a running Asura instance at an incomplete restore.

Verify and restore

Test the backup in a separate SQLite directory or PostgreSQL database with a copy of the matching configuration and key. Keep the test instance isolated from production check targets, agents and notification destinations until you have reviewed its configuration. Confirm that the database opens, expected monitors and history are present, and stored credentials can be read.

For a production restore, stop Asura first and preserve the current database and configuration separately. For SQLite, restore into a clean data directory with the correct file ownership and encryption key; do not mix the restored database with WAL or shared-memory files from another database. For PostgreSQL, use the restored dedicated database and its intended owner. Start the matching Asura version and verify its logs and state before resuming normal operation.

JSON configuration export

Settings offers full and redacted v2 exports. Both require super_admin: true; ordinary resource permissions do not grant configuration transfer access. IDs in an export belong to that file. Import resolves their relationships to the destination’s IDs.

Resource Portable configuration
Monitors Definitions, protocol settings, assertions, groups, tags, channel routing, proxy references, escalation references, and explicit agent references
Shared resources Groups, tags, proxies, notification channels, escalation policies and their steps
Operations Maintenance schedules, active state and monitor selections; on-call rotations, cadence anchors and overrides
Status pages Page settings, branding, password protection, monitor membership and display order

History, sessions, audit records and status-page subscribers stay in the database backup. Authentication, roles, server settings and other YAML configuration stay in the configuration backup. Agent enrollment tokens and heartbeat credentials are never portable export data.

A full export contains credentials for its portable resources, including channel and proxy settings and status-page password hashes. Store it as a secret. A redacted export is for sharing: it removes targets, settings, assertions, channel settings, proxy credentials and page password hashes. Import rejects redacted files. Review names, descriptions, branding and other free-form content before sharing either kind of file.

curl --fail --show-error -H "X-API-Key: ${ASURA_API_KEY}" \
  https://example.com/api/v1/export > configuration.json

curl --fail --show-error -H "X-API-Key: ${ASURA_API_KEY}" \
  'https://example.com/api/v1/export?redact_secrets=true' > configuration-redacted.json

Add your configured server.base_path before /api/v1 when Asura is hosted below the domain root.

JSON configuration import

Import transfers supported configuration, not historical database state. Export and import JSON are limited to 32 MiB. Test the file on an isolated instance and take a database backup before replacing existing configuration.

Mode Purpose
merge Create imported items and retain uniquely matching existing items. Resources match by name; status pages match by slug. Ambiguous existing names cause the import to fail.
replace Delete the existing portable configuration and replace it with the file. This also deletes related monitoring and notification history, and status-page subscribers. Notification history is removed when its channel is deleted, including entries without a monitor. Take a database backup first. 
curl --fail --show-error -X POST -H "X-API-Key: ${ASURA_API_KEY}" \
  -H "Content-Type: application/json" --data-binary @configuration.json \
  'https://example.com/api/v1/import?mode=merge'

Import validates and writes the configuration in one transaction. A failure rolls back the import, including a replacement’s deletions. The success response reports created and skipped entries. Review the resulting configuration and check targets before allowing normal monitoring and notification delivery. Import requires the same explicit super-admin authority as export.

Heartbeat enrollment

Each newly imported heartbeat monitor receives a fresh credential. The web import result shows its new ping URL once; the API response returns heartbeats entries containing monitor_id, monitor_name and the one-time token. Update the corresponding job with this new credential. A heartbeat skipped during a merge keeps its existing credential. Exports cannot recover either credential.

Agent references

Agent references resolve to already enrolled destination agents with unique matching names, or to an explicit source-to-destination agent_mapping supplied with the import; see configuration transfer for the request format. Import never creates or enables agents or transfers agent tokens. Review every mapping: assignment delegates eligible monitor data to that agent.

Older export files

V1 files can resolve the name-based relationships they contain. V1 maintenance selections with numeric monitor IDs are rejected because those files did not include the monitor IDs needed to translate the selections safely. Review and recreate those selections explicitly, or export v2 configuration from an upgraded copy of the original database.