Aerospike Shared-Memory Tool (ASMT)

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

The Aerospike Shared-Memory Tool (ASMT) backs up and restores Aerospike shared memory segments to disk, enabling warm restart across reboots in an Aerospike Database Enterprise Edition (EE) cluster. The tool backs up primary indexes, secondary indexes, and data stages from the server node (host machine) memory to the file system. After the backup, the server node can reboot without the time-consuming stage of rebuilding the indexes.

Warm restart with `asmt`

Use the following steps to perform a warm restart of an Aerospike Database cluster node when planned maintenance includes a host reboot or power cycle:

Cleanly shut down the Aerospike cluster node process (asd).
Use asmt to copy the node’s indexes from shared memory to the local file system.
Perform maintenance on the server, then reboot or power cycle the host.
After the server restarts, use asmt to restore the indexes from the file system to shared memory.
Start asd, which will warm restart the node because the primary index is in shared memory.

Multi-node maintenance

If you are maintaining more than one node:

AP namespaces: After the node rejoins, wait for migrations to complete before working on the next node. This is especially important for in-memory namespaces without persistence, where data is lost on host reboot. In Database 4.3.0 and later, use cluster-stable to check status. It returns ERROR while migrations are in progress. For the full host-reboot workflow, follow Planned maintenance with host reboot.
SC namespaces: Follow the SC planned maintenance procedure. You do not need to wait for migrations between nodes, but the handoff must complete before you shut down the next node.

The alternative – a cold restart – is a much longer process because it requires the Aerospike cluster node to scan all storage devices to reconstruct the primary index.

When not to use ASMT

In some situations a cold restart is preferable to restoring indexes with ASMT:

Suspected memory corruption or DIMM maintenance. If the host reboot is due to faulty or suspect DIMMs, restoring indexes from those shared memory segments may reintroduce corrupt data. Let the node cold restart so it rebuilds the indexes cleanly from storage.
Reclaiming shared memory after cluster expansion. When nodes have been added to the cluster and data has rebalanced, existing nodes may hold oversized shared memory segments from their previous partition ownership. Skipping ASMT and allowing a cold restart lets the node reallocate shared memory based on its current data footprint.

Avoiding cold restart side effects

During planned maintenance that involves a host reboot, shared memory segments holding the primary index are wiped. Without ASMT, the subsequent Aerospike startup is a cold restart, which rebuilds the primary index by scanning data storage. This rebuild process can resurrect deleted records as zombie records.

Using ASMT to persist and restore the primary index across the reboot ensures a warm restart, avoiding the index rebuild and its side effects.

Next: Install ASMT
Options for ASMT
Back up indexes with ASMT
Restore indexes with ASMT
How to speed up cold start knowledge base article.