Loading TOC...
Ops Director Guide (PDF)

Ops Director Guide — Chapter 2

Installing and Configuring Ops Director

Ops Director provides system monitoring, management, analysis, and support capabilities, as well as license auditing and role-based access control (RBAC) management, to system administrators. Ops Director‘s web-based interface offers graphical and tabular data representation intended to highlight irregular performance or alerts on a given cluster, host, database, or application server. Follow instructions in this chapter for installing and configuring Ops Director.

This chapter covers the following topics:

System Requirements

Ops Director requires that you have MarkLogic Server Version 9.0-3 or later running on the Application Cluster and MarkLogic Server Version 9.0-2 or later on the Managed Clusters. When a cluster is configured to be managed by Ops Director, a SecureManage App Server is created with SSL enabled.

In general, the hardware requirements for Ops Director are the same as those described in Memory, Disk Space, and Swap Space Requirements in the Installation Guide. However, it is recommended that you have at least 32 GB of memory on a host where Ops Director application runs.

Installing Ops Director on an Application Cluster

Ops Director is an application built on top of MarkLogic Server and running on a designated MarkLogic cluster called Ops Director Application Cluster. Managed Clusters will later be connected to the Ops Director Application Cluster. An Ops Director Application Cluster can serve as both an Application Cluster and a Managed Cluster.

The following procedure describes how to install Ops Director on an application cluster.

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

Select the Ops Director tab at the top of the page.

  1. In the Ops Director Setup page, click on install.

  1. In the Install Ops Director page, select Generate new MarkLogic Ops Director certificate from the Ops Director Certificate Authority pulldown menu. Click OK.

This procedure secures inter-cluster communication by means of an internally-generated, self-signed certificate. If you plan to use externally signed certificates, see Securing Ops Director with Externally Signed Certificates.

  1. A Certificate Authority configuration page appears. Fill in the blank fields with all of your relevant information. Click OK.

In most cases, you may leave the default values for all other settings. However, in some cases you have to specify values different from the default ones. In particular, for installation on AWS, it is important to change the forest data directory.

  1. The Ops Director Setup page will be displayed. If you want this cluster to serve as both the Ops Director Application Cluster and as a Managed Cluster, select manage this cluster. Otherwise click OK.

  1. If you opted to have the cluster serve as both the Ops Director Application Cluster and as a Managed Cluster, the Configure as a Managed Cluster page will appear. Enter the name of the local host in this cluster that contains the OpsDirectorApplication and OpsDirectorSystem application servers. Set the port number for the OpsDirectorSystem server (8009, be default) and select MarkLogic Ops Director Certificate Authority from the Ops Director Certificate Authority pulldown menu.

    Set the level for log messages sent to Ops Director, as well as the frequency at which the metering data is collected. For details on the log levels, see Understanding the Log Levels in the Administrator's Guide.

    In order to set the log interval filter in Ops Director to Raw, as described in Date and Time Filters, you must also set the Ops Director Metering to raw here in the Admin Interface.

    When finished, Click OK.

  1. The Configuration page will now display all of the resources created by installing Ops Director. The resources created are summarized in the table below.

The following resources are created on the host where your Ops Director application runs.

Resource TypeResource Name and Function
Certificate Authority The Certificate Authority (MarkLogic Ops Director in this example) is used to generate the secure credentials required for the Ops Director application and Managed Clusters to securely communicate.
Certificate Templates

OpsDirector-SSL-Template for SSL on the Application Cluster.

OpsDirector Template for SSL, if also configured as a Managed Cluster.

Roles

opsdir-guest role is used for a default user of the Ops Director application.

opsdir-user role is required for any user to be able to access the Ops Director application.

opsdir-license-admin role grants a user rights to manage licenses for the Ops Director application.

opsdir-admin role grants a user administrative rights to the Ops Director application.

Execute Privileges

opsdir-admin protects administrative functions.

opsdir-license-admin is required to access license information.

opsdir-user is required to access the browser application.

Database and ForestsThe OpsDirector database and forests hold the Ops Director configuration data.
App Servers

OpsDirectorApplication (port 8008) provides the Ops Director browser application and consumes the data stored in the OpsDirector database.

OpsDirectorSystem (port 8009) receives data transmitted from Managed Clusters and stores it in the OpsDirector database.

External Security Configurations

OpsDirector-External-Security for authentication of clients.

OpsDirectorSystem for secure communication with OpsDirectorSystem server.

Secure Credentials

OpsDirector-Credential to sign OpsDirector-SSL-Template.

MarkLogic-OpsDirector for accessing OpsDirectorSystem server.

Connecting a Managed Cluster to Ops Director

The following procedure describes how to configure a cluster to be managed by Ops Director.

Before you log into the cluster to be managed, you must copy the value of Ops Director Certificate Authority field in the Admin Interface from the host where Ops Director is installed to a host of your Managed Cluster.

The above operation of copying the value of Ops Director Certificate Authority field from the host where Ops Director is installed to a host of your Managed Cluster can also be scripted with the REST Management API.

  1. On the host where Ops Director is installed, make sure that MarkLogic Server is running, open Admin Interface, and click on Clusters in the left tree menu.
  2. Select the local cluster. The Edit Local Cluster Configuration page appears. Select the Ops Director tab to display the Ops Director Setup page.
  3. Scroll down to the Ops Director Certificate Authority section and copy the certificate by selecting everything between and including -----BEGIN CERTIFICATE----- and -----END CERTIFICATE-----.

Log on to a host on the cluster to be managed by Ops Director and do the following:

  1. Log into the Admin Interface.
  2. Click Security on the left tree menu.
  3. Select Certificate Authorities.
  4. Select the Import tab at the top of the Summary page.
  5. Paste the certificate copied from the host where Ops Director is installed.
  6. Click OK.

  1. Click Clusters on the left tree menu.
  2. Select the local cluster. The Edit Local Cluster Configuration page appears.
  3. Select the Ops Director tab at the top of the page.
  4. The Ops Director Setup page will be displayed. Select manage this cluster.

  1. The Configure as a Managed Cluster page will appear. Enter the name of the host where your Ops Director application runs, i.e. the host you set up in Installing Ops Director on an Application Cluster.
  2. Select MarkLogic Ops Director Certificate Authority from the Ops Director Certificate Authority pulldown menu.

    Set the level for log messages sent to Ops Director, as well as the frequency at which the metering data is collected. For details on the log levels, see Understanding the Log Levels in the Administrator's Guide.

    When finished, click OK.

  1. The Ops Director Setup page will be displayed. Click OK.

When you designate a Managed Cluster, a SecureManage App Server is created on each of its hosts to manage the secure connections with the Ops Director Application Cluster.

Launching the Ops Director Application

In a browser window, enter the hostname of the host where Ops Director runs and the port number of the OpsDirectorApplication server (by default, 8008). For example:

https://englab.marklogic.com:8008

Logging into Ops Director

To log into Ops Director, enter a valid user name and password.

User in this context means an existing MarkLogic user, with the opsdir-admin role, whether that user credential comes from LDAP or internal security. If internal security is used, the user must exist on the Ops Director Application Cluster.

Customizing the Email Address on Login Page

Ops Director does not provide a GUI to add/edit/delete the email address. The user with admin privileges (or equivalent role) should insert a document with URI /email.json with read permissions for users with the opsdir-guest role into OpsDirector database.

The easiest way to achieve this is to execute the following code in Query Console:

declareUpdate();
xdmp.documentInsert("/email.json", 
   {emailAddress: "support@marklogic.com"}, 
   {permissions: xdmp.permission("opsdir-guest", "read")});

Configuring the Ops Director Data Retention Policy

The following data accumulates in the OpsDirector database:

  • Meters data
  • Log files
  • Configuration data of managed clusters
  • System alerts

Ops Director has a built-in auto-cleanup mechanism to delete accumulated data periodically.

Once a day, at 11:00 PM local time, a task runs to delete accumulated Ops Director data based on the defined data retention policy. By default, all types of data -- meters, logs, cluster configuration data, and system alerts -- will be retained for 60 days.

The default data retention period for each type of data is defined in the configuration file /config/opsdirector.xml stored in the OpsDirector database. You may retrieve content of this file as described below.

Open Query Console on the host where Ops Director runs: http://<hostname>:8000/qconsole/

In the Query Console, set Query Type to XQuery and Database to OpsDirector.

Execute the following code:

xquery version "1.0-ml";
doc("/config/opsdirector.xml")

In the response, look for the following elements:

  • max-meters-age -- specifies the maximum age for meters data;
  • max-logs-age -- specifies the maximum age for log files;
  • max-resource-age -- specifies the maximum age for cluster configuration data and system alerts.

By default, the maximum age for each class of data is set to 60 days, as in the example below:

<config xmlns="http://marklogic.com/v1/opsdirector/config">
  <max-meters-age>P60D</max-meters-age>
  <max-logs-age>P60D</max-logs-age>
  <max-resource-age>P60D</max-resource-age>
</config>

You can modify the default data retention period as follows: edit the configuration file /config/opsdirector.xml and replace default P60D values with other values of type xs:dayTimeDuration, which will define your preferred data retention periods for corresponding data classes.

For details on xs:dayTimeDurationdata type, see.

Ops Director includes a utility library to safely change values in the configuration file. You can see its usage in the example below.

For example, to retain meters data and log files for 30 days only, execute the following query on the OpsDirector database:

xquery version "1.0-ml";

import module namespace
   config="http://marklogic.com/v1/opsdirector/config"
      at "/MarkLogic/opsdirector/config.xqy";

let $expire := xs:dayTimeDuration("P30D")
for $property in ("max-meters-age", "max-logs-age")
   return
      config:set-atomic-property($property, $expire);

If you want a certain class of data to be stored forever, you may set the data retention period for that class to infinity in the configuration file /config/opsdirector.xml. However, this setting will cause the OpsDirector database to grow ever larger as data accumulates. Make sure that you have sufficient capacity to handle this growth.

Disconnecting a Managed Cluster from Ops Director

A Managed Cluster can be disconnected from Ops Director. Once disconnected, the Managed Cluster stops sending configuration, metrics, and log data to the Ops Director cluster.

Ops Director will continue to make Management API calls to assess the cluster health as long as there is a valid session for that cluster. After the session expires, Ops Director will stop making calls and the disconnect will be complete.

The procedure for disconnecting a Managed Cluster from Ops Director is as follows:

  1. Log into the Admin Interface on the Managed Cluster.
  2. Click Clusters on the left tree menu.
  3. Select the local cluster. The Edit Local Cluster Configuration page appears.
  4. Select the Ops Director tab at the top of the page.
  5. In the Ops Director Setup page click on stop managing this cluster.

  1. In the Stop Managing this Cluster page check the Remove Ops Director Certificate Authority box and click OK.

If you plan to have this cluster managed again by the same instance of Ops Director at some point in the future, you may leave the certificate authority installed, i.e. leave the Remove Ops Director Certificate Authority box unchecked.

Removing Ops Director

This section describes how to remove the Ops Director application. Before removing Ops Director, you should disconnect the Managed Clusters, as described in Disconnecting a Managed Cluster from Ops Director.

The following procedure described how to remove Ops Director from the MarkLogic host.

  1. Log into the Admin Interface.
  2. Click Clusters on the left tree menu.
  3. Select the local cluster. The Edit Local Cluster Configuration page appears.
  4. Select the Ops Director tab at the top of the page.
  5. In the Install Ops Director section, click on uninstall.

Running Ops Director on Amazon Web Services (AWS)

When AWS hosts are stopped and restarted, they are assigned new host names and new IP addresses. They do not get new MarkLogic host ids, as those are persistent. Ops Director will recover from AWS host renaming under the following circumstances:

  • If a Managed Cluster host is renamed, when Ops Director receives information from it, the fact that an existing host id has appeared with a new host name will be used to update the Ops Director configuration. At that point, things return to normal.
  • If an Ops Director host is renamed, the Managed Cluster will be unable to communicate with it. But the next time Ops Director polls that Managed Cluster, it will detect that out-of-date session endpoint and update it. At that point, things return to normal.

However, if you stop both the Ops Director host and the Managed Cluster hosts at the same time, then all hosts will come back with new host names and there's no way to fix the problem automatically.

You can fix the problem with a script. For example, Ops Director used to be AMAZONOLD and now it's AMAZONNEW. On the Managed Cluster(s) that are still trying to talk to AMAZONOLD, use the following script in Query Console to fix them:

xquery version "1.0-ml";
import module namespace admin = "http://marklogic.com/xdmp/admin"
      at "/MarkLogic/admin.xqy";

let $config := admin:get-configuration() 
let $config := admin:cluster-set-opsdirector-session-endpoint($config,
               "https://AMAZONNEW:8009/v1/opsdirector/session")

return
    admin:save-configuration($config)

Securing Ops Director with Externally Signed Certificates

The procedures described in Installing Ops Director on an Application Cluster make use of an internally-generated, self-signed certificate. This section describes how to configure Ops Director to use externally signed certificates. Some of the steps are scripted, some rely on the use of the Admin Interface.

The topics in this section are:

Prerequisites for External Certificate Usage

In order to use externally signed certificates, you must obtain them for each host, as described in Procedures for Obtaining a Signed Certificate in the Security Guide and summarized below.

  1. Create Certificate Signing Requests (CSRs) for each host involved.
  2. Send these CSRs off to be signed by an external authority; you need the authority to return server certificates for each host.
  3. Create a CSR for the Ops Director credential. Instead of using a hostname as the template name, use the word OpsDirector, or some other unambiguous description of the certificate.
  4. Send the Ops Director credential off to be signed by an external authority; you need the authority to return a client certificate for this CSR.

You need server certificates for each host and the corresponding private keys (generated at or before step 1, above) and the client certificate for Ops Director CSR and its corresponding private key.

If the signing authority is Verisign or Thawte or another well established authority, then MarkLogic will already have the appropriate Certificate Authority installed. If you are using a less well-known authority, you must install the appropriate Certificate Authority on each MarkLogic cluster.

Import an External Certificate into Ops Director Application Cluster

Do the following on the Ops Director Application Cluster:

This procedure requires that you have the admin role.

  1. Log into the Admin Interface on the host where Ops Director application runs.
  2. Click Clusters on the left tree menu.
  3. Select the local cluster. The Edit Local Cluster Configuration page appears.
  4. Select the Ops Director tab at the top of the page.
  5. Click Install Ops Director and select Use externally signed certificates.

  1. In the Certificate Templates page of the Admin Interface, create a certificate template named OpsDirector-SSL-Template, as described in Creating a Certificate Template in the Security Guide. The values you enter in the subject, such as organizationName and organizationalUnitName, must match the values in the signed certificate from the certification authority.
  2. Import the signed certificate and private key from the certification authority into the Ops Director cluster host, as described in Importing a Signed Certificate into MarkLogic Server in the Security Guide.
  3. In the External Security page of the Admin Interface, create an external security configuration named OpsDirectorSystem, as described in Creating an External Authentication Configuration Object in the Security Guide. Use certificate authentication and select the appropriate ssl client certificate authority.
  4. Update the configuration of the OpsDirectorSystem server to use the OpsDirectorSystem external security object, as described in Configuring an App Server for External Authentication in the Security Guide.
  5. Create a secure credential for accessing the managed cluster, as described in Creating Secure Credentials from a Certificate Authority in the Security Guide. The credential must be named opsdir-{cluster-id}. For example: opsdir-14824388627490821138.
  6. Create a user called opsdirector-system-user, as described in Creating a User in the Administrator's Guide. The external name of the user must match the subject of the Ops Director client certificate using the format:
    C=country,ST=state,L=locality,O=organization,CN=unit

    For example:

    C=US,ST=CA,L=San Carlos,O=MarkLogic Corporation,CN=OpsDirector

Import an External Certificate into Managed Clusters

Do the following on each Managed Cluster:

This procedure requires that you have the admin role.

  1. Log into the Admin Interface on the host that contains SecureManage App Server.
  2. Click Security on the left tree menu.
  3. Select Certificate Templates.
  4. Select the Create tab at the top of the page.
  5. In the Create Certificate Templates page, create a certificate template named OpsDirector Template, as described in Creating a Certificate Template in the Security Guide. Make sure that the values you enter in the subject match the values in the signed certificate from the certification authority.
  6. Import the signed certificate and private key from the certification authority into each host in the managed cluster, as described in Importing a Signed Certificate into MarkLogic Server in the Security Guide.
  7. In the External Security page of the Admin Interface, create an external security configuration named OpsDirectorSystem, as described in Creating an External Authentication Configuration Object in the Security Guide. Use certificate authentication and select the appropriate ssl client certificate authority.
  8. Create a secure credential, named MarkLogic-OpsDirector, as described in Secure Credentials in the Security Guide. The target uri pattern must point to the hostname and port where the OpsDirectorSystem server is installed on the Application Cluster. It must use the Ops Director client certificate.
  9. Create a user called opsdirector-system-user., as described in Creating a User in the Administrator's Guide. The external name of the user must match the subject of the Ops Director client certificate using the format:
    C=country,ST=state,L=locality,O=organization,CN=unit

    For example:

    C=US,ST=CA,L=San Carlos,O=MarkLogic Corporation,CN=OpsDirector
  10. In the Admin Interface click Clusters in the left tree menu, select the local cluster, and select the Ops Director tab at the top of the page; click manage this cluster and choose Use externally signed certificates.
« Previous chapter
Next chapter »
Powered by MarkLogic Server 7.0-4.1 and rundmc | Terms of Use | Privacy Policy