Skip to main content

NetScaler (Citrix ADC) module

Uploads cert + key to NetScaler ADC over NITRO REST, creates the sslcertkey object or updates it in place, and chains intermediate certificates with fingerprint-based global names to survive multi-cert deployments. The module never binds or 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 over HTTPS when use_ssl is on (the UI default), plain HTTP when it is off. There is no port field: the module connects to port 443 / 80 unless the nsip carries an explicit host:port.
  • Auth: username + password (a netscaler_password credential), sent as X-NITRO-USER / X-NITRO-PASS headers on every request. Client TLS certificates are not supported.
  • Artifacts: /nitro/v1/config/systemfile uploads followed by an sslcertkey create or in-place update, then sslcertkey?action=link for the intermediate chain.
  • Intermediate naming: SHA-256 fingerprint prefix (cap_ic_<fp>) so identical intermediates across different certs converge on one object rather than duplicating.
  • Already-current skip: when the certkey already holds the certificate being deployed, the update is skipped and the target reports unchanged.
  • 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 with management access) reachable from the backend on the NITRO port (443 with use_ssl, 80 without, or the port written into nsip).
  • A system user whose command policy allows show ns version, add/rm system file, show/add/update/link/unlink ssl certKey and — with save_config on — save ns config. The module never binds SSL profiles or vservers, so no binding rights are needed.

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:
    • nsip — management IP or DNS name, optionally host:port.
    • Credential.
    • use_ssl — HTTPS (default in the form) or plain HTTP. A target created through the API without use_ssl sends the credential over HTTP.
    • ssl_verify — verify the appliance's management certificate. With an IPv4 nsip the module warns that a SAN mismatch is likely.
    • strict_chain_linking (bool) — true: an incomplete chain fails the target; false (soft): chain problems are warnings. A broken link (unlinked and not restorable) always fails.
    • save_config — save the running configuration after the deploy (default on).
  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. Pre-flight — GET /nitro/v1/config/nsversion, the same probe the health check uses. An unreachable appliance fails with NETSCALER_CONNECT, a rejected credential with NETSCALER_AUTH, before any file is written.
  2. Upload the leaf cert and key to /nsconfig/ssl/ (or cert_path) via systemfile as cap_<project>_<certkey>.pem / .key. A file that already exists is deleted and uploaded again.
  3. Read the sslcertkey. If it already holds this certificate (same serial, and issuer/subject where NetScaler reports them), the update is skipped: the log says "already current" and the target reports changed: false. Otherwise the certkey is updated in place, or created if missing.
  4. Upload each intermediate certificate as its own file and create a certificate-only cap_ic_<fp> certkey (dedup by fingerprint — an intermediate that already exists with the same identity is reused and never rewritten).
  5. Link the chain with POST sslcertkey?action=link (leaf → first intermediate → next …). A link that is already correct is skipped; a link to a different issuer is unlinked first and restored if the new link fails. The module does not touch any profile or virtual-server binding.
  6. Verify each link by reading the certkey back (GET sslcertkey/<name>). A read-back that shows a different link than the one just set is a link failure.
  7. Save the configuration when save_config is on.

Targets that name the same nsip in one run execute one after another; different appliances run in parallel up to the module concurrency.

What is and is not modified

An intermediate certkey CertAutoPilot did not create (found by content match) is treated as read-only: it is only used as a link target, never modified or deleted. The leaf certkey named in certkey_name (or an override) is adopted and updated in place — that is the point of naming it. The module never reads, writes or unbinds vservers or SSL profiles — 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 even when the certkey is already current.

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 on the in-place update.
http_timeoutPer-request timeout in seconds, 5–300 (default 30). Values outside the range are rejected by the form and the API.
skip_chain_linkingDo not install or link intermediate certkeys.

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, and because the older version has a different serial the already-current skip never suppresses it. Eligibility, the version picker, and auto-rollback: Rollback.

Troubleshooting​

NETSCALER_CONNECT or NETSCALER_AUTH before anything was uploaded​

The pre-flight nsversion probe failed. CONNECT: check nsip (host and port), use_ssl, ssl_verify against the management certificate, and firewall rules — the target health check reproduces it. AUTH: wrong password, or the user's command policy lacks show ns version.

After linking, the module read the certkey back and it did not show the link it had just set — the appliance accepted the link but reports a different linkcertkeyname (or none). Inspect the certkey on the ADC (show ssl certKey <name>), relink by hand if needed, or set strict_chain_linking to false so the run continues with a warning. If the log says the chain is broken, an old link was removed and could not be restored: relink the named certkey manually.

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​