Back up indexes with ASMT

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

The Aerospike Shared-Memory Tool (ASMT) backs up indexes that are stored in shared memory, which is a feature of Aerospike Database Enterprise Edition (EE).

Prerequisites

Ensure that the asmt executable has write permission to the backup directory.
Stop the Aerospike daemon process (asd) after quiescing it. If the node is still running, asmt will fail.
Verify that the backup directory does not already contain ASMT segment files (.dat or .dat.gz) for the same instance and namespace, as asmt does not overwrite existing segment files. Files for other namespaces in the same directory do not block the backup.

Backup procedure

(Optional) Pre-run check

You can run asmt with the -a option to check whether the indexes can be backed up, without actually executing the backup operation.

sudo ./asmt -a -b -p <path-to-backup-directory> -n <namespaces>

Run ASMT as the same user and group as asd. Use sudo only when asd runs as root. Shared-memory segment ownership must match so ASMT can read segments on backup.

When -a is combined with -b, the backup directory must already exist and be writable.

Required option	Description
`-a`	Analyze whether the indexes can be backed up without performing the backup operation.
`-b`	Specifies the backup operation.
`-p`	Specifies the path to the backup directory.
`-n`	One or more namespaces to be backed up. Use a comma-separated list for multiple namespaces.

Back up the indexes

sudo ./asmt -b -v -p <path-to-backup-directory> -n <namespaces>

Required option	Description
`-b`	Specifies the backup operation.
`-p`	Specifies the path in which to persist the indexes.
`-n`	One or more namespaces to be backed up. Use a comma-separated list for multiple namespaces.

See Options for ASMT for the complete list of options.

ASMT backs up the indexes from shared memory to the file system. The length of time to execute the command depends on the size of the indexes. The backup directory contains files with a .dat extension, persisting the shared-memory blocks, with the file names corresponding to shared-memory keys. Compressed backup files have a .dat.gz extension. The pi-base and si-meta files for a namespace are never compressed, because ASMT must examine their contents prior to restoring the indexes.

Example output

Backing up the test namespace with verbose output and compression:

sudo asmt -b -v -z -p /opt/aerospike/asmt-backup -n test

Aerospike Shared Memory Tool, Version 2.2.0
Copyright (C) 2022-2024 Aerospike, Inc.  All rights reserved.

asmt -b -v -z -p /opt/aerospike/asmt-backup -n test

Performing backup operation with compression.

key         shmid  user  group  mode  natt  segsz      inst  nsid  name  type      stage
----------  -----  ----  -----  ----  ----  ---------  ----  ----  ----  --------  -----
0xa2001000  7      root  root   0666  0     2097152    0     1     test  si-meta   -
0xa2001100  5      root  root   0666  0     67108864   0     1     test  si-stage  0x100
0xae001000  4      root  root   0666  0     2097152    0     1     test  pi-base   -
0xae001001  3      root  root   0666  0     2637824    0     1     test  pi-treex  -
0xae001100  0      root  root   0666  0     134217728  0     1     test  pi-stage  0x100

Transferred 100% of data in 0.2s.

Successfully backed up 5 Aerospike database segments.

The resulting backup directory:

ls -lh /opt/aerospike/asmt-backup/
total 5.1M
-rw-rw-rw-. 1 root root 2.0M Apr 14 02:30 a2001000.dat
-rw-rw-rw-. 1 root root 318K Apr 14 02:30 a2001100.dat.gz
-rw-rw-rw-. 1 root root 2.0M Apr 14 02:30 ae001000.dat
-rw-rw-rw-. 1 root root  46K Apr 14 02:30 ae001001.dat.gz
-rw-rw-rw-. 1 root root 789K Apr 14 02:30 ae001100.dat.gz

The pi-base file (ae001000.dat) and si-meta file (a2001000.dat) are always uncompressed. The treex and stage files are compressed (.dat.gz) because the -z option was used.

What to do next

Reboot the server that hosts your Aerospike cluster node. After the server is rebooted, and before you restart the Aerospike node, run ASMT to restore the indexes. With the indexes in shared memory, the node can perform a warm start.