Skip to main content

NetScaler (Citrix ADC) module

Uploads cert + key to NetScaler ADC over NITRO REST, creates the sslcertkey object, and chains intermediate certificates with fingerprint-based global names to survive multi-cert deployments. The module never relinks virtual servers: updating an existing certkey in place preserves its bindings automatically, while a newly created certkey must be bound to its vservers manually (outside CertAutoPilot).

Overview​

  • Transport: NITRO REST (HTTPS, port 443).
  • Auth: username + password over NITRO (a netscaler_password credential). Client TLS certificates are not supported.
  • 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: supported — a rollback updates the sslcertkey in place to a previous retained certificate version (Rollback). No delete on the next deploy — stale cleanup is out-of-band.
  • Chain depth cap: 5 intermediates.

Prerequisites​

  • 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).

Create the module credential​

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

Create a NetScaler target​

  1. Settings → Distribution → Targets → New. Module: NetScaler.
  2. Fields:
    • Host — NSIP or management DNS name.
    • Port — default 443.
    • Credential.
    • 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.

Object naming​

CertKey Name is optional. Leave it empty and each certificate deploying through the target gets its own auto-generated certkey object:

cap-<token>-<domain>        # token: 8-char hash derived from the certificate; truncated to 31 chars total

This lets one NetScaler target serve many certificates without their certkeys colliding. Set the name explicitly only to adopt an existing certkey already bound to vservers — the module then updates it in place, preserving all bindings. The name can also be set per distribution (per target, with a * default row) from the certificate's Distributions → Overrides drawer.

On-appliance file names are derived from the certkey name automatically; fixed cert_filename/key_filename values are only accepted together with an explicit certkey name (a shared fixed file would be rewritten by every certificate and served wrong after a config reload).

Execution flow​

  1. Upload the leaf cert and key to /nsconfig/ssl/ via systemfile as cap_<project>_<certkey>.pem / .key. (Intermediates are uploaded separately under fingerprint-derived cap_ic_* names, so identical chains deduplicate.)
  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 intermediate chain to the sslcertkey via sslcertkey_sslcertkey_binding. (The module does not touch any profile or virtual-server binding — bindings to vservers are managed outside CertAutoPilot.)
  5. Verify the link graph (GET sslcertkey?filter=certkey:...). A broken chain always fails the target; other link errors fail only in strict chain mode and are downgraded to a warning in soft mode.
Never-delete policy for existing objects

A certkey object CertAutoPilot did not create is treated as read-only: it is never modified and never deleted. Note the module does not read, write or unbind vservers or SSL profiles at all — bindings are entirely yours to manage.

A failed config save still reports success

save_config (on by default) persists the running configuration. If the save fails it is recorded as a warning and the target still reports success — the certkey is live and serving, but the appliance will revert to the previous certificate on its next reboot, possibly months later. Check config_saved in the target detail (the UI shows a "Not persisted" alert) and re-run the distribution, which retries the save.

Target fields not covered above​

FieldMeaning
cert_pathDirectory the certificate files are uploaded to. Default /nsconfig/ssl; must be absolute and may not contain ...
no_domain_checkSkip the domain/SAN sanity check before updating the certkey.
http_timeoutPer-request timeout in seconds (default 30; no upper bound is enforced, unlike F5's 5–300).
skip_chain_linkingDo not install or link intermediate certkeys.

There is no port field: append :port to the NSIP if the appliance's management service listens elsewhere.

Rollback​

Supported via previous-version re-deploy: a rollback updates the sslcertkey in place to a previous retained certificate version — the module's normal deploy path, fed older material. Because the certkey keeps its name, existing VIP/profile bindings persist untouched. Eligibility, the version picker, and auto-rollback: Rollback.

Troubleshooting​

"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.

The certkey updated but nothing is serving it​

The module never binds a certkey to a vserver — a newly created certkey serves nothing until you bind it once on the ADC. Renewals then update that same certkey in place, so the binding persists and needs no further action. Confirm with show ssl vserver <name>.

See also​