Loading TOC...
Ops Director Guide (PDF)

Ops Director Guide — Chapter 2

Installing and Configuring Ops Director

Ops Director provides you with system monitoring, management, analysis, and support capabilities, as well as license auditing and role-based access control (RBAC) management. The Ops Director 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. This chapter contains instructions 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. For definitions of the Application Cluster and Managed Cluster terms, see Terms.

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 runs on a designated MarkLogic cluster called Ops Director Application Cluster. Managed Clusters are 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. Navigate to Configure > Clusters in the left tree menu.
  3. Select the local cluster. The Edit Local Cluster Configuration page displays.

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

  5. On the Ops Director Setup page, click install.

  6. On the Install Ops Director page, select Generate new MarkLogic Ops Director certificate from the Ops Director Certificate Authority 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.

  7. A Certificate Authority configuration page displays. 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.

  8. The Ops Director Setup page displays. 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.

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

    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.

  10. The Ops Director Setup page displays, with the settings configured during the installation of Ops Director.

    Click ok.

  11. The Summary page for the local cluster displays.

    Select the Ops Director tab again. Notice that the About Ops Director description specifies 'Ops Director is currently installed on this cluster'.

    Also, if you opted to have the cluster serve as both the Ops Director Application Cluster and as a Managed Cluster, the description specifies 'Managing 1 cluster'.

  12. Click Configure on the left tree menu. In the right page, select the Summary tab. The Configuration Summary page displays all of the resources created by installing Ops Director.

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

Resource Type Resource 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 Forests The 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.

Do not connect new managed clusters to Ops Director if you started the process of Ops Director upgrade and have not completed it. Adding managed clusters in the middle of Ops Director upgrade can lead to error conditions. For more details, see Upgrade Error Prevention and Troubleshooting.

Before you log into the cluster to be managed, you must copy the value of the Ops Director Certificate Authority field in the Admin Interface from the host where Ops Director is installed to a host of your Managed Cluster. You can either use the REST Management API to script the operation, or you can follow these steps:

  1. On the host where Ops Director is installed, make sure that MarkLogic Server is running, open the Admin Interface, and click Configure > Clusters in the left tree menu.
  2. Select the local cluster. The Edit Local Cluster Configuration page displays. 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 the Admin Interface of a host on the cluster to be managed by Ops Director and do the following:

  1. Select Configure > Security > Certificate Authorities on the left menu.
  2. On the right page, select the Import tab at the top of the Summary page.
  3. Paste the certificate copied from the host where Ops Director is installed.
  4. Click ok.
  1. Select Configure > Clusters on the left tree menu.
  2. Select the local cluster. The Edit Local Cluster Configuration page displays.
  3. Select the Ops Director tab at the top of the page.
  4. The Ops Director Setup page displays. Select manage this cluster.
  1. The Configure as a Managed Cluster page displays. Enter the name of the host where your Ops Director application runs. This is 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 menu.
  3. 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.

  4. The Ops Director Setup page displays. Click ok.

    When you designate a Managed Cluster, a SecureManage App Server is created in each group on the managed cluster to provide secure connections with the Ops Director Application Cluster. For more detail, see Security and Database Dependencies of Managed Clusters.

Launching Ops Director and Logging In

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

You are asked for credentials with a standard authentication dialog box. To log into Ops Director, enter a valid user name and password an existing MarkLogic user with the opsdir-admin role and click Log in.

User credentials can come from LDAP or internal security. If internal security is used, the user must exist on the Ops Director Application Cluster.

By default, Ops Director is configured with digest-based authentication. To enable application-level authentication, perform the steps described in Switching from Digest to Application-Level Authentication.

When you use digest-based authentication, make sure to refresh the Ops Director application in the browser after you log into the application with different credentials, which may have different access to resources than the previous user that was logged-in. If you do not refresh the Ops Director application in the browser, the application may show stale information.

Switching from Digest to Application-Level Authentication

To enable application-level authentication, perform the following steps:

  1. Install SSL certificate on the Ops Director application server, as described in General Procedure for Setting up SSL for an App Server in the Security Guide.
  2. Log into the Admin Interface on the host where the Ops Director application is running.
  3. In the left menu, select Configure > Groups > Default > App Servers > OpsDirectorApplication. On the right page, select the Configure tab.
  4. Scroll down to the authentication menu and change the selection from digest (default) to application-level.

  5. Click ok and wait for the operation to complete.
  6. 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
  7. The Ops Director login screen displays. Enter a valid user name and password and click LOGIN.

    Switching from digest authentication to application-level authentication without first installing an SSL certificate to enable HTTPS on port 8008 presents a security problem because credentials are sent over HTTP as clear text.

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--is 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. Follow these instructions to retrieve the contents of this file.

  1. Open Query Console on the host where Ops Director runs:
    http://<hostname>:8000/qconsole/
  2. On the Query Console, set Query Type to XQuery and Database to OpsDirector.
  3. 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 following example:

<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 to 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. For example, to retain meters data and log files for 30 days only, run the following query on the OpsDirector database:

xquery version "1.0-ml";

declare namespace
   cfg="http://marklogic.com/v1/opsdirector/config";
declare default function namespace
   "http://www.w3.org/2005/xpath-functions";
declare option xdmp:mapping "false";

let $config := doc("/config/opsdirector.xml")/cfg:config
let $_ := if (empty($config))
          then error((), "No config document?")
          else ()

let $expire := xs:dayTimeDuration("P30D")

for $property in ("max-meters-age", "max-logs-age")
let $qname := 
   fn:QName("http://marklogic.com/v1/opsdirector/config", $property)
let $node := $config/*[node-name(.) = $qname]

return
   if (empty($node))
   then xdmp:node-insert-child($config, element { $qname } { $expire })
   else xdmp:node-replace($node/text(), text { $expire })

If you want a specific class of data to be stored forever, set the data retention period for that class to infinity in the configuration file /config/opsdirector.xml. Note that this setting will cause the OpsDirector database to grow 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. Select Configure > Clusters on the left tree menu.
  3. Select the local cluster. The Edit Local Cluster Configuration page displays.
  4. Select the Ops Director tab at the top of the page.
  5. In the Ops Director Setup page, click stop managing this cluster.

  6. On the Stop Managing this Cluster page, select 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 Remove Ops Director Certificate Authority box unchecked.

Removing Ops Director

This section describes how to remove the Ops Director application.

Before you remove Ops Director, disconnect all 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. Select Configure > Clusters on the left tree menu.
  3. Select the local cluster. The Edit Local Cluster Configuration page displays.
  4. Select the Ops Director tab at the top of the page.
  5. In the Install Ops Director section, click uninstall.

  6. The Uninstall Ops Director page displays and asks for confirmation: 'This change will cause a cluster restart. Do you wish to continue?' Click ok.

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. There is no way to fix the problem automatically, but you can fix the problem with a script. In this example, Ops Director used to be AMAZONOLD and now is AMAZONNEW. On each Managed Cluster that is still trying to talk to AMAZONOLD, use the following script on the Query Console:

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.

You may perform these configuration steps either via the Admin Interface or via scripting. In both cases, first you must have your prerequisites ready. For this, follow steps described in Prerequisites for External Certificate Usage

Then, to configure Ops Director to use externally signed certificates via the Admin Interface, perform the steps described in the following sections:

To configure Ops Director to use externally signed certificates via scripting, perform the steps described in the following sections:

Prerequisites for External Certificate Usage

To use externally signed certificates, you must obtain the following externally signed certificates:

  • Server certificates for each host in your enterprise that belong to the Ops Director setup, with the corresponding private keys. This includes all hosts in your Ops Director Application Cluster and all hosts in your Managed Clusters.
  • One client certificate, with the corresponding private key, that you will have to install on one host per cluster in your enterprise. The client certificate will be used for creating the Ops Director secure credential. You may reuse the same client certificate and the corresponding private key for all clusters in your enterprise.

To obtain these certificates, perform the following steps:

  1. Request a server certificate for each host in your enterprise that belong to the Ops Director setup:
    • Create a Certificate Signing Request (CSR) for a server certificate.
    • Use hostname of the host as the common name of the certificate.
    • You may use Open SSL toolkit to generate a CSR.
    • Send this CSR off to be signed by an external Certificate Authority (CA).
    • The authority returns the signed server certificate, with the corresponding private keys.
  2. Request one client certificate for the Ops Director secure credential:
    • Create a Certificate Signing Request (CSR) for a client certificate.
    • Use the word OpsDirector as the common name of the certificate.
    • You may use Open SSL toolkit to generate a CSR.
    • Send this CSR off to be signed by an external Certificate Authority (CA).
    • The authority returns the signed client certificate, with the corresponding private keys.

      If the signing authority is Verisign or Thawte or another well established authority, 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. You can do this via the Admin Interface, from Security / Certificate Authorities page.

Import an External Certificate into Ops Director Application Cluster via the Admin Interface

You may configure Ops Director to use externally signed certificates only during its installation. If you have Ops Director already installed and configured with an internal MarkLogic certificate, you must uninstall Ops Director before performing the steps described in this section. For details on uninstalling Ops Director, see Removing Ops Director.

Do the following steps on the Ops Director Application Cluster:

This procedure requires that you have the admin role.

  1. Install Ops Director and specify that it shall use externally signed certificates, as follows:

    Log into the Admin Interface on the host where you plan to install Ops Director.

    Click Clusters on the left tree menu, and select the local cluster. The Edit Local Cluster Configuration page displays. Select the Ops Director tab at the top of the page.

    On the Ops Director Setup page, click install. On the Install Ops Director page, select Use externally signed certificates and click ok.

  2. Create a certificate template named OpsDirector-SSL-Template, as follows:

    Select Configure > Security > Certificate Templates in the left tree menu. The Certificate Templates page displays. Select the Create tab at the top of the page.

    In the Create Certificate Templates page, enter OpsDirector-SSL-Template in the template name field. Make sure that all the values you enter in the subject match the values in the externally signed server certificate that you have received from the Certificate Authority. Click ok.

  3. Install the signed server certificate and the corresponding private key for the Ops Director cluster host, as follows:

    Select Configure > Security > Certificate Templates > Security > OpsDirector-SSL-Template in the left tree menu. The Configure Certificate Template page displays.

    Select the Import tab at the top of the page. The Import Certificates page displays.

    Either paste an individual certificate into the text area, or click Choose File to browse to the location of the file containing the signed certificate. Zip files can be uploaded directly without the need to unzip them.

    Click ok.

  4. Create an external security configuration object named OpsDirectorSystem as follows:

    Select Configure > Security > Certificate Templates > Security > OpsDirector-SSL-Template in the left tree menu. In the right pane, select the Create tab. The New External Security page displays.

    Enter OpsDirectorSystem in the name field. Select certificate in the authentication menu. Click Show and select the appropriate SSL client certificate authority. You may leave the default values for all other settings.

    Click ok.

  5. Update the configuration of the OpsDirectorSystem application server to use the OpsDirectorSystem external security object, as follows:

    In the left menu, select Configure. In the Summary page, in the App Servers column, select the OpsDirectorSystem application server. The OpsDirectorSystem Configuration page displays.

    Scroll down to the authentication menu and select application-level. For internal security, select false. In the external securities menu, select OpsDirectorSystem.

    Click ok.

  6. On each cluster to be managed by Ops Director:

    Create a secure credential for accessing the managed cluster. The credential must be named opsdir-cluster-ID where cluster-ID is the identifier of the managed cluster, for example: opsdir-9004898302214424527. Perform the following steps:

    Repeat this step for each cluster to be managed by Ops Director.

    To obtain the identifier of the managed cluster, open the Admin Interface on one of the hosts of the managed cluster. In the left tree menu, select Configure > Clusters and select the local cluster. Select the Summary tab in the right pane. The Local Cluster Summary page displays.

    Copy the value of the Cluster ID field.

    Select Configure > Security > Secure Credentials in the left tree menu. Select the Create tab at the top of the right pane. The New Credential page displays.

    In the credential name field, enter opsdir-cluster-ID, where cluster-ID is the identifier of the managed cluster. In this example we use opsdir-9004898302214424527. Click ok.

    Select Configure > Clusters and select the local cluster. In the right pane, select the Summary tab. The Local Cluster Summary page displays.

    Select and copy the text from and including -----BEGIN CERTIFICATE----- to -----END CERTIFICATE-----.

    Select Configure > Security > Secure Credentials > opsdir-cluster-ID in the left tree menu, for example, opsdir-9004898302214424527.

    Scroll down to the credential certificate field and paste the certificate you copied. Paste the same certificate into the credential private key field.

    Scroll down further; under credential targets, set the target url pattern field to https://.*:8003/.* where 8003 is the port used by the SecureManage server.

    Click ok.

  7. Create a user called opsdirector-system-user, as follows:

    Select Configure > Security > Certificate Templates > Security > Users in the left tree menu. Select the Create tab at the top of the right pane. The New User page displays.

    In the user name field, enter opsdirector-system-user. Provide a password of your liking.

    Set the external name of the new user to match the subject of the Ops Director client certificate, using the following format:

    C=country,ST=state,L=locality,O=organization,CN=unit

    For example:

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

    Note that Common Name (CN) is set to OpsDirector, just as the client certificate was named.

    Under Role, select opsdir-admin-internal.

    Click ok.

Import an External Certificate into Managed Clusters via the Admin Interface

Do the following steps on each Managed Cluster:

This procedure requires that you have the admin role.

  1. Log into the Admin Interface on the managed cluster host that contains the SecureManage App Server.
  2. Create a certificate template named OpsDirector Template, as follows:

    Select Configure > Security > Certificate Templates. Select the Create tab at the top of the right pane. The Create Certificate Templates page displays.

    In the template name field, enter OpsDirector Template. Make sure all the values you enter in the subject match the values in the externally signed server certificate that you have received from the Certificate Authority. Click ok.

  3. On each host, install the signed server certificate and the corresponding private key in the managed cluster, as follows:

    Log into the Admin Interface on the host.

    Select Configure > Security > Certificate Templates, and click on the certificate name (OpsDirector Template). The Configure Certificate Template page displays.

    Select the Import tab at the top of the page. The Import Certificates page displays.

    Either paste an individual certificate into the text area, or click Choose File to browse to the location of the file containing the signed certificate for this host. Select the file, and click Open. Zip files can be uploaded directly without the need to unzip them. Click ok.

  4. Back on the host that contains the SecureManage App Server, create an external security configuration object named OpsDirectorSystem (one per managed cluster), as follows:

    In the Admin interface, select Configure > Security > External Security. Select the Create tab at the top of the right pane. The New External Security page displays.

    Enter OpsDirectorSystem in the name field. Select certificate in the authentication menu. Select the appropriate ssl client certificate authority. You may leave the default values for all other settings. Click ok.

  5. Create a secure credential named MarkLogic-OpsDirector for accessing the Ops Director Application Cluster as follows:

    In the Admin Interface of the managed cluster host that contains the SecureManage App Server, select Configure > Security > Secure Credentials and select the Create tab at the top of the right pane. The New Credential page displays.

    In the credential name field, enter MarkLogic-OpsDirector.

    Use the signed client certificate (the one with the common name OpsDirector) and the corresponding private key that you received from the Certificate Authority. Copy the certificate and the key into credential certificate and credential private key fields correspondingly.

    In the target-url-pattern field, enter https://.*:8009/.*, where 8009 is the port used by the OpsDirectorSystem server on the Ops Director Application Cluster.

    Click ok.

  6. Create a user called opsdirector-system-user, as follows:

    In the Admin Interface, select Configure > Security > Users. In the right pane, select the Create tab at the top of the page. The New User page displays.

    In the user name field, enter opsdirector-system-user. Provide a password of your liking.

    For roles, select manage-admin and security.

    Set the external name of the user to match the subject of the Ops Director client certificate, using the following format:

    C=country,ST=state,L=locality,O=organization,CN=unit

    For example:

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

    Note that Common Name (CN) is set to OpsDirector, just as the client certificate was named.

    Click ok.

  7. Configure the managed cluster to use externally signed certificates, as follows:

    In the Admin Interface, select Configure > Clusters in the left menu, then select the local cluster. In the right pane, select the Ops Director tab at the top of the page. Select manage this cluster. The Configure as a Managed Cluster page displays.

    Enter the name of the host where your Ops Director application runs.

    Select Use externally signed certificates from the Ops Director Certificate Authority menu.

    You can modify some default settings, such as the level for log messages sent to Ops Director and the frequency at which the metering data is collected.

    When finished, click ok.

Import an External Certificate into Ops Director Application Cluster via Scripting

You may configure Ops Director to use externally signed certificates only during its installation. If you have Ops Director already installed and configured with an internal MarkLogic certificate, you must uninstall Ops Director before performing the steps described in this section. For details on uninstalling Ops Director, see Removing Ops Director.

You may configure Ops Director to use externally signed certificates with use of scripts, which you can run from the Query Console, but some steps can only be performed via the Admin Interface.

The assumptions for this section are:

  • The Ops Director Application Cluster is a single node cluster. Its host is named opsdir.marklogic.com.
  • The base filename of the Ops Director's host server certificate is opsdir-server.
  • The managed cluster is a three-node cluster with hosts named englab-1.marklogic.com, englab-2.marklogic.com, and englab-3.marklogic.com. Note that these are the fully qualified host names for those hosts.
  • The base filenames of the managed cluster hosts server certificates are englab-1-server, englab-2-server, and englab-3-server correspondingly.
  • The base filename of the Ops Director client certificate is managed-cluster.

Do the following steps on the Ops Director Application Cluster:

This procedure requires that you have the admin role.

  1. Start the Ops Director installation and specify for it to use externally signed certificates, as follows:

    Log into the Admin Interface on the host where you plan to install Ops Director.

    In the left tree menu, select Configure > Clusters, and select the local cluster. The Edit Local Cluster Configuration page displays. Select the Ops Director tab at the top of the page.

    On the Ops Director Setup page, click install. On the Install Ops Director page, select Use externally signed certificates and click ok.

  2. Create a certificate template named OpsDirector-SSL-Template as follows:

    In the left tree menu, select Configure > Security > Certificate Templates. The Certificate Templates page displays. Select the Create tab at the top of the page.

    In the Create Certificate Templates page, enter OpsDirector-SSL-Template in the template name field. Make sure that all the values you enter in the subject match the values in the externally signed server certificate that you have received from the Certificate Authority. Click ok.

  3. Install the signed server certificate and the corresponding private key for the Ops Director cluster host, as follows:

    Open Query Console on the Ops Director cluster host (for example, http://opsdir.marklogic.com:8000/qconsole/).

    In the Query Console, select XQuery as Query Type, and run the following script:

    xquery version "1.0-ml";
    import module namespace pki = "http://marklogic.com/xdmp/pki" at "/MarkLogic/pki.xqy";
    
    let $temp as element(pki:template) := 
       pki:get-template-by-name("OpsDirector-SSL-Template")
    let $id := pki:template-get-id($temp)
    let $opts := 
       <options xmlns="xdmp:document-get"><format>text</format></options>
    let $cert := 
       xdmp:document-get("/share/certs/opsdir-server.crt", $opts)
    let $key := xdmp:document-get("/share/certs/opsdir.key", $opts)
    
    return
       pki:insert-host-certificate($id, $cert, $key)
  4. Create an external security configuration object named OpsDirectorSystem, as follows:

    In the left tree menu of the Admin Interface, select Configure > Security > External Security. In the right pane, select the Create tab at the top of the page. The New External Security page displays.

    Enter OpsDirectorSystem in the name field. Select certificate in the authentication menu. Select the appropriate ssl client certificate authority. You may leave the default values for all other settings.

    Click ok.

  5. Update the configuration of the OpsDirectorSystem application server to use the OpsDirectorSystem external security object, as follows:

    In the Query Console on the Ops Director cluster host, select XQuery as Query Type, and run the following script:

    xquery version "1.0-ml";
    
    import module namespace pki = "http://marklogic.com/xdmp/pki" at "/MarkLogic/pki.xqy";
    import module namespace admin="http://marklogic.com/xdmp/admin" at "/MarkLogic/admin.xqy";
    
    declare default function namespace "http://www.w3.org/2005/xpath-functions";
    declare option xdmp:mapping "false";
    
    let $template as element(pki:template) := 
       pki:get-template-by-name("OpsDirector-SSL-Template")
    let $ext-sec := "OpsDirectorSystem"
    let $tmpl-id := $template/pki:template-id
    let $config := admin:get-configuration()
    let $servers := for $group in xdmp:groups()
       for $id in admin:group-get-appserver-ids($config, $group)
       where admin:appserver-get-name($config, $id) eq 'OpsDirectorSystem'
       return ($group, $id)
    
    let $group-id := $servers[1]
    let $od-system := $servers[2]
    
    let $config := admin:appserver-set-enabled($config, $od-system, true())
    let $config := admin:appserver-set-authentication($config, 
       $od-system, "basic")
    let $config := admin:appserver-set-ssl-certificate-template($config,
       $od-system, $tmpl-id)
    let $config := admin:appserver-set-external-security($config,
       $od-system, $ext-sec, true(), "application-level")
    
    return
       admin:save-configuration($config)
  6. Create a secure credential for accessing the managed cluster. The credential must be named opsdir-cluster-ID, where cluster-ID is the identifier of the managed cluster.

    The uri-pattern must point to the hostname and port where the SecureManage application server is installed (for example, https://.*:8003/.*). The credential must use the signed client certificate (the one with the common name OpsDirector) and the corresponding private key that you received from the Certificate Authority.

    In the Query Console on the Ops Director cluster host, select XQuery as Query Type, and run the following script:

    xquery version "1.0-ml";
    
    import module namespace sec="http://marklogic.com/xdmp/security' at "/MarkLogic/security.xqy";
    
    let $cluster := ??? (: the xdmp:cluster() of /the managed cluster/ :)
    let $sport := 8003 (: the port used by the SecureManage server :)
    let $opts := 
       <options xmlns="xdmp:document-get"><format>text</format></options>
    
    let $credname := "opsdir-" || $cluster
    let $cert := 
       xdmp:document-get("/share/certs/managed-cluster-client.crt", $opts)/node()
    let $privkey := 
       xdmp:document-get("/share/certs/managed-cluster.key", $opts)/node()
    let $uri-pattern := "https://.*:" || $sport || "/.*"
    
    return
       sec:create-credential(
          $credname,
          "Credential for accessing " || $credname || " port " || $sport,
          (), (), $cert, $privkey, fn:false(),
          sec:uri-credential-target($uri-pattern, "basic"),
          xdmp:permission("opsdir-guest", "read"))

    Run this script for each cluster to be managed by Ops Director, with the corresponding value of the $cluster variable.

  7. Create a user called opsdirector-system-user. The external name of the user must match the subject of the Ops Director client certificate. The user must have the opsdir-admin-internal role.

    In the Query Console on the Ops Director cluster host, select XQuery as Query Type, and run the following script:

    xquery version "1.0-ml";
    
    import module namespace sec="http://marklogic.com/xdmp/security" at "/MarkLogic/security.xqy";
    
    let $name := "opsdirector-system-user"
    let $desc := "Ops Director system user"
    let $passwd := 
       xdmp:hmac-sha256("somesecret", xdmp:random()||xdmp:random(), "hex")
    let $roles := "opsdir-admin-internal"
    let $external := "C=US,ST=CA,L=San Carlos,O=MarkLogic,CN=OpsDirector"
    
    return
       sec:create-user-with-role(
          $name, $desc, $passwd, $roles, (), (), $external)

    Note that Common Name (CN) is set to OpsDirector, just as the client certificate was named.

Import an External Certificate into Managed Clusters via Scripting

You may install externally signed certificates on managed clusters using scripts that you can run from the Query Console, but some steps can only be performed via the Admin Interface.

The assumptions for this section are:

  • The Ops Director Application Cluster is a single node cluster. Its host is named opsdir.marklogic.com.
  • The base filename of the Ops Director's host server certificate is opsdir-server.
  • The managed cluster is a three-node cluster with hosts named englab-1.marklogic.com, englab-2.marklogic.com, and englab-3.marklogic.com. Note that these are the fully qualified host names for those hosts.
  • The base filenames of the managed cluster's hosts server certificates are englab-1-server, englab-2-server, and englab-3-server correspondingly.
  • The base filename of the Ops Director client certificate is managed-cluster.

Do the following on each Managed Cluster:

This procedure requires that you have the admin role.

  1. Log into the Admin Interface on the managed cluster host that contains the SecureManage App Server.
  2. Create a certificate template named OpsDirector Template, as follows:

    In the left menu, select Configure > Security > Certificate Templates. The Certificate Templates page displays. Select the Create tab at the top of the page.

    In the Create Certificate Templates page, enter OpsDirector Template in the template name field. Make sure that all the values you enter in the subject match the values in the externally signed server certificate that you have received from the Certificate Authority. Click ok.

  3. Install the signed server certificate and the corresponding private key for each host in the managed cluster, as follows:

    Open theQuery Console on the managed cluster host that contains SecureManage App Server (for example, http://englab-1.marklogic.com:8000/qconsole/).

    In the Query Console, select XQuery as Query Type, and run the following script:

    xquery version "1.0-ml";
    
    import module namespace pki = "http://marklogic.com/xdmp/pki" at "/MarkLogic/pki.xqy";
    
    let $temp as element(pki:template) := 
       pki:get-template-by-name("OpsDirector Template")
    let $id := pki:template-get-id($temp)
    let $opts := 
       <options xmlns="xdmp:document-get"><format>text</format></options>
    
    for $host in ("englab-1", "englab-2", "englab-3")
       let $cert := 
          xdmp:document-get("/share/certs/" || $host || "-server.crt",
          $opts)/node()
       let $privkey := 
          xdmp:document-get("/share/certs/" || $host || ".key",
          $opts)/node()
    
    return
       pki:insert-host-certificate($id, $cert, $privkey)
  4. Create an external security configuration object named 'OpsDirectorSystem' (one per managed cluster), as follows:

    Open the Admin Interface on the managed cluster host that contains SecureManage App Server.

    In the left menu, select Configure > Security > External Security. In the right pane, select the Create tab at the top of the page. The New External Security page displays.

    Enter OpsDirectorSystem in the name field. Select certificate in the authentication menu. Select the appropriate ssl client certificate authority. You may leave the default values for all other settings.

    Click ok.

  5. Create a secure credential named MarkLogic-OpsDirector for accessing the Ops Director Application Cluster.

    The uri-pattern must point to the hostname and port where the OpsDirectorSystem application server is installed (for example, https://.*:8009/.*), and the credential must use the signed client certificate (the one with the common name OpsDirector) and the corresponding private key that you received from the Certificate Authority.

    Open the Query Console on the managed cluster host that contains SecureManage App Server. Select XQuery as Query Type, and run the following script:

    xquery version "1.0-ml";
    
    import module namespace sec="http://marklogic.com/xdmp/security" at "/MarkLogic/security.xqy";
    
    let $credname := "MarkLogic-OpsDirector"
    let $opts := 
       <options xmlns="xdmp:document-get"><format>text</format></options>
    let $cert := 
       xdmp:document-get("/share/certs/managed-cluster-client.crt",
       $opts)/node()
    let $privkey := 
       xdmp:document-get("/share/certs/managed-cluster.key", $opts)/node()
    let $uri-pattern := "https://.*:8009/.*"
    
    return
       sec:create-credential(
          $credname,
          "Credential for accessing .*:8009",
          (), (), $cert, $privkey, fn:false(),
          sec:uri-credential-target($uri-pattern, "basic"),
          xdmp:permission("admin", "read"))
  6. Create a user called opsdirector-system-user. The external name of the user must match the subject of the Ops Director client certificate. The user must have the manage-admin and security roles.

    Open the Query Console on the managed cluster host that contains the SecureManage App Server. Select XQuery as Query Type, and run the following script:

    xquery version "1.0-ml";
    
    import module namespace sec="http://marklogic.com/xdmp/security" at "/MarkLogic/security.xqy";
    
    let $name := "opsdir-system-user"
    let $desc := "Ops Director system user"
    let $passwd := 
       xdmp:hmac-sha256("somesecret", xdmp:random()||xdmp:random(), "hex")
    let $roles := ("manage-admin", "security")
    let $external := "C=US,ST=CA,L=San Carlos,O=MarkLogic,CN=OpsDirector"
    
    return
       sec:create-user-with-role(
          $name, $desc, $passwd, $roles, (), (), $external)

Note that Common Name (CN) is set to OpsDirector, just as the client certificate was named.

  1. Configure the managed cluster to use externally signed certificates, as follows:

    In the Admin Interface of the managed cluster host, select Configure > Clusters in the left tree menu. Select the local cluster, and in the right pane, select the Ops Director tab at the top of the page. Select manage this cluster . The Configure as a Managed Cluster page displays.

    Enter the name of the host where your Ops Director application runs.

    From the Ops Director Certificate Authority menu, select Use externally signed certificates.

    You can modify some default settings, such as the level for log messages sent to Ops Director, as well as the frequency at which the metering data is collected.

    When finished, click ok.

Upgrading Ops Director

This section describes the upgrade process for the Ops Director application. It covers the following topics:

Upgrade Process Overview

Ops Director is shipped with the MarkLogic Server. This means that a server upgrade necessarily upgrades the version of Ops Director, from the perspective of executable code. However, the server upgrade process updates neither the databases that Ops Director uses nor the configurations of Ops Director application servers.

The Ops Director upgrade process provides a seamless way to update the application, databases, and configuration from the Ops Director UI. For details on the possible upgrade workflows, see Upgrade Scenarios and Workflows.

Version Compatibility and Order of Upgrade

The Ops Director application is part of the MarkLogic Server release; its version depends on the version of the server installed. For example:

  • Ops Director version 1.0-1 is installed with MarkLogic Server releases 9.0-3 and 9.0-4;
  • Ops Director version 1.1-1 is installed with MarkLogic Server release 9.0-5.

Ops Director can manage only clusters that run either the same version of MarkLogic Server as the version it was shipped with or one of the older versions starting with MarkLogic Server 9.0-2. The version compatibility table follows.

Ops Director Version Installed with MarkLogic Server release Can manage clusters with MarkLogic releases
1.0-1 9.0-3, 9.0-4 from 9.0-2 to 9.0-4
1.1-1 9.0-5 from 9.0-2 to 9.0-5

This version compatibility defines the order of upgrade: first, the Ops Director Application Cluster must be upgraded to the latest MarkLogic Server release. Then you can upgrade managed clusters to the latest MarkLogic Server release.

Upgrade Scenarios and Workflows

Possible scenarios and workflows of upgradingOps Director are described in this section.

The Ops Director upgrade procedure requires that you have the admin role. It is not sufficient to login as opsdir-admin. You must login with administrator credentials of the MarkLogic Server.

Scenario 1: Single host, MarkLogic Server upgraded, Ops Director databases need update.

In this scenario, the Ops Director Application Cluster is a single-node cluster. The single host has already been upgraded to the latest MarkLogic Server release. The Ops Director databases and configuration need to be updated.

Perform the following steps:

  1. Launch the Ops Director application on the Ops Director host: in a browser window, enter the hostname and the port number of the OpsDirectorApplication server (by default, 8008).
  2. Login with admin credentials. The following message displays:

    Ops Director update required. Ops Director is being updated on this cluster. Please wait....

    The waiting indicator shows that the update is in progress.

  3. Once the update has completed and the Ops Director application is ready to run, the following message displays:

    Ops Director update completed. Ops Director has been updated to version version.

  4. Click ok to launch the Ops Director application.

    If you encounter errors in the Ops Director application after upgrade, clear the browser cache and reload the Ops Director application.

Scenario 2: Multiple hosts, one or more need upgrade of MarkLogic Server release.

In this scenario, the Ops Director Application Cluster is a multi-node cluster. Some of the hosts have already been upgraded to the latest MarkLogic Server release, but one or more hosts still have to be upgraded.

Perform the following steps:

  1. Launch the Ops Director application on a host of the Ops Director cluster: in a browser window, enter the hostname and the port number of the OpsDirectorApplication server (by default, 8008).
  2. Login with admin credentials. The following message displays:

    Cluster upgrade must be completed. The following host(s) must be upgraded before Ops Director can run on this host: [hostname1], [hostname2], [hostname3]. Retry when upgrades have been completed.

  3. For each host from the list of hosts provided in the message on the previous step, upgrade to the latest MarkLogic Server release. Follow the steps described in Upgrading from Previous Releases in the Installation Guide.

    After you installed the latest MarkLogic Server release on the host and started MarkLogic Server, make sure to open the Admin Interface in a browser (http://hostname:8001/), and, when the Admin Interface prompts you to upgrade the databases and the configuration files, click the button to confirm the upgrade. Also, make sure to reload Ops Director application in the browser (http://hostname:8008/) after the server is upgraded.

  4. While hosts are being upgraded, you may check the status of the upgrade by clicking the Retry button on the message box from step 2.

    Once all hosts have been upgraded, the following message displays: 'Ops Director update required. Ops Director is being updated on this cluster. Please wait...'.

    The waiting indicator shows that the update is in progress.

    Once the update is completed and the Ops Director application is ready to run, the following message displays:

    Ops Director update completed. Ops Director has been updated to version version.

  5. Click ok to launch the Ops Director application.

    If you encounter errors in the Ops Director application after the upgrade, clear the browser cache and reload the Ops Director application.

Scenario 3: Multiple hosts, all upgraded, Ops Director databases' update is in progress.

In this scenario, the Ops Director Application Cluster is a multi-node cluster. All hosts in the cluster have already been upgraded to the latest MarkLogic Server release. The Ops Director databases update is currently in progress (due to being initiated from a different host).

Perform the following steps:

  1. Launch the Ops Director application on a host of the Ops Director cluster: in a browser window, enter the hostname and the port number of the OpsDirectorApplication server (by default, 8008).
  2. Login with admin credentials. The following message displays:

    Ops Director update in progress. Ops Director is being updated on this cluster. Please wait....

    The waiting indicator shows that the update is in progress. Once the update is completed and the Ops Director application is ready to run, the following message displays:

    Ops Director update completed. Ops Director has been updated to version [version].

  3. Click ok to launch the Ops Director application.

    If you encounter errors in the Ops Director application after upgrade, clear the browser cache and reload the Ops Director application.

Upgrade Error Prevention and Troubleshooting

Before you being to upgrade the Ops Director Application Cluster hosts to the latest MarkLogic Server release, make sure to close your browser containing the Ops Director application. If you do not close your browser, you may see errors in the browser window.

If you have started an Ops Director upgrade, do not connect new managed clusters until the upgrade process has completed. Adding managed clusters in the middle of an upgrade can cause error conditions.

If upgrading any host in the cluster to the latest MarkLogic Server release fails, address the problem before trying to launch Ops Director.

Undelivered data from managed clusters might be lost during the upgrade process, just like during network outage.

« Previous chapter
Next chapter »