---
title: "Secure Aerospike Backup Service"
description: "Protect Aerospike Backup Service (ABS) credentials, the HTTPS listener, backup encryption, Secret Agent integration, and Kubernetes defaults."
---

# Secure Aerospike Backup Service

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

Aerospike Backup Service (ABS) stores cluster passwords, cloud keys, and backup encryption keys. Treat the configuration file and the REST API as sensitive.

The REST API does not implement user authentication or authorization. Restrict who can reach the listen ports with network policy, Kubernetes NetworkPolicy, or an authenticating proxy. Optional [`service.https`](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/configure#https-server) encrypts the listen port (and can require client certificates). `service.http.rate` is a request rate limiter, not authentication; an empty `white-list` rate-limits all clients, and only `0.0.0.0/0` disables it.

## Applies to

-   Product: Aerospike Backup Service (ABS) 3.7.x.
-   Audience: operators and security engineers who deploy ABS or manage its credentials, keys, and certificates.
-   Prerequisites: ABS is installed. See [Install Aerospike Backup Service](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/install).
-   Outcome: only trusted clients can reach the ABS listen port, the configuration file holds no plaintext passwords or keys, and `GET /v1/config` returns literal secrets as `"[secret]"`.

## What this page covers

| Topic | When to use it |
| --- | --- |
| [HTTPS listener](#https-listener) | TLS on the ABS listen port, including mutual TLS, CRLs, and certificate rotation |
| [API secrets](#api-secrets) | GET/PUT of configuration that contains passwords or keys |
| [Logs](#logs) | What ABS records and what it redacts |
| Secret Agent | Production passwords and keys that must not sit in plaintext YAML |
| `password-path` | A password file mounted into the ABS host or Pod |
| Cluster TLS | Aerospike Database with TLS or mTLS |
| Backup encryption | `.asb` files encrypted at rest in storage |
| Cloud credentials | S3, GCS, and Azure authentication |
| Rotation | How long ABS keeps using an old secret |
| Helm | Hardened chart defaults and writable volumes |

CLI details for Secret Agent itself are in [Secret usage with backup and restore](https://aerospike.com/docs/database/tools/backup-and-restore/absctl/secrets) and [Aerospike Secret Agent](https://aerospike.com/docs/database/manage/security/secrets/).

## HTTPS listener

Omit `service.https` to keep plaintext HTTP on `service.http.port` (default 8080). To terminate TLS on ABS:

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

You can leave HTTP enabled on a different port while HTTPS is running. At least one listener must stay enabled.

When omitted, `client-auth` defaults to `none`. For mutual TLS, set `client-auth` to `require-and-verify` (or `request`) and `client-ca-file` to a PEM bundle of trusted client CAs.

To revoke client certificates, set `crl-file` as well. `crl-file` requires `client-ca-file` and `client-auth: require-and-verify`. The file is one DER-encoded CRL or one or more PEM-encoded CRLs. Every accepted client certificate must have a matching, authentic, current issuer CRL. A missing matching CRL, or an expired or future-dated CRL, rejects the handshake. OCSP and OCSP stapling are not supported.

```yaml
service:

  https:

    cert-file: /etc/aerospike-backup-service/tls/tls.crt

    key-file: /etc/aerospike-backup-service/tls/tls.key

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

`key-file-password` is a passphrase for an encrypted private key. Supply a literal value or a Secret Agent path (`secrets:RESOURCE_LABEL:KEY`).

When `https.disabled` is `true`, ABS does not probe certificate files at startup, so placeholder paths in a template are valid until you enable the listener.

### Rotate certificates without a restart

Rewrite `cert-file`, `key-file`, `client-ca-file`, and `crl-file` **at the same paths**. ABS polls about every 10 seconds and uses successfully loaded material on new TLS handshakes. In-flight connections are not dropped.

-   Changing the configured path values is a static-field change and requires a restart.
-   An invalid replacement (parse failure, certificate/key mismatch, or unreadable CRL) is ignored. The last good material stays in service.
-   For `client-ca-file`, append the new CA before removing the old one so clients can migrate.
-   TLS session resumption is disabled when `crl-file` is set, so a new CRL cannot be bypassed by a resumed session. Existing connections are not closed when the CRL changes.

Mount certificates from Kubernetes Secrets or cert-manager at stable paths so rotation does not require a configuration change. See [Install ABS on Kubernetes with Helm](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/install#install-abs-on-kubernetes-with-helm).

## API secrets

GET endpoints such as `/v1/config`, `/v1/config/clusters`, and `/v1/config/storage` replace literal secret values with the sentinel `"[secret]"`. Secret Agent references (`secrets:...`) are returned unchanged.

If you use a GET → edit other fields → PUT workflow, leave every unchanged secret field as `"[secret]"`. ABS treats that sentinel as “keep the stored value” and does not overwrite the real secret.

To change a secret, send the new literal value or a new Secret Agent reference. Sending `"[secret]"` for a newly added entity that has no stored secret yet is invalid.

Keep configuration YAML in version control without literals, and prefer `POST /v1/config/apply` after editing the file on disk. See [API usage examples](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/api-examples#read-and-update-configuration).

## Logs

ABS does not log HTTP request bodies or raw configuration dumps. Literal secret values are redacted in structured logs. Use Prometheus metrics and the backup and restore job APIs when you investigate a failure. See [Monitor ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/monitoring).

## Secret Agent

Configure one or more agents under `secret-agents`. Reference an agent from a cluster, storage backend, or routine with `secret-agent-name`, or embed a `secret-agent` block.

A value that starts with `secrets:` is a Secret Agent path: `secrets:RESOURCE_LABEL:KEY`. `RESOURCE_LABEL` is the label you configured in Secret Agent. `KEY` is the secret name inside that resource.

ABS validates `secrets:` references when it loads or applies configuration. A malformed path, or a reference without a Secret Agent, fails then rather than when a backup starts.

```yaml
secret-agents:

  secret-agent:

    address: secret-agent.example.com

    port: 3005

    connection-type: TCP

    ca-file: /etc/ssl/certs/ca.pem

aerospike-clusters:

  prod:

    seed-nodes:

      - host-name: 10.0.1.10

        port: 3000

    credentials:

      user: backup-user

      password: secrets:cluster-creds:password

      secret-agent-name: secret-agent
```

For mutual TLS to Secret Agent, set `cert-file`, `key-file`, and `name` (SNI) together with `ca-file`.

ABS does not read Kubernetes Secrets by name. Mount the Secret as a file and use `password-path`, or put the value in Secret Agent.

Literal passwords in YAML work for tests. Do not use them in production.

## File-based cluster password

```yaml
credentials:

  user: backup-user

  password-path: /etc/aerospike-backup-service/secrets/cluster-password
```

`password` and `password-path` are mutually exclusive.

## Cluster TLS

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

`tls.name` is the TLS name (SNI) ABS uses to verify the server certificate. Seed `tls-name` must match how the Database node is configured. For PKI authentication, set `auth-mode: PKI` and provide client certificates.

## Backup encryption

Set encryption on the **backup policy**. Restore must use the same key.

```yaml
backup-policies:

  daily:

    parallel: 8

    encryption:

      mode: AES256

      key-file: /etc/aerospike-backup-service/secrets/backup.key
```

`mode` is `NONE`, `AES128`, or `AES256`. Supply the key with `key-file`, `key-env`, or `key-secret` (Secret Agent).

Store encryption keys separately from backup objects. Anyone with both the objects and the key can read records.

## Cloud storage credentials

Prefer the cloud SDK default chain (instance role, workload identity, environment) when the ABS host already has it.

For static keys, set them on the storage object. You can use Secret Agent paths for the secret values:

```yaml
storage:

  s3-backups:

    s3-storage:

      bucket: company-as-backups

      path: prod

      s3-region: us-east-1

      access-key-id: secrets:s3-creds:access-key-id

      secret-access-key: secrets:s3-creds:secret-access-key

      secret-agent-name: secret-agent
```

Azure accepts a shared access signature (SAS) in the endpoint URL. Treat that URL as a secret and give the token only the permissions ABS needs, for a short lifetime.

## Credential rotation

ABS keeps resolved credentials only as long as a job needs them. A change does not always apply on the next API call. ABS does not cache Secret Agent values across jobs. If Secret Agent is unreachable, new jobs that need a secret fail. Running jobs keep the values they resolved at start.

| Credential | When the new value is used |
| --- | --- |
| Storage (S3, GCS, Azure) | When ABS refreshes the storage client, up to about 10 minutes |
| Cluster password | When ABS opens a new Database connection after the previous one is idle |
| Encryption key | When a **new** backup job starts. Running jobs keep the old key |
| HTTPS server certificate and key (`service.https` `cert-file` and `key-file`) | Rewrite the files at the same paths. ABS polls about every 10 seconds and serves a successfully loaded pair on new handshakes |
| HTTPS client CA bundle (`service.https` `client-ca-file`) | Rewrite the file at the same path. Append the new CA before removing the old one |
| HTTPS client CRL (`service.https` `crl-file`) | Rewrite the file at the same path. ABS polls about every 10 seconds and applies a successfully parsed DER or PEM CRL to new connections |

Plan rotation so a backup is not mid-flight when you replace storage credentials or encryption keys. After you rotate cluster passwords, wait for idle connections or restart ABS if you need the new password immediately.

## Helm and Kubernetes

The ABS Helm chart defaults to a hardened container:

-   `runAsNonRoot` with UID 65532
-   `readOnlyRootFilesystem: true`
-   drop all capabilities
-   `seccompProfile: RuntimeDefault`
-   `automountServiceAccountToken: false`

The chart mounts an `emptyDir` volume at `/tmp`. File-based local storage or a log file on disk need an extra writable volume. See [Install ABS on Kubernetes with Helm](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/install#install-abs-on-kubernetes-with-helm).

## Next steps

-   [Configure ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/configure)
-   [Upgrade ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/upgrade)
-   [Restore data](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/restore)
-   [Monitor ABS](https://aerospike.com/docs/database/tools/backup-and-restore/backup-service/monitoring)