CertAutoPilot logo CertAutoPilot
Get started →

NetScaler (Citrix ADC) module

Uploads cert + key to NetScaler ADC over NITRO REST, creates the sslcertkey object, chains intermediate certificates with fingerprint-based global names to survive multi-cert deployments, and relinks any virtual servers bound to the previous cert.

01Overview

  • Transport: NITRO REST (HTTPS, port 443).
  • Auth: username + password, or client TLS certificate.
  • Artifacts: /nitro/v1/config/systemfile uploads followed by /nitro/v1/config/sslcertkey object creation + link to intermediate chain.
  • Intermediate naming: SHA-256 fingerprint prefix so identical intermediates across different certs converge on one object rather than duplicating.
  • Rollback: not supported. Old sslcertkey objects remain. No delete on the next deploy — stale cleanup is out-of-band.
  • Chain depth cap: 5 intermediates.

02Prerequisites

  • NSIP or SNIP reachable from the backend on 443.
  • A management user with permission to create sslcertkey objects and bind SSL profiles.
  • Firmware 12.0+ (NITRO REST is stable from there).

03Create the module credential

  1. Settings → Distribution → Credentials → New → NetScaler.
  2. Username + password.
  3. Save.

04Create a NetScaler target

  1. Settings → Distribution → Targets → New. Module: NetScaler.
  2. Fields:
    • Host — NSIP or management DNS name.
    • Port — default 443.
    • Credential.
    • SSL profile / VS name — the object we update to reference the new cert.
    • Intermediate naming strategy — fingerprint (recommended) or prefix. Fingerprint-based survives multi-cert deployments; prefix-based matches what legacy tooling emits.
    • Chain error handling — strict (fail if chain is incomplete) or soft (warn-and-continue).
    • TLS skip verify — for management self-signed cert during bring-up.
  3. Save → health check calls /nitro/v1/config/nsversion.

05Execution flow

  1. Upload cert PEM + key PEM to /nsconfig/ssl/ via systemfile with fingerprint-suffixed names.
  2. Upload each intermediate certificate as its own file (dedup by fingerprint — identical intermediates across certs become one object).
  3. Create the sslcertkey object if missing, or update it.
  4. Link the sslcertkey to its chain via sslcertkey_sslcertkey_binding.
  5. Update the profile / virtual server binding to reference the new sslcertkey name.
  6. Verify the link graph (GET sslcertkey?filter=certkey:...) and fail the distribution if any chain edge is missing.
Never-delete policy for existing objects

If the target VS / profile already references a cert object not created by CertAutoPilot, the module treats it as read-only — we unbind our updates from it but never delete it. This prevents accidental removal of certs shared across unrelated services on the same ADC.

06Rollback — not supported

Old sslcertkey objects remain. To revert manually, bind the profile/VS to the previous sslcertkey name (still present). Automated rollback is not offered because SSL profile rebinds can cause session drops.

07Troubleshooting

"Chain link verification failed"

An intermediate referenced by the cert is missing from the upload set. Check the cert's issuer chain completeness (openssl crl2pkcs7 ...). If your CA consistently omits an intermediate you can pre-upload it manually to the NetScaler and set chain handling to soft.

"sslcertkey object locked"

Another administrative session is editing the object. Wait and retry, or force-save the other session.

"VS rebind failed"

The VS name in the target config doesn't exist, or the user lacks bind permission on it. show lb vserver <name> on the CLI to confirm.