Loading TOC...
Administrator's Guide (PDF)

Administrator's Guide — Chapter 6

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

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

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:

  1. Log into the Admin Interface.
  2. Click the Clusters icon on the left tree menu.
  3. Select the local cluster. The Edit Local Cluster Configuration page appears.

  1. To configure FIPS 140-2 mode, select true or false as needed. For SSL FIPS Enabled, select true.
  2. 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:

  1. Click Clusters in the left navigation tree and click the name of the cluster you want to configure.
  2. When the page opens, click configure to navigate to the Edit Local Cluster Configuration page.

  3. Use the drop-down menus to configure encryption for data, config files, and/or log files.
    SettingDescription
    data encryptionSpecifies whether or not encryption is enabled for user data. The force option will force encryption for all data in the cluster. The database configuration cannot overwrite this setting. The default-on option will defer to encryption on. The database configuration can overwrite this setting. The default-off option will defer to encryption off. The database configuration can overwrite this setting.
    config encryptionSpecifies whether or not encryption is enabled for configuration files
    logs encryptionSpecifies whether or not encryption is enabled for log files.
    Key Management Service (KMS)

    Specifies whether the 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

  4. Click ok when you are done.

To configure an external KMS, do the following:

  1. Select external in the Key Management Service (KMS) field.

  2. Enter the following information to identify the external KMS and the required encryption keys.
    SettingDescription
    host nameThe host name of the Key Management Server (KMS).
    portThe KMS client socket port number.
    data encryption key idThe encryption key at the KMS to encrypt user data.
    config encryption key idThe encryption key at the KMS to encrypt configuration files.
    logs encryption key idThe 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
  3. Click ok when you are done.

Coupling Clusters

You can use the Admin Interface to couple local and foreign clusters to enable inter-cluster communication. To replicate a database from one cluster to a database in another cluster, the two clusters must be coupled. For information on how inter-cluster communication relates to database replication, see the Database Replication Guide. For details, on coupling clusters specifically, see Coupling the Local and Foreign Clusters in the Database Replication Guide.

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

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:

  1. 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.

  2. 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 LocalnameDescription
ui-activeSet to true for the configuration to take effect. Set to false to return to the default behavior (no notification dialog or banner).
ui-labelText to be displayed in the banner.
ui-header-colorThe background color of the banner.
ui-header-text-colorThe color of the message text in the banner.
ui-messageThe 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 configuraton 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.

  1. 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')
  2. Modify the configuration to meet your requirements.
  3. 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)
  4. 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. :)

« Previous chapter
Next chapter »
Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy