XDR security

For the complete documentation index see: llms.txt

All documentation pages available in markdown.

This page describes the login process between XDR nodes and how to set up access control and TLS.

Each source node connects and logs in to each destination node independently. The xdr-client tend thread manages this process through the following stages, provided security is enabled on your cluster with a valid configuration file.

Establish the connection.

The tend thread attempts to connect from the source node to the destination node.
- On success: It logs an info message and proceeds to Step 2.
  Terminal window
```
INFO (xdr-client): (cluster.c:2278) connected to destdc 172.17.0.5:3116
```
- On failure: It automatically retries the connection.
Authenticate with the destination node.

After connecting, the thread logs in to the destination if authentication is configured in the source cluster’s xdr dc section.
- On success: It logs the session details and proceeds to Step 3.
  Terminal window
```
INFO (xdr-client): (cluster.c:1539) logged in to node 172.17.0.5:3116 - session-ttl 120
```
- On failure: It logs warnings and returns to Step 1.
  Terminal window
```
WARNING (xdr-client): (cluster.c:1470) login to node 172.17.0.5:3116 failed: 65
WARNING (xdr-client): (cluster.c:1470) (repeated:11) login to node 172.17.0.5:3116 failed: 65
```
- If security is disabled on destination: It logs a confirmation message and bypasses session token management.
  Terminal window
```
INFO (xdr-client): (cluster.c:1463) security not configured on node 172.17.0.5:3116
```
Refresh the session token.

The access token automatically refreshes one minute before the destination node’s configured session-ttl expires.
Terminal window
```
INFO (xdr-client): (cluster.c:1045) refreshing session token for destdc 172.17.0.5:3116
```
- On success: It logs the updated session details.
  Terminal window
```
INFO (xdr-client): (cluster.c:1539) logged in to node 172.17.0.5:3116 - session-ttl 120
```
- On failure: It logs a warning and returns to Step 1.
  Terminal window
```
WARNING (xdr-client): (cluster.c:1470) login to node 172.17.0.5:3116 failed: 65
```
Handle disconnections.

If the connection drops at any point due to a node restart, network disruption, or any other issue, the entire flow restarts at Step 1.

Authorized user and password file

For access control or LDAP, if the target cluster has security enabled, add all three of the following items to the source cluster configuration. Make sure this file is adequately secured.

auth-mode specifies the mode of authentication.
auth-user specifies the user that authenticates to the destination cluster when security is enabled.
auth-password-file supplies the password for the user specified in auth-user. The value must follow one of these formats:
- file:/path_to/xaupwd — Read from the filesystem (the file: prefix is optional).
- env:XAUPWD — Read from the named environment variable (Database 5.3.0+).
- vault:auth-password — Read the named secret from HashiCorp Vault (Database 5.1.0+).
- secrets:AerospikeSecrets:AuthPassword — Fetched using Aerospike Secret Agent (Database 6.4.0+).

See examples of these parameters in Securing with access control and Securing with LDAP.

Password file format

When reading from the filesystem, the file contains the password as plain text on a single line:

$ less /private/security-credentials-DC1.txt
passwordOnDestination

On the destination cluster, the auth-user must have permission to write the namespaces, sets, and record operations that XDR ships. Aerospike provides a pre-defined write-only write role for this purpose. See Pre-defined roles.

Securing with access control

To learn about configuring Aerospike’s local-to-the-server user access control, see Configuring access control.

For an explanation of the auth-user and auth-password-file parameters, see Authorized user and password file.

DC configuration for access control

xdr {
    dc dataCenter1 {
        node-address-port someIpAdress1 somePort1
           ...
           auth-mode internal
           auth-user somebodyOnDestination1
           # auth-user must be accompanied by auth-password-file
           auth-password-file /private/security-credentials-DC1.txt
           namespace someNamespace {
           ...
           }
        }
    dc dataCenter2 {
        node-address-port someIpAdress2 somePort2
           ...
           auth-mode internal
           auth-user somebodyOnDestination2
           # auth-user must be accompanied by auth-password-file
           auth-password-file /private/security-credentials-DC2.txt
           namespace someNamespace {
           ...
           }
        }
 }

Securing with access control using PKI

The following example secures the connection with a TLS certificate and uses the common name (CN) in the certificate as username to authenticate at the destination cluster. Starting with Database 8.1.0, you can use pki-user-append-ou to include the certificate’s OU (Organizational Unit Name) value in the username for PKI authentication.

You do not need to specify a password in this mode as the TLS certificate validity authenticates the user.

xdr {
    dc dataCenter1 {
        node-address-port someIpAdress1 somePort1 someTlsNameDefinition1
        tls-name localTls
        auth-mode pki
        namespace someNamespace {
        ...
        }
    }
    ...
}

Securing with LDAP

To learn about configuring LDAP, see Configuring LDAP.

For an explanation of the auth-user and auth-password-file parameters, see Authorized user and password file.
If you are using LDAP authentication, you must set auth-mode to external.

DC configuration for LDAP with auth-mode external

xdr {
    dc dataCenter1 {
        node-address-port someIpAdress1 somePort1
           ...
           auth-mode external
           auth-user somebodyOnDestination1
           auth-password-file /private/security-credentials-DC1.txt
           namespace someNamespace {
           ...
           }
        }
 }

Data masking with XDR

When XDR replicates data from a source cluster with masking rules to a destination cluster, the source cluster always ships the original unmasked data.

How the writes behave at the destination cluster depends on the privileges held by the XDR auth-user. If the XDR auth-user has the write-masked privilege, XDR can write masked bins. This matches the data masking behavior of non-XDR clients.

For consistent masking behavior across clusters, ensure that:

The destination cluster has the same masking rules configured as the source cluster.
The XDR user credentials have appropriate masking privileges based on your security requirements.

For more information about data masking, see Data masking.

Securing with TLS

Consider implementing TLS among the cluster nodes. For details, see TLS configuration.

Configure TLS within the network.tls configuration in aerospike.conf. This section defines variable names based on TLS certificates. In the following example for XDR, the variable names someTlsNameDefinition... and localTls are variable references to TLS certificates you have installed on your system and configured under tls.
The xdr section only refers to those TLS variable name definitions.
Those TLS variable name definitions come after the port number of the node-address-port parameter.

The following example secures the connection with a TLS certificate and with LDAP user authentication auth-mode external.

xdr {
    dc dataCenter1 {
        node-address-port 10.0.0.100 4333 destination-cluster-tls-name
        tls-name this-cluster-tls-name
        auth-mode external # auth-mode only necessary if using security
        auth-user somebodyOnDestination1 # auth-user only necessary if using security
        auth-password-file /private/security-credentials-DC1.txt # auth-password-file only necessary if using security
        namespace someNamespace {
        ...
        }
    }
    ...
}

To configure TLS and authentication without restarting nodes, set the TLS and authentication parameters before adding node addresses or namespaces. See Configure a new datacenter with TLS.