SSL certificate renewals are one of those NetScaler tasks that should be routine, but they are easy to get wrong when a certificate is tied to a production VPN or load balancing virtual server.
The certificate itself is usually not the difficult part. The problems come from the surrounding pieces:
- The new certificate does not match the private key
- An intermediate certificate is missing
- The new certificate is installed but the virtual server is still using the old one
- An existing certificate is replaced instead of updated, leaving bindings behind
- One node of a high availability pair does not have the certificate files
- The configuration is changed but not saved
- The certificate looks correct in the GUI but the public service is presenting something unexpected
This guide covers the process on NetScaler 14.1. The GUI varies slightly between builds, but the underlying workflow is the same, and the CLI commands have been stable for years.
Before you start
Identify exactly which certificate you are replacing and where it is being used.
For a typical NetScaler Gateway deployment, the certificate is bound to a VPN virtual server. Virtual servers have their own certificate configuration, so installing a new certificate does not automatically make it the one presented to users.
You should have:
- The renewed server certificate
- The private key that matches it, unless you are reusing a certificate-key pair already on the appliance
- Any required intermediate CA certificates
- Access to the administrative interface
- A way to test the service externally afterwards
If you are replacing an existing certificate with another for the same domain, updating the existing certificate-key pair is the cleanest approach.
If you are changing to a different domain, NetScaler performs a domain check. That can be disabled when the change is intentional, but not simply to make an error go away.
Supported formats
NetScaler accepts PEM, DER and PFX (PKCS12).
PEM .crt .pem .cer
DER .der
PFX .p12 .pfx
The file extension generally doesn’t matter. The contents determine the format and the certificate is parsed accordingly.
1. Identify the existing certificate
From the GUI:
Traffic Management → SSL → Certificates → Server Certificates
Or from the CLI:
show ssl certKey
For a specific certificate:
show ssl certKey <certkey-name>
That gives you the status, subject, issuer, expiry date and the certificate and key paths.
If you aren’t sure which certificate is bound to a particular virtual server:
show ssl vserver <vserver-name>
Do this before changing anything. Troubleshooting a renewal is far easier when you know exactly which certificate object and virtual server you’re working with.
2. Check the new certificate and private key
Before uploading anything, confirm the certificate is the one you intended.
Check:
- Subject
- SAN entries
- Expiry date
- Issuer
- Certificate type
The hostname users connect to must be covered by the Common Name or, preferably, a Subject Alternative Name.
If the certificate was issued using the existing private key, you can update the existing certificate-key pair rather than creating a new object.
If you’ve been given a new private key, confirm it matches the new certificate. A certificate and key that don’t form a matching pair will not give you a working configuration.
3. Get the intermediate chain right
This is the most common cause of certificate problems after a renewal.
A client may trust the root CA without having the intermediate CA certificate needed to build a chain back to it. NetScaler must send the intermediate certificates during the TLS handshake.
It must not send the root CA certificate. NetScaler’s documentation is explicit about this: the PKI trust model requires root CAs to be installed on clients out of band, through the operating system or browser. A root CA sent by the appliance is ignored by the client.
A typical chain:
Server certificate
|
v
Intermediate CA
|
v
Root CA (on the client, not sent by the appliance)
Why this matters more for Citrix clients than browsers
Here’s the trap that catches people out.
A browser will often paper over a missing intermediate. It may have cached the intermediate from another site, or fetch it via the Authority Information Access extension in the certificate.
Citrix Workspace app generally will not.
So the classic outcome after a renewal is that the gateway loads fine in Chrome, the administrator concludes the certificate is correct, and every Workspace app client fails with a handshake error. If you’re seeing that pattern, the missing intermediate is where to look. It’s one of the causes behind SSL Error 47 handshake failures.
Test with a Citrix client, not just a browser.
Checking the links
show ssl certlink
And the chain for a specific certificate:
show ssl certchain <cert-name>
Linking manually
If the CA supplied an intermediate with the renewal, install it and link the server certificate to it:
link ssl certkey <server-certkey> <intermediate-certkey>
Then verify:
show ssl certlink
Or use a certificate bundle instead
There’s a simpler option that many people don’t know about.
Rather than adding and linking each certificate individually, you can group the server certificate and up to nine intermediates in a single file, then add it with the -bundle option:
add ssl certKey <certkey-name> -cert /nsconfig/ssl/bundle.pem -key /nsconfig/ssl/bundle.pem -bundle YES
The file must be in this order:
Server certificate (must be first)
Server key (optional)
Intermediate 1
Intermediate 2
Intermediate 3 ...
NetScaler creates intermediate certificate files automatically, named <bundlename>.pem_ic1, .pem_ic2 and so on, and links them for you.
Most CAs supply a bundle file with the renewal anyway, so this is often less work than linking manually.
Two restrictions worth knowing: the bundle option is not supported on the NetScaler FIPS platform or in a cluster setup, and the file must be valid PEM with no more than nine intermediates.
4. Update the existing certificate-key pair
If the new certificate is replacing the existing one for the same service, update the existing certificate-key pair rather than deleting it and creating a new object.
This matters because the existing pair may already be bound to one or more SSL virtual servers. Updating it in place means those bindings continue to work without being touched.
Using the GUI
Traffic Management → SSL → Certificates → Server Certificates
Select the existing certificate and click Update, then choose to update the certificate and key.
Select the new certificate file. For PEM, provide the matching private key. For PFX, NetScaler prompts for the password.
If the new certificate is for the same domain, leave the domain check enabled.
Using the CLI
With the files uploaded to /nsconfig/ssl:
update ssl certKey <certkey-name> -cert /nsconfig/ssl/new-certificate.pem -key /nsconfig/ssl/private-key.pem
Then verify:
show ssl certKey <certkey-name>
NetScaler’s default certificate directory is /nsconfig/ssl, and absolute paths are recommended.
One version note: from 14.1 build 21.x, the maximum path length for certificate and key parameters increased from 63 to 255 characters. On earlier builds, a deeply nested path can fail for reasons that aren’t obvious.
If the domain is deliberately changing
update ssl certKey <certkey-name> -cert /nsconfig/ssl/new-certificate.pem -key /nsconfig/ssl/private-key.pem -noDomainCheck
Use -noDomainCheck only when the domain change is intentional. If you expected vpn.example.com and received a certificate for something else, stop and check the certificate rather than bypassing the warning.
5. Check the certificate binding
show ssl vserver <vserver-name>
You should see the certificate-key pair associated with the virtual server.
If you created a new certificate-key pair rather than updating the existing one, you need to bind it:
bind ssl vserver <vserver-name> -certkeyName <certificate-key-pair>
Then verify again.
Binding a new certificate-key pair replaces the previous binding. Connections that have already completed their TLS handshake aren’t affected, but others can be terminated.
That disruption is another reason to prefer updating the existing pair.
6. Re-check the chain after the update
Don’t assume the chain survived the certificate replacement.
show ssl certlink
show ssl certchain <cert-name>
If the renewed certificate was issued from a different intermediate CA, you’ll need to install the new intermediate and link to it. CAs do change their intermediates, and a renewal issued from a new one will break a chain that worked perfectly the day before.
7. If you have an HA pair, check both nodes
Don’t assume configuration synchronisation has put every certificate and key file where it needs to be.
Certificate and key files must exist on both the primary and secondary appliances, using the same directory path.
NetScaler provides HA file synchronisation specifically for SSL certificates, keys and CRLs:
sync HA files ssl
Then confirm the files exist on both appliances.
This matters most before a failover. A renewal can look completely successful while the primary is active and then fail the moment the secondary takes over, which is usually at the worst possible time.
8. Save the configuration
Easy to forget, and the consequences only appear later.
save ns config
From the GUI, use the Save icon.
Configuration changes must be saved to persist across a restart. Unsaved changes are lost if the appliance reboots or is shut down.
Make this part of the renewal procedure rather than treating it as optional. “Everything worked until the appliance rebooted three weeks later” is a specific and avoidable kind of problem.
9. Verify from outside
The GUI tells you what’s configured. It doesn’t tell you what an external client receives.
Browse to the actual FQDN users connect to and inspect the certificate. Check the subject, SAN, expiry, issuer and chain, and confirm there are no warnings.
If the service is a gateway, test an actual client login, not just the web page. The certificate exists to support the real service.
10. Use OpenSSL to see what’s actually being presented
openssl s_client -connect vpn.example.com:443 -servername vpn.example.com -showcerts
-servername matters when SNI is involved, because it tells the server which hostname the client is requesting. -showcerts displays the full chain the server returns.
For stricter verification:
openssl s_client -connect vpn.example.com:443 -servername vpn.example.com -showcerts -verify_return_error
Read the certificate chain section of the output. If the server certificate is correct but an intermediate is missing, this is where you’ll see it.
The value of this test is that it checks the live endpoint, not the certificate object stored on the appliance. Those can disagree.
Common problems after a renewal
Users still see the old certificate
show ssl vserver <vserver-name>
If you created a new certificate-key pair rather than updating the existing one, you may have installed the certificate without binding it.
The certificate is valid but clients report a chain error
Check the intermediate:
show ssl certlink
show ssl certchain <cert-name>
Then test the live endpoint with OpenSSL. Remember that a browser may succeed where a Citrix client fails.
The certificate and private key don’t match
Confirm the certificate was issued from the CSR associated with the private key you’re using.
If the CA issued the renewal from a different CSR, you need the corresponding key. Any private key for the same hostname will not do.
NetScaler rejects the certificate on the domain check
If the domain change is intentional:
update ssl certKey <certkey-name> -cert /nsconfig/ssl/new.pem -key /nsconfig/ssl/new.key -noDomainCheck
Note that -cert and -key are still required. -noDomainCheck on its own isn’t a complete command.
The primary works but the secondary fails after failover
sync HA files ssl
Then confirm the files exist on both nodes at matching paths.
Everything works until the appliance reboots
save ns config
Get warned before the certificate expires
Renewals are far easier when you know they’re coming.
NetScaler has a certificate expiry monitor that writes to the appliance syslog and audit logs as a certificate approaches expiry:
set ssl certKey <certkey-name> -expiryMonitor ENABLED -notificationPeriod 60
Then verify:
show ssl certKey <certkey-name>
Sixty days gives you enough time to raise a change, obtain the certificate and schedule the work properly. Thirty is the default and is usually enough, but it leaves less room when a CA validation process drags.
If you’re monitoring the appliance with a syslog server or SIEM, those notifications are worth alerting on. A certificate expiry is one of the few outages you can see coming weeks in advance.
The order that matters
Most renewal problems come from doing these in the wrong order, or skipping one:
- Identify which certificate-key pair the virtual server actually uses
- Confirm the new certificate and key match, and cover the right hostname
- Update the existing certificate-key pair rather than creating a new one
- Check the intermediate chain is still correct after the update
- Confirm the binding on the virtual server
- Synchronise files to the secondary HA node
- Save the configuration
- Verify the live endpoint from outside, with a real client
The certificate update itself takes two minutes. The other seven steps are what stop you finding out something was wrong at the next failover or reboot.
NetScaler references
- Install, link and update certificates – certificate formats, linking intermediates and the root CA behaviour
- Add a certificate bundle – grouping a server certificate with its intermediates in one file
From my early days on the helpdesk through roles as a service desk manager, systems administrator, and network engineer, I’ve spent more than 25 years in the IT world. As I transition into cyber security, my goal is to make tech a little less confusing by sharing what I’ve learned and helping others wherever I can.