---
title: "Run absctl restore"
description: "Learn how to use absctl restore to recover data from .asb backup files to an Aerospike Database cluster."
---

# Run absctl restore

> For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt)
> 
> All documentation pages available in markdown.

`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:

Terminal window

```shell
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:

Terminal window

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

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

Terminal window

```shell
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:

Terminal window

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

::: note
`--namespace` accepts one or two comma-separated values only. If more than two values are provided, namespace remapping and validation are skipped.
:::
::: tip
Run with the `-Z` or `--help` option to see an overview of all supported command-line options.
:::

## 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`](https://aerospike.com/docs/database/reference/config#network__alternate-access-address) when the cluster nodes publish IP addresses through [`access-address`](https://aerospike.com/docs/database/reference/config#network__access-address) which are not accessible over WAN and alternate IP addresses accessible over WAN through [`alternate-access-address`](https://aerospike.com/docs/database/reference/config#network__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`.

::: note
The `--retry-*` flags control `absctl restore`’s retry loop for restore writes on retryable errors. The `--info-*` flags control retries for info commands.
:::

## 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](https://httpd.apache.org/docs/2.4/mod/mod_ssl.html). 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.

Terminal window

```shell
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`.

::: note
If the backup was created with `absctl backup --compress` or `--encrypt`, restore must use matching `--compress`/`--encrypt` settings and the same key material.
:::

| 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](https://aerospike.com/docs/database/tools/backup-and-restore/absctl/backup/use/#use-compression-and-encryption-during-backup). |
| `-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](https://aerospike.com/docs/database/tools/backup-and-restore/absctl/backup/use/#use-compression-and-encryption-during-backup). |
| `--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`:

Terminal window

```shell
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:

Terminal window

```shell
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:

```text
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](https://aerospike.com/docs/database/reference/metrics#namespace__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`. |

::: note
The `--no-generation` option may cause you to lose a more recent version of your data by overwriting it with an older version.
:::

### 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:

1.  If the record from the backup is expired, based on its TTL value, the backup record is ignored.
2.  If the record does not exist in the namespace, the backup record is added to the namespace.
3.  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.

4.  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.

5.  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.