Run absctl restore

absctl restore restores data from .asb backup files to an Aerospike Database cluster.

Get started

To run absctl restore, specify:

--host: IP address or hostname of a cluster node to restore to.
One of --directory, --directory-list (multi-file backups), or --input-file (single-file backups).
--namespace: Source namespace (use SOURCE,DEST to restore to a different namespace). Required for restore operations.

Restore from a directory

To restore to a cluster that contains a node with IP address 1.2.3.4 using backup files in the local directory backup_2024_08_24, run the following command:

absctl restore --host 1.2.3.4 --directory backup_2024_08_24 --namespace test

If --namespace is a single value, the backup is restored to that same namespace.

When you specify --directory, absctl restore looks for multiple .asb backup files in the given directory.

Restore from a single file

Use --input-file to restore from a single backup file:

absctl restore --host HOST --input-file FILENAME --namespace NAMESPACE

Pass - to --input-file to read from stdin, which allows for pipelines:

cat backup.asb.gz | gunzip | absctl restore --input-file - --namespace NAMESPACE [...]

Restore to a different namespace

Use --namespace to restore to a different namespace. Specify the original and new namespace names separated by a comma:

absctl restore --host 1.2.3.4 --directory backup_2024_08_24 --namespace test,prod

Connection options

The following options are available when specifying a cluster to restore:

Option	Default	Description
`-h HOST` or `--host HOST`	127.0.0.1	The host that acts as the entry point to the cluster. Any of the cluster nodes can be specified. The remaining cluster nodes will be automatically discovered.
`-p PORT` or `--port PORT`	3000	Port to connect to.
`-U USER` or `--user USER`	-	User name with write permission. Mandatory if the server has security enabled.
`-P PASSWORD` or `--password PASSWORD`	-	Password to authenticate the given user. Supports `env-b64:VAR`, `b64:BASE64`, `file:PATH`, or clear-text.
`--auth`	INTERNAL	Authentication mode used by the Aerospike server. INTERNAL uses user/password. EXTERNAL uses external auth (such as LDAP) and requires TLS. PKI uses TLS certificate auth and does not require a username.
`-w THREADS` or `--parallel THREADS`	auto	The number of reader worker threads. When batch writes are enabled (default), writer concurrency is controlled by `--max-async-batches`; when batch writes are disabled, `--parallel` also controls writer threads. Default is the number of CPUs.
`--tls-enable`	disabled	Indicates a TLS connection should be used.
`--services-alternate`	false	Use to connect to `alternate-access-address` when the cluster nodes publish IP addresses through `access-address` which are not accessible over WAN and alternate IP addresses accessible over WAN through `alternate-access-address`.
`--client-timeout MS`	30000	Initial host connection timeout in milliseconds.
`--client-idle-timeout MS`	0	Timeout in milliseconds for idle connections. `0` means no idle timeout.
`--client-login-timeout MS`	10000	Timeout in milliseconds for client login.

Timeout options

The following options control Aerospike client timeouts/retries and restore backoff behavior:

Option	Default	Description
`-T TIMEOUT` or `--info-timeout TIMEOUT`	10000	Timeout (ms) for Aerospike info commands.
`--socket-timeout MS`	10000	Socket timeout for write transactions in milliseconds. If this value is 0, it is set to total-timeout. If both are 0, there is no socket idle time limit.
`--total-timeout MS`	10000	Total socket timeout in milliseconds. If this value is 0, there is no total transaction time limit.
`--retry-base-interval MS`	1000	The base interval to use in the exponential backoff retry strategy, in milliseconds.
`--retry-multiplier FLOAT`	1.0	Multiplier for exponential backoff retry strategy.
`--retry-max-attempts N`	0	Maximum number of write attempts for restore writes on retryable errors (total attempts; `0`/`1` means one attempt).
`--info-retry-interval MS`	1000	Base interval for info command retries.
`--info-retry-multiplier FLOAT`	1.0	Multiplier for info command retries.
`--info-max-retries N`	3	Maximum number of retries for info commands.

You can control backoff behavior for retryable restore writes with --retry-base-interval, --retry-multiplier, and --retry-max-attempts.

TLS options

The following security options are available for authentication. Defaults: --tls-enable is disabled; --tls-protocols allows TLSv1.2–TLSv1.3 (shown as +TLSv1.2 in help); all other TLS fields are unset.

Option	Description
`--tls-cafile=TLS_CAFILE`	Path to a trusted CA certificate file.
`--tls-capath=TLS_CAPATH`	Path to a directory of trusted CA certificates.
`--tls-name=TLS_NAME`	Server TLS context used to authenticate each TLS connection.
`--tls-protocols=TLS_PROTOCOLS`	Sets the TLS protocol selection criteria using the same format as Apache’s SSL Protocol. If not specified, `absctl restore` uses `+TLSv1.2` (TLSv1.2–TLSv1.3).
`--tls-keyfile=TLS_KEYFILE`	Path to the key for mutual authentication if the Aerospike cluster supports it.
`--tls-keyfile-password=TLS_KEYFILE_PASSWORD`	Password to load a protected TLS keyfile. Supports `env-b64:VAR`, `b64:BASE64`, `file:PATH`, or clear-text.
`--tls-certfile=TLS_CERTFILE <path>`	Path to the chain file for mutual authentication if the Aerospike cluster supports it.

TLS_NAME is only used when connecting with a secure TLS enabled server. The following example restores a cluster backup to node 1.2.3.4 using the default Aerospike port of 3000 with TLS configured.

absctl restore --host 1.2.3.4 --port 3000 --directory backup_2024_08_24 --namespace test --tls-enable --tls-name cluster_name --tls-cafile /cluster_name.pem --tls-protocols +TLSv1.2 --tls-keyfile /cluster_name.key --tls-certfile /cluster_name.pem

Input options

The following input options are available to specify the source backup files. Defaults are shown in command help; compression and encryption default to NONE, bandwidth and records-per-second default to 0.

Option	Description
`-d PATH` or `--directory PATH`	Directory containing the `.asb` backup files. Required unless `--input-file` or `--directory-list` is provided.
`--directory-list PATH1[,PATH2[,...]]`	Comma-separated list of paths to directories that hold backup files. Required, unless -i or -d is used. Paths may not contain commas. Example: `absctl restore --directory-list /PATH/TO/DIR1,/PATH/TO/DIR2`
`-i PATH` or `--input-file PATH`	Path to a single file that contains the backup. `-` means `stdin`. Required unless `--directory` or `--directory-list` is provided.
`-N BANDWIDTH` or `--bandwidth BANDWIDTH`	Throttles restore throughput to not exceed the given bandwidth in MiB/s (shared across restore workers).
`--nice`	Deprecated alias for `--bandwidth`.
`-L N` or `--records-per-second N`	Limit the number of records restored per second.
`--parent-directory DIRECTORY`	Common root path for all paths used in `--directory-list`. This path is prepended to all entries in `--directory-list`. Example: `absctl restore --parent-directory /common/root/path --directory-list /path/to/dir1/,/path/to/dir2`
`--encrypt ENCRYPTION_ALG`	Decryption algorithm to use on backup files as they are read. Options are `AES128`, `AES256`, or `NONE`. Must be accompanied by either `--encryption-key-file`, `--encryption-key-env`, or `--encryption-key-secret`. See compression and encryption.
`-z COMPRESSION_ALG` or `--compress COMPRESSION_ALG`	Decompression algorithm to use on backup files as they are read. Options are `ZSTD` or `NONE`. See compression and encryption.
`--compression-level N`	ZSTD compression level setting (accepted for compatibility; ignored during restore).

Reading from stdin, piping, and uncompressing

Instead of --input-file or --directory, use - with standard Unix pipes to read the backup data from stdin.

The following example commands uncompress a gzip file and then pipe the data to absctl restore with the dash - option to read from stdin:

gunzip -c BACKUP-FILE.GZ | absctl restore --host HOST -i - --namespace NAMESPACE
zcat BACKUP-FILE.GZ | absctl restore --host HOST -i - --namespace NAMESPACE
cat BACKUP-FILE.GZ | gzip -d | absctl restore --host HOST -i - --namespace NAMESPACE

The following example concatenates a single uncompressed backup file and pipes the data to absctl restore with the dash - option:

cat BACKUP-FILE | absctl restore --host HOST -i - --namespace NAMESPACE

Output definitions

After a restore, absctl restore prints a status summary report like the following:

Restore report
--------------
Start Time:          Wed, 28 Jan 2026 12:34:56 UTC
Duration:            1m23s

Records Read:        123
sIndex Read:         2
UDFs Read:           1

Expired Records:     0
Skipped Records:     0
Ignored Records:     0
Fresher Records:     5
Existed Records:     10

Inserted Records:    108
In Doubt Errors:     0

The status fields are described as follows:

Field	Description
Expired Records	The record in the backup set has expired (the current time is greater than the void time) and the record is not loaded into the target.
Skipped Records	Specific data was selected from the restore. Records not selected are shown as skipped.
Ignored Records	Record-specific errors (for example, `AEROSPIKE_RECORD_TOO_BIG`) that are ignored due to `--ignore-record-error`.
Inserted Records	Record from backup set successfully inserted into target.
Existed Records	The `--unique` option was chosen for the restore, so only records that do not exist are inserted. Records not inserted due to them existing in the target are counted as existed.
Fresher Records	The default mode of `absctl restore` is to check generation on insertion. This avoids inserts if the active record is newer than the backup. To ignore the generation check, use the `--no-generation` write policy.
In Doubt Errors	Records with in-doubt write errors during restore.

The Aerospike server counts record insertions that failed due to Ignored Records, Existed Records, and Fresher Records as failed client writes and increments the client_write_error metric.

Data selection options

Use the following options to specify the types of data to be restored:

Option	Default	Description
`-n ORIGINAL-NS,NEW-NS` or `--namespace ORIGINAL-NS,NEW-NS`	Original namespace	Required. Provide `ORIGINAL-NS` or `ORIGINAL-NS,NEW-NS`. If only `ORIGINAL-NS` is specified, restore writes back to that same namespace. If the namespace from which the backup was taken does not match `ORIGINAL-NS`, `absctl restore` aborts with an error. If `NEW-NS` is specified, the backup is restored to `NEW-NS`.
`-s SET1,SET2,...` or `--set-list SET1,SET2,...`	All sets	Specific set or comma-separated list of sets to restore.
`-B BIN1,BIN2,...` or `--bin-list BIN1,BIN2,...`	All bins	Specific bin or comma-separated list of bins to restore.
`-R` or `--no-records`	-	Do not restore any record data (metadata or bin data). By default, `absctl restore` restores record data, secondary index definitions, and UDF modules.
`-I` or `--no-indexes`	-	Do not restore any secondary index definitions.
`--no-udfs`	-	Do not restore any UDF modules.
`--ignore-record-error`	false	Ignore permanent record specific error. For example, AEROSPIKE_RECORD_TOO_BIG. By default such errors are not ignored and `absctl restore` terminates. Optional: Use verbose mode to see errors in detail.

Write policy options

Use the following options to specify which records take precedence during a restore. There are no default values for these options.

Option	Description
`-u` or `--unique`	Existing records take precedence. Only records that do not exist in the namespace are restored, regardless of generation numbers. If a record exists in the namespace, the record from the backup is ignored. If both `--unique` and `--replace` are set, `--replace` takes precedence.
`-g` or `--no-generation`	Records from backups take precedence. Disables the generation check. Records from the backup always overwrite records that already exist in the namespace, regardless of generation numbers. This option can be combined with `--unique` or `--replace`.
`-r` or `--replace`	Replace records. Controls how records from the backup overwrite existing records in the namespace. By default, restoring a record from a backup only replaces the bins contained in the backup; all other bins of an existing record remain untouched. Existing record is completely replaced; that is, any bins that are not contained in the backup are discarded. This option still does a generation check by default and should be combined with the `-g` option if no generation check is desired. If both `--replace` and `--unique` are set, `--replace` takes precedence.
`--extra-ttl N`	For records with expirable void-times, add `N` seconds of `extra-ttl` to the recorded `void-time`.

Write policy for duplicate key IDs

If the target namespace already contains keys with the same IDs as the backup you are restoring, absctl restore uses the following write policy logic for managing existing keys:

If the record from the backup is expired, based on its TTL value, the backup record is ignored.
If the record does not exist in the namespace, the backup record is added to the namespace.
If an older version of the record (that is, with a lower generation count) already exists in the namespace, the backup record is restored. If you want absctl restore to ignore this condition, specify this option:

--unique: absctl restore does not touch any existing records, regardless of generation counts.

If a newer version of the record (that is, with a higher or same generation count) already exists in the namespace, the backup record is ignored. If you want absctl restore to ignore this condition, specify this option:

--no-generation: absctl restore overwrites any existing records, regardless of generation count.

If the record in the namespace contains bins that are not present in the backup, those bins in the namespace are preserved. If you want absctl restore to ignore this condition, specify this option:

--replace: When restoring a record from the backup, absctl restore does not preserve namespace bins that are not present in the backup.

Transaction processing options

Use the following options to specify details in write transactions:

Option	Default	Description
`--batch-size N`	128	Maximum allowed number of records per async batch write call.
`--max-async-batches N`	32	Maximum number of outstanding async record batch write calls at a time.
`--disable-batch-writes`	-	Disables the use of batch writes when restoring records to the Aerospike cluster.
`--warm-up N`	auto	Warm Up fills the connection pool with connections for all nodes. Default is `max-async-batches` + 1.

Additional options for `absctl restore`

Use the following additional options to read more information about a restore transaction, work with secondary indexes, or validate backup files:

Option	Default	Description
`-v` or `--verbose`	disabled	Output considerably more information about the running restore.
`--log-level`	debug	Log level (debug, info, warn, error).
`--log-json`	false	Enable JSON logging.
`--std-buffer`	4	Buffer size for stdin and stdout operations in MiB.
`--validate`	-	Validate the integrity of the backup files but do not restore any data.
`--apply-metadata-last`	false	If set to true, metadata (secondary indexes and UDFs) from separate file will be restored after all records have been processed.

Configure `absctl restore` with configuration files

Use the --config PATH flag to specify the YAML configuration file path.

Legacy astools.conf INI-style configuration is not supported; use YAML with --config instead.

`absctl restore` error messages

absctl restore may return any of the following error messages:

Record exists: When the --unique option is used, this informational message is displayed.
Generation mismatch: The backup copy and existing copy of a key do not match, and so the key is not restored. You can override this behavior with the --no-generation option.
Invalid username or password: The wrong username or password was specified on the command line.

Record-level conflicts are counted in the restore report and may be skipped depending on write policy (--unique, --no-generation) or --ignore-record-error. Authentication or connection errors terminate the restore.