MarkLogic 9 Product Documentation

Administrator's Guide — Chapter 22

Adding a Host to a Cluster

This only applies for multi-host clusters. For information about installing MarkLogic and a more detailed procedure about joining a cluster, see the Installation Guide.

To add a host to a cluster, perform the following steps using the Admin Interface:

1. Install MarkLogic Server on the host if it is not already installed.
2. Start MarkLogic Server.
3. Access the Admin Interface on the host in which you want to add to the cluster and accept the license agreement.
4. After the server restarts, you will be prompted to join a cluster.

   

5. Enter the DNS name or the IP address of one of the machines in the cluster. For example, if this is the second host you are installing, you can enter the DNS name of the first host you installed.
6. You will be prompted for an admin username and password. Enter the admin username and password for the security database used by the cluster. Click OK.
7. Select a Group to assign this host. Click OK.
8. Click OK to confirm that you are joining the cluster.
9. Click OK for the confirmation message that indicates that you have joined the cluster.

Changing the Group of the Host

To change the group to which a host belongs, perform the following steps using the Admin Interface:

1. Click the Hosts icon in the left tree menu.
2. Click the name of the host you want to change, either on the tree menu or the summary page.
3. Select from the available groups in the Group drop-down menu.
4. Click OK to confirm the change.

Changing the group to which a host belongs is a cold task; the server restarts to reflect the changes.

Shutting Down or Restarting a Host

To shut down or to restart a host, perform the following steps:

1. Click the Hosts icon on the left tree menu.
2. Click the name of the host you want to shut down or restart, either on the tree menu or the summary page.
3. Click the Status tab at the top right.
4. Click the Shutdown or the Restart button as appropriate.
5. Click OK to confirm to confirm the shutdown or restart operation.
6. If you have forest failover enabled for any of the host forests, you will see a Immediately fail over forests to replica hosts option. Check the box to fail over the forests to replica hosts.

   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.

Clearing a Forest on a Host

Clearing a forest on a host permanently deletes the data in the forest. The configuration information of the forest will be preserved. For example, you may want to clear the forest if you want to load new data into the same configuration.

To clear the data from a forest, perform the following steps using the Admin Interface:

1. Click the Hosts icon on the left tree menu.
2. Click the name of the host which contains the forest you want to clear, either on the tree menu or the summary page.
3. Click the Forests icon under the selected host.
4. Click the Clear button corresponding to the forest you want to clear.
5. Click OK to confirm clearing the data from the forest.

Deleting a Forest on a Host

Deleting a forest on a host permanently deletes the data in the forest as well as the configuration information. A forest cannot be deleted if it is still attached to a database. You must first detach the forest from the database before you can delete from a host.

Assuming that the forest is not attached to any database, perform the following steps to delete a forest from a host.

1. Click the Hosts icon on the left tree menu.
2. Click the name of the host which contains the forest you want to delete, either on the tree menu or the summary page.
3. Click the Forests icon under the selected host.
4. Click on the Delete button corresponding to the forest you want to delete.
5. Click OK to confirm deleting the forest from the host.

   

6. Click the Delete button.
7. Click OK to confirm dropping the host.

Deleting a host is a hot admin task for the other hosts in the group.

Leaving the Cluster

A host has to leave a cluster first to be moved to another cluster. Leaving a cluster is also a way to switch a host from a single host environment to a multi-host environment or vice versa. A host cannot leave a cluster if there are still forests assigned to it or if it has any foreign clusters associated with it; you must delete all forests assigned to the host and de-couple any clusters associated with a host before you can leave the cluster. In a single-host environment, a host cannot leave a cluster because it will always have forests assigned to it.

Perform the following steps to make a host leave a cluster:

1. Access the Admin Interface from any host in the cluster.
2. Click on the Hosts icon in the left tree menu.
3. Click on the name of the host you want to remove from the cluster. The host configuration screen appears:

   

4. Click on the Leave button.
5. Click OK to confirm leaving the cluster.
6. The host restarts to load the new configuration.
7. Click OK to self-install initial databases and application servers.
8. You will be prompted to join a cluster.
9. To join another cluster, enter the name of one of the hosts in that cluster and click OK. Otherwise, click Skip.
10. Set up an admin user name and password if prompted.
11. Log in with the admin user name and password if prompted.

You should see the Admin Interface.

Displaying License Options

In addition to the features that come standard in MarkLogic, there are optionally licensed features that you may want to take advantage of for more advanced projects.

To display the license options for a host, perform the following steps using the Admin Interface:

1. Click the Hosts icon on the left tree menu.
2. Click the name of the host in which contains you want to change the license key, either on the tree menu or the summary page. The Host Configuration page appears.
3. Click the Status tab. The Host Status page appears.
4. The License Options are listed in the Options field.

Changing the License Key For a Host

At any time, you can change the license key for a host from the Host Status page. You might need to change the license key if your license key expires, if you need to use some features that are not covered in your existing license key, if you upgrade your hardware with more CPUs and/or more cores, if you need a license that covers a larger database, if you require different languages, or for various other reasons. Changing the license key sometimes results in an automatic restart of MarkLogic (for example, if your new license enables a new language).

To change the license key for a host, perform the following steps using the Admin Interface:

1. Click the Hosts icon on the left tree menu.
2. Click the name of the host in which contains you want to change the license key, either on the tree menu or the summary page. The Host Configuration page appears.
3. Click the Status tab. The Host Status page appears.
4. Click the License Key button. The License Key Entry page appears.
5. Enter your new license key information. For information about licensing of MarkLogic Server, contact your MarkLogic sales representative.
6. After entering valid information in the Licensee and License Key fields, click OK. If it needs to, MarkLogic will automatically restart, and the new license key will take effect.

   Any optionally licensed features enabled by your license key appear in the License Key Options field.

Rolling Back a Transaction

Use Host Status page of the Admin Interface to rollback stalled or long-running transactions, discarding any updates made by the transaction. The Host Status page includes a list of transactions which have started but not yet completed.

To rollback the MarkLogic Server portion of a prepared XA transaction, see Rolling Back a Prepared XA Transaction Branch.

To rollback a transaction using the Admin Interface, complete the following steps:

1. Open the Admin Interface in your browser by navigating to http://yourhost:8001.
2. Click Hosts in the left tree menu. The tree expands to show available hosts.
3. Click the name of the target host in the left tree menu. The configuration view for the host appears.
4. Click the Status tab at the top of the page. The status view for the host appears.
5. Locate the target transaction in transaction list. If you do not see a transaction list on the status page, then there are no open transactions on this host.
6. Click [rollback] next to a transaction to initiate a transaction rollback. For example:

   

   A confirmation dialog appears.

7. Click OK to confirm the rollback. The host status page appears.

There may be a slight delay between when a rollback is initiated and when the transaction terminates. During this period, the transaction still appears on the host status page, with a transaction status of awaiting rollback.