--- 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 and TLS. ## XDR login flow 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. ::: note These log patterns and stages apply strictly to connections made by the `xdr-client` tend thread, not other auxiliary `xdr-client` threads. ::: 1. 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 ```bash INFO (xdr-client): (cluster.c:2278) connected to destdc 172.17.0.5:3116 ``` - **On failure:** It automatically retries the connection. 2. 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](https://aerospike.com/docs/database/8.1.2/manage/xdr/static-xdr). - **On success:** It logs the session details and proceeds to Step 3. Terminal window ```bash 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 ```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 ``` - **If security is disabled on destination:** It logs a confirmation message and bypasses session token management. Terminal window ```bash INFO (xdr-client): (cluster.c:1463) security not configured on node 172.17.0.5:3116 ``` 3. Refresh the session token. The access token automatically refreshes one minute before the destination node’s configured [`session-ttl`](https://aerospike.com/docs/database/reference/config#security__session-ttl) expires. Terminal window ```bash 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 ```bash 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 ```bash WARNING (xdr-client): (cluster.c:1470) login to node 172.17.0.5:3116 failed: 65 ``` 4. 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`](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 user that authenticates to the destination cluster when security is enabled. - [`auth-password-file`](https://aerospike.com/docs/database/reference/config#xdr__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](https://aerospike.com/docs/database/8.1.2/manage/security/vault) (Database 5.1.0+). - `secrets:AerospikeSecrets:AuthPassword` — Fetched using [Aerospike Secret Agent](https://aerospike.com/docs/database/8.1.2/manage/security/secrets) (Database 6.4.0+). See examples of these parameters in [Securing with access control](#securing-with-access-control) and [Securing with LDAP](#securing-with-ldap). ### Password file format When reading from the filesystem, the file contains the password as plain text on a single line: Terminal window ```bash $ 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](https://aerospike.com/docs/database/8.1.2/manage/security/rbac#pre-defined-roles). ## Securing with access control To learn about configuring Aerospike’s local-to-the-server user access control, see [Configuring access control](https://aerospike.com/docs/database/8.1.2/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 configuration 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 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. You do not need to specify a 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 To learn about configuring LDAP, see [Configuring LDAP](https://aerospike.com/docs/database/8.1.2/manage/security/ldap). - For an explanation of the `auth-user` and `auth-password-file` parameters, see [Authorized user and password file](#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 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 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](https://aerospike.com/docs/database/8.1.2/learn/security/data-masking). ## Securing with TLS Consider implementing TLS among the cluster nodes. For details, see [TLS configuration](https://aerospike.com/docs/database/8.1.2/manage/network/tls). - Configure TLS within the [`network.tls`](https://aerospike.com/docs/database/reference/config#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`. 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 { ... } } ... } ``` 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](https://aerospike.com/docs/database/8.1.2/manage/xdr/dynamic-xdr#configure-a-new-datacenter-with-tls).