Skip to main content

asrestore command-line options

The asrestore utility restores backups created with asbackup. If the namespace on the cluster already contains existing records, a configurable write policy determines which records take precedence - records in the namespace or records from the backup. The Write Policy section on the overview page has more details on this.

If a transaction fails it is retried according to --max-retries and --retry-scale-factor. By default these are 5 and 150ms respectively. An exponential backoff strategy is followed where the delay is retry-scale-factor * 2 ** (retry_attempts - 1), or 0 on the first try. If --max-retries is exceeded the transaction is counted as a failure in the info level log output. The specific errors in which a retry is not affected are "record exists" (when the --unique option is used), "generation mismatch" (unless if the --no-generation option is used) and "invalid username or password".

When run with the --directory option, asrestore expects multiple .asb backup files in the given directory. Alternatively, --input-file makes asrestore read the complete backup from the given single file. If - is specified as the file, asrestore reads the backup from stdin. This allows for pipelines:

cat backup.asb.gz | gunzip | asrestore --input-file - [...]

Required permissions

Access requirements for the asrestore utility depend on what kind of objects exist in the namespace.

  • If the namespace contains no user-defined functions or secondary indexes, read-write is the minimum necessary access role.

  • If the namespace contains user-defined functions, udf-admin is the minimum necessary access role to restore UDFs for server 6.0 or newer. Otherwise, data-admin can be used.

  • If the namespace contains secondary indexes, sindex-admin is the minimum necessary access role to restore secondary indexes for server 6.0 or newer, otherwise, data-admin can be used.

For more information about Aerospike's role-based access control system, see Privileges, permissions, and scopes.


The -Z or --help option of asrestore gives an overview of all supported command line options.

asrestore --help

The most basic form of running asrestore is to just specify the cluster to restore (--host) and the local directory containing the backup files (--directory). Suppose that we have a cluster that contains a node with IP address To restore a backup from directory backup_2015_08_24, we would issue the following command.

asrestore --host --directory backup_2015_08_24

By default, the backup is restored to the namespace that it was taken from. The --namespace option can be used to restore to a different namespace. Suppose that the previous backup example was taken from namespace test, and you want to restore it to namespace prod. Issue the following command:

asrestore --host --directory backup_2015_08_24 --namespace test,prod

Connection Options

-h HOST or --host HOST127.0.0.1The 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 PORT3000Port 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 to authenticate the given user. The first form passes the password on the command line. The second form prompts for the password.
-A or --authINTERNALSet authentication mode when user and password are defined. Modes are (INTERNAL, EXTERNAL, EXTERNAL_INSECURE, PKI) and the default is INTERNAL. This mode must be set EXTERNAL when using LDAP.
-t THREADS or --parallel THREADS20The number of client threads to spawn for writing to the cluster. Higher numbers mean faster restores, which may, however, have a negative impact on server performance.
--tls-enabledisabledIndicates a TLS connection should be used.
-S or --services-alternatefalseUse 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.

Timeout Options

-T TIMEOUT or --timeout TIMEOUT10000Timeout (ms) for Aerospike commands to write records, create indexes and create UDFs.
--socket-timeout MS10000Socket 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 MS0Total socket timeout in milliseconds. If this value is 0 and --timeout is set, then the --timeout value is used as the write transaction timeout. Default is 0, that is, no timeout.
--max-retries N5Maximum number of retries before aborting the current write transaction.
--retry-scale-factor MS150000 (150ms)The scale factor to use in the exponential backoff retry strategy, in microseconds. Note: --retry-delay and --sleep-between-retries are deprecated in favor of --retry-scale-factor.

TLS Options

--tls-cafile=TLS_CAFILEPath to a trusted CA certificate file.
--tls-capath=TLS_CAPATHPath to a directory of trusted CA certificates.
--tls-name=TLS_NAMEThe default TLS name used to authenticate each TLS socket connection. Note: this must also match the cluster name.
--tls-protocols=TLS_PROTOCOLSSet the TLS protocol selection criteria. This format is the same as Apache's SSL Protocol. If not specified the asrestore will use -all +TLSv1.2 if has support for TLSv1.2, otherwise it will be -all +TLSv1.
--tls-cipher-suite=TLS_CIPHER_SUITESet the TLS cipher selection criteria. The format is the same as OpenSSL's Cipher List Format.
--tls-keyfile=TLS_KEYFILEPath to the key for mutual authentication (if Aerospike Cluster is supporting it).
--tls-keyfile-password=TLS_KEYFILE_PASSWORDPassword to load protected tls-keyfile. It can be one of the following:
1) Environment varaible: env:VAR
2) File: file:PATH
3) String: PASSWORD
User will be prompted on command line if --tls-keyfile-password specified and no password is given.
--tls-certfile=TLS_CERTFILE <path>Path to the chain file for mutual authentication (if Aerospike Cluster is supporting it).
--tls-cert-blacklist PATHPath to a certificate blocklist file. The file should contain one line for each blocklisted certificate. Each line starts with the certificate serial number expressed in hex. Each entry may optionally specify the issuer name of the certificate (serial numbers are only required to be unique per issuer). Example: 867EC87482B2 /C=US/ST=CA/O=Acme/OU=Engineering/CN=TestChainCA
--tls-crl-checkEnable CRL checking for leaf certificate. An error occurs if a valid CRL files cannot be found in TLS_CAPATH.
--tls-crl-checkallEnable CRL checking for entire certificate chain. An error occurs if a valid CRL files cannot be found in TLS_CAPATH.
--tls-log-session-infoEnable logging session information for each TLS connection.

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


asrestore --host --directory backup_2015_08_24 --namespace test --tls-enable --tls-cafile /cluster_name.pem --tls-protocols TLSv1.2 --tls-keyfile /cluster_name.key --tls-certfile /cluster_name.pem

Input Options

-d PATH or --directory PATH-Directory from which to read the .asb backup files. Mandatory, unless --input-file is given.
-i PATH or --input-file PATH-The single file from which to read the backup. - means stdin. Mandatory, unless --directory is given.
-N BANDWIDTH, TPS or --nice BANDWIDTH, TPS-Throttles asrestore's read operations from the backup file(s) to not exceed the given I/O bandwidth in MiB/s and its database write operations to not exceed the given number of transactions per second. Useful to limit the impact of asrestore on server performance.
-y COMPRESSION_ALG or --compress COMPRESSION_ALGnoneThe decompression algorithm to be used on backup files as they are read. This option must match that used when taking the backup. The options available are zstd. Refer to compression and encryption.
-z ENCRYPTION_ALG or --encrypt ENCRYPTION_ALGnoneThe decryption algorithm to be used on backup files as they are read. This option must match that used when taking the backup. The options available are aes128 and aes256. This option must be accompanied by either --encryption-key-file or encryption-key-env. Refer to compression and encryption.

Data Selection Options

-n ORIGINAL-NS,NEW-NS or --namespace ORIGINAL-NS,NEW-NSOriginal namespaceNamespace to be restored. By default, asrestore restores a backup to the namespace from which it was taken. If this option is specified and the namespace from which the backup was taken does not match ORIGINAL-NS, asrestore aborts with an error. This ensures that we restore the data that we intend to restore. If NEW-NS is specified, the backup will be restored to NEW-NS instead of the namespace from which it was taken.
-s SET1,SET2,... or --set-list SET1,SET2,...All setsThe sets to restore.
-B BIN1,BIN2,... or --bin-list BIN1,BIN2,...All binsThe bins to restore.
-R or --no-records-Do not restore any record data (metadata or bin data). By default, asrestore restores record data, secondary index definitions, and UDF modules.
-I or --no-indexes-Do not restore any secondary index definitions.
-F or --no-udfs-Do not restore any UDF modules.
-K or --ignore-record-errorfalseIgnore permanent record specific error. For example, AEROSPIKE_RECORD_TOO_BIG. By default such errors are not ignored and asrestore terminates. Optional: Use verbose mode to see errors in detail.

Write Policy Options

-u or --unique-Existing records take precedence. With this option, 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. Note: this option is mutually exclusive to --replace and --no-generation.
-g or --no-generation-Records from backups take precedence. This option disables the generation check. With this option, records from the backup always overwrite records that already exist in the namespace, regardless of generation numbers. Note: this option is mutually exclusive to --unique. Warning: by using this option you may lose a more recent version of your data by overwriting it with an older version.
-r or --replace-Replace records. This 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. With this option, the 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 would need to be combined with the -g option if no generation check is desired. Note: this option is mutually exclusive to --unique.
-l or --extra-ttl N-For records with expirable void-times, add N seconds of extra-ttl to the recorded void-time.

Transaction Processing Options

--batch-size N128 or 16The max allowed number of records per C client async batch write call. Default is 128 with batch writes enabled, or 16 without batch writes. Without batch writes, records are grouped and written in a logical "batch".
--max-async-batches N32The max number of outstanding async record batch write calls at a time. For pre-6.0 servers, batches are only a logical grouping of records, and each record is uploaded individually. The true max number of async Aerospike calls would then be max-async-batches * batch-size.
--disable-batch-writes-Disables the use of batch writes when restoring records to the Aerospike cluster. By default, the cluster is checked for batch write support, so only set this flag if you explicitly don't want batch writes to be used or asrestore is failing to recognize that batch writes are disabled and is failing to work because of it.
--event-loops N1The number of C client event loops to initialize for processing of asynchronous Aerospike transactions.

Restore from S3

To restore files from Amazon S3, prefix file/directory names with s3://BUCKET/KEY, where BUCKET is the name of the S3 bucket to download from, and KEY is the key of the object to download/prefix of files in the S3 "directory". If using the default S3 endpoint, --s3-region REGION must be set to the region that the bucket you're uploading to is in. If using another endpoint, specify that endpoint with --s3-endpoint-override URL.

Files are downloaded in chunks of 5MB, and the maximum number of simultaneous downloads across all threads is controlled with --s3-max-async-downloads.

--s3-region REGION-Sets the S3 region of the bucket being uploaded to/downloaded from. Must be set if using the default S3 endpoint.
--s3-endpoint-override URL-Sets the S3 endpoint to use. Must point to an S3-compatible storage system.
--s3-profile PROFILE_NAMEdefaultSets the S3 profile to use for credentials.
--s3-max-async-downloads N32The maximum number of simultaneous download requests from S3.
--s3-bucket BUCKET-The S3 bucket to use for all S3 objects. With this option given, S3 paths are then interpreted as s3://KEY, that is, the bucket name should be omitted from the path.
--s3-log-level LEVELFatalThe log level of the AWS S3 C++ SDK. The possible levels are, from least to most granular.
  • Off
  • Fatal
  • Error
  • Warn
  • Info
  • Debug
  • Trace


To restore all records to an S3 bucket test-bucket in region us-west-1 under directory test-dir:

asrestore -d s3://test-bucket/test-dir --s3-region us-west-1


Same example but using --s3-bucket.

asrestore -d s3://test-dir --s3-region us-west-1 --s3-bucket test-bucket

Configuration File Options

asrestore can be configured by using tools configuration files. Refer to Aerospike Tools Configuration for more details. The following options affect configuration file behavior.

--no-config-file disabledDo not read any configuration file. Mutually exclusive to --only-config-file.
--instance NAME-Section with these instance is read. For example, in case instance a is specified sections cluster_a, asrestore_a is read.
--config-file PATH-Read this file after default configuration file.
--only-config-file PATH-Read only this configuration file. Mutually exclusive to --no-config-file.

Other Options

-v or --verbosedisabledOutput considerably more information about the running restore.
-L or --indexes-last-Create indexes after restoring everything else. By default, indexes are restored before everything else, which can prevent costly SSD reads required to build the indexes.
-w or --wait-Wait for secondary indexes to finish building before proceeding. Wait for restored UDFs to be distributed across the cluster.
-m or --machine PATH-Output machine-readable status updates to the given path, typically a FIFO.

If you would like to change the target set to which to restore data, contact Aerospike Support for assistance.

Resource usage

For more information about backup and restore required resources asbackup and asrestore resource usage.