Skip to main content

Administrating MarkLogic Server

Keeping XDQP Certificates Up to Date

When a host is initialized, MarkLogic automatically generates a self-signed certificate for it in case you enable XDQP SSL. These SSL certificates are good for 10 years.

Warning

To keep an XDQP SSL-configured host running, you must renew its certificate before the old one expires.

At the host level, by default, MarkLogic detects when each host's certificate expires within 3 months and logs a warning message like this, alerting you to renew its certificate:

2023-07-26 15:39:58.791 Warning: XDQP host certificate will expire in 9 day(s). Please renew it using admin:host-renew-xdqp-certificate and admin:host-activate-new-xdqp-certificate.

At the cluster level, MarkLogic provides 3 APIs to keep these XDQP certificates up to date. The following table describes each API, and the outline following the table describes how you could use them to keep your certificates up to date:

API

Action

admin.hostNeedRenewXdqpCertificate()

Obtains a cluster-wide list of hosts whose XDQP certificates expire within the specified time frame:

  • The default time frame is 3 months.

  • The time frame that you specify is how often you must use this API to check for expiring certificates. That is, if you specify 12 months for your time frame, you must also use this API every 12 months to catch any expiring certificates so that you can update them.

  • If the API returns an empty sequence, no certificates expire within your specified time frame.

  • This action does not require all hosts in the cluster to be online.

admin.hostRenewXdqpCertificate()

Generates a new XDQP certificate for any host within a cluster whose current certificate expires within the specified time frame:

  • The default time frame is 3 months.

  • Use the same time frame with this API as you used with admin.hostNeedRenewXdqpCertificate().

  • Calling this API on one host in a cluster automatically generates new certificates for any other hosts in that cluster whose certificates also expire within the specified time frame.

  • You must make sure that all hosts in the cluster are online:

    • If a host is offline or goes offline, this API returns an error message like this one:

      [1.0-ml] XDMP-HOSTOFFLINE: xdmp:renew-host-certificate(ho:host-id("16773022918143520398"), "-----BEGIN CERTIFICATE-----
MIICzjCCAbagAwIBAgIJAMgG7xp+keyY...") -- Host is offline or not responding

    • If you see this error message, you must call the API again to complete this process.

admin.hostActivateNewXdqpCertificate()

Activates new XDQP certificates generated with admin.hostRenewXdqpCertificate() for any hosts in the cluster:

  • You must generate new XDQP certificates before attempting to activate them.

  • Calling this API on one host in a cluster automatically activates any other new certificates for hosts in that cluster.

  • This action does not require all hosts in the cluster to be online.

Here is an outline of how to use these APIs periodically (that is, every 3 months or every year or every whatever time frame you specify in the APIs) to keep your certificates up to date:

  1. Use admin.hostNeedRenewXdqpCertificate() on one host in the cluster to find any hosts on that cluster whose certificates expire within your chosen time frame. If the API returns an empty sequence, skip the rest of these steps.

  2. During a maintenance window, update any expiring certificates:

    1. Make sure that all hosts in the cluster are online.

    2. Use admin.hostRenewXdqpCertificate() on one host in the cluster to generate new certificates for any hosts in that cluster whose certificates expire within your chosen time frame:

      1. Use the same time frame here as you used in Step 1.

      2. Check for the error message that this API returns to indicate that a host is or has gone offline. If the message occurs, make sure that all hosts are online and call the API again.

    3. Use admin.hostActivateNewXdqpCertificate() on one host in the cluster to activate any new certificates for all hosts in that cluster.

  3. Make sure that all expiring certificates have been updated by using admin.hostNeedRenewXdqpCertificate() again and checking that it returns an empty sequence.

In this section: