Powered by Zoomin Software. For more details please contactZoomin

Administrate MarkLogic Server

Coupling Clusters

  • Last Updated: September 10, 2026
  • 5 minute read
    • MarkLogic Server
    • Version 12.0
    • Documentation

You can use the Admin Interface to couple local and foreign clusters to enable inter-cluster communication.

Note:

  • The foreign cluster must be running the same version of MarkLogic Server as the local cluster.

  • The procedures described in this section must be repeated for every cluster being coupled.

  • If you are using OAuth external security with JSON Web Tokens (JWT) and you are setting up a foreign cluster with your Security database replicated to the foreign cluster, then you must sync your local and foreign internal keystores after creating OAuth external security objects on your local cluster.

    Sync them by first exporting the internal keystore from your local cluster with

    then importing the internal keystore into your foreign cluster with

Each local cluster to be coupled must have one or more bootstrap hosts that store the configuration information needed to establish an initial connection to foreign clusters.

The clusters in a production system typically have more than one bootstrap host to ensure availability. When establishing an initial connection with a local cluster, a foreign cluster connects to the first available bootstrap host.

You must identify the bootstrap hosts in each cluster before attempting any of the configuration procedures described in this section.

It is best to choose the host that hosts your security forest as your bootstrap host. If you have configured your security forest for local disk failover, then also choose the host that hosts your replica security forest as a bootstrap host.

By default, the name of the local cluster is that of a bootstrap host. During configuration, give it a meaningful name to make it easier to identify when coupling clusters.

v12.1.0 and up

To couple clusters, follow these steps. The Configuring Clusters Field Reference section defines the fields:

First, configure the local cluster:

  1. Click Clusters in the left tree menu. The clusters summary page appears.

  2. Under Clusters in the left tree menu, click the name of the local cluster. The Local Cluster configuration page appears.

  3. Configure these fields, and click OK to save the configuration:

    The clusters summary page reappears.

Then, couple one of the local cluster's designated bootstrap hosts to a foreign cluster:

  1. Click the Couple tab. The Couple Cluster wizard, Step 1 page appears.

  2. Review the local cluster settings, configure these foreign cluster fields, and click Next:

    The Couple Cluster wizard, Step 2 page appears.

  3. Configure these foreign cluster fields, and click Next:

    The Confirm Couple Clusters modal appears.

  4. Click Confirm. The Couple Cluster wizard, Step 3 page appears. (You may have to log in to the foreign bootstrap host before this page appears.)

  5. Click Confirm. The clusters summary page appears with the foreign cluster configuration added after the local cluster configuration (click + to see settings).

    Bootstrapped indicates whether the foreign cluster configuration has been received by the local cluster.

    Last Bootstrap indicates the last time that the foreign cluster configuration was received by the local cluster.

    Initially, Bootstrapped may appear false and Last Bootstrap as never. Refresh your browser page to see the current status.

v12.0.x

To couple clusters, follow these steps. The Configuring Clusters Field Reference section defines the fields:

First, configure the local cluster:

  1. Click Clusters on the left tree menu.

  2. Under Clusters, click the name of the cluster.

  3. On the Local Cluster page, enter the cluster name.

  4. Under Bootstrap Hosts, select one or more hosts to serve as the bootstrap host or hosts for this cluster.

  5. Click OK to save the configuration.

Then, couple one of the local cluster's designated bootstrap hosts to a foreign cluster:

  1. Click the Couple tab.

  2. In the Foreign Cluster portion of the page, enter the host name for any host in the foreign cluster to be coupled. You can also specify the Admin Port (if necessary) and the communication protocol to be used between the clusters (HTTP or HTTPS). If you have SSL enabled on the Admin App Server on the bootstrap host in the foreign cluster, then set Protocol to https.

  3. Click OK.

  4. In the Foreign Cluster Configuration page, if you are using SSL for inter-cluster communication, then configure the SSL security settings and timeout values.

  5. In the Verify Add Foreign Cluster page, confirm all of the settings are correct and click OK.

  6. Click OK for any subsequent validate screens.

  7. When validation is complete, the Summary page appears with the summary for the Foreign Cluster configuration.

    Bootstrapped indicates whether the foreign cluster configuration has been received by the local cluster.

    Last Bootstrap indicates the last time that the foreign cluster configuration was received by the local cluster.

    Initially, Bootstrapped may appear false and **Last Bootstrap" as never. Refresh your browser page to see the current status.

Configuring Clusters Field Reference

This table describes any fields that you may encounter while configuring a local cluster or coupling clusters:

Field Name

Description

Location
[v12.1.0 and up]

Admin Port

Specifies the port number for the foreign cluster's Admin App Server interface.

Range: 1-65535 (valid port numbers)

Default: 8001

Step 1 of Couple Cluster wizard

Bootstrap Hosts

Identifies one or more hosts in the local cluster that store configuration information for establishing connections to foreign clusters.

Values: Select from available hosts in the local cluster (checkboxes)

Default: None selected (must be configured)

Local Cluster configuration page

Cluster Name

Provides a descriptive name for the local cluster to identify it to foreign clusters.

Values: Free-form text string

Default: Bootstrap host name

Local Cluster configuration page

Host Name

Specifies the hostname or IP address of any host in the foreign cluster to be coupled.

Values: Valid hostname or IP address

Default: None (must be configured)

Step 1 of Couple Cluster wizard

Host Timeout

Sets the timeout duration for host communication during the coupling process.

Values: Numeric value in seconds

Default: System default timeout

Step 2 of Couple Cluster wizard

Protocol

Determines the communication protocol used between local and foreign clusters for admin interface communication.

Values: http or https

Default: http

Step 1 of Couple Cluster wizard

SSL FIPS Enabled

Controls whether FIPS 140-2 compliant cryptographic operations are used for SSL communication.

Values: true or false

Default: false

Local Cluster configuration page

XDQP SSL Ciphers

[v12.0.x]

Not used.

N/A

XDQP SSL Ciphersuites

Defines the SSL cipher suites permitted for XDQP communication when SSL is enabled.

Values: SSL cipher suite specification string

Default: System default cipher suites

Step 2 of Couple Cluster wizard (if XDQP SSL = True)

XDQP SSL Enabled

Controls whether SSL encryption is used for XDQP communication between clusters.

Values: True or False

Default: False

Step 2 of Couple Cluster wizard

XDQP SSL Min Allow TLS

Sets the minimum TLS version required for XDQP SSL communication.

Values: TLS version specifications (e.g., 1.2, 1.3)

Default: System default minimum TLS version

Step 2 of Couple Cluster wizard (if XDQP SSL = True)

XDQP Timeout

Defines the timeout duration for XDQP communication between clusters.

Value: Numeric value in seconds

Default: System default XDQP timeout

Step 2 of Couple Cluster wizard

Alert