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_sslis on (the UI default), plain HTTP when it is off. There is no port field: the module connects to port 443 / 80 unless thensipcarries an explicithost:port. HTTPS offers TLS 1.3 and TLS 1.2 — including the TLS 1.2 RSA key-exchange ciphers (TLS_RSA_WITH_AES_*) that many NSIP management SSL profiles are limited to; a modern appliance still negotiates ECDHE. When the two sides share no version or cipher,NETSCALER_CONNECTsays so instead of a bare "handshake failure". - Auth: username + password (a
netscaler_passwordcredential), sent asX-NITRO-USER/X-NITRO-PASSheaders on every request. Client TLS certificates are not supported. - Artifacts:
/nitro/v1/config/systemfileuploads followed by ansslcertkeycreate or in-placeupdate, thensslcertkey?action=linkfor 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
sslcertkeyin 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 intonsip).
Minimum access
Give a dedicated NetScaler system user one custom command policy (ALLOW) that matches exactly these commands — NetScaler checks every NITRO request against the policy in its CLI form:
show ns version,add system file,rm system fileshow ssl certKey,add ssl certKey,update ssl certKey,link ssl certKey,unlink ssl certKeysave ns config— unless you turnsave_configoff
The built-in sysadmin and network policies are not enough: their published expressions refuse add system file and rm system file, which every deploy needs (rm because each renewal deletes and re-uploads the files). superuser works but gives full control. No rights on vservers or SSL profiles are needed: the module never binds anything.
add system cmdPolicy cap_certkey ALLOW "(^show\s+ns\s+version)|(^(add|rm)\s+system\s+file(\s+.*)?$)|(^(show|add|update|link|unlink)\s+ssl\s+certKey(\s+.*)?$)|(^save\s+ns\s+config)"
add system user certautopilot <strong-password>
bind system user certautopilot cap_certkey 100
save ns config
Test the expression against your firmware before relying on it.
Create the module credential
- Settings → Distribution → Credentials → New → NetScaler.
- Username + password.
- Save.
Create a NetScaler target
- Settings → Distribution → Targets → New. Module: NetScaler.
- Fields:
nsip— management IP or DNS name, optionallyhost:port.- Credential.
use_ssl— HTTPS (default in the form) or plain HTTP. A target created through the API withoutuse_sslsends the credential over HTTP.ssl_verify— verify the appliance's management certificate. With an IPv4nsipthe module warns that a SAN mismatch is likely. To trust a private CA or a self-signed management certificate, see Trusting the appliance's certificate.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).
- 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 may use only letters, digits, ., _ and - (at most 128 characters; this is checked only when a value is new or changed, so a filename saved earlier keeps working) and 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
- Pre-flight —
GET /nitro/v1/config/nsversion, the same probe the health check uses. An unreachable appliance fails withNETSCALER_CONNECT, a rejected credential withNETSCALER_AUTH, before any file is written. - Upload the leaf cert and key to
/nsconfig/ssl/(orcert_path) viasystemfileascap_<project>_<certkey>.pem/.key. A file that already exists is deleted and uploaded again. - 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 reportschanged: false. Otherwise the certkey is updated in place, or created if missing. - 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). - 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. - 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. - Save the configuration when
save_configis on.
Targets that name the same nsip in one run execute one after another; different appliances run in parallel up to the module concurrency.
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.
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
| Field | Meaning |
|---|---|
cert_path | Directory the certificate files are uploaded to. Default /nsconfig/ssl; must be absolute and may not contain ... |
no_domain_check | Skip the domain/SAN sanity check on the in-place update. |
http_timeout | Per-request timeout in seconds, 5–300 (default 30). Values outside the range are rejected by the form and the API. |
skip_chain_linking | Do not install or link intermediate certkeys. |
ca_cert | Optional PEM CA certificate(s) added to the host's trust roots while ssl_verify is on — the appliance's private CA. Refused (400) while ssl_verify is off, and refused (400) while use_ssl is off — it applies to an HTTPS connection only. |
tls_fingerprint_sha256 | Optional SHA-256 fingerprint of the certificate the NSIP serves; checked on every HTTPS connection, with ssl_verify on or off. Refused (400) while use_ssl is off. The health check shows the value. |
Trusting the appliance's certificate
Two optional ways to trust the management certificate, both empty by default — a target that sets neither behaves exactly as before 1.7.0:
- Verify it. Turn
ssl_verifyon; when the certificate comes from a private CA, paste that CA inca_cert(PEM, one or more certificates, up to 64 KiB) and it is added to the host's trust roots for this target.ca_certis only read whilessl_verifyis on — saving it with verification off is refused (400). - Pin it. Put the SHA-256 fingerprint of the certificate the appliance serves in
tls_fingerprint_sha256(64 hex characters, colons optional, any case). The pin is checked on every connection whetherssl_verifyis on or off, so a self-signed management certificate can be trusted exactly. The health check shows the value to paste: its checks listtls_fingerprint_sha256:AB:CD:…. A wrong pin refuses the connection before anything is sent: the target fails withTLS_TRUST_REFUSED(not retried — the other targets of the run are not rolled back for it) and the error names the fingerprint the appliance presented — update the pin when the management certificate changes.
A deploy, dry run or health check that sends a password to an appliance that is neither verified nor pinned reports the warning TLS_UNVERIFIED_PASSWORD with the served fingerprint (a plain-HTTP target is not warned by this code — nothing is encrypted there at all). Clear it by pinning that fingerprint or by turning ssl_verify on (with ca_cert for a private CA). The TLS options are part of the credential-binding rule: for a target whose credential is bound, the person who entered the secret or an organization owner may change them freely; anyone else may only add a check — pin the served fingerprint while ssl_verify stays on, or add a pin or a ca_cert to a target that verified nothing. Turning ssl_verify off (even while adding a pin — that swaps the chain check for a certificate of the editor's choosing), adding a ca_cert beside the system roots while ssl_verify is on (a new trust anchor), or replacing or removing a pin or a CA is refused with 422 CREDENTIAL_TLS_CHANGE_NOT_ALLOWED, and a new NetScaler target that only pins (ssl_verify off with a fingerprint) is judged like one that does not verify at all.
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. An appliance that presents a certificate other than the pinned tls_fingerprint_sha256 is reported as TLS_TRUST_REFUSED instead (nothing sent, not retried, the presented fingerprint in the error) — see Trusting the appliance's certificate.
"link verification failed" (NETSCALER_LINK)
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>.