asrestore utility restores backups created with asbackup. If the namespace on the cluster 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
--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
asrestore expects multiple
.asb backup files in the given directory. Alternatively,
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 - [...]
Access requirements for the
asrestore utility depend on what kind of objects exist in the namespace.
If the namespace contains user-defined functions,
udf-adminis the minimum necessary access role to restore UDFs for server 6.0 or newer. Otherwise,
data-admincan be used.
If the namespace contains secondary indexes,
sindex-adminis the minimum necessary access role to restore secondary indexes for server 6.0 or newer, otherwise,
data-admincan be used.
For more information about Aerospike's role-based access control system, see Privileges, permissions, and scopes.
--help option of
asrestore gives an overview of all supported command line options.
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
22.214.171.124. To restore a backup from directory
backup_2015_08_24, we would issue the following command.
asrestore --host 126.96.36.199 --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 188.8.131.52 --directory backup_2015_08_24 --namespace test,prod
|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.|
|3000||Port to connect to.|
|-||User name with write permission. Mandatory if the server has security enabled.|
|-||Password to authenticate the given user. The first form passes the password on the command line. The second form prompts for the password.|
|INTERNAL||Set 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.|
|20||The 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.|
|disabled||Indicates a TLS connection should be used.|
|false||Use to connect to |
|10000||Timeout (ms) for Aerospike commands to write records, create indexes and create UDFs.|
|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.|
|0||Total socket timeout in milliseconds. If this value is 0 and |
|5||Maximum number of retries before aborting the current write transaction.|
|150000 (150ms)||The scale factor to use in the exponential backoff retry strategy, in microseconds. Note: |
|Path to a trusted CA certificate file.|
|Path to a directory of trusted CA certificates.|
|The default TLS name used to authenticate each TLS socket connection. Note: this must also match the cluster name.|
|Set the TLS protocol selection criteria. This format is the same as Apache's SSL Protocol. If not specified, |
|Set the TLS cipher selection criteria. The format is the same as OpenSSL's Cipher List Format.|
|Path to the key for mutual authentication (if Aerospike Cluster is supporting it).|
|Password to load protected tls-keyfile. It can be one of the following:|
1) Environment varaible:
User will be prompted on command line if
|Path to the chain file for mutual authentication (if Aerospike Cluster is supporting it).|
|Path 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: |
|Enable CRL checking for leaf certificate. An error occurs if a valid CRL files cannot be found in TLS_CAPATH.|
|Enable CRL checking for entire certificate chain. An error occurs if a valid CRL files cannot be found in TLS_CAPATH.|
|Enable 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
184.108.40.206 using the default Aerospike port of
3000 with TLS configured.
HOST is "
asrestore --host 220.127.116.11:cert1:3000 --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
|-||Directory from which to read the |
|-||A comma-separated list of paths to directories that hold backup files. Required, unless -i or -d is used. The paths may not contain commas. Example: |
|-||The single file from which to read the backup. |
|-||A common root path for all paths used in --directory-list. This path is prepended to all entries in --directory-list. Example: |
|none||The decompression algorithm to use on backup files as they are read. This option must match that used when taking the backup. The options available are |
|none||The decryption algorithm use on backup files as they are read. This option must match that used when taking the backup. The options available are |
asrestore restores data to a namespace, it prints out a summary line to indicate the status of the restore. Within the status line there are a number of fields which are quantified with integers as shown below:
2023-02-15 11:06:45 GMT [INF]  Expired 0 : skipped 0 : err_ignored 0 : inserted 795922: failed 3094502 (existed 0 , fresher 3094502)
The status fields are described in the following table.
|expired||The record in the backup set has expired (i.e. the current time is greater than the void time) and so the record is not loaded into the target.|
|skipped||Specific data was selected from the restore. Records not selected are shown as skipped.|
|err_ignored||Certain errors such as errors in the bin name or AEROSPIKE_ERR_RECORD_TOO_BIG cause |
|inserted||Record from backup set successfully inserted into target.|
|failed(fresher)||The default mode of |
Record insertions that failed due to err_ignored, failed(existed), and failed(fresher) are counted by the Aerospike server as failed client writes and will increment the client_write_error metric.
Data Selection Options
|Original namespace||Namespace to be restored. By default, |
|All sets||The sets to restore.|
|All bins||The bins to restore.|
|-||Do not restore any record data (metadata or bin data). By default, |
|-||Do not restore any secondary index definitions.|
|-||Do not restore any UDF modules.|
|false||Ignore permanent record specific error. For example, AEROSPIKE_RECORD_TOO_BIG. By default such errors are not ignored and |
Write Policy Options
|-||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 |
|-||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 |
|-||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 |
|-||For records with expirable void-times, add |
Transaction Processing Options
|128 or 16||The 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".|
|32||The 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.|
|-||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 |
|1||The 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
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
Files are downloaded in chunks of 5MB, and the maximum number of simultaneous downloads across all threads is controlled with
asrestore requires certain permissions for successful use with Amazon S3. The IAM JSON policy should include the following elements. Replace
backup-bucket with the name of the S3 bucket you are using for the restore.
S3 restore options
|-||Sets the S3 region of the bucket being uploaded to/downloaded from. Must be set if using the default S3 endpoint.|
|-||Sets the S3 endpoint to use. Must point to an S3-compatible storage system.|
|default||Sets the S3 profile to use for credentials.|
|32||The maximum number of simultaneous download requests from S3.|
|1000||The AWS S3 client's connection timeout in milliseconds. Equivalent to |
|Fatal||The log level of the AWS S3 C++ SDK. The possible levels are, from least to most granular. |
To restore all records to an S3 bucket
test-bucket in region
us-west-1 under directory
asrestore -d s3://test-bucket/test-dir --s3-region us-west-1
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.
|disabled||Do not read any configuration file. Mutually exclusive to |
|-||Section with these instance is read. For example, in case instance |
|-||Read this file after default configuration file.|
|-||Read only this configuration file. Mutually exclusive to |
|disabled||Output considerably more information about the running restore.|
|-||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.|
|-||Wait for secondary indexes to finish building before proceeding. Wait for restored UDFs to be distributed across the cluster.|
|-||Output machine-readable status updates to the given path, typically a FIFO.|
|-||Validate the integrity of the backup files but do not restore any data.|
Validate Backup Files
When used with the
asrestore identifies invalid backup files and displays the bad data.
Validate mode works with any method used to supply backups to asrestore e.g.
--directory-list etc. Validate mode ignores data selection and Aerospike TLS/connection related
arguments because no connection is made to the database. If validating backups in S3, a connection is still made to s3.
Note Validate mode cannot detect all corrupted data, only issues that make the backup files impossible to parse. For example, if a backup file contains a record with corrupted data that can still be considered a valid record, that issue will not be identified. See the details of the backup file format, here, for more information.
This example shows backing up a single record to a directory, corrupting the backup file, then identifying the invalid data.
% asbackup -h 127.0.0.1:3000 -n test -d test-backup-dir
2023-07-19 20:33:55 UTC [INF]  Backed up 1 record(s), 0 secondary index(es), 0 UDF file(s), 168 byte(s) in total (~168 B/rec)
% ls test-backup-dir
% cat test-backup-dir/test_00000.asb
# namespace test
+ k S 4 key1
+ n test
+ d 7JEZLUt/jONdXXjTS8ply6qqyWA=
+ s demo
+ g 1
+ t 430086781
+ b 3
- I foo 123
- S bar 3 abc
- Z baz T
Then corrupt the backup file.
% sed -i '' -e 's/S/2/g' ./test-backup-dir/test_00000.asb
% cat test-backup-dir/test_00000.asb
# namespace test
+ k 2 4 key1
+ n test
+ d 7JEZLUt/jONdXXjT28ply6qqyWA=
+ s demo
+ g 1
+ t 430086781
+ b 3
- I foo 123
- 2 bar 3 abc
- Z baz T
And run asrestore in validate mode.
% ./bin/asrestore --validate -d test-backup-dir
2023-07-19 20:48:42 UTC [INF]  Starting validation of test-backup-dir
2023-07-19 20:48:42 UTC [INF]  Found 1 backup file(s) in test-backup-dir
2023-07-19 20:48:42 UTC [INF]  Validating backup files
2023-07-19 20:48:42 UTC [INF]  Finished validating backup file(s)
2023-07-19 20:48:42 UTC [INF]  validating test-backup-dir/test_00000.asb
2023-07-19 20:48:42 UTC [INF]  Opened backup file test-backup-dir/test_00000.asb
2023-07-19 20:48:42 UTC [ERR]  Invalid key type character "2" in block (line 4, col 5)
2023-07-19 20:48:42 UTC [ERR]  Error while parsing record
2023-07-19 20:48:42 UTC [ERR]  Error while parsing backup file test-backup-dir/test_00000.asb (line 4)
2023-07-19 20:48:42 UTC [INF]  0 UDF file(s), 0 secondary index(es), 0 record(s) (0 rec/s, 11 KiB/s, 0 B/rec, retries: 0)
2023-07-19 20:48:42 UTC [INF]  Expired 0 : skipped 0 : err_ignored 0 : inserted 0: failed 0 (existed 0 , fresher 0)
2023-07-19 20:48:42 UTC [INF]  27% complete, ~0s remaining
If you would like to change the target set to which to restore data, contact Aerospike Support for assistance.
For more information about backup and restore required resources
asrestore resource usage.