Restore indexes with the Aerospike Shared-Memory Tool (ASMT)

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

Before restarting the Aerospike node, you can run ASMT to restore the indexes. The length of time it takes to restore indexes depends on their size.

Prerequisites

Ensure that the Aerospike daemon process (asd) is not running.
Ensure that asmt has read permission to the backup files.

Restore procedure

(Optional) Pre-run check

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

sudo ./asmt -a -r -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 create segments on restore.

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

Required option	Description
`-a`	Analyze whether an index can be restored without performing the restore operation.
`-r`	Specifies the restore operation.
`-p`	Specifies the path to the directory containing the index backup files.
`-n`	One or more namespaces to be restored. Use a comma-separated list for multiple namespaces.

Restore the indexes

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

Required option	Description
`-r`	Specifies the restore operation.
`-p`	Specifies the path to the directory containing the index backup files.
`-n`	One or more namespaces to be restored. Use a comma-separated list for multiple namespaces.

See Options for ASMT for the complete list of options.

After ASMT restores the indexes, the backup directory still contains backup files.

Example output

Restoring the test namespace from a compressed backup:

sudo asmt -r -v -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 -r -v -p /opt/aerospike/asmt-backup -n test

Performing restore operation.

key         user  group  mode     filsz    segsz      inst  nsid  name  type      stage
----------  ----  -----  -------  -------  ---------  ----  ----  ----  --------  -----
0xa2001000  root  root   0100666  2097152  2097152    0     1     test  si-meta   -
0xa2001100  root  root   0100666  325190   67108864   0     1     test  si-stage  0x100
0xae001000  root  root   0100666  2097152  2097152    0     1     test  pi-base   -
0xae001001  root  root   0100666  46305    2637824    0     1     test  pi-treex  -
0xae001100  root  root   0100666  807471   134217728  0     1     test  pi-stage  0x100

Transferred 100% of data in 0.1s.

Successfully restored 5 Aerospike database segment files.

The -z option is not needed on restore. ASMT automatically detects and decompresses .dat.gz files.

Troubleshooting

Do not restart the Aerospike daemon (asd) before ASMT finishes restoring the indexes. If you do so, both ASMT and asd will fail. If this happens, you must follow these steps:

Delete any shared-memory segments that ASMT created before it failed. You can do so by running the following commands:

# remove primary index shared memory segments
ipcs | grep ^0xae | awk '{print $1}' | xargs -i sudo ipcrm -M {}
# remove secondary index shared memory segments
ipcs | grep ^0xa2 | awk '{print $1}' | xargs -i sudo ipcrm -M {}
# remove data-stage shared memory segments (ASMT 2.0.1 and later, Aerospike Database 7.0.0 and later)
ipcs | grep ^0xad | awk '{print $1}' | xargs -i sudo ipcrm -M {}

Run asmt again to restore the indexes.

What to do next

With the indexes restored to shared memory, start asd so the node can perform a warm restart. If you are restoring nodes one at a time during planned maintenance, see Multi-node maintenance on the ASMT overview page.