Replace an SSL Certificate on Citrix NetScaler (ADC)

NetScaler represents a server certificate and its private key as a certificate-key pair (the ssl certKey object), which is bound to SSL virtual servers and services. Updating that object in place keeps every binding: all SSL virtual servers it is bound to - including NetScaler Gateway virtual servers - switch to the new certificate automatically, without a gap. The alternative - unbind, remove, add, bind - takes each virtual server down between the steps.

Before you beginCopy Anchor Link

• Find the certificate-key pair to replace: Traffic Management > SSL > Certificates > Server Certificates lists them, or show ssl certKey in the CLI. Note its name, its files under /nsconfig/ssl, the linked intermediate, every virtual server it is bound to (show ssl certKey <name> lists them) and the HA state.
• Copy the current certificate and key files somewhere safe - you need them for a rollback.
• Prepare either a PFX file with its password, or PEM certificate and key files (plus the key's password if it is encrypted).
• Check whether the new certificate has the same name as the old one. If not - for example when moving from gateway.example.com to *.example.com - NetScaler's domain check rejects the update unless you select No Domain Check.

Step-by-step certificate replacementCopy Anchor Link

1. Update the certificate-key pairCopy Anchor Link

In the GUI (accepts a PFX directly):

1. Go to Traffic Management > SSL > Certificates > Server Certificates, select the certificate and click Update.
2. Select Update the certificate and key.
3. Under Certificate File Name, choose Choose File > Local and select the new file:
   • a .pfx file - you are asked for its password; no separate key file is needed, or
   • a PEM certificate - then also upload the key file, and give its password if the key is encrypted.
4. If the certificate name differs from the old one, select No Domain Check.
5. Click OK.

In the CLI (PEM files):

1. Copy the new files to /nsconfig/ssl (for example with SCP) and make the key readable only by root.

2. Update the pair and check it:

   Copy Text

   update ssl certKey gateway-cert -cert /nsconfig/ssl/gateway-2026.pem -key /nsconfig/ssl/gateway-2026.key
   show ssl certKey gateway-cert

   Add -password for an encrypted key and -noDomainCheck when the certificate name changes. For a PFX file, use the GUI.

2. Check the chainCopy Anchor Link

If the new certificate comes from a different intermediate CA, the pair still links to the old intermediate. Install the new intermediate as its own certificate (in the GUI under Traffic Management > SSL > Certificates > CA Certificates > Install, without a key), then replace the link:

add ssl certKey intermediate-2026 -cert /nsconfig/ssl/intermediate-2026.pem
unlink ssl certKey gateway-cert
link ssl certKey gateway-cert intermediate-2026
show ssl certlink

Since release 13.0 build 47.x, the GUI can also link automatically when the intermediate and root certificates are on the appliance: use the Link button on the server certificate.

3. Check the bindingsCopy Anchor Link

show ssl vserver <vserver-name>

The virtual server should list the updated certificate-key pair.

4. Save and synchronize HACopy Anchor Link

Save the configuration - otherwise the change is lost on the next reboot - and push the SSL files to the HA secondary. Run both on the primary:

save ns config
sync HA files SSL

In the GUI, save with the disk icon, and start the file sync under Traffic Management > SSL > Start SSL certificate, key file synchronization for HA. The secondary also copies /nsconfig/ssl by itself every minute and whenever a file is added; the command forces it now.

Get warned before the next expiryCopy Anchor Link

Turn on the expiry monitor. It writes entries to the appliance's syslog and audit log when the certificate is due to expire; SNMP alerts for certificate expiry have to be configured separately.

set ssl certKey gateway-cert -expiryMonitor ENABLED -notificationPeriod 30

The notification period is in days. In the GUI: select the certificate, click Update and select Notify When Expires.

Product-specific considerationsCopy Anchor Link

If you created a new certificate-key pair instead of updating the old one, bind it to each virtual server yourself:

bind ssl vserver <vserver-name> -certkeyName <new-certkey>

Unbinding the old pair first makes the virtual server inactive until a valid certificate is bound again; check the SNI settings of the virtual server if it serves several certificates.

A single PEM file can carry the server certificate and up to nine intermediates: add it with add ssl certKey ... -bundle YES, and NetScaler creates and links the intermediates itself. A separate object type, the certificate-key bundle (ssl certKeyBundle), can be updated directly with update ssl certKeyBundle from release 14.1 build 12.x; on older releases a bundle has to be unbound, deleted, added and bound again.

Verify the new certificateCopy Anchor Link

show ssl certKey gateway-cert
show ssl certlink
show ssl vserver <vserver-name>

Then test every hostname over the network:

openssl s_client -connect gateway.example.com:443 -servername gateway.example.com -showcerts </dev/null

Check subject and SAN, issuer, expiry date and that the intermediate is sent. Confirm the files have reached the HA secondary (show ssl certKey there) and test it before a failover.

RollbackCopy Anchor Link

Run update ssl certKey with the saved old files (and -noDomainCheck if the name differs), restore the old intermediate link, save and sync HA. Keep both sets of files until every virtual server is validated.

Common problemsCopy Anchor Link

• The pair was updated but still links to the old intermediate, which did not issue the new certificate.
• The files exist on the primary but not on the HA secondary.
• A new pair was created and never bound to the virtual server.
• The domain check rejected an intentional name change - use No Domain Check.
• The configuration was not saved and the change was lost after a reboot.

Automating certificate replacement with aethercertCopy Anchor Link

The aethercert NetScaler target uploads the certificate/key, creates or updates the named sslcertkey, and uploads/links intermediate certificates. It intentionally does not bind the certkey to an SSL vserver, because that association is environment-specific.

See Deploy targets for the fields this preset takes, what it needs on the host, and how far it has been verified.

SourcesCopy Anchor Link

• NetScaler: install, link, and update certificates
• NetScaler: ssl certKey command reference
• NetScaler: bind a certificate to a virtual server
• NetScaler: synchronize SSL files in HA