A newer version of this documentation is available.

View Latest

XDCR Security

XDCR security is configurable

Overview

By default, for inter-cluster communications, XDCR transmits both password and data in non-secure form. Optionally, a secure connection can be enabled between clusters, in order to secure either password alone, or both password and data.

Note that if the password received by the destination cluster requires authentication by an LDAP server, the destination cluster communicates with the LDAP server in plain text, using saslauthd. This is described in Setting Up saslauthd.

A secure XDCR connection is enabled either by SCRAM-SHA or by TLS — depending on the administrator-specified connection-type, and the server-version of the destination cluster. Use of TLS involves certificate management: for information on preparing and using certificates, see Certificate-Based Authentication.

Start Enablement

Proceed as follows:

  1. On the source cluster, left-click on the XDCR tab. This brings up the XDCR Replications screen.

  2. Do one of the following:

    • To create a new cluster-reference, in the Remote Clusters panel, left-click on the Add Remote Cluster button, to the right. This brings up the Add Remote Cluster dialog.

    • To edit an existing cluster-reference, in the Remote Clusters panel, left-click on the Edit tab, at the right of the row of an existing cluster-reference. This brings up the Edit Remote Cluster dialog.

    In the dialog you have brought up, enter appropriate information for the Cluster Name and IP/Hostname. Then, proceed as appropriate for the type of connection you wish to establish, according to the instructions below. Note that in each example, the username and password specified must be those of the Full, Cluster, or XDCR Administrator for the destination cluster.

Enable a Non-Secure Connection

In the open Add or Edit dialog, enter the Username for Remote Cluster, and Password. Then, left-click on the Save button, at the lower right of the dialog.

Enable a 'Half' Secure Connection

A Half secure connection secures the specified password only: it does not secure data. The password is secured:

  • By hashing with SCRAM-SHA, when the destination cluster is running Couchbase Enterprise Server 5.5 or later.

  • By TLS encryption, when the destination cluster is running a pre-5.5 Couchbase Enterprise Server.

The root certificate of the destination cluster must be provided, for a successful TLS connection to be achieved. If this certificate is provided and a SCRAM-SHA connection is achieved, the certificate is ignored. The root certificate can be obtained by accessing the Root Certificate tab, on the Security screen for the remote cluster: copy the certificate from the interactive panel in which it appears.

To enable a secure half connection with a destination cluster that may be either pre-5.0 or 5.0 and beyond, proceed as follows:

  1. In the open Add or Edit dialog, enter the Username for Remote Cluster, and Password.

  2. Check the Enable Secure Connection checkbox. When the dialog expands vertically, select the Half radio button.

  3. Copy and paste the root certificate for the destination cluster into the interactive panel, below the radio buttons. The dialog now appears approximately as follows:

    addRemoteClusterDialog
  4. Left-click on the Save button, at the lower-right of the dialog.

Enable a 'Full' Secure Connection

A Full secure connection handles both authentication and data-transfer via TLS. Select the Full radio-button. When the dialog expands vertically to reveal two additional interactive panes, proceed in one of the following ways, as appropriate.

  • Specify username, password, and root certificate:

    1. In the open Add or Edit dialog, enter the Username for Remote Cluster, and Password.

    2. Copy and paste the root certificate for the destination cluster into the top interactive pane, below the radio buttons — leaving both of the lower interactive panes blank. The dialog now appears approximately as follows:

      editRemoteClusterDialogWithFullConnectionByPwd
    3. Left-click on the Save button, at the lower-right of the dialog.

  • Specify root and client certificates, and client private key.

    General information on preparing client certificates and keys is provided in X.509 for TLS. Information on configuring clusters to handle client certificates is provided in Handling Client Certificates. Note that if the client certificate has been generated using the root certificate, the client certificate itself must be specified. Alternatively, if the client certificate has been generated using intermediate certificates, the entire certificate chain — including the client certificate and all intermediate certificates — must be specified.

    Proceed as follows:

    1. Copy and paste the root certificate for the destination cluster into the top interactive pane.

    2. Copy and paste the client certificate for the local cluster into the middle interactive pane.

    3. Copy and paste the client private key for the local cluster into the bottom interactive pane.

    4. Ensure that the Username for Remote Cluster and Password fields are blank. The dialog now appears approximately as follows:

      editRemoteClusterDialogWithFullConnectionByCerts
    5. Left-click on the Save button, at the lower-right of the dialog.

Starting Replication

If you are adding a new cluster-reference, in the Ongoing Replications panel, click Add Replication, provide the cluster and bucket information, and click Replicate. This starts replication.

Alternatively, if you are editing an existing replication, you do not have to take any further action: the existing replication automatically restarts, with TLS enabled. During restart, XDCR uses the last checkpoint of the replication stream.

Note that it is good practice periodically to rotate XDCR certificates, and instantiate new ones.

XDCR Security Error-Messages

When creating the cluster reference, if certificates on the destination and source clusters are mismatched, the following error message is displayed: Attention - Got certificate mismatch while trying to send https request to HOST:18091.

If XDCR is underway, and stops due to a certificate mismatch, the following error message is displayed: Error replicating vbucket <`bucketNumber>. Please see logs for details.`