XDCR

XDCR

XDCR commands used with the couchbase-cli tool.

Description

Remote XDCR replications, connections, and operations are managed with the following XDCR commands and options.

CLI commands and parameters

Table 1. couchbase-cli xdcr commands
Command Description
xdcr-setup Manage the XDCR replication configuration.
setting-xdcr Set XDCR related replication settings.
xdcr-replicate Manage the XDCR replication operations.
ssl-manage Manage cluster SSL certificate.

The following are couchbase-cli xdcr-setup options.

Table 2. xdcr-setup options
xdcr-setup options Description
--create Creates a new XDCR configuration.
--edit Modifies an existing XDCR configuration.
--delete Deletes an existing XDCR configuration.
--list Lists all XDCR configurations.
--xdcr-cluster-name=[clustername] Cluster name.
--xdcr-hostname=[hostname] Remote host name to connect to.
--xdcr-username=[username] Remote cluster administrator username.
--xdcr-password=[password Remote cluster administrator password.
--xdcr-demand-encryption=[0 | 1] Enables and disables data encrypted using ssl. True is 1 and enables data encryption. False is 0 and disables data encryption. Default: 0
--xdcr-certificate=[certificate] Pem-encoded certificate. This self-signed certificate must be present if xdcr-demand-encryption is true.

The following are couchbase-cli setting-xdcr options.

Table 3. setting-xdcr options
setting-xdcr options Description
--max-concurrent-reps=[32] Maximum concurrent replications per bucket, 8 to 256.
--checkpoint-interval=[1800] Intervals between checkpoints, 60 to 14400 seconds.
--worker-batch-size=[500] Document worker batch size, 500 to 10000.
--doc-batch-size=[2049]kilobytes Document batching size, 10 to 100000 kilobytes.
--failure-restart-interval=[30] Interval for restarting failed XDCR, 1 to 300 seconds.
--optimistic-replication-threshold=[256] Document body size threshold (bytes) to trigger optimistic replication.

The following are couchbase-cli xdcr-replicate options.

Table 4. xdcr-replicate options
xdcr-replicate options Description
--create Create and start a new replication
--delete Stop and cancel a replication
--list List all XDCR replications
--pause Pause the replication
--resume Resume the replication
--settings Update settings for the replication
--xdcr-replicator=[replicator] Replication ID
--xdcr-from-bucket=[bucket-name] Local bucket name to replicate from
--xdcr-cluster-name=[remote-cluster] Remote cluster to replicate to
--xdcr-to-bucket=[remote-bucket] Remote bucket to replicate to
--max-concurrent-reps =[ 16 ] Maximum concurrent replications per bucket, 8 to 256. Default: 16
--checkpoint-interval =[ 1800 ] Intervals between checkpoints , 60 to 14400 seconds
--worker-batch-size =[ 500 ] Document worker batch size, 500 to 10000
--doc-batch size =[ 2048 ] kilobytes Document batch size, 10 to 100000 kilobytes
--failure-restart-interval =[ 30 ] Interval for restarting failed xdcr, 1 to 300 seconds
--optimistic-replication-threshold =[ 256 ] Document body size threshold (bytes) to trigger optimistic replication
--xdcr-replication-mode=[xmem | capi] Replication protocol, either capi or xmem

The following are couchbase-cli ssl-manage options. This option is available for Enterprise Edition only.

Table 5. ssl-manage command options
ssl-manage options (Enterprise Edition only) Description
--retrieve-cert=[certificate] Retrieves the self-signed certificate from the destination cluster to the source cluster. Specify a local location (full path) and file name for the pem-encoded certificate. For example, --retrieve-cert=./newCert.pem .
--regenerate-cert=[certificate] Regenerates a self-signed certificate on the destination cluster. Specify the full path for the location of the pem-encoded certificate file. For example, --regenerate-cert=./newRegen.pem .

Example: Creating a remote cluster reference

To create a remote cluster reference:

couchbase-cli xdcr-setup -c 10.3.121.121:8091 -u Administrator  -p password 
    --create 
    --xdcr-cluster-name=RemoteCluster  
    --xdcr-hostname=10.3.121.123:8091  
    --xdcr-username=Administrator  
    --xdcr-password=password

Upon success, the following response is returned:

SUCCESS: init RemoteCluster

Now, you can start replication to the remote cluster using memcached protocol as the existing default:

couchbase-cli xdcr-replicate -c 10.3.121.123:8091 -u Administrator -p password 
        --xdcr-cluster-name RemoteCluster 
        --xdcr-from-bucket default 
        --xdcr-to-bucket backup
      

An XDCR protocol for the mode of replication can be specified for XDCR. To explicitly set the protocol to memcached:

couchbase-cli xdcr-replicate -c 10.3.121.123:8091 -u Administrator -p password
    --xdcr-cluster-name RemoteCluster 
    --xdcr-from-bucket default 
    --xdcr-to-bucket backup 
    --xdcr-replication-mode xmem
      

To set the protocol to CAPI:

couchbase-cli xdcr-replicate -c 10.3.121.123:8091 -u Administrator -p password
    --xdcr-cluster-name=RemoteCluster 
    --xdcr-from-bucket=default 
    --xdcr-to-bucket=backup
    --xdcr-replication-mode=capi
      

To change a XDCR replication protocol for an existing XDCR replication:

  1. Delete the replication.
  2. Re-create the replication with your preference.

If there is already an existing replication for a bucket, you get an error when starting the replication again with new settings:

couchbase-cli xdcr-replicate -c 10.3.121.121:8091 -u Administrator -p password 
    --xdcr-cluster-name=RemoteCluster 
    --xdcr-from-bucket=default 
    --xdcr-to-bucket=backup
    --xdcr-replication-mode=capi
      

Results in the following error:

ERROR: unable to create replication (400) Bad Request
        {u'errors': {u'_': u'Replication to the same remote cluster and bucket already exists'}}
ERROR: Replication to the same remote cluster and bucket already exists
      

Example: Listing XDCR remote clusters

In the following example, the couchbase-cli xdcr-setup command is executed from the local host and the specified host is the remote host. To list all XDCR configurations:


couchbase-cli xdcr-setup 
  -c 10.5.2.117:8091 
  -u Administrator -p password 
  --list        
      

Example: Listing XDCR replication streams

In the following example, the couchbase-cli xdcr-replicate command is executed from the local host and the specified host is the remote host. To list all XDCR replication streams:


couchbase-cli xdcr-replicate 
  -c 10.5.2.117:8091 
  -u Administrator -p password 
  --list        
      

Response

The follow response example is for the couchbase-cli xdcr-setup --list command option and shows the local host, UUID, URI, and user name:


cluster name: source1
      uuid: bfa861d3734c90559522a88b9db81606
      host name: 10.5.2.54:8091
      user name: Administrator
      uri: /pools/default/remoteClusters/source1
      

The follow response example is for the couchbase-cli xdcr-replicate --list command option and shows the replication stream from the source bucket to the remote bucket:


stream id: bfa861d3734c90559522a88b9db81606/test2/test
   status: running
   source: test2
   target: /remoteClusters/bfa861d3734c90559522a88b9db81606/buckets/test