Certificate Installation when Hostname different than FQDN
15 July 2021 02:51 PM


Each node in MarkLogic Server Cluster has a hostname, a human-readable nickname corresponding to the network address of the device. MarkLogic retrieves the hostname from underlying operating system during installation. On Linux, we can retrieve platform hostname value by running "$ hostname" from a shell prompt. 

$ hostname

In most environments, hostname is the same as the platform's Fully-Qualified-Domain-Name (FQDN). However, there are scenarios where hostname could be different than the FQDN. On such environments you would use FQDN ( to connect to platform instead of hostname

$ ping

PING ( 56(84) bytes of data.

64 bytes from ( icmp_seq=1 ttl=64 time=0.011 ms

During Certificate Installation to Certificate template on environments where hostname and FQDN mismatch, MarkLogic looks for the CN field in the Installed Certificate to find a matching hostname in the cluster. However since CN field (reflecting FQDN) does not match the hostname known to MarkLogic, MarkLogic does not assign the installed Certificate to any specific host in Cluster.

Subject: C=US, ST=NJ, L=Princeton, O=MarkLogic, OU=Eng,

Installing Certificates in this scenario results in the installed Certificate not replacing the Temporary Certificate, and the Temporary Certificate will still be used with HTTPS App Server instead of the installed Certificates.

This article details different solutions to address this issue. 


1) Hostname change

By default MarkLogic picks the hostname value presented by the underlying operating system. However we can always change the hostname string stored in MarkLogic Server after installation using Admin API admin:host-set-name ( )

Changing the hostname in MarkLogic (to reflect the FQDN name) will not affect the underlying Platform/OS hostname values, but will result in MarkLogic being able to find the correct host for the installed Certificate (CN field = hostname), and thus able to link then installed Certificate to specific host in Cluster.

2) XQuery code linking Installed Cert to specific Host

You can also use below XQuery code from QConsole against Security DB (as content source) to update Certificate xml files in Security DB, linking Installed Certificate to Specific host.

Please change the Certificate Template-Name, and Host-Name in below XQuery to reflect values from your environment.

xquery version "1.0-ml";

import module namespace pki = ""  at "/MarkLogic/pki.xqy";
import module namespace admin = ""  at "/MarkLogic/admin.xqy";

(: Change to your hostname string :)
(: if Qconsole is launched from the same host, then below can be used as well :)
(: let $hostname := xdmp:host-name()    :)
let $hostname :=""
let $hostid := admin:host-get-id(admin:get-configuration(), $hostname)

(: FQDN name matching Certificate CN field value :)
let $fqdn := ""

(: Change to your Template Name string :)
let $templateid := pki:template-get-id(pki:get-template-by-name("YourTemplateName"))

for $i in cts:uris()
(   (: locate Cert file with Public Key :)
    and fn:doc($i)//pki:certificate/pki:authority=fn:false()
    and fn:doc($i)//pki:certificate/pki:host-name=$fqdn
return <h1> Cert File - {$i} 
{xdmp:node-insert-child(doc($i)/pki:certificate, <pki:host-id>{$hostid}</pki:host-id>)}
    (: extract cert-id :)
    let $certid := fn:doc($i)//pki:certificate/pki:certificate-id
    for $j in cts:uris()
        (: locate Cert file with Private key :)
        and fn:doc($j)//pki:certificate-private-key/pki:certificate-id=$certid
    return <h2> Cert Key File - {$j}
    {xdmp:node-insert-child(doc($j)/pki:certificate-private-key, <pki:host-id>{$hostid}</pki:host-id>)}
} </h1>

Also, note that above will not replace/overwrite the temporary Certificate, however our App Server will start using Installed Certificate from this point instead of Temporary Certificate. One can also delete the now unused Temporary Certificate file from QConsole without any negative effect.

3) Certificate with Subject Alternative Name (SAN Cert)

You can also request your IT (or Certificate issuer) to provide a Certificate with altSubjectName that matches MarkLogic's understanding of the host. MarkLogic, during the Installation of the Certificate, will look for Alternative names and link Certificate to correct host based on altSubjectName field.


Further Reading


(4 vote(s))
Not helpful

Comments (0)