MarkLogic 9 Product Documentation

Administrator's Guide — Chapter 5

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. Click the Configure tab to open the Edit Local Cluster Configuration page.

   

4. To configure FIPS 140-2 mode, select true or false as needed. For SSL FIPS Enabled, select true.
5. 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. Click the Keystore tab to open the Edit Keystore Configuration page.

   

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

4. Click ok when you are done.

To configure an external KMS, do the following:

1. Select the External KMS tab.

   

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

3. Click ok when you are done.

Configuring Ops Director

You can use the Admin Interface to designate the cluster as either an Ops Director Application Cluster or a Managed Clusters. An Ops Director Application Cluster can serve as both an Application Cluster and a Managed Cluster. For details on configuring a cluster for Ops Director, see Installing and Configuring Ops Director in the Ops Director Guide.

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 the each local cluster to be coupled with foreign clusters.

1. On the local host, select Local Cluster under Clusters at the bottom of the left-hand menu:

   

2. Select the Configure tab to display the Edit Local Cluster Configuration page. Enter the cluster name:

   

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

   

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

5. In the Local Cluster Configuration page, select the Couple tab.

   

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

   

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

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

   

9. Click OK for any subsequent validate screens.
10. When validation is conplete, 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.

    

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:

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. :)