Skip to content

Aerospike Backup Service 3.7.0 release notes

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

September 29, 2026  |  Download

New in this version

Aerospike Backup Service (ABS) 3.7.0 is built on backup-go v0.12.0. It adds an optional HTTPS listener for the REST API, redacts secrets in configuration responses and logs, and runs the Linux packages as an unprivileged service account. It also adds cumulative incremental backups, cron schedule timezones, filter expressions on routines, and set index backup.

This release has breaking changes for the configuration API, configuration validation, and Linux package installations. See Upgrade ABS for a checklist before you replace ABS 3.6.2 and earlier.

Breaking changes

Configuration API

  • Configuration API GET endpoints (/v1/config and related read paths) no longer return literal secret values. Literal passwords, keys, and similar fields are replaced with the sentinel "[secret]". Secret Agent references (secrets:...) are returned as-is. [BKRS-333]

  • PUT requests that round-trip a GET response must leave unchanged secret fields as "[secret]". ABS treats that sentinel as “keep the stored value.” Sending "[secret]" for a newly added entity that has no stored secret is invalid. See API secrets. [BKRS-269, BKRS-393]

  • Endpoints that change configuration return a status code that describes the outcome, instead of 400 Bad Request for every error. This applies to POST, PUT, and DELETE under /v1/config/routines, /v1/config/storage, /v1/config/clusters, and /v1/config/policies, and to the routine enable and disable endpoints. [BKRS-439]

    • A routine, storage destination, cluster, or policy that does not exist returns 404 Not Found. The response body matches the GET response, such as routine "daily" not found.
    • A name that is already taken, or an entity that a backup routine still references when you delete it, returns 409 Conflict.
    • A malformed body, failed validation, or unreachable TLS endpoint still returns 400 Bad Request.

    Clients that branch on 400, or that match response text to tell a missing entity from a bad payload, must branch on the status code instead.

Configuration validation

  • Configuration paths must be canonical. ABS validates local, S3, GCP, and Azure storage paths, restore backup-data-path, password paths, TLS and HTTPS files, encryption-key files, GCP key files, Secret Agent TLS files, and log file paths. Paths that contain .., start with ~, contain redundant separators, end with /, or use a non-canonical prefix such as ./ fail validation. Relative storage paths must stay under their storage root. [BKRS-271, BKRS-338, BKRS-390]
  • Names of routines, storage destinations, clusters, policies, and Secret Agents must be usable as a single path segment. A name cannot be . or .., contain /, \, or a NUL byte, start with ~, or start or end with whitespace. Namespace names in routines and restore requests must follow Aerospike naming rules: at most 31 bytes of Latin letters, digits, _, -, and $, and not the reserved name null. [BKRS-414]
  • A compression or encryption block in a backup policy or restore request must set mode. For compression, ZSTD requires level (-1 to 22), and NONE must not set level. To turn off compression or encryption, set mode: NONE or omit the block. Earlier releases accepted a compression block without mode, and every backup and restore that used it failed at run time. [BKRS-441]
  • Secret Agent references (secrets:...) are validated when the configuration is loaded or applied. A malformed reference, or a reference without a configured Secret Agent, fails the load or apply instead of the first job that needs the secret. [BKRS-287]
  • An empty HTTP rate-limiter white-list applies rate limiting to every client. Disable limiting only with the CIDR 0.0.0.0/0. Prefixes such as 0.0.0.0 without /0 are not treated as a full exemption. [BKRS-272]
  • List fields such as namespaces, set-list, bin-list, node-list, and the rate-limiter white-list reject duplicate values and empty strings. The seed-nodes, prefer-racks, and rack-list fields reject duplicate values. The rate-limiter tps and size values must be positive. [BKRS-313, BKRS-448]

Linux packages

  • The .deb and .rpm packages create the system account aerospike-backup-service and run ABS as that account under a systemd sandbox, instead of as root. Check the following before you upgrade. Most of these fail only when ABS first uses the path or file, not at startup. [BKRS-277]
    • Only /etc/aerospike-backup-service, /var/lib/aerospike-backup-service, and /var/log/aerospike-backup-service are writable. A routine whose local-storage path is anywhere else fails with read-only file system. Add the path to ReadWritePaths in a systemd drop-in, and make the service account its owner.
    • /root and /home are hidden from ABS. Move cloud credentials such as ~/.aws/credentials under /var/lib/aerospike-backup-service, which is the account’s home directory. You can also set them in /etc/default/aerospike-backup-service (Debian) or /etc/sysconfig/aerospike-backup-service (RPM).
    • Cluster and HTTPS TLS files (cert-file, key-file, ca-file, and HTTPS client-ca-file) and password-path files must be readable by the service account. Set them to mode 0600 with owner aerospike-backup-service.
    • A listener on a port below 1024 no longer binds. Grant CAP_NET_BIND_SERVICE with AmbientCapabilities and CapabilityBoundingSet in a drop-in.
  • The packages set the configuration file to mode 0600, owned by aerospike-backup-service, on every install and upgrade. [BKRS-277]
  • The log file moves from /var/log/aerospike-backup-service.log to /var/log/aerospike-backup-service/aerospike-backup-service.log. The package moves an existing log and its rotated files. If you customized the configuration file, update service.logger.file-writer.filename. ABS refuses to start when it cannot write its log file. [BKRS-277]
  • The systemd unit file moves to /usr/lib/systemd/system and is replaced on every upgrade. Put local changes in a drop-in with systemctl edit aerospike-backup-service. The package renames an earlier unit file in /etc/systemd/system to aerospike-backup-service.service.pre-hardening.bak, because that copy would keep ABS running as root. Reapply its changes as a drop-in. [BKRS-277]
  • To downgrade from 3.7.0 to an earlier Debian package, purge the 3.7.0 package first. See Roll back a failed upgrade.
  • RPM only: the upgrade to 3.7.0 leaves the service stopped and disabled, because the earlier package’s removal script still runs. Run systemctl enable --now aerospike-backup-service after this upgrade. Later upgrades are not affected.

Local backup file permissions

  • In every deployment, ABS creates local-storage backup files with mode 0600 and directories with mode 0700, owned by the account ABS runs as. These modes do not follow the umask, so adding another account to the service’s group does not grant access. Tools that read local backups as another user, such as a separate asrestore account or a log shipper, must run as the ABS account or restore through the REST API. Cloud storage is not affected.

Kubernetes

  • The Helm chart disables automounting the service account token and sets a hardened container securityContext (non-root UID 65532, read-only root filesystem, drop all capabilities). Local disk storage and file logs need an extra writable volume. See Install ABS on Kubernetes with Helm. [BKRS-302]

New features

  • Optional service.https listener (default port 8443) with TLS certificate and key, minimum protocol version, cipher suites, and optional mutual TLS (client-auth, client-ca-file). Set crl-file to revoke client certificates with DER or PEM certificate revocation lists (CRLs). crl-file 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. Omit https to keep HTTP-only behavior. You can run HTTP and HTTPS together if the ports differ, and at least one listener must stay enabled. [BKRS-285, BKRS-299, BKRS-314]
  • Rewriting the HTTPS cert-file, key-file, client-ca-file, and crl-file at the same paths reloads TLS material about every 10 seconds without a restart. Changing the configured paths still requires a restart. [BKRS-367, BKRS-376, BKRS-314]
  • TLS key files for the HTTPS listener and for cluster connections can use PKCS#8 encryption, the OpenSSL 3 default, as well as legacy PEM encryption. HTTPS client-ca-file and crl-file files can include the text that openssl x509 -text and openssl crl -text print. [BKRS-426]
  • Backup policy incr-mode: differential (default) copies records changed since the last successful backup, and cumulative copies records changed since the last successful full backup. Restore-by-timestamp with cumulative mode uses the last full backup plus the latest covering incremental. [BKRS-369]
  • Optional schedule-timezone on service.backup and on each routine. Cron expressions default to UTC. Accepted values are UTC, Local, or an IANA name such as America/New_York. Changing service.backup.schedule-timezone requires a restart. Backup folder names and timestamp-format suffixes stay UTC. [BKRS-370, BKRS-388]
  • Routine filter-exp applies a Base64-encoded Aerospike filter expression, so the backup includes only matching records. The field is mutually exclusive with a multi-set set-list. [BKRS-259]
  • Set indexes in a namespace are included in backup and restore together with secondary indexes, unless you set no-indexes. This requires Aerospike Database 8.1.2 and later, which lists set indexes in sindex-list. When a namespace has a set index, ABS writes the backup metadata in .asb format version 3.3, which ABS 3.6.2 and earlier cannot read. [BKRS-334]

Improvements

  • HTTP and HTTPS listeners bound read-timeout (30s), write-timeout (60s), and idle-timeout (120s) in addition to header timeout. Existing configurations that omit the fields pick up the new defaults. [BKRS-297]
  • Each namespace in a routine run is retried on its own, in a separate folder under the run’s timestamp, such as data/NAMESPACE.2 for the second attempt. A failed attempt deletes nothing, and ABS removes the folders of earlier attempts after the namespace completes. To check which namespaces a run contains, use GET /v1/backups/full/ROUTINE_NAME or the run’s metadata.yaml files instead of folder names. [BKRS-405]
  • ABS no longer retries a backup failure that cannot succeed on retry, such as an invalid configuration, corrupt data, a missing resource, or a filter expression that the server rejects. A malformed filter-exp reports a Base64 decoding error. [BKRS-438]
  • A restore that sets policy.namespace is rejected before it starts unless every namespace in the restore matches policy.namespace.source. Earlier releases started the restore and then failed on records from the other namespaces. See Restore to the same namespace or a new namespace. [BKRS-438]
  • ABS no longer caches resolved Secret Agent values across jobs. If Secret Agent is unreachable, new jobs that need a secret fail. [BKRS-292]
  • Literal secrets are redacted in structured logs and error messages. HTTP request bodies are not logged. [BKRS-333, BKRS-266, BKRS-354, BKRS-389, BKRS-398]
  • HTTPS configuration with disabled: true does not probe placeholder certificate paths at startup. Enabling the listener still fails if the files are missing or invalid. [BKRS-377]
  • The HTTP rate limiter tracks each IPv6 client by its /64 prefix and caps the number of tracked clients, so a client that rotates addresses cannot grow the limiter’s memory without bound. [BKRS-417]
  • Restore job IDs are at most 253 - 1, the largest integer that JSON clients such as JavaScript represent exactly. [BKRS-448]
  • When -c names an HTTP or HTTPS URL, fetching the configuration times out after 30 seconds. A second SIGINT or SIGTERM during shutdown stops ABS immediately instead of waiting for the graceful shutdown to finish. [BKRS-424]

Bug fixes

  • Fixed a namespace backup failure that deleted the run folder shared by every namespace in the run. Namespaces that had already completed lost their data, and the run could be reported as successful without them. [BKRS-405]
  • Fixed a routine run that waited until shutdown when a namespace backup could not start, for example because the cluster was unreachable. ABS then skipped later runs of that routine as already in progress and reported no failure. The run now fails immediately. [BKRS-407]
  • Fixed retention with retention.incremental: 0 deleting an incremental backup that was still being written when concurrent-incremental is enabled. Retention now deletes only completed incremental backups. [BKRS-411]
  • Fixed restore by timestamp for backup chains that include backups written by ABS 3.0.x, whose metadata.yaml has no compression setting. [BKRS-456]
  • Fixed cluster TLS connections when key-file-password is a Secret Agent reference. ABS did not resolve the reference before it decrypted the client key, logged the error, and opened the connection without TLS. [BKRS-394]
  • Fixed S3 storage that uses a Secret Agent without a static access-key-id losing its Secret Agent setting when ABS saved and reloaded the configuration. [BKRS-419]
  • Fixed a deadlock between closing and opening Aerospike Database cluster connections. Closing one cluster’s connection no longer waits for another cluster to finish connecting. [BKRS-444]
  • Fixed configuration changes through the API that were only partly applied when the client disconnected during the request. Memory, the configuration file, and the scheduler could then describe different configurations. ABS now finishes applying a change after it passes validation. [BKRS-424]
  • Fixed aerospike_backup_service_last_successful_backup_timestamp being set from two sources. ABS set it from the start time of the run, and again from the backup history it reads from storage. The metric now comes only from the backup history, which ABS refreshes after each successful backup. [BKRS-327]

For additional details about fixes, improvements, and maintenance in this release, see the release page on GitHub.