Please use the form below to provide your feedback. Because your feedback is valuable to us, the information you submit in this form is recorded in our issue tracking system (JIRA), which is publicly available. You can track the status of your feedback using the ticket number displayed in the dialog once you submit the form.

A newer version of this documentation is available.

View Latest

Secure a Replication

      +
      Securing a replication means that either the administrator password that is sent to the remote cluster, or both the password and the data itself, is transmitted securely.

      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 according to the destination cluster’s prior configuration. For details on configuration options, see Configure LDAP.

      XDCR security 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 an overview of certificates, see Certificates. For specific details on how to prepare and handle certificates for servers and clients, see Manage Certificates.

      The following security-levels are supported:

      • Half-secure: 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.

          Before using half-secure replication, see the important information provided in SCRAM SHA and XDCR, below.

          For step-by-step instructions, see Enable Half-Secure Replications.

      • Fully secure: Handles both authentication and data-transfer via TLS. For step-by-step instructions, see Enable Fully Secure Replications.

      SCRAM SHA and XDCR

      SCRAM-SHA is a multi-request protocol. The first request from the client (XDCR source to XDCR target) is responded to with a 401; the subsequent request completes the protocol. Therefore, when using half-secure replication, external monitoring or firewall software should allow (which is to say, ignore) these 401 responses; since they are part of the normal SCRAM-SHA protocol.

      If the monitoring or firewall software acts on these 401 responses by resetting or killing connections, SCRAM-SHA errors are displayed on the XDCR source cluster: if this occurs, check with your network monitoring or firewall administrators.

      If the monitoring or firewall software interferes with the XDCR connections, even though the XDCR replication will attempt to reconnect and continue to work through the connection interruptions, various issues may arise due to the continued interruptions — including XDCR having to restart replications from sequence 0.

      Please note that because various XDCR processes make frequent calls to the target, in order to monitor for changes in topology and collection manifest, 401 responses associated with the SCRAM-SHA multi-request protocol will be seen by the external monitoring or firewall software continuously, while the replication is in progress.

      Capella Trusted CAs

      CAs used by the Couchbase cloud data-platform, Capella, are automatically trusted, when fully secure XDCR connections are made to Capella databases from Couchbase Enterprise Server 7.2+, using Couchbase Web Console or the REST API. This means that when a reference is configured by means of:

      • Couchbase Web Console, the interactive pane, provided for specifying the CA, can be left blank. The Enable Secure Connection checkbox and the option for Full (TLS encrypt password and data) must still be selected.

      • The REST API POST /pools/default/remoteClusters, the option --data-urlencode "certificate=$(cat <local-pathname-to-target-root-certificate>)", provided for specifying the CA, does not need to be used. The option --xdcr-secure-connection full must still be used.

      Note that when the reference is configured by means of the CLI, the --xdcr-certificate flag, provided for specifying the CA, does still need to be used to specify the Capella CA.