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

Administrator's Guide — Chapter 6

Groups

This chapter describes groups in MarkLogic Server, and includes the following sections:

This chapter describes how to use the Admin Interface to create and configure groups. For details on how to create and configure groups programmatically, see Creating and Configuring Groups in the Scripting Administrative Tasks Guide.

Overview of Groups

The basic definitions for group, host, and cluster are the following:

  • A group is a set of similarly configured hosts within a cluster.
  • A host is an instance of MarkLogic Server running on a single machine.
  • A cluster is a set of hosts that work together.

For single-node configurations, you can only use one group at a time (because there is only one host). For clusters configurations with multiple hosts, you can have as many group configurations as makes sense in your environment.

Groups allow you to have several configurations, each of which applies to a distinct set of hosts. Different configurations are often needed when different hosts perform different tasks, or when the hosts have different system capabilities (disk space, memory, and so on). In cluster configurations, 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).

HTTP, ODBC, XDBC, and WebDAV servers are defined at the group level and apply to all hosts within the group. Schemas and namespaces can also be defined at the group level to apply group-wide.

The Configure tab of the Group Administration section of the Admin Interface enables you to define configuration information for memory settings, SMTP server settings, and other configuration settings. The values for the settings are set at installation time based on your system memory configuration at the time of the installation. For a description of each configuration option, see the Help tab of the Group Administration section of the Admin Interface.

Example

The relationships between a cluster, a group and a host in MarkLogic Server may be best illustrated with an example.

In this example, each machine is set up as a host within the example cluster. Specifically, hosts E1, E2 and E3 belong to a group called Evaluator-Nodes. They are configured with HTTP servers and XDBC servers to run user applications. All hosts in the Evaluator-Nodes group have the same MarkLogic Server configuration.

Hosts D1, D2 and D3 belong to a group called Data-Nodes. Hosts in the Data-Nodes group are configured with data forests and interact with the nodes in the Evaluator-Nodes group to service data requests. See the sections on databases, forests and hosts for details on configuring data forests.

For more information about clusters, see the Scalability, Availability, and Failover Guide.

If you are administering a single-host MarkLogic environment, the host is automatically added to a Default group during the installation process. You will only have one host in the group and will not be able to add other hosts to the group.

Procedures for Configuring and Managing Groups

The following procedures describe how to create and manage groups in MarkLogic Server:

Creating a New Group

To create a new group, perform the following steps:

  1. Log into the Admin Interface.
  2. Click the Groups icon on the left tree menu.
  3. Click the Create tab on the Group Summary page. The Create Group page displays.

  1. Go to the Group Name field and enter a short hand name for the group.

    MarkLogic Server will use this name to refer to the group.

  2. You can change the value of List Cache Size, Compressed Tree Cache Size and Expanded Tree Cache Size or leave the defaults. They specify the amount of memory dedicated to caching term list, tree data in compressed form and tree data in expanded form.
  3. System Log Level specifies the minimum log level messages sent to the operating system. Log levels are listed in decreasing level of log details. You may change the system log level or leave it at the default level.
  4. File Log Level specifies the minimum log level messages sent to the log file. Log levels are listed in decreasing level of log details. You may change the file log level or leave it at the default level.
  5. The Rotate Log Files field specifies how often to start a new log file. You may change this field or use the default value provided.
  6. The Keep Log Files field specifies how many log files are kept. You may change this field or use the default value provided.
  7. Set Failover Enable to true if you want to enable failover for the hosts in the group. To use failover, you must also enable failover for individual forests. If you set Failover Enable to false, failover is disabled for all the hosts in the group, regardless of their forest configurations.
  8. The SSL Enabled option and XDQP SSL Ciphers field are to enable SSL for XDQP.
  9. Click OK.

    For information about auditing, including how to configure various audit events, see Auditing Events.

Adding a group is a 'hot' administrative task; the changes are reflected immediately without a restart.

Viewing Group Settings

To view the settings for a particular group, perform the following steps:

  1. Log into the Admin Interface.
  2. Click the Groups icon on the left tree menu.
  3. Click the Configure tab at the top right.
  4. Locate the group for which you want to view settings.
  5. Click the icon for this group.
  6. View the settings.

Deleting a Group

You must drop all hosts assigned to a group before you can delete a group. To delete a group, perform the following steps:

  1. Log into the Admin Interface.
  2. Click the Groups icon on the left tree menu.
  3. Click the Configure tab at the top right.
  4. Locate the Group to be deleted.
  5. Click on Hosts to check that there is no host assigned to the group. All hosts assigned to a group must be dropped before the group can be deleted. Dropping a host from a group does not drop the host from the cluster.
  6. Click the icon for this group again.
  7. Click Delete. Deleting a group deletes it from the system.
  8. A confirmation message displays. Click OK to permanently delete the group.

Deleting a group is a hot operation; the server does not need to restart to reflect your changes.

Enabling SSL communication over XDQP

To enable encrypted SSL communication between hosts in the group, set xdqp ssl enabled to true. All communications to and from hosts in the group will be secured, even if the other end of the socket is in a group that does not have SSL enabled.

The SSL keys and certificates used by the hosts are automatically generated when you install or upgrade MarkLogic Server. No outside authority is used to sign certificates used between servers communicating over the internal XDQP connections in a cluster. Such certificates are self-signed and trusted by each server in the cluster.

For details on configuring SSL communication between web browsers and App Servers, see Configuring SSL on App Servers. For details on configuring FIPS 140-2 mode for SSL communication, see OpenSSL FIPS 140-2 Mode.

The following screen capture shows the options related to configuring SSL for intra-cluster XDQP communication.

Configuring an SMTP Server

The installation process configures an SMTP server based on the environment at installation time. A single SMTP server is configured for all of the hosts in a group. The SMTP configuration is used when applications use the xdmp:email function.

To change the SMTP server or the SMTP timeout for the system (the time after which SMTP requests fail with an error), perform the following steps:

  1. Log into the Admin Interface.
  2. Click the Groups icon on the left tree menu.
  3. Click the Configure tab at the top right.
  4. In the SMTP Relay field, enter the hostname for your SMTP server.
  5. In the SMTP Timeout field, enter the time (in seconds) after which requests will time out.
  6. Click OK.

Changing any SMTP settings is a hot operation; the server does not need to restart to reflect your changes.

Restarting All Hosts in a Group

Perform the following steps to restart all the hosts in a group from the Admin Interface:

  1. Click the Groups icon on the left tree menu.
  2. Click the name of the group you want to restart, either from the menu tree of from the Group Summary page.
  3. Click the Status tab on the top right.
  4. Click Restart.
  5. A confirmation message displays while restarting. Click OK to restart all of the hosts in the MarkLogic Server group.

    The restart operation normally completes within a few seconds. It is possible, however, for it to take longer under some conditions (for example, if the Security database needs to run recovery or if the connectivity between hosts in a cluster is slow). If it takes longer than a few seconds for MarkLogic Server to restart, than the Admin Interface might return a 503: Service Unavailable message. If you encounter this situation, wait several seconds and then reload the Admin Interface.

« Previous chapter
Next chapter »