Administrator's Guide — Chapter 5

Clusters

This chapter describes cluster configuration using the Admin Interface. A cluster is a set of hosts that work together. This chapter includes the following sections:

Overview of Cluster Configuration
OpenSSL FIPS 140-2 Mode
Procedures for Configuring Clusters
Configuring a MarkLogic Application Message and Banner

Overview of Cluster Configuration

In MarkLogic clusters, a common configuration is to have one group defined for the evaluator nodes (hosts that service query requests) and another group defined for the data nodes (hosts to which forests are attached).

The Cluster configuration page found in the Admin Interface enables you to configure FIPS 140-2 mode for a cluster and to couple local and foreign clusters. For a description of each configuration option, see the help tab of the group configuration page in the Admin Interface. For a discussion of how clustering works in MarkLogic Server, see Clustering in MarkLogic Server in the Scalability, Availability, and Failover Guide.

OpenSSL FIPS 140-2 Mode

MarkLogic Server uses FIPS-capable OpenSSL to implement the Secure Sockets Layer (SSL v3) and Transport Layer Security (TLS v1) protocols. When you install MarkLogic Server, FIPS mode is enabled by default and SSL RSA keys are generated using secure FIPS 140-2 cryptography. This implementation disallows weak ciphers and uses only FIPS 140-2 approved cryptographic functions. Should your applications experience any difficulty running in SSL FIPS-mode, you can disable FIPS-mode using the Admin Interface as described below.

For more information on the OpenSSL FIPS 140-2 cryptographic capabilities, refer to the documentation provided by the OpenSSL Project at: http://www.openssl.org/docs/fips/fipsvalidation.html.

Procedures for Configuring Clusters

The following procedures describe how to configure clusters in MarkLogic Server:

Configuring OpenSSL FIPS 140-2 Mode
Cluster Encryption Options
Coupling Clusters

Configuring OpenSSL FIPS 140-2 Mode

When FIPS 140-2 mode is enabled, the OpenSSL library is initialized into FIPS 140-2 mode at system startup. Note that this is the default behavior of MarkLogic Server. If FIPS mode is enabled or disabled on a running system, the OpenSSL library is reconfigured appropriately without requiring a server restart. When the FIPS mode setting changes and secure XDQP is configured, all XDQP connections are dropped and reestablished.

To configure a cluster to run in FIPS 140-2 mode, perform the following steps:

Log into the Admin Interface.
Click the Clusters icon on the left tree menu.
Select the local cluster. Click the Configure tab to open the Edit Local Cluster Configuration page.
To configure FIPS 140-2 mode, select true or false as needed. For SSL FIPS Enabled, select true.
Click OK to save the change.

Cluster Encryption Options

The Key Management Service (KMS) manages a keystore that stores the encryption keys used to encrypt data in a secure location. This keystore can be either the MarkLogic embedded PKCS #11 secured wallet, or an external third party KMS that conforms to the KMIP-standard interface. The embedded keystore is installed by default when you install MarkLogic 9.0-x or later.

This section describes how to configure encryption for a group. For more details on configuring encryption to protect your data on media, see Encryption at Rest in the Security Guide.

Adding or changing any encryption information will require a restart of all of the hosts in the cluster.

To configure encryption using the embedded keystore in the Admin UI, do the following:

Click Clusters in the left navigation tree and click the name of the cluster you want to configure.
Click the Keystore tab to open the Edit Keystore Configuration page.

Use the drop-down menus to configure encryption for data, config files, and log files.

Setting	Description
data encryption	Specifies whether or not encryption is enabled for user data. The options are: `force` -- Force encryption for all data in the cluster. The database configuration cannot overwrite this setting. `default-on` -- By default encryption is on. The database configuration can overwrite this setting. `default-off` -- By default encryption is off. The database configuration can overwrite this setting.
config encryption	Specifies whether or not encryption is enabled for configuration files
logs encryption	Specifies whether or not encryption is enabled for log files.
kms type	Specifies whether the KMS is internal to MarkLogic or an external KMS A keystore is a secure location where the actual encryption keys used to encrypt data are stored. The keystore for encryption at rest is a key management system (KMS). This keystore can be either the MarkLogic embedded PKCS #11 secured wallet, or an external third party KMS

Click ok when you are done.

To configure an external KMS, do the following:

Select the External KMS tab.

Enter the following information to identify the external KMS and the required encryption keys.

Setting	Description
host name	The host name of the Key Management Server (KMS).
port	The KMS client socket port number.
external data encryption key id	The encryption key at the KMS to encrypt user data.
external config encryption key id	The encryption key at the KMS to encrypt configuration files.
external logs encryption key id	The encryption key at the KMS to encrypt log files.

The encryption keys must be a URN representation of a UUID as defined by Network Working Group Request for Comments: 4122 :

http://www.ietf.org/rfc/rfc4122.txt

For example:

06ea22c9-b972-4652-8d0f-9e58c62e0f7f

Click ok when you are done.

Change the Internal KMS Password

The default password value for the internal KMS is the admin user password for that instance. You can change the password for the internal KMS using the Change Internal KMS Password screen. To change the internal KMS password, follow these steps:

Click Clusters in the left navigation tree and click the name of the cluster that has the KMS keystore with the password you want to change.
Click the Keystore tab to open the Edit Keystore Configuration page. Click the change password button on the Edit Keystore Configuration page. This opens the Change Internal KMS Password page.
Enter the current password in the first field, and then enter the new password in the second field. Confirm the new password by entering it again in the third field.
Click ok when you are done.

For more about MarkLogic encryption at rest and the internal KMS, see Configuring Encryption at Rest in the Encryption chapter of the Security Guide.

Synchronizing the KMS Keys

You can synchronize the KMS keys with the enveloped keys on MarkLogic Server. This is useful when you use Encryption at Rest feature.

To synchronize the KMS keys, do the following:

Click Clusters in the left navigation tree and click the name of the cluster that has the KMS keystore with the keys you want to synchronize.
Click the Keystore tab to open the Edit Keystore Configuration page.
Click the Synchronize Keys button on the Edit Keystore Configuration page. This opens the Synchronize Keys page.
Click ok to confirm that you want to synchronize the MarkLogic Server keys with your KMS.

Coupling Clusters

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

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

The procedure described in this section must be repeated for every cluster.

Before coupling clusters, you must specify a bootstrap host for each cluster. By default, the name of the cluster is that of the bootstrap host. You must edit the cluster name in the Local Cluster Configuration on each local cluster to be coupled with foreign clusters.

On the local host, select Local Cluster under Clusters at the bottom of the left-hand menu:
Select the Configure tab to display the Edit Local Cluster Configuration page. Enter the cluster name:
Each cluster to be coupled must have one or more bootstrap hosts that stores the configuration information needed to establish an initial connection to foreign clusters. You must identify the bootstrap hosts in each cluster before attempting any of the configuration procedures described in this chapter.
The clusters in a production system will typically have more than one bootstrap host to ensure availability. When establishing an initial connection with a local cluster, a foreign cluster will connect to the first available bootstrap host.
In the Local Cluster Configuration page, select one or more hosts to serve as the bootstrap hosts for this cluster.
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.
Click OK to save the Local Cluster Configuration.
The remaining steps in this procedure describe how to couple a foreign cluster configuration to the bootstrap host on your local cluster. If you have designated more than one bootstrap host on your local cluster, pick any one of them.
In the Local Cluster Configuration page, select the Couple tab.
In the Foreign Cluster portion of the Local Cluster Configuration 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). When you have SSL enabled on the Admin App Server on the bootstrap host in the foreign cluster, set the protocol to https. Click Ok and the Foreign Cluster Configuration page appears.

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

Foreign Cluster Setting	Description
`xdqp ssl enabled`	Set to true to enable SSL to encrypt all XDQP traffic between the clusters.
`xdqp ssl allow sslv3`	Set to `true` to enable the Secure Sockets Layer (SSL) v3 protocol for inter-cluster XDQP communication.
`xdqp ssl allow tls`	Set to `true` to enable the Transport Layer Security (TLS) protocol for inter-cluster XDQP communication.
`xdqp ssl ciphers`	Enter one or more of the SSL ciphers defined in http://www.openssl.org/docs/apps/ciphers.html or leave as default. If MarkLogic Server is operating in FIPS mode, then the cipher must be a FIPS-approved cipher or SSL communication will fail.
`xdqp timeout`	Specify the time, in seconds, before the XDQP connection between the local cluster and the foreign cluster times out. Default is 10 seconds.
`host timeout`	Specify the time, in seconds, before a MarkLogic Server host on the local cluster communicating with a host on the foreign cluster times out. Default is 30 seconds.

In the Verify Add Foreign Cluster page confirm all of the settings are correct and click OK.
Click OK for any subsequent validate screens.
When validation is complete, the Summary window appears and displays 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 the foreign cluster configuration was received by the local cluster. Initially the status of Bootstrapped may appear as false and Last Bootstrap as never. Refresh your browser page to see the current status.

Configuring a MarkLogic Application Message and Banner

This topic describes how to configure your cluster to display a notification dialog and an application banner when users navigate to one of the built-in MarkLogic application pages, such as Query Console or the Monitoring Dashboard.

Administrators might want to use this feature in situations such as the following:

Notify users of important system status changes, such as a planned outage.
Make it easy for users to distinguish between MarkLogic clusters, such as testing versus production environments.

The notification dialog is only displayed to each user once per host from which he or she connects to a MarkLogic application. If the notification message changes, the dialog will be displayed again, next time the user navigates to one of the affected applications.

Specify the UI configuration in the configuration document in the App-Services database with the URI /cluster-ui-settings.xml. MarkLogic installs a deactivated default configuration that you can use as a baseline for customization.

For more details, see the following topics:

Example Configuration
Configuration Reference
Example: Creating a New Configuration Document
Example: Activate/Deactivate a Configuration
Example: Modify the Notification Dialog Text
Example: Modify the Banner Text

Example Configuration

This example is based on the following configuration. (Whitespace has been added to improve readability.) For more details on the structure and meaning of the elements, see Configuration Reference.

<env-ui:environment-ui xml:lang="zxx" 
    xmlns:env-ui="http://marklogic.com/environment-ui">
  <env-ui:ui-active>true</env-ui:ui-active>
  <env-ui:ui-label>Welcome to the PRODUCTION STAGING cluster</env-ui:ui-label>
  <env-ui:ui-header-color>#33CC99</env-ui:ui-header-color>
  <env-ui:ui-header-text-color>#000000</env-ui:ui-header-text-color>
  <env-ui:ui-message>
    This cluster will be unavailable on odd Tuesdays of even months.
  </env-ui:ui-message>
</env-ui:environment-ui>

This configuration has the following effects on the UI of applications such as Query Console and the Monitoring Dashboard:

The first time a user navigates to one of the built-in MarkLogic applications, MarkLogic displays the following dialog. The text comes from the ui-message configuration element.
After the user dismisses the dialog, the configured banner is displayed at the top of the application page. The text comes from the ui-label configuration element, and the banner colors come from the ui-header-color and ui-header-text-color elements.
When no UI customization is active, no banner is displayed.

Configuration Reference

The /cluster-ui-settings.xml document in the App-Services database must have the following structure. All elements are required.

<env-ui:environment-ui xml:lang="zxx" 
    xmlns:env-ui="http://marklogic.com/environment-ui">
  <env-ui:ui-active>boolean</env-ui:ui-active>
  <env-ui:ui-label>banner_text</env-ui:ui-label>
  <env-ui:ui-header-color>color_code</env-ui:ui-header-color>
  <env-ui:ui-header-text-color>color_code</env-ui:ui-header-text-color>
  <env-ui:ui-message>notification_dialog_text</env-ui:ui-message>
</env-ui:environment-ui>

The following table describes the child elements in more detail:

Element Local Name	Description
`ui-active`	Set to true for the configuration to take effect. Set to false to return to the default behavior (no notification dialog or banner).
`ui-label`	Text to be displayed in the banner.
`ui-header-color`	The background color of the banner.
`ui-header-text-color`	The color of the message text in the banner.
`ui-message`	The message to be displayed in the notification dialog box. The message is displayed to user only once (per host from which the user connects to the cluster), unless you update the configuration with a new message.

Example: Creating a New Configuration Document

Use this example to create an entirely new configuration document, rather than replacing just a portion of the existing configuration. For incremental changes, see the remaining examples.

Follow this procedure to create a new configuration using the template configuration that is installed with MarkLogic. Note that the template configuration is not active by default.

Read the template configuration from the App-Services database to get a baseline for your changes. To read the default configuration:
```
xquery version "1.0-ml";
fn:doc('/cluster-ui-settings.xml')
```
Modify the configuration to meet your requirements.

Insert the new configuration into the App-Services database. For example:

xquery version "1.0-ml";
let $new-config := (: YOUR CONFIG ELEM HERE :)
return xdmp:document-insert('/cluster-ui-settings.xml', $new-config)

Navigate to one of the built-in MarkLogic applications to observe your changes. For example, navigate to Query Console (http://host:8000/qconsole). If you already had one of the applications open in your browser, reload the page.

If you do not get a dialog or see the banner, there is likely an error in your configuration. MarkLogic validates your configuration against the schema in INSTALL_DIR/Config/environment-ui.xsd.

Example: Activate/Deactivate a Configuration

Use the following script to activate or deactivate a configuration. Run the script in Query Console against the App-Services database.

xquery version "1.0-ml";
declare namespace env-ui = "http://marklogic.com/environment-ui";

(: Set this var to false to deactivate, true to activate :)
let $state := fn:false()
let $env-ui-node := 
  fn:doc('/cluster-ui-settings.xml')/env-ui:environment-ui
return 
  if (exists($env-ui-node)) then
    xdmp:node-replace(
      $env-ui-node/env-ui:ui-active, 
      <env-ui:ui-active>{$state}</env-ui:ui-active>)
  else ()

(: Reload Query Console to see your changes :)

Example: Modify the Notification Dialog Text

Use the following script to change the text displayed in the notification dialog box. Changing the text causes the dialog to be displayed to users the next time they navigate to one of the built-in MarkLogic applications.

Run this script in Query Console against the App-Services database.

xquery version "1.0-ml";
declare namespace env-ui = "http://marklogic.com/environment-ui";

(: Set this variable to your new notification :)
let $new-message := "This is your new message."
let $env-ui-node := 
  fn:doc('/cluster-ui-settings.xml')/env-ui:environment-ui
return 
  if (exists($env-ui-node)) then
    xdmp:node-replace(
      $env-ui-node/env-ui:ui-message, 
      <env-ui:ui-message>{$new-message}</env-ui:ui-message>)
  else ()

(: Reload Query Console to see your changes. :)

When you reload Query Console, the notification dialog box should be displayed. It should contain your new message.

Example: Modify the Banner Text

Use the following script to change the text in the banner that appears at the top of each built-in MarkLogic application page. Run the script in Query Console against the App-Services database.

xquery version "1.0-ml";
declare namespace env-ui = "http://marklogic.com/environment-ui";

(: Set this variable to your new banner label :)
let $new-label := "This is your new banner text."
let $env-ui-node := 
  fn:doc('/cluster-ui-settings.xml')/env-ui:environment-ui
return 
  if (exists($env-ui-node)) then
    xdmp:node-replace(
      $env-ui-node/env-ui:ui-label, 
      <env-ui:ui-label>{$new-label}</env-ui:ui-label>)
  else ()

(: Reload Query Console to see your changes. :)