Configure Aerospike Backup Service

For the complete documentation index see: 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 first.

An ABS configuration file has two layers:

How ABS runs: the 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.

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.

Aerospike publishes a JSON schema for this configuration file 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.
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. Later sections show other storage backends, filter expressions, and rack or partition slices.

View full configuration file

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

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.

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

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.

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 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. Changing this service-level default requires a process restart.

`aerospike-clusters`

This section defines how ABS connects to your Aerospike Database cluster(s).

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. Configure Secret Agent connections for ABS in the secret-agents section.

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

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.

Cluster TLS

Use tls when the Database cluster requires TLS. Seed tls-name must match the node TLS name.

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 for PKI authentication and Secret Agent TLS.

`secret-agents`

The secret-agents section defines one or more connections to the Aerospike Secret Agent.

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:

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.

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)

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.

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

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.

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

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

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

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 for more details.

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

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

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

For CLI equivalents, see absctl backup (--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.

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.

The HTTP API is not authenticated. Restrict who can reach the listen address. See Secure ABS.

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.

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.

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.

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: apply configuration, trigger jobs, pause a routine
Restore data
Secure ABS
ABS configuration reference
API usage examples