Aerospike Backup Control quickstart

This quickstart guides you through an end-to-end workflow using absctl (the Aerospike Backup Control CLI) to back up and restore a namespace using Docker. In approximately 5 minutes, you will practice a minimal setup by backing up data to local files and restoring them to your cluster.

Completing this exercise helps you master the basic command flow before you move on to advanced configurations like:

• cloud storage: Streaming directly to S3, GCS, or Azure.
• security: Implementing encryption and filtering.
• automation: Using YAML-based configurations.

What you will do

• Run absctl from a Docker container.
• Mount a local directory into the container to store backup files.
• Back up the test namespace into Aerospike backup (.asb) files.
• Restore that backup from the same directory.

Prerequisites

• Docker Desktop installed and running
• A running Aerospike Database cluster with data in the test namespace

Tip

If you don’t have an Aerospike cluster running, see the Database quickstart to set one up with Docker.

Note

This quickstart uses host.docker.internal to connect from the container to your host machine, which works with Docker Desktop on macOS and Windows. On Linux, you may need to use --network host and connect to 127.0.0.1 instead.

Back up a namespace

1. Create a local directory to store the backup files that absctl writes.

   mkdir -p ./data

2. Run absctl backup to back up the test namespace.

   The following command starts the absctl container, mounts your local ./data directory into the container, and then runs the backup command inside the container.

   docker run -it --rm \
     -v ./data:/data/backup \
     aerospike.jfrog.io/ecosystem-container-preview-public-local/absctl:v1.0.0-1 \
     absctl backup -h host.docker.internal:3000 -n test -d /data/backup

   • -v ./data:/data/backup: Mounts your ./data directory to the /data/backup directory in the Docker container.
   • -h host.docker.internal:3000: Connects to Aerospike running on your host machine.
   • -n test: Specifies the namespace to back up.
   • -d /data/backup: Writes backup files to the mounted directory.

3. Verify the backup completed successfully.

   You should see a backup report similar to:

   Backup report
   -------------
   Start Time:          Mon, 03 Feb 2026 10:30:00 UTC
   Duration:            1.234s
   
   Records Read:        100
   sIndex Read:         0
   UDFs Read:           0
   
   Bytes Written:       12345
   Files Written:       1

   Check that .asb files exist in your local ./data directory:

   ls ./data

   You should see one or more .asb files in the directory.

Restore a namespace

1. Run absctl restore to restore the backup to the same namespace.

   This command reads the backup files from the mounted ./data directory and writes the records back into the test namespace.

   docker run -it --rm \
     -v ./data:/data/backup \
     aerospike.jfrog.io/ecosystem-container-preview-public-local/absctl:v1.0.0-1 \
     absctl restore -h host.docker.internal:3000 -n test -d /data/backup

2. Verify the restore completed successfully.

   You should see a restore report similar to:

   Restore report
   --------------
   Start Time:          Mon, 03 Feb 2026 10:35:00 UTC
   Duration:            2.345s
   
   Records Read:        100
   sIndex Read:         0
   UDFs Read:           0
   
   Expired Records:     0
   Skipped Records:     0
   Ignored Records:     0
   Fresher Records:     0
   Existed Records:     0
   
   Inserted Records:    100
   In Doubt Errors:     0

This example restores back into the same namespace for simplicity. In a larger workflow, you can also restore to a different namespace or validate backup files before restoring them.

What’s next

• See absctl backup for the full backup command reference
• See absctl restore for the full restore command reference
• See Back up to cloud storage to store backups in AWS S3, GCP, or Azure
• Read the absctl installation page for other installation methods