---
title: "XDR security"
description: "Guide to securing Aerospike XDR with access control, LDAP, TLS, and PKI authentication for cross-DC replication."
---

# XDR security

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

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

## XDR login flow

Your cluster must have security enabled with a valid configuration file.

The login flow applies from each source node to each destination node independently. The `xdr-client` tend thread follows the login process as described in the following stages.

1.  The login process establishes the connection from the source node to the destination node.
    
    a. If the connection from the tend thread is successful, it logs an info message
    
    Terminal window
    
    ```bash
    INFO (xdr-client): (cluster.c:2278) connected to destdc 172.17.0.5:3116
    ```
    
    b. If login fails, it retries the connection to the destination node.
    
2.  Once the connection is established, it logs in to each destination node if access control is configured in the [`xdr dc` sub-stanza](https://aerospike.com/docs/database/manage/xdr/static-xdr/#the-xdr-stanza).
    
    a. If login is successful, it logs an info message.
    
    Terminal window
    
    ```bash
    INFO (xdr-client): (cluster.c:1539) logged in to node 172.17.0.5:3116 - session-ttl 120
    ```
    
    b. If login fails, it logs warning messages then goes back to Step 1.
    
    Terminal window
    
    ```bash
    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
    ```
    
    c. If security is not enabled on the destination node, it logs an info message after successfully establishing the connection by the tend thread.
    
    Terminal window
    
    ```bash
    INFO (xdr-client): (cluster.c:1463) security not configured on node 172.17.0.5:3116
    ```
    
3.  Once the login is successful, the access token is refreshed one minute before the [`session-ttl`](https://aerospike.com/docs/database/reference/config#security__session-ttl) configured on the destination node during the login. It logs an info message.
    
    Terminal window
    
    ```bash
    INFO (xdr-client): (cluster.c:1045) refreshing session token for destdc 172.17.0.5:3116
    ```
    
    a. If login succeeds during refreshing access token, it logs an info message.
    
    Terminal window
    
    ```bash
    INFO (xdr-client): (cluster.c:1539) logged in to node 172.17.0.5:3116 - session-ttl 120
    ```
    
    b. If login fails during refreshing access token, it logs a warning message then goes back to Step 1.
    
    Terminal window
    
    ```bash
    WARNING (xdr-client): (cluster.c:1470) login to node 172.17.0.5:3116 failed: 65
    ```
    
4.  If the connection is broken any time after successful establishment due to node (source or destination) restart or any other reason, it goes back to Step 1.
    
    ::: note
    These log items and flow are limited to connections and login by the `xdr-client` tend thread. They do not include connections by other `xdr-client` threads.
    :::
    

## Authorized user and password file

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

-   [`auth-mode`](https://aerospike.com/docs/database/reference/config#xdr__auth-mode) specifies the mode of authentication.
-   [`auth-user`](https://aerospike.com/docs/database/reference/config#xdr__auth-user) specifies the name of a user with read/write permissions on the target cluster. **Must be accompanied by `auth-password-file` and `auth-mode`**.
-   [`auth-password-file`](https://aerospike.com/docs/database/reference/config#xdr__auth-password-file) points to a file that contains the password of the username specified in `auth-user`. The value of `auth-password-file` can also be stored in HashiCorp Vault. See [Optional security with Vault integration](https://aerospike.com/docs/database/manage/security/vault).
-   In Database 6.4.0 and later, the value of `auth-password-file` can be fetched using the Secret Agent. See [Integrating with secrets management services](https://aerospike.com/docs/database/manage/security/secrets).

See examples of these parameters in [Securing with access control](#securing-with-access-control) and [Securing with LDAP](#securing-with-ldap).

### Contents of security configuration file

Terminal window

```bash
$ less /private/security-credentials-DC1.txt

passwordOnDestination
```

## Securing with access control

For background on configuring Aerospike’s local-to-the-server user access control, see [Configuring Access Control](https://aerospike.com/docs/database/manage/security/rbac).

For an explanation of the `auth-user` and `auth-password-file` parameters, see [Authorized user and password file](#authorized-user-and-password-file).

### DC sub-stanza for access control

Terminal window

```bash
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 (versions 5.7+)

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`](https://aerospike.com/docs/database/reference/config#network__pki-user-append-ou) to include the certificate’s `OU` (Organizational Unit Name) value in the username for PKI authentication.

No need to specify password in this mode as the TLS certificate validity authenticates the user.

Terminal window

```bash
xdr {

    dc dataCenter1 {

        node-address-port someIpAdress1 somePort1 someTlsNameDefinition1

        tls-name localTls

        auth-mode pki

        namespace someNamespace {

          ...

        }

    }

    ...

}
```

## Securing with LDAP

For background about configuring LDAP, see [Configuring LDAP](https://aerospike.com/docs/database/manage/security/ldap).

-   For an explanation of the `auth-user` and `auth-password-file` parameter, see [Authorized user and password file](#authorized-user-and-password-file).
-   If you are using LDAP authentication, `auth-mode` must be set to `external`.

### DC sub-stanza for LDAP with auth-mode external

Terminal window

```bash
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 is dependent on the privileges held by the XDR auth-user. If the XDR auth-user has the `write-masked` privilege, XDR will be able to 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](https://aerospike.com/docs/database/learn/security/data-masking).

## Securing with TLS

Consider implementing TLS among the cluster nodes. For details, see [TLS Configuration](https://aerospike.com/docs/database/manage/network/tls).

-   TLS is configured in the [`tls`](https://aerospike.com/docs/database/reference/config#network__tls) stanza of the configuration file. This stanza defines variable names based on TLS certificates. In this example for XDR, the variable names `someTlsNameDefinition...` and `localTls` are variable references to TLS certificates you have installed on your system and configured in the `tls` stanza.
-   The `xdr` stanza 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`.

Terminal window

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

          ...

        }

    }

    ...

}
```