MarkLogic 9 Product Documentation

Ops Director Guide — Chapter 2

Before You Install Ops Director

Make sure the following conditions are in place before you begin the installation process:

• Internet access is required to install Ops Director 2.0. Make sure you can connect to the Internet.
• Make sure you are running MarkLogic Server 9.0-7 or greater.
• Make sure you have access to ports 8000, 8001, 8002, 8008, and 8009 on the managed cluster.
• Start MarkLogic Server and log into the Admin UI (port 8001).
• If you have not already uninstalled a previous version of Ops Director, follow the instructions in Removing Ops Director.

  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.

Ops Director 2.0 Installation

To install or upgrade to Ops Director 2.0 or greater, follow these instructions:

1. Download the Ops Director zip file from marklogic.com at:

   https://developer.marklogic.com/products/opsdirector

2. Unzip the file, and cd to the directory containing the files.
3. Either edit the Ops Director settings in the gradle.properties file or enter them as options on the command line. The following table contains the host settings.

   Setting	Description
   mlHost	Host where Ops Director will be installed. Default value: localhost.
   mlUsername	Username for admin access to that host. Default value: admin.
   mlPassword	Password for admin access to that host. Default value: admin. MarkLogic strongly that recommends you change this value.
   opsdirDataExpires	An xs:dayTimeDuration specifying how long to keep historical data in the Ops Director database. Default value: P60D

   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:

     Setting	Definition
     opsdirCaCountry	The two-letter code for the country in which the server is located (for example, US)
     opsdirCaProvince	The two-letter code for the state or province in which the server is located (for example, CA)
     opsdirCaLocality	The city in which your server is located (for example, San Carlos)
     opsdirCaOrgName	The organization or company to which the server belongs (for example, MarkLogic)
     opsdirCaOrgUnit	The organizational unit to which the server belongs (for example, Engineering)
     opsdirCaEmail	The email address to contact regarding this server (for example, webmaster@yourcompany.com)

   • 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.

4. Log into the MarkLogic Server Admin UI.
5. From the same Ops Director 2.0 installation directory, run the installer:

   ./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.

Ops Director Resources

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

Configure the Ops Director Cluster

Once you have obtained the CA file (in this example, it is /tmp/opsdir.ca), follow these steps to configure the Ops Director cluster:

1. If necessary, use 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

2. Install Ops Director:

   ./gradlew -PopsdirCa=external mlDeploy

   You may need to specify additional options, such as mlHost, depending on your configuration.

3. 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"
     }
    }
   }

   Our examples use MarkLogic-specific values. You may use other values, but you must use them consistently.

4. Use 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

5. Obtain the ID of the Certificate Authority from Step 1, replacing 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.

6. Create a JSON file (in this example, we call it /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" ]
   }

7. Use curl to POST this file on the REST Management API (port 8002):

   curl --anyauth -u admin:admin -X POST -H \
        "content-type:application/json" \
        -d @/tmp/od-extsec.json \
        http://node1:8002/manage/v2/external-security

8. Create an XML file (in this example, we call it /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>

9. Use curl to PUT this file on the REST Management API (port 8002):

   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.

10. Use the following shell script to generate certificate requests for each of the hosts, replacing host_list with the names of the hosts in your cluster separated by spaces:

    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

11. Get a signed server certificate for each CSR from the CA in step 1.
12. To install the certificates, run the following code, replacing host_list with the names of the hosts in your cluster separated by spaces, and store the certificate in /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.

13. Verify that the certificates have been installed. In the Admin UI, navigate to Configure > Security > Certificate Templates > OpsDirector-SSL-Template. In the right pane, select the Status tab. Make sure each node has a signed certificate and that it is not Temporary.
14. Create a JSON file (in this example, we call it /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.

15. Use 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

Configure the 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
• Setting Up 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.

1. If necessary, use the following 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

2. Use one of the following commands to obtain the ID of the managed cluster:
   • XQuery:

     xquery version "1.0-ml";
     xdmp:cluster()

   • REST (via curl):

     curl -s --anyauth -u admin:admin http://builder:8002/manage/v2 \
        | grep "<id>" | sed "s/<id>//" | sed "s/<.*>//"

3. Create the following JSON file to create a certificate template for the hosts on the cluster (in this example, we call it /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"
     }
     }
   }

4. Use 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

5. Run the following code, substituting the names of each of the hosts in your cluster, separated by spaces, for host_list:

   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

6. Get a signed server certificate for each CSR from the CA in step 1.
7. To install these certificates, run the following code, substituting the names of each of the hosts in your cluster, separated by spaces, for host_list, and replacing /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.

8. Verify that the certificates have been installed. Navigate to Configure > Security > Certificate Templates > OpsDirector-SSL-Template. In the right pane, select the Status tab. Make sure each node has a signed certificate and that it is not Temporary.
9. Use one of the following commands to obtain the ID of the CA from step 1, replacing OpsDirector CA with the name of your CA:
   • XQuery:

     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()))

   • REST (via 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.

10. Create the following JSON file (in this example, we use /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" ]
    }

11. Use 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

12. Create the following JSON file (in this example, we use /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"
    }

13. Use 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.

14. Get a signed client certificate for the CSR from the CA in step <HyperlinkSerif>1.
15. Create an XML file (in this example we use /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>

16. Use 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

17. Create the following JSON file (in this example, we use /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!

18. Use 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.

1. Create a JSON file (in this example, we use /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"
   }

2. Use 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.

3. Get a signed client certificate for that CSR from the CA.
4. Create an XML file (in this example, we use /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>

5. Use 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

Now you can manage the cluster using external certificates.

Configure the Ops Director 2.0 and Earlier Cluster

To configure the Ops Director 2.0 and earlier cluster:

1. Use 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

2. Install Ops Director.
   • If you are using MarkLogic 9.0-7 or earlier, use the Admin UI. See Installing Ops Director for details.
   • If you are using MarkLogic 9.0-8 or later, use the Gradle installer for Ops Director 2.0-0:

     ./gradlew -PopsdirCa=external mlDeploy

     You may need to specify additional options, such as mlHost, depending on your configuration.

3. In the Admin UI, navigate to Configure > Groups > Default. On the Scheduled Tasks tab, disable the task /common/tasks/running.xqy:

   

4. Create the following JSON file (in this example, we use /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"
     }
     }
   }

5. Use 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

6. Obtain the ID of the Certificate Authority from Step 1. If you are using a different certificate, replace 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).

7. Create a JSON file (in this example, we call it /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" ]
   }

8. Use 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

9. To update the server configuration, create an XML file (in this example, we call it /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>

10. Use curl to PUT this file to the REST Management API (port 8002):

    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.

11. Generate server certificate requests for each of the hosts:
    1. Navigate to Configure > Security > Certificate Templates > OpsDirector-SSL-Template. In the right pane, select the Request tab.
    2. Generate CSRs for all hosts.
    3. On the Status tab, download the Pending Certificate Requests.
    4. Get them signed as server certificates, and put all of the signed certificates in a ZIP file at /tmp/od-certs.zip.
12. Use 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.

13. Verify that the certificates have been installed. Navigate to Configure > Security > Certificate Templates > OpsDirector-SSL-Template. In the right pane, select the Status tab. Make sure each node has a signed certificate and that it is not Temporary.

    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.

14. In the Admin UI, navigate to Configure > Groups > Default. On the Scheduled Tasks tab, enable the task /common/tasks/running.xqy:
15. Create a JSON file (in this example, we call it /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" ]
    }

16. Use 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

    The external name must exactly match the subject of the client certificates that you generated when setting up a managed cluster.

Manage a Cluster using Ops Director 2.0 and Earlier

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
• Setting Up 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.

1. Use the following 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

2. Use one of the following commands to obtain the ID of the managed cluster:
   • XQuery:

     xquery version "1.0-ml";
     xdmp:cluster()

   • REST (via curl):

     curl -s --anyauth -u admin:admin http://builder:8002/manage/v2 \
        | grep "<id>" | sed "s/<id>//" | sed "s/<.*>//"

3. Create the following JSON file to create a certificate template for the hosts on the cluster (in this example, we call it 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"
     }
     }
   }

4. Use 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

5. Use one of the following commands to obtain the ID of the CA from step 1:
   • XQuery:

     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()))

   • REST (via 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.

6. Create the following JSON file (in this example, we use /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" ]
   }

7. Use 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

8. Run the following XQuery code to generate server certificate requests for each of the hosts:

   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

9. Get a signed server certificate for each CSR from the CA in step .
10. Put all of the signed certificates in a ZIP file (in this example, we use /tmp/mc-certs.zip).
11. Use 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.

12. Verify that the certificates have been installed. Navigate to Configure > Security > Certificate Templates > OpsDirector-SSL-Template. In the right pane, select the Status tab. Make sure each node has a signed certificate and that it is not Temporary.
13. Run the following XQuery code to generate a client CSR:

    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)

14. Get the CSR signed as a client certificate.
15. Run the following XQuery code to create a credential using the client certificate and its private key, replacing certificate with the client certificate and private_key with the private key for the certificate:

    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()))

16. Create a JSON file (in this example, we call it /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.

17. Use 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://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.

1. Run the following XQuery code to generate a client CSR:

   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.

2. Get the CSR signed as a client certificate.
3. Run the following XQuery code to create a credential using the client certificate and its private key, replacing cluster_ID with the cluster ID, certificate with the client certificate, and private_key with the private key:

   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.