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:
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.
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.
The following procedures describe how to configure clusters in MarkLogic Server:
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:
true
or false
as needed. For SSL FIPS Enabled, select true
.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:
To configure an external KMS, do the following:
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
06ea22c9-b972-4652-8d0f-9e58c62e0f7f
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:
For more about MarkLogic encryption at rest and the internal KMS, see Configuring Encryption at Rest in the Encryption chapter of the Security Guide.
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:
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.
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.
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.
https
. Click Ok and the Foreign Cluster Configuration page appears.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. |
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:
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:
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:
ui-message
configuration element.ui-label
configuration element, and the banner colors come from the ui-header-color
and ui-header-text-color
elements.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:
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.
xquery version "1.0-ml"; fn:doc('/cluster-ui-settings.xml')
xquery version "1.0-ml"; let $new-config := (: YOUR CONFIG ELEM HERE :) return xdmp:document-insert('/cluster-ui-settings.xml', $new-config)
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
.
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 :)
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.
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. :)