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:
The following table shows installation compatibility requirements for MarkLogic Server and Ops Director:
Ops Director 1.1 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.
Ops Director 2.0.1 has been tested with the following software versions:
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.
The installation procedure has changed from Ops Director 1.x to Ops Director 2.x. Please follow the instructions for the version of Ops Director you are installing.
The following installations are available:
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 1.x on an application cluster.
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.
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.
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.
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.
Follow these instructions to install Ops Director and greater.
Make sure the following conditions are in place before you begin the installation process:
The Ops Director installer is written in ML Gradle. A version of Gradle is included in the Ops Director 2.0 installation directory. For more information about Gradle, visit https://docs.gradle.org/current/userguide/userguide.html.
To install or upgrade to Ops Director 2.0 or greater, follow these instructions:
cd
to the directory containing the files.gradle.properties
file or enter them as options on the command line. The following table contains the host settings.The following settings determine how the Ops Director cluster communicates with the managed clusters. Choose one of the following Certificate Authority options:
opsdirCa=generate
If you set this value, you also need to add the following values:
opsdirCa=external
Use this setting to use an external certificate for Ops Director.
opsdirCa=
ML_ID
Use this setting to use a certificate that is already installed where ML_ID is the MarkLogic ID number for the certificate.
./gradlew --no-daemon mlDeploy
If this is the first time you are installing Ops Director 2.0, a lot of periods will display, followed by files being downloaded.
The following resources are created on the host where your Ops Director application runs.
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:
-----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:
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.
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.
To enable application-level authentication, perform the following steps:
https://englab.marklogic.com:8008
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.
The following data accumulates in the OpsDirector
database:
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.
http://<hostname>:8000/qconsole/
xquery version "1.0-ml"; doc("/config/opsdirector.xml")
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:dayTimeDuration
data 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.
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:
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.
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 describes how to remove Ops Director 1.1 and earlier from the MarkLogic host.
When you use this method of uninstalling Ops Director, the Ops Director database is not uninstalled.
The following procedure describes how to remove Ops Director 2.0 and later from the MarkLogic host.
opsdirector-2-0-0
).mlGroupName
in the gradle.properties
file, enter the command:mlGroupName
in the gradle.properties
file, enter the command (on one line):gradlew mlUndeploy -PmlGroupName=
mlGroupName -Pconfirm=true -PconfirmManaged=true
where mlGroupName is the value from the gradle.properties
file.
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:
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)
The procedures described in Installing Ops Director make use of an internally-generated, self-signed certificate.
To use externally signed certificates with any version of Ops Director, you must get the Certificate Signing Requests (CSRs) from MarkLogic, pass the CSRs to the Certificate Authority and receive signed certificates, and then install the signed certificates on the cluster. You must ensure that you have secured a certificate authority (CA) and can get signed certificates issued by that CA for each of the nodes involved.
In this example, we will be working with a two-node Ops Director cluster with hosts named node1 and node2, and a two-node managed cluster with hosts named node3 and node4. In each step, a code example is presented showing how the REST Management API (RMA) can be used to accomplish the task. Where the RMA cannot be used, XQuery scripts are shown.
Your MarkLogic server hosts must have fully-qualified names that can be resolved by DNS.
If the signing authority is Verisign, 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.
Before you begin this procedure, make sure you have a way of obtaining certificates.
The following sections contain instructions for configuring Ops Director to use externally signed certificates.
The steps involved for configuring Ops Director to use externally signed certificates are:
Once you have obtained the CA file (in this example, it is /tmp/opsdir.ca
), follow these steps to configure the Ops Director cluster:
curl
to install the Certificate Authority on the cluster, replacing /tmp/opsdir.ca
with the location and name of your CA file:curl --anyauth -u admin:admin -X POST -H "content-type:text/plain" \ --data-binary @/tmp/opsdir.ca \ http://node1:8002/manage/v2/certificate-authorities
./gradlew -PopsdirCa=external mlDeploy
You may need to specify additional options, such as mlHost
, depending on your configuration.
{ "template-name": "OpsDirector-SSL-Template", "template-description": "Ops Director SSL Template", "key-type": "rsa", "key-options": { "key-length": "2048" }, "req": { "version": "0", "subject": { "countryName": "US", "stateOrProvinceName": "California", "localityName": "San Carlos", "organizationName": "MarkLogic Corporation" } } }
Our examples use MarkLogic-specific values. You may use other values, but you must use them consistently.
curl
to post this certificate template to the REST Management API, replacing /tmp/od-template.json
with the location and name of your template filename:curl --anyauth -u admin:admin -X POST -H \ "content-type:application/json" \ -d @/tmp/od-template.json \ http://node1:8002/manage/v2/certificate-templates
OpsDirector CA
with the common name of your certificate of the Certifcate Authority. The following XQuery code accomplishes this:xquery version "1.0-ml"; import module namespace pki = "http://marklogic.com/xdmp/pki" at "/MarkLogic/pki.xqy"; xdmp:invoke-function(function () { /pki:certificate[pki:authority=true()][pki:host-name='OpsDirector CA']/pki:certificate-id/data() }, map:entry("database", xdmp:security-database()))
If you prefer, the following curl
command will do it with the REST Management API. Note that this command relies on the https://stedolan.github.io/jq/
tool, which must be on your system.
curl -s --anyauth -u admin:admin \ "http://node1:8002/manage/v2/certificate-authorities?format=json" \ | jq ".\"certificate-authorities-default-list\".\"list-items\".\"list-item\"[]\ | select(.nameref==\"OpsDirector CA\") | .idref" \ | tr -d '"'
Either of these techniques will give you the ID of the certificate authority.
/tmp/od-extsec.json
) that creates an external authentication configuration object, replacing CA_ID with the CA ID you obtained in the previous step:{ "external-security-name": "OpsDirectorSystem", "description": "Ops Director System", "authentication": "certificate", "cache-timeout": 300, "authorization": "internal", "ssl-client-certificate-authority": [ "CA_ID" ] }
curl --anyauth -u admin:admin -X POST -H \ "content-type:application/json" \ -d @/tmp/od-extsec.json \ http://node1:8002/manage/v2/external-security
/tmp/od-server.xml
) to update the server configuration to modify some of the properties of the OpsDirectorSystem
application server. In this example, replace Insert_the_certificate_here with your certificate:<http-server-properties xmlns="http://marklogic.com/manage"> <enabled>true</enabled> <authentication>application-level</authentication> <external-securities> <external-security>OpsDirectorSystem</external-security> </external-securities> <ssl-certificate-template>OpsDirector-SSL-Template</ssl-certificate-template> <ssl-client-certificate-pems> <ssl-client-certificate-pem>Insert_the_certificate_here</ssl-client-certificate-pem> </ssl-client-certificate-pems> </http-server-properties>
curl --anyauth -u admin:admin -X PUT -H \ "content-type:application/xml" \ --data-binary @/tmp/od-server.xml \ http://node1:8002/manage/v2/servers/OpsDirectorSystem/properties?group-id=Default
If you are not using the Default group for the Ops Director servers, update group-id
accordingly.
for host in host_list; do echo "Generating CSR for $host to /tmp/$host.csr ..." curl -s --anyauth -X POST -u admin:admin -H \ "content-type:application/json" -d "{\"operation\": \ \"generate-certificate-request\", \"common-name\": \ \"$host\", \"dns-name\": \"$host\" }" \ //node1:8002/manage/v2/certificate-templates/OpsDirector-SSL-Template \ > /tmp/$host.csr done
/tmp/
hostname.crt
for each host:for host in host_list; do "Installing server certificate for $host from /tmp/$host.crt ..." curl -s --anyauth -X POST -u admin:admin -H \ "content-type:text/plain" --data-binary @/tmp/$host.crt \ http://node1:8002/manage/v2/certificates done
If you prefer, you can put all of the certificates in a single ZIP file and post that to the /manage/v2/certificates
endpoint.
Uploading a ZIP file of certificates fails if the ZIP file contains an empty directory entry.
/tmp/od-user.json
) that creates a user called opsdirector-system-user
:{ "user-name": "opsdirector-system-user", "description": "Ops Director system user", "role": [ "opsdir-admin-internal" ], "external-name": [ "C=US,O=MarkLogic Corporation,CN=OpsDirector" ] }
Make sure the external name exactly matches the client certificates generated in later steps.
curl
to POST this to the REST Management API (port 8002):curl -s --anyauth -X POST -u admin:admin -H \ "content-type:application/json" \ -d @/tmp/od-user.json \ http://node1:8002/manage/v2/users
When using external certificates, configuring a new managed cluster requires changes on both the managed cluster and the Ops Director Cluster.
These instructions use "node3" as the name of the host on the managed cluster you are using to do the installation; replace that with the name of a host on the cluster you want to manage.
Setting up the Managed Cluster
Follow these instructions on the managed cluster to set up the managed cluster to work with Ops Director.
curl
command to install the CA on the cluster, replacing /tmp/opsdir.ca
with the location and name of your CA:curl --anyauth -u admin:admin -X POST -H "content-type:text/plain" \ --data-binary @/tmp/opsdir.ca \ http://node3:8002/manage/v2/certificate-authorities
/tmp/md-template.json
), replacing cluster_ID with the managed cluster ID from the previous step:{ "template-name": "OpsDirector Template cluster_ID", "template-description": "Ops Director SSL Template", "key-type": "rsa", "key-options": { "key-length": "2048" }, "req": { "version": "0", "subject": { "countryName": "US", "stateOrProvinceName": "California", "localityName": "San Carlos", "organizationName": "MarkLogic Corporation" } } }
curl
to POST this JSON file to the REST Management API (port 8002):curl --anyauth -u admin:admin -X POST -H \ "content-type:application/json" \ -d @/tmp/md-template.json \ http://node3:8002/manage/v2/certificate-templates
for host in host_list; do echo "Generating CSR for $host to /tmp/$host.csr ..." curl -s --anyauth -X POST -u admin:admin -H \ "content-type:application/json" \ -d "{\"operation\": \"generate-certificate-request\", \ \"common-name\": \"$host\", \"dns-name\": \"$host\" }" \ "http://node3:8002/manage/v2/certificate-templates/OpsDirector Template cluster_ID" > /tmp/$host.csr done
/tmp/host.crt
with the location and name of your saved certificate:for host in host_list; do echo "Installing server certificate for $host from /tmp/$host.crt ..." curl -s --anyauth -X POST -u admin:admin -H \ "content-type:text/plain" --data-binary @/tmp/$host.crt \ http://node3:8002/manage/v2/certificates done
If you prefer, you can put all of the certificates in a single ZIP file and post that to the /manage/v2/certificates
endpoint.
Uploading a ZIP file of certificates fails if the ZIP file contains an empty directory entry.
OpsDirector CA
with the name of your CA:xquery version "1.0-ml"; import module namespace pki = "http://marklogic.com/xdmp/pki" at "/MarkLogic/pki.xqy"; xdmp:invoke-function(function () { /pki:certificate[pki:authority=true()][pki:host-name='OpsDirector CA']/pki:certificate-id/data() }, map:entry("database", xdmp:security-database()))
curl
):curl -s --anyauth -u admin:admin "http://node3:8002/manage/v2/certificate-authorities?format=json" | jq ".\"certificate-authorities-default-list\".\"list-items\".\"list-item\"[] | select(.nameref==\"OpsDirector CA\") | .idref" | tr -d '"'
The https://stedolan.github.io/jq/
tool must be on your system for the REST command to work.
In this example, the Certificate Authority is 5955670036362913372.
/tmp/md-extsec.json
) to create an external security module, replacing cluster_ID with the name of your cluster and 5955670036362913372
with your CA:{ "external-security-name": "OpsDirectorSystem-cluster_ID", "description": "Ops Director System", "authentication": "certificate", "cache-timeout": 300, "authorization": "internal", "ssl-client-certificate-authority": [ "5955670036362913372" ] }
curl
to POST this certificate template to the REST Management API (port 8002):curl --anyauth -u admin:admin -X POST -H \ "content-type:application/json" \ -d @/tmp/md-extsec.json \ http://node3:8002/manage/v2/external-security
/tmp/md-client.json
) to generate a CSR for the Ops Director client certificate, matching the parameters to those from step 14 in the previous section:{ "operation": "client-certificate-request", "countryName": "US", "organizationName": "MarkLogic Corporation", "commonName": "OpsDirector" }
curl
to POST this certificate template to the REST Management API (port 8002):curl -s --anyauth -X POST -u admin:admin -H \ "content-type:application/json" \ -d @/tmp/md-client.json \ http://node3:8002/manage/v2/credentials/secure \ > /tmp/md-client.csr
The server responds by generating a private/public key pair, storing the relevant private key in the Security database and returning a client certificate request.
/tmp/md-secure-credential.xml
) that constructs a secure credential for accessing the Ops Director cluster, replacing cluster_ID with the cluster ID, certificate with the certificate you obtained in the previous step, and 8009 with the Ops Director system port:<secure-credential-properties xmlns="http://marklogic.com/manage/secure-credential/properties"> <name>MarkLogic-OpsDirector-cluster_ID</name> <description>Secure credential to access the Ops Director cluster</description> <certificate>certificate</certificate> <targets> <target> <uri-pattern>https://.*:8009/.*</uri-pattern> <authentication>basic</authentication> </target> </targets> <signing>false</signing> <permissions> <permission> <role-name>admin</role-name> <capability>read</capability> </permission> </permissions> </secure-credential-properties>
curl
to POST this credential to the REST Management API (port 8002):curl -s --anyauth -X POST -u admin:admin -H \ "content-type:application/xml" \ --data-binary @/tmp/md-secure-credential.xml \ http://node3:8002/manage/v2/credentials/secure
/tmp/md-user.json
) to construct a user called opsdirector-system-user-
cluster_ID, replacing cluster_ID with the ID of the cluster, and replacing the parameters in the external-name
field with the external name from step 12:{ "user-name": "opsdirector-system-user-cluster_ID", "description": "Ops Director system user", "role": [ "manage-admin", "security" ], "external-name": [ "C=US,O=MarkLogic Corporation,CN=OpsDirector" ] }
The external name must exactly match what you put in the client certificate!
curl
to POST this certificate template to the REST Management API (port 8002):curl -s --anyauth -X POST -u admin:admin -H \ "content-type:application/json" \ -d @/tmp/md-user.json \ http://node3:8002/manage/v2/users
Setting Up the Ops Director Cluster
Follow these instructions on the Ops Director cluster to set up the managed cluster to work with Ops Director.
/tmp/od-client.json
) to generate a CSR for the Ops Director managed cluster client certificate, making sure to match the parameters in step 12:{ "operation": "client-certificate-request", "countryName": "US", "organizationName": "MarkLogic Corporation", "commonName": "OpsDirector" }
curl
to POST the request to the REST Management API on the Ops Director cluster:curl -s --anyauth -X POST -u admin:admin -H \ "content-type:application/json" \ -d @/tmp/od-client.json \ http://node1:8002/manage/v2/credentials/secure \ > /tmp/od-client.csr
The server responds by generating a private/public key pair, storing the relevant private key in the Security database, and returning a client certificate request.
/tmp/od-secure-credential.xml
) that constructs a secure credential for accessing the managed cluster, replacing cluster_ID with the name of your cluster ID and certificate with the certificate obtained in the previous step:<secure-credential-properties xmlns="http://marklogic.com/manage/secure-credential/properties"> <name>opsdir-cluster_ID</name> <description>Secure credential to access the cluster_ID cluster</description> <certificate>certificate</certificate> <targets> <target> <uri-pattern>https://.*:8003/.*</uri-pattern> <authentication>basic</authentication> </target> </targets> <signing>false</signing> <permissions> <permission> <role-name>admin</role-name> <capability>read</capability> </permission> </permissions> </secure-credential-properties>
curl
to POST this to the REST Management API (port 8002):curl -s --anyauth -X POST -u admin:admin -H \ "content-type:application/xml" \ --data-binary @/tmp/md-secure-credential.xml \ http://node1:8002/manage/v2/credentials/secure
The following sections describe how to configure MarkLogic Server 9.0-8 and earlier and Ops Director 2.0 and earlier to use externally signed certificates.
The steps involved for configuring Ops Director to use externally signed certificates are:
To configure the Ops Director 2.0 and earlier cluster:
curl
to install the Certificate Authority on the cluster:curl --anyauth -u admin:admin -X POST -H "content-type:text/plain" \ --data-binary @/tmp/opsdir.ca \ http://node1:8002/manage/v2/certificate-authorities
./gradlew -PopsdirCa=external mlDeploy
You may need to specify additional options, such as mlHost, depending on your configuration.
/tmp/od-template.json
) to create a certificate template for the hosts on the cluster:{ "template-name": "OpsDirector-SSL-Template", "template-description": "Ops Director SSL Template", "key-type": "rsa", "key-options": { "key-length": "2048" }, "req": { "version": "0", "subject": { "countryName": "US", "stateOrProvinceName": "California", "localityName": "San Carlos", "organizationName": "MarkLogic Corporation" } } }
curl
to POST this to the REST Management API (port 8002):curl --anyauth -u admin:admin -X POST -H \ "content-type:application/json" \ -d @/tmp/od-template.json \ http://node1:8002/manage/v2/certificate-templates
OpsDirector CA
with the common name of your certificate. The following XQuery code accomplishes this:xquery version "1.0-ml"; import module namespace pki = "http://marklogic.com/xdmp/pki" at "/MarkLogic/pki.xqy"; xdmp:invoke-function(function () { /pki:certificate[pki:authority=true()][pki:host-name='OpsDirector CA']/pki:certificate-id/data() }, map:entry("database", xdmp:security-database()))
If you prefer, the following curl
command will do it with the REST Management API. Note that this command relies on the https://stedolan.github.io/jq/
tool, which must be on your system.
curl -s --anyauth -u admin:admin \ "http://node1:8002/manage/v2/certificate-authorities?format=json" \ | jq ".\"certificate-authorities-default-list\".\"list-items\".\"list-item\"[]\ | select(.nameref==\"OpsDirector CA\") | .idref" \ | tr -d '"'
Either of these techniques will give you the ID of the OpsDirector CA
certificate authority (in this example, it is 5955670036362913372
).
/tmp/od-extsec.json
) where the external security name is called OpsDirectorSystem
, replacing the 5955670036362913372
with the number you got when running the previous step:{ "external-security-name": "OpsDirectorSystem", "description": "Ops Director System", "authentication": "certificate", "cache-timeout": 300, "authorization": "internal", "ssl-client-certificate-authority": [ "5955670036362913372" ] }
curl
to post the JSON code to the external security endpoint using the REST Management API (in this example, http://node1:8002/manage/v2/external-security
):curl --anyauth -u admin:admin -X POST -H \ "content-type:application/json" \ -d @/tmp/od-extsec.json \ http://node1:8002/manage/v2/external-security
/tmp/od-server.xml
) to update the server configuration to modify some of the properties of the OpsDirectorSystem
application server. In this example, the CA is ssl-client-certificate-pem
, and replace certificate with your certificate:<http-server-properties xmlns="http://marklogic.com/manage"> <enabled>true</enabled> <authentication>application-level</authentication> <external-securities> <external-security>OpsDirectorSystem</external-security> </external-securities> <ssl-certificate-template>OpsDirector-SSL-Template</ssl-certificate-template> <ssl-client-certificate-pems> <ssl-client-certificate-pem>certificate</ssl-client-certificate-pem> </ssl-client-certificate-pems> </http-server-properties>
curl --anyauth -u admin:admin -X PUT -H \ "content-type:application/xml" \ --data-binary @/tmp/od-server.xml \ http://node1:8002/manage/v2/servers/OpsDirectorSystem/properties?group-id=Default
If you are not using the Default group for the Ops Director servers, update the group-id
accordingly.
/tmp/od-certs.zip
.curl
to upload the certificates:curl --anyauth -u admin:admin -X POST -H \ "content-type:application/xml" \ --data-binary @/tmp/od-certs.zip \ http://node1:8002/manage/v2/certificates
Uploading a ZIP file of certificates fails if the ZIP file contains an empty directory entry.
If any nodes still show a pending certificate request or a temporary certificate, go back to step <HyperlinkSerif>11. Make sure you select to generate requests for All nodes and repeat the steps to download, sign, and upload the certificates.
/tmp/od-user.json
) that creates a user called opsdirector-system-user
, replacing password with a password of your choice:{ "user-name": "opsdirector-system-user", "password": "password", "description": "Ops Director system user", "role": [ "opsdir-admin-internal" ], "external-name": [ "C=US,O=MarkLogic Corporation,CN=OpsDirector" ] }
curl -s --anyauth -X POST -u admin:admin -H \ "content-type:application/json" \ -d @/tmp/od-user.json \ http://node1:8002/manage/v2/users
The external name must exactly match the subject of the client certificates that you generated when setting up a managed cluster.
When using external certificates, configuring a new managed cluster requires changes on both the managed cluster and the Ops Director Cluster.
Setting Up the Managed Cluster
Follow these instructions on the managed cluster to set up the managed cluster to work with Ops Director 2.0 and earlier.
curl
command to install the CA on the cluster, replacing /tmp/opsdir.ca
with your CA location and name:curl --anyauth -u admin:admin -X POST -H "content-type:text/plain" \ --data-binary @/tmp/opsdir.ca \ http://node3:8002/manage/v2/certificate-authorities
md-template.json
), replacing cluster_ID with the managed cluster ID from the previous step:{ "template-name": "OpsDirector Template cluster_ID", "template-description": "Ops Director SSL Template", "key-type": "rsa", "key-options": { "key-length": "2048" }, "req": { "version": "0", "subject": { "countryName": "US", "stateOrProvinceName": "California", "localityName": "San Carlos", "organizationName": "MarkLogic Corporation" } } }
curl
to POST this JSON file to the REST Management API (port 8002):curl --anyauth -u admin:admin -X POST -H \ "content-type:application/json" \ -d @/tmp/md-template.json \ http://node3:8002/manage/v2/certificate-templates
xquery version "1.0-ml"; import module namespace pki = "http://marklogic.com/xdmp/pki" at "/MarkLogic/pki.xqy"; xdmp:invoke-function(function () { /pki:certificate[pki:authority=true()][pki:host-name='OpsDirector CA']/pki:certificate-id/data() }, map:entry("database", xdmp:security-database()))
curl
):curl -s --anyauth -u admin:admin "http://node3:8002/manage/v2/certificate-authorities?format=json" | jq ".\"certificate-authorities-default-list\".\"list-items\".\"list-item\"[] | select(.nameref==\"OpsDirector CA\") | .idref" | tr -d '"'
The https://stedolan.github.io/jq/
tool must be on your system for the REST command to work.
Either of these techniques will give you the ID of the OpsDirector CA
certificate authority.
/tmp/md-extsec.json
) to create an external security module, replacing cluster_ID with the ID of the Ops Director cluster and CA_ID with your CA ID:{ "external-security-name": "OpsDirectorSystem-cluster_ID", "description": "Ops Director System", "authentication": "certificate", "cache-timeout": 300, "authorization": "internal", "ssl-client-certificate-authority": [ "CA_ID" ] }
curl
to POST this certificate template to the REST Management API (port 8002):curl --anyauth -u admin:admin -X POST -H \ "content-type:application/json" \ -d @/tmp/md-extsec.json \ http://node3:8002/manage/v2/external-security
xquery version "1.0-ml"; import module namespace pki="http://marklogic.com/xdmp/pki" at "/MarkLogic/pki.xqy"; declare namespace x509="http://marklogic.com/xdmp/x509"; let $tid := pki:get-template-by-name("OpsDirector Template")/pki:template-id for $hid in xdmp:hosts() let $hostname := xdmp:host-name($hid) let $csr := pki:generate-certificate-request($tid, $hostname, (), ()) return $csr
/tmp/mc-certs.zip
).curl
to upload the certificates:curl --anyauth -u admin:admin -X POST -H \ "content-type:application/zip" \ --data-binary @/tmp/mc-certs.zip \ http://node3:8002/manage/v2/certificates
Uploading a ZIP file of certificates fails if the ZIP file contains an empty directory entry.
The subject must exactly match the external name of the opsdirector-system-user
on the Ops Director cluster.
xquery version "1.0-ml"; declare namespace x509 = "http://marklogic.com/xdmp/x509"; let $country := "US" let $state := () let $city := () let $org := "MarkLogic Corporation" let $unit := () let $email := () let $common := "OpsDirector" let $keys := xdmp:rsa-generate() let $privkey := $keys[1] let $pubkey := $keys[2] let $req := <x509:req> <x509:version>0</x509:version> <x509:subject> { $country ! <x509:countryName>{.}</x509:countryName> } { $state ! <x509:stateOrProvinceName>{.}</x509:stateOrProvinceName> } { $city ! <x509:localityName>{.}</x509:localityName> } { $org ! <x509:organizationName>{.}</x509:organizationName> } { $unit ! <x509:organizationalUnitName>{.}</x509:organizationalUnitName> } { $email ! <x509:emailAddress>{.}</x509:emailAddress> } { $common ! <x509:commonName>{.}</x509:commonName> } </x509:subject> <x509:publicKey>{$pubkey}</x509:publicKey> </x509:req> let $csr := xdmp:x509-request-generate($req, $privkey) return ($csr, $privkey)
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 := "certificate" let $privkey := "private_key" let $uri-pattern := "https://.*:8009/.*" return xdmp:invoke-function(function() { sec:create-credential($credname, "A credential for accessing .*:8009", (), (), $cert, $privkey, fn:false(), sec:uri-credential-target($uri-pattern, "basic"), xdmp:permission("security", "read")) }, map:entry("database", xdmp:security-database()))
/tmp/od-user.json
) that creates a user called opsdirector-system-user
, replacing password with a password of your choice:{ "user-name": "opsdirector-system-user", "password": "password", "description": "Ops Director system user", "role": [ "opsdir-admin-internal" ], "external-name": [ "C=US,O=MarkLogic Corporation,CN=OpsDirector" ] }
The external name must exactly match the subject of the client certificates that you generated when setting up a managed cluster.
curl -s --anyauth -X POST -u admin:admin -H \ "content-type:application/json" \ -d @/tmp/od-user.json \ http://node3:8002/manage/v2/users
Setting Up the Ops Director Cluster
Follow these instructions on the Ops Director cluster to set up the managed cluster to work with Ops Director 2.0-0 and earlier.
xquery version "1.0-ml"; declare namespace x509 = "http://marklogic.com/xdmp/x509"; let $country := "US" let $state := () let $city := () let $org := "MarkLogic Corporation" let $unit := () let $email := () let $common := "OpsDirector" let $keys := xdmp:rsa-generate() let $privkey := $keys[1] let $pubkey := $keys[2] let $req := <x509:req> <x509:version>0</x509:version> <x509:subject> { $country ! <x509:countryName>{.}</x509:countryName> } { $state ! <x509:stateOrProvinceName>{.}</x509:stateOrProvinceName> } { $city ! <x509:localityName>{.}</x509:localityName> } { $org ! <x509:organizationName>{.}</x509:organizationName> } { $unit ! <x509:organizationalUnitName>{.}</x509:organizationalUnitName> } { $email ! <x509:emailAddress>{.}</x509:emailAddress> } { $common ! <x509:commonName>{.}</x509:commonName> } </x509:subject> <x509:publicKey>{$pubkey}</x509:publicKey> </x509:req> let $csr := xdmp:x509-request-generate($req, $privkey) return ($csr, $privkey)
The subject must exactly match external name of the opsdirector-system-user
on the managed cluster.
xquery version "1.0-ml"; import module namespace sec="http://marklogic.com/xdmp/security" at "/MarkLogic/security.xqy"; let $credname := "opsdir-cluster_ID" let $opts := <options xmlns="xdmp:document-get"><format>text</format></options> let $cert := "certificate" let $privkey := "private_key" let $uri-pattern := "https://.*:8003/.*" return xdmp:invoke-function(function() { sec:create-credential($credname, "A credential for accessing SecureManage on the cluster", (), (), $cert, $privkey, fn:false(), sec:uri-credential-target($uri-pattern, "basic"), xdmp:permission("security", "read")) }, map:entry("database", xdmp:security-database()))
You can now manage the cluster from the Admin UI using Ops Director 2.0-0 and earlier.
This section describes the upgrade process for the Ops Director application. It covers the following topics:
Ops Director 1.0-0 and 1.1-1 were shipped with MarkLogic Server. This meant that a server upgrade automatically upgraded the version of Ops Director, from the perspective of executable code.
Starting with Ops Director 2.0, upgrading MarkLogic Server does not automatically upgrade Ops Director; you must upgrade Ops Director separately.
The MarkLogic Server upgrade process updates neither the databases that Ops Director uses nor the configurations of Ops Director application servers.
The Ops Director application was part of the MarkLogic Server release up to Ops Director 1.1-1 and MarkLogic Server 9.0-6; the version of Ops Director depended on the version of the server installed:
When you are upgrading Ops Director from one version to another, the MarkLogic Server version needs to be compatible with the versions listed in the preceding version compatibility matrix. If you are upgrading to a version of Ops Director that needs a different MarkLogic Server version, first upgrade the MarkLogic Server, and then upgrade Ops Director.
The following version compatibility matrix explains which versions of Ops Director can be upgraded on which versions of MarkLogic Server.
If Running Ops Director Version | Can Upgrade To Ops Director Version |
---|---|
1.0-0 | 1.1-1 |
1.1-1 | 2.0, 2.0.1 |
2.0 | 2.0.1 |
When you are upgrading from Ops Director 1.1-1, you must first upgrade the MarkLogic Server version before you install Ops Director 2.x.
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.
credentials. The following message displays:Ops Director update required. Ops Director is being updated on this cluster. Please wait...
.
Ops Director update completed. Ops Director has been updated to version
version.
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.
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.
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.
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.
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).
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]
.
If you encounter errors in the Ops Director application after upgrade, clear the browser cache and reload the Ops Director application.
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.