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 |
---|---|
Obtains a cluster-wide list of hosts whose XDQP certificates expire within the specified time frame:
|
|
Generates a new XDQP certificate for any host within a cluster whose current certificate expires within the specified time frame:
|
|
Activates new XDQP certificates generated with
|
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:
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.During a maintenance window, update any expiring certificates:
Make sure that all hosts in the cluster are online.
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:Use the same time frame here as you used in Step 1.
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.
Use
admin.hostActivateNewXdqpCertificate()
on one host in the cluster to activate any new certificates for all hosts in that cluster.
Make sure that all expiring certificates have been updated by using
admin.hostNeedRenewXdqpCertificate()
again and checking that it returns an empty sequence.