Aerospike Shared-Memory Tool (ASMT)

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.

Note

This tool is not intended for namespaces where the primary index is configured on Persistent Memory or Flash (SSDs), as those would persist upon an instance restart.

Warm restart with asmt

Follow the steps below to perform a warm restart of an Aerospike Database cluster node when regular maintenance or a server reboot are required:

1. Cleanly shut down the Aerospike cluster node process (asd).
2. Use asmt to copy the node’s indexes from shared memory to the local file system.
3. Perform any required maintenance on the server, rebooting or power cycling when finished.
4. After the server restarts, use asmt to restore the indexes from the file system to shared memory.
5. Start asd, which will warm restart the node because the indexes are in shared memory.

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.

Caution

You cannot use ASMT while asd is running.

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.

Strong consistency

For namespaces with strong-consistency enabled, perform planned maintenance that involves a host reboot one node at a time, using ASMT to back up and restore the primary index on each node. See the SC planned maintenance procedure for the full steps, including quiescing nodes before shutdown.

Tip

ASMT backup and restore are I/O-bound, so using the -z compression option is recommended for planned maintenance. Compression reduces file sizes by 15-30%, which translates to 20-30% faster backup and restore operations. The benefit is most significant when the backup volume has limited throughput, such as cloud-attached block storage (for example, EBS) or a NAS.

Related topics

• Next: Installing ASMT
• Options for ASMT
• Backing up indexes with ASMT
• Restoring indexes with ASMT
• How to speed up cold start knowledge base article.