--- title: "Configure Aerospike Backup Service" description: "What each Aerospike Backup Service (ABS) configuration section is for, including how the process listens and logs, with working YAML for local, S3, GCS, Azure, Secret Agent, TLS, retention, and compact backups." --- # Configure Aerospike Backup Service > For the complete documentation index see: [llms.txt](https://aerospike.com/docs/llms.txt) > > All documentation pages available in markdown. ## What this is This page is the configuration guide for Aerospike Backup Service (ABS): what each section of the YAML file does, with copy-paste examples. For what these objects are and how a backup behaves once it runs, read [Concepts](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/concepts) first. An ABS configuration file has two layers: - _How ABS runs_: the [`service`](#service) section. Listen address, HTTP and HTTPS, timeouts, optional rate limiting, logging, schedule timezone, and the timestamp format used in backup storage paths. - _What ABS backs up_: named entries under `aerospike-clusters`, `storage`, `backup-policies`, and `backup-routines`, plus optional `secret-agents`. A routine ties a cluster, a storage destination, and a policy to a schedule. Restore is not a YAML routine. Restore requests reuse named clusters and storage; each request carries its own policy. See [Restore data](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/restore). Names must match exactly: a routine’s `source-cluster`, `storage`, and `backup-policy` are strings that point at keys in the other maps. A typo here is the most common reason a routine never starts. For every field and its default, see the [ABS configuration reference](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/config). Aerospike publishes a [JSON schema for this configuration file](https://raw.githubusercontent.com/aerospike/aerospike-backup-service/refs/tags/v3.7.0/docs/config.schema.json) that enables autocomplete and validation in the VSCode and IntelliJ editors. ## Applies to - Product: Aerospike Backup Service (ABS) 3.7.x. - Audience: operators who write or maintain the ABS configuration file. - Prerequisites: ABS is installed. See [Install Aerospike Backup Service](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/install). - Outcome: `POST /v1/config/apply` returns `200`, and `GET /v1/config/routines` lists your routines. --- ## Full configuration template Use this template as a reference. It wires together HTTP and HTTPS, cluster TLS, Secret Agent, encrypted compressed backups, and one scheduled routine. Omit keys you do not need; ABS applies the defaults in the [configuration reference](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/config). Later sections show other storage backends, filter expressions, and rack or partition slices. View full configuration file ```yaml # yaml-language-server: $schema=https://raw.githubusercontent.com/aerospike/aerospike-backup-service/refs/tags/v3.7.0/docs/config.schema.json service: http: address: 0.0.0.0 port: 8080 context-path: / timeout: 5000 read-timeout: 30000 write-timeout: 60000 idle-timeout: 120000 rate: tps: 1024 size: 1024 white-list: - 10.0.0.0/8 # disabled: true # Set with https when you want TLS-only https: address: 0.0.0.0 port: 8443 cert-file: /etc/aerospike-backup-service/tls/tls.crt key-file: /etc/aerospike-backup-service/tls/tls.key # key-file-password: secrets:abs-tls:key-passphrase # If the key is encrypted min-version: "1.2" client-auth: none # none | request | require-and-verify # client-ca-file: /etc/aerospike-backup-service/tls/clients-ca.pem # For mutual TLS # crl-file: /etc/aerospike-backup-service/tls/clients.crl # Requires require-and-verify logger: level: INFO format: PLAIN stdout-writer: true file-writer: filename: /var/log/aerospike-backup-service/aerospike-backup-service.log maxsize: 100 maxage: 7 maxbackups: 3 compress: false backup: timestamp-format: ISO schedule-timezone: UTC # UTC | Local | IANA name such as America/New_York aerospike-clusters: abs-cluster: # <--- Custom user-defined cluster name seed-nodes: - host-name: asd.example.com port: 4333 tls-name: asd.example.com credentials: user: backup-user password: secrets:cluster-creds:password # Secret Agent path secret-agent-name: secret-agent # <--- Refers to the secret agent name under secret-agents auth-mode: INTERNAL tls: name: asd.example.com ca-file: /etc/ssl/certs/ca.pem cert-file: /etc/ssl/certs/client.pem key-file: /etc/ssl/private/client.key prefer-racks: [100, 101] max-parallel-scans: 8 secret-agents: secret-agent: # <--- Custom user-defined secret agent name address: secret-agent.example.com port: 3005 connection-type: TCP ca-file: /etc/ssl/certs/ca.pem cert-file: /etc/ssl/certs/client-cert.pem # Mutual TLS to Secret Agent key-file: /etc/ssl/private/client-key.pem name: secret-agent.example.com # SNI; required with client certs storage: s3: # <--- Custom user-defined storage name s3-storage: # Storage type; can be one of "local-storage", "s3-storage", "azure-storage", "gcp-storage" path: backups bucket: as-backup-bucket s3-region: eu-central-1 min-part-size: 52_428_800 # Minimum upload chunk size in bytes access-key-id: secrets:s3-creds:access-key-id secret-access-key: secrets:s3-creds:secret-access-key secret-agent-name: secret-agent backup-policies: dailyBackupPolicy: # <--- Custom user-defined policy name parallel: 8 # Parallelism level (May affect performance) parallel-write: 8 # Write parallelism level (May affect performance) file-limit: 1000 # Max backup file size in MB (May affect performance) compression: # Backup files will be compressed before uploading (May affect performance) mode: ZSTD level: 3 compact: false # Skip Base64 encoding for BLOB types when true concurrent-incremental: false # Allow incremental backups to run concurrently with-cluster-configuration: false # Include cluster configuration in the backup when true incr-mode: differential # differential (default) or cumulative encryption: mode: AES256 key-file: /etc/aerospike-backup-service/secrets/backup.key retention: full: 10 # Retain 10 full backups incremental: 5 # Retain incremental backups for the 5 latest full backups backup-routines: dailyLocalBackupRoutine: # <--- Custom routine name interval-cron: "@daily" # Full backup will be triggered daily at midnight incr-interval-cron: "0 0 0/2 * * ? *" # Incremental backups every 2 hours # schedule-timezone: America/New_York # Optional override of service.backup.schedule-timezone source-cluster: abs-cluster # <--- Refers to the cluster name under aerospike-clusters storage: s3 # <--- Refers to the storage name under storage backup-policy: dailyBackupPolicy # <--- Refers to the policy name under backup-policies namespaces: ["test"] # <--- Required field; use [] to back up the whole cluster # set-list: ["app"] # Optional; omit or [] to include all sets # bin-list: ["name", "email"] # Optional; omit or [] to include all bins # filter-exp: "kwOTUQKjYWdlGQ==" # Optional Base64 filter; mutually exclusive with multi-set set-list ``` --- ## Configuration sections ### `service` The `service` section configures how the ABS process runs. It does not define backup jobs. ```yaml service: http: address: 0.0.0.0 port: 8080 context-path: / timeout: 5000 read-timeout: 30000 write-timeout: 60000 idle-timeout: 120000 rate: tps: 1024 size: 1024 white-list: - 10.0.0.0/8 https: port: 8443 cert-file: /etc/aerospike-backup-service/tls/tls.crt key-file: /etc/aerospike-backup-service/tls/tls.key logger: level: INFO format: PLAIN stdout-writer: true file-writer: filename: /var/log/aerospike-backup-service/aerospike-backup-service.log maxsize: 100 maxage: 7 maxbackups: 3 compress: false backup: timestamp-format: ISO schedule-timezone: UTC ``` Omit keys you do not need to change. ABS applies the defaults in the [configuration reference](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/config). ::: note The REST API does not authenticate callers. HTTPS (`service.https`) encrypts the listen port; it is not user authentication. You can still put an authenticating proxy or service mesh in front of ABS. See [Secure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/secure). ::: #### HTTP server `service.http` binds the REST API, `/metrics`, `/health`, and `/ready` on plaintext HTTP. | Field | Purpose | | --- | --- | | `address` | Bind address. Default `0.0.0.0`. | | `port` | Listen port. Default `8080`. | | `context-path` | Prefix for API paths when ABS sits behind a reverse proxy. Must start with `/`. Default `/`. | | `disabled` | Set `true` to turn this listener off. Default `false`. At least one of HTTP or HTTPS must stay enabled. | | `timeout` | Maximum time in milliseconds to read HTTP request headers. Default `5000`. | | `read-timeout` | Maximum time in milliseconds to read the entire request, including the body. Default `30000`. | | `write-timeout` | Maximum time in milliseconds to write the response. Default `60000`. | | `idle-timeout` | Maximum time in milliseconds to wait for the next request when keep-alives are enabled. Default `120000`. | `service.http.rate` is a token-bucket limiter. It is **not** API authentication: - Rate limiting applies to all clients by default (empty `white-list`). - Entries in `white-list` are CIDRs or IP addresses that are exempt. - Only `white-list: ["0.0.0.0/0"]` (that exact CIDR) exempts every client and disables limiting. A value such as `0.0.0.0` without `/0` is not a full exemption. Restrict who can reach `address` and `port`. See [Secure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/secure). #### HTTPS server Omit `service.https` to keep HTTP-only behavior. When present, ABS also listens with TLS. Default port is `8443`. HTTP and HTTPS may run together; their ports must differ. Set `service.http.disabled: true` for TLS-only. ```yaml service: http: disabled: true https: address: 0.0.0.0 port: 8443 cert-file: /etc/aerospike-backup-service/tls/tls.crt key-file: /etc/aerospike-backup-service/tls/tls.key min-version: "1.2" client-auth: require-and-verify client-ca-file: /etc/aerospike-backup-service/tls/clients-ca.pem crl-file: /etc/aerospike-backup-service/tls/clients.crl ``` | Field | Purpose | | --- | --- | | `cert-file`, `key-file` | PEM server certificate and private key. Required when HTTPS is enabled. | | `key-file-password` | Passphrase for an encrypted key. Literal, or a Secret Agent path. | | `min-version` | Minimum TLS protocol. `1.2` (default) or `1.3`. | | `cipher-suites` | Allowed cipher suite names. Empty uses Go’s secure defaults. | | `client-auth` | `none` (default), `request`, or `require-and-verify`. | | `client-ca-file` | Trusted client CA bundle for mutual TLS. Required when `client-auth` is not `none`. | | `crl-file` | One DER-encoded CRL, or one or more PEM-encoded CRLs, for client certificates. Requires `client-ca-file` and `client-auth: require-and-verify`. A missing matching CRL, or an expired or future-dated CRL, rejects the handshake. OCSP is not supported. | | `disabled` | Set `true` to skip the HTTPS listener. Placeholder cert paths are not probed when the listener is disabled. | | Timeouts and `rate` | Same fields and defaults as `service.http`. | Rewrite `cert-file`, `key-file`, `client-ca-file`, and `crl-file` **at the same paths** to rotate material without a restart. Changing the path values requires a restart. See [Secure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/secure#https-listener). #### Logging `service.logger` controls process logs. | Field | Purpose | | --- | --- | | `level` | `TRACE`, `DEBUG`, `INFO`, `WARN` (or `WARNING`), or `ERROR`. Default `INFO`. | | `format` | `PLAIN` or `JSON`. Default `PLAIN`. | | `stdout-writer` | Write logs to standard output. Default `true`. | | `file-writer.filename` | Log file path. Required if you set `file-writer`. | | `file-writer.maxsize` | Rotate when the file reaches this size in megabytes. Default `100`. | | `file-writer.maxage` | Days to keep rotated files. Default `0` (do not remove old log files based on age). | | `file-writer.maxbackups` | Number of rotated files to keep. Default `0` (retain all rotated log files). | | `file-writer.compress` | Gzip rotated files. Default `false`. | On Linux packages, systemd already captures stdout. Use `journalctl -u aerospike-backup-service` unless you also want a file. In Docker, use `docker logs`. Set `DEBUG` or `TRACE` only while you troubleshoot; both are noisy. #### Backup path timestamps `service.backup.timestamp-format` chooses the human-readable date in backup **storage paths**. It does not change the `.asb` payload. Folder names and this suffix stay UTC even when [`schedule-timezone`](#quartz-schedules) is not UTC. | Value | Path suffix example | | --- | --- | | (omit) | Unix milliseconds only, for example `1714521600000` | | `ISO` | `1714521600000_2006-01-02T15-04-05` | | `EU` | `1714521600000_02-Jan-2006-15-04-05` | | `US` | `1714521600000_Jan-02-2006-15-04-05` | `service.backup.schedule-timezone` is the default timezone for cron evaluation. See [Quartz schedules](#quartz-schedules). Changing this service-level default requires a process restart. --- ### `aerospike-clusters` This section defines how ABS connects to your Aerospike Database cluster(s). ```yaml aerospike-clusters: abs-cluster: # <--- Custom user-defined cluster name seed-nodes: - host-name: localhost port: 3000 credentials: user: tester password: secrets:cluster-creds:password # Secret Agent path secret-agent-name: secret-agent # <--- Refers to the Secret Agent name under secret-agents prefer-racks: [100, 101] ``` The `seed-nodes` parameter defines the host and port for the Aerospike cluster on the network. The `credentials` parameter passes a plaintext username and a reference to a password stored in the Secret Agent. You can also use a plaintext username and password without the Secret Agent reference for testing purposes. If a credential value starts with `secrets:`, ABS treats it as a Secret Agent reference in the format `secrets:RESOURCE_LABEL:KEY`. For path syntax examples, see [Secret usage with backup and restore](https://aerospike.com/docs/database/tools/backup-and-restore/absctl/secrets). Configure Secret Agent connections for ABS in the [`secret-agents`](#secret-agents) section. ::: note ABS does not support directly passing a Kubernetes Secret. ::: ::: database privileges The database user configured under `credentials` must have the appropriate RBAC roles assigned on the Aerospike cluster. For a list of required privileges for backup and restore operations, see [Privileges](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/concepts#privileges). ::: #### `max-parallel-scans` `max-parallel-scans` sets a per-cluster limit on the number of concurrent primary index (PI) queries across all routines. PI queries were historically called scans, which is where the parameter name comes from. ```yaml aerospike-clusters: abs-cluster: max-parallel-scans: 4 ``` #### `prefer-racks` Set `prefer-racks` on a cluster for routines that do not set `rack-list`, `node-list`, or `partition-list`. `prefer-racks` only affects which replica is read for each partition. ABS prefers nodes in `prefer-racks[0]` first, then `prefer-racks[1]`, and so on, but reads from other racks when a replica is not available on a preferred rack. Each backup is complete and independently restorable. This setting is mutually exclusive with `rack-list`, `node-list`, and `partition-list` on any routine that uses this cluster. Use `prefer-racks` on a single ABS deployment when you want a full backup that prefers local rack reads and reduces cross-datacenter traffic. For parallel backup sliced by rack, use `rack-list` on separate routines. See [Rack-aware backup: prefer-racks vs rack-list](#rack-aware-backup-prefer-racks-vs-rack-list). #### Cluster TLS Use `tls` when the Database cluster requires TLS. Seed `tls-name` must match the node TLS name. ```yaml aerospike-clusters: prod: seed-nodes: - host-name: asd.example.com port: 4333 tls-name: asd.example.com credentials: user: backup-user password-path: /etc/aerospike-backup-service/secrets/cluster-password auth-mode: INTERNAL tls: name: asd.example.com ca-file: /etc/ssl/certs/ca.pem cert-file: /etc/ssl/certs/client.pem key-file: /etc/ssl/private/client.key ``` See [Secure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/secure) for PKI authentication and Secret Agent TLS. --- ### `secret-agents` The `secret-agents` section defines one or more connections to the [Aerospike Secret Agent](https://aerospike.com/docs/database/manage/security/secrets#connecting-to-aerospike-secret-agent). ```yaml secret-agents: secret-agent: # <--- Custom user-defined secret agent name address: localhost port: 3005 connection-type: TCP ``` A value that starts with `secrets:` is validated when ABS loads or applies configuration. A malformed reference, or a `secrets:` value without a Secret Agent, fails at that moment rather than when a backup starts. `connection-type` accepts `TCP` or `UNIX` (case-insensitive; examples use the canonical uppercase form). To configure TLS, use `ca-file` alone for server verification, or add `cert-file`, `key-file`, and `name` together for mutual TLS authentication: ```yaml secret-agents: secure-agent: address: secret-agent.example.com port: 3005 connection-type: TCP ca-file: /etc/ssl/certs/ca.pem # CA certificate to verify the server cert-file: /etc/ssl/certs/client-cert.pem # Client certificate for mutual TLS key-file: /etc/ssl/private/client-key.pem # Client private key for mutual TLS name: secret-agent.example.com # Required for mutual TLS (SNI) ``` --- ### `storage` The `storage` section sets up storage destinations. ABS supports local file system, Amazon S3, Google Cloud Storage, and Azure Blob Storage. Local `path` values must be clean: no `..` segments and no `./` prefix. A value such as `./localStorage` fails validation. Use `localStorage` or an absolute path instead. Object-storage `path` values are relative to the bucket or container. When ABS runs from the Linux `.deb` or `.rpm` package, its systemd sandbox makes most of the file system read-only. Keep local backups under `/var/lib/aerospike-backup-service`. To use another local path, such as `/local/backups` in the following example, add it to `ReadWritePaths` in a systemd drop-in and make the `aerospike-backup-service` account its owner. See [Breaking changes in ABS 3.7.0](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/upgrade#breaking-changes-in-abs-370). ```yaml storage: # Example 1: Local Storage storage1: local-storage: path: /local/backups # Clean path: no ".." and no "./" prefix # Example 2: S3 Storage storage2: s3-storage: bucket: my-backup-bucket path: backups s3-profile: default s3-region: eu-central-1 min-part-size: 52_428_800 # Minimum upload chunk size in bytes # Example 3: Azure Storage storage3: azure-storage: account-name: my-storage-account account-key: my-secret-key container-name: my-container endpoint: 'https://my-storage-account.blob.core.windows.net' path: backups # Example 4: GCP Storage storage4: gcp-storage: bucket-name: my-gcp-bucket key-file-path: /path/to/service-account-key.json endpoint: 'https://storage.googleapis.com' path: backups ``` You can set an object storage class on S3, Azure, and GCP destinations. Use `storage-class.data` (and `storage-class.metadata` for S3 and Azure) to choose the durability and availability tier. `storage-class.metadata` supports fewer values than `storage-class.data` because ABS needs fast retrieval for metadata objects. Supported values depend on the provider and field: - S3 `data`: `STANDARD`, `GLACIER`, `STANDARD_IA`, `ONEZONE_IA`, `INTELLIGENT_TIERING`, `DEEP_ARCHIVE`, `OUTPOSTS`, `GLACIER_IR`, `SNOW`, `EXPRESS_ONEZONE` - S3 `metadata`: `STANDARD`, `STANDARD_IA`, `INTELLIGENT_TIERING`, `EXPRESS_ONEZONE`, `ONEZONE_IA`, `OUTPOSTS` - Azure Blob Storage `data`: `Hot`, `Cool`, `Cold`, `Archive` - Azure Blob Storage `metadata`: `Hot`, `Cool`, `Cold` - Google Cloud Storage `data`: `STANDARD`, `NEARLINE`, `COLDLINE`, `ARCHIVE` (GCP has no `metadata` class; ABS always stores GCP metadata as `STANDARD`) ```yaml storage: s3-tiered: s3-storage: bucket: my-backup-bucket path: backups s3-region: eu-central-1 storage-class: data: STANDARD metadata: STANDARD ``` --- ### `backup-policies` A backup policy is a set of parameters that define how to perform a backup. ```yaml backup-policies: dailyBackupPolicy: # <--- Custom user-defined policy name parallel: 8 # Parallelism level (May affect performance) parallel-write: 8 # Write parallelism level (May affect performance) file-limit: 1000 # Max backup file size in MB (May affect performance) compression: # Backup files will be compressed before uploading (May affect performance) mode: ZSTD level: 3 compact: false # Skip Base64 encoding for BLOB types when true concurrent-incremental: false # Allow incremental backups to run concurrently with-cluster-configuration: false # Include cluster configuration in the backup when true incr-mode: differential # differential (default) or cumulative encryption: mode: AES256 key-file: /etc/aerospike-backup-service/secrets/backup.key retention: full: 10 # Retain 10 full backups incremental: 5 # Retain incremental backups for the 5 latest full backups ``` - `parallel`: Specifies the number of parallel reader threads that read Aerospike partitions. - `parallel-write`: Specifies writer threads that encode and upload backup files. If you omit `parallel-write`, ABS uses the `parallel` value for writers as well. - `file-limit`: Specifies the size of each backup file in MB. - `compression`: Specifies a compression algorithm and compression level. - `compact`: Set to `true` to skip Base64 encoding for BLOB types (Bytes, HLL, RawMap, RawList), which produces smaller backup files. See [Performance tuning](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/performance-tuning#compact). - `concurrent-incremental`: Set to `true` to allow incremental backups to run while another backup for the same routine is active. Defaults to `false`. See [Schedule overlap](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/concepts#schedule-overlap). - `with-cluster-configuration`: Set to `true` to include cluster configuration in the backup. Defaults to `false`. - `incr-mode`: `differential` (default) copies records changed since the last successful backup. `cumulative` copies records changed since the last successful full backup. See [Full and incremental backups](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/concepts#full-and-incremental-backups). - `retention`: Specifies that the previous `full` backups are retained in storage, in addition to any incremental backups made during the last `incremental` full backups. ABS 3.4 introduced two optional query controls: `max-concurrent-nodes` limits how many nodes ABS queries at once, and `use-scan-compression` compresses records on the wire between Aerospike Database and ABS (Aerospike Database Enterprise Edition only). Omit these fields to query every node in parallel without compression. --- ### `backup-routines` The `backup-routines` section schedules one or more routines to run from specified sources at specified intervals. ```yaml backup-routines: dailyLocalBackupRoutine: # <--- Custom routine name interval-cron: "@daily" # Full backup will be triggered daily at midnight incr-interval-cron: "0 0 0/2 * * ? *" # Incremental backups every 2 hours source-cluster: abs-cluster # <--- Refers to the cluster name under aerospike-clusters storage: s3 # <--- Refers to the storage name under storage backup-policy: dailyBackupPolicy # <--- Refers to the policy name under backup-policies namespaces: ["test"] # <--- Required field; use [] to back up the whole cluster set-list: ["app"] # Optional; omit or [] to include all sets bin-list: ["name", "email"] # Optional; omit or [] to include all bins ``` List fields such as `namespaces`, `set-list`, `bin-list`, and `node-list` must not contain duplicate values or empty strings. An empty list (`[]`) is valid when the field is optional. #### `filter-exp` Set `filter-exp` to a Base64-encoded Aerospike filter expression so the backup includes only matching records. The field is mutually exclusive with a multi-set `set-list` (one set, or all sets). How to generate the string is in [Filter records with an expression](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/backup#filter-records-with-an-expression). ```yaml backup-routines: adultsBackup: interval-cron: "@daily" source-cluster: abs-cluster storage: s3 backup-policy: dailyBackupPolicy namespaces: ["test"] set-list: ["users"] filter-exp: "kwOTUQKjYWdlGQ==" # age > 25 ``` #### `node-list` Set `node-list` on a routine to back up partitions whose master is on one of the listed nodes when the job starts. Each node can be an IP address and port, a hostname and port, or a node ID. See [`node-list`](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/config#backup-routines.ROUTINE_NAME.node-list) in the configuration reference. Each routine with `node-list` is potentially partial: assign non-overlapping node slices across parallel ABS instances so together they cover every partition you intend to back up. See [Parallel backups](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/parallel-backup). `node-list` is mutually exclusive with `partition-list`, `rack-list`, and the cluster’s `prefer-racks` setting. If partition ownership changes during a long backup, queries can read from the current master outside the listed node, and partitions whose masters migrate onto a listed node after the job starts are not included in that routine’s backup. See the topology note under `rack-list`. #### `rack-list` Set `rack-list` on a routine to back up partitions whose master is on a node in one of the listed racks when the job starts. Rack IDs are integers, such as `rack-list: [1]` or `rack-list: [1, 2]`. A single routine can list multiple rack IDs. ABS backs up the union of primary partitions whose masters are on nodes in any listed rack. For parallel deployment, assign one rack ID per routine so non-overlapping slices together cover the namespace. Each routine with `rack-list` is potentially partial. In a cluster with N racks and evenly distributed masters, one routine per rack often backs up about 1/N of the namespace. In namespaces with [active rack](https://aerospike.com/docs/database/manage/namespace/rack-aware#designate-an-active-rack) enabled, all masters sit on the active rack; routines that target other racks may back up few or no partitions. Parallel backup by rack assumes masters are spread across racks. With active rack, use a single full backup with `prefer-racks`, or slice by `node-list` or `partition-list` instead. Run one routine per rack (on separate ABS instances or schedules) and restore all slices to recover the full data set. See [Parallel backups](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/parallel-backup). `rack-list` is mutually exclusive with `node-list`, `partition-list`, and the cluster’s `prefer-racks` setting. :::caution Topology changes during backup When the job starts, ABS resolves primary (master) partitions for nodes in the listed racks and queries that fixed partition set. If partition ownership changes during a long backup, queries can read from the current master for a selected partition, which may be on a different rack than when the job started. Plan capacity and cross-zone traffic accordingly. If a partition’s master migrates onto a listed rack after the job starts, that partition was not in the initial slice and is not included in that routine’s backup.::: ```yaml backup-routines: rack1Backup: interval-cron: "@daily" source-cluster: abs-cluster storage: s3 backup-policy: dailyBackupPolicy namespaces: ["test"] rack-list: [1] rack2Backup: interval-cron: "@daily" source-cluster: abs-cluster storage: s3 backup-policy: dailyBackupPolicy namespaces: ["test"] rack-list: [2] ``` #### `partition-list` Set `partition-list` on a routine to back up a fixed range of partitions (out of 4096 total). Use the format `"start-count"`, where the first number is the partition index to start at, and the second number is the number of partitions to include. `partition-list` is mutually exclusive with `node-list`, `rack-list`, and the cluster’s `prefer-racks` setting. See [Parallel backups](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/parallel-backup) for more details. ```yaml backup-routines: firstHalfBackup: interval-cron: "@daily" source-cluster: abs-cluster storage: s3 backup-policy: dailyBackupPolicy namespaces: ["test"] partition-list: "0-2048" ``` --- ## Quartz schedules `interval-cron` (full backup) and `incr-interval-cron` (incremental) use [Quartz cron](https://github.com/reugn/go-quartz?tab=readme-ov-file#cron-expression-format) with **six or seven fields**: second, minute, hour, day of month, month, day of week, and optional year. Cron expressions are evaluated in **UTC** unless you set `schedule-timezone`. Accepted values: | Value | Meaning | | --- | --- | | omitted or `UTC` | Coordinated Universal Time (default). Existing configurations are unchanged. | | `Local` | Timezone of the host (`TZ` or `/etc/localtime`). | | IANA name, for example `America/New_York` | Named zone. Useful in containers that themselves run UTC. The ABS binary embeds IANA timezone data, so named zones resolve without system tzdata. | `UTC` and `Local` are case-insensitive. IANA names are case-sensitive. Abbreviations such as `EST` resolve to fixed-offset zones without daylight saving, and POSIX `TZ` strings such as `EST5EDT` follow their embedded rules. Prefer canonical `Area/Location` names such as `America/New_York`. Set a service-wide default under `service.backup` (requires a process restart) or override it on a routine (can be applied through the routine API without restarting ABS): ```yaml service: backup: schedule-timezone: America/New_York backup-routines: nightly: interval-cron: "0 0 2 * * ? *" # 02:00 in America/New_York (inherits the service default) source-cluster: abs-cluster storage: s3 backup-policy: dailyBackupPolicy namespaces: ["test"] utc-maintenance: interval-cron: "0 0 2 * * ? *" # 02:00 UTC schedule-timezone: UTC # optional per-routine override source-cluster: abs-cluster-global storage: s3 backup-policy: dailyBackupPolicy namespaces: ["test"] ``` Backup folder names and the optional `timestamp-format` suffix stay UTC regardless of `schedule-timezone`. Restore `time` is Unix milliseconds and is not reinterpreted. :::caution Daylight saving For `Local` and IANA zones, a daily 02:30 schedule does not fire on the spring-forward day when 02:30 does not exist locally. Daily schedules in the repeated fall-back hour fire once. Use UTC when you need even spacing between runs. ::: You can also use `@hourly`, `@daily`, `@weekly`, `@monthly`, and `@yearly`. | Expression | Meaning | | --- | --- | | `@hourly` | Every hour on the hour | | `@daily` | Every day at 00:00 in the schedule timezone (UTC if you omit `schedule-timezone`) | | `@weekly` | Every Sunday at 00:00 in the schedule timezone | | `@monthly` | First day of each month at 00:00 in the schedule timezone | | `@yearly` | January 1 at 00:00 in the schedule timezone | | `0 0 0/2 * * ? *` | Every two hours on the hour | | `0 0 2 * * ? *` | Daily at 02:00 in the schedule timezone | | `0 0 * * * ? *` | Every hour (equivalent to `@hourly`) | ::: caution A five-field Unix crontab string is not valid. Do not copy `0 */2 * * *` from Linux cron into ABS. ::: --- ## Rack-aware backup: prefer-racks vs rack-list In a namespace that uses rack awareness, each partition has one master copy on a single node. Other nodes may hold replica copies of the same partition. ABS uses your settings to decide which copy to read: - `prefer-racks`: Back up every partition in the namespace. For each partition, read from a replica on a preferred rack when one exists; otherwise read from another rack. - `rack-list` or `node-list`: Back up partitions whose master is on the listed racks or nodes when the job starts. Each routine covers a slice of the namespace; restore all slices for a full data set. See [Rack awareness](https://aerospike.com/docs/database/manage/namespace/rack-aware) for more information on masters, replicas, and racks. | Goal | Use | Do not use | | --- | --- | --- | | Full backup with preferred local rack reads | `prefer-racks` on the cluster (single routine) | `prefer-racks` on N parallel ABS instances | | Parallel backup sliced by rack | `rack-list` per routine (N routines) | `prefer-racks` per ABS instance | | Parallel backup sliced by host | `node-list` per routine | `prefer-racks` on the cluster | ::: caution Running one ABS instance per rack, each with `prefer-racks: [N]`, creates N independent full backups of the entire namespace. Restoring every slice together runs overlapping full restores and can make progress metrics misleading. Use `rack-list` per routine when you need non-overlapping shards. ::: For CLI equivalents, see [`absctl backup`](https://aerospike.com/docs/database/tools/backup-and-restore/absctl/backup/use#back-up-by-rack) (`--prefer-racks` vs `--rack-list`). --- ## How to apply configuration After you edit the configuration file, tell ABS to load it. Changes made through the configuration API (`PUT`/`POST` under `/v1/config/...`) apply immediately. Terminal window ```shell curl -X POST "$BASE_URL/v1/config/apply" ``` You can change clusters, storage, policies, and routines without restarting the process. Changes to the `service` section (HTTP and HTTPS listeners, logging, and `service.backup`) require a restart. If the file’s `service` section differs from the running configuration, `POST /v1/config/apply` returns `400`. Jobs that are already running keep the configuration they started with. New jobs and future cron triggers use the applied configuration. Restarting the process also reloads the file. When a routine’s schedule or filters change, ABS unschedules and reschedules that routine’s Quartz jobs. Backup history for affected routines is resynchronized from storage in the background. Deleted routines are unscheduled. For where ABS reads its configuration from, see [Configuration sources and reload](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/architecture#configuration-sources-and-reload). The HTTP API is not authenticated. Restrict who can reach the listen address. See [Secure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/secure). You can also change clusters, storage, policies, and routines through the configuration API (`PUT`/`POST` under `/v1/config/...`). For most production use, keep the YAML file in version control and apply it. See [API usage examples](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/api-examples). --- ## Complete production examples ### S3-compatible (MinIO) example The following sample consists of four sections: - `aerospike-clusters` defines how ABS reaches Aerospike Database, naming that cluster `absCluster1`. In Docker Compose, the hostname is the Aerospike container name `aerospike-cluster`. - `storage` defines a destination named `minioStorage` that uses `s3-endpoint-override` to send backup data to MinIO instead of Amazon S3. - `backup-policies` defines `keepFilesPolicy` with a single reader thread and retention. - `backup-routines` defines `minioKeepFilesRoutine`, which runs a full backup daily and an incremental backup hourly against the `test` namespace. ::: note Backup policies are defined in the configuration file. Restore policies are not defined beforehand; they are sent in the body of each restore request. ::: ```yaml service: http: address: 0.0.0.0 port: 8080 logger: level: DEBUG file-writer: filename: /var/log/aerospike-backup-service/aerospike-backup-service.log aerospike-clusters: absCluster1: seed-nodes: - host-name: aerospike-cluster port: 3000 credentials: user: admin password: admin storage: minioStorage: s3-storage: path: backups bucket: as-backup-bucket s3-profile: minio s3-region: eu-central-1 s3-endpoint-override: http://minio:9000 backup-policies: keepFilesPolicy: parallel: 1 retry-policy: max-retries: 1 retention: full: 10 incremental: 5 backup-routines: minioKeepFilesRoutine: backup-policy: keepFilesPolicy source-cluster: absCluster1 storage: minioStorage interval-cron: "@hourly" incr-interval-cron: "0 0/5 * * * ?" namespaces: ["test"] ``` ### Linux (local cluster) example For a local test on Linux, this smaller example connects to a namespace called `test` in an Aerospike Database cluster at `127.0.0.1:3000` and writes backups to MinIO on localhost. Change `storage` to `local-storage` if you want files on disk. ```yaml service: http: address: 0.0.0.0 port: 8080 logger: level: DEBUG file-writer: filename: /var/log/aerospike-backup-service/aerospike-backup-service.log aerospike-clusters: absCluster1: seed-nodes: - host-name: localhost port: 3000 credentials: user: tester password: testers storage: minioStorage: s3-storage: path: backups bucket: as-backup-bucket s3-profile: minio s3-region: eu-central-1 s3-endpoint-override: http://localhost:9000 backup-policies: keepFilesPolicy: parallel: 1 retry-policy: max-retries: 1 retention: full: 10 incremental: 5 backup-routines: minioKeepFilesRoutine: backup-policy: keepFilesPolicy source-cluster: absCluster1 storage: minioStorage interval-cron: "@hourly" incr-interval-cron: "0 0/5 * * * ?" namespaces: ["test"] ``` --- ## Next steps - [Back up data](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/backup): apply configuration, trigger jobs, pause a routine - [Restore data](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/restore) - [Secure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/secure) - [ABS configuration reference](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/config) - [API usage examples](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/api-examples)