- Overview
- Reference Guide
- Setup & Architecture
- Release Notes
- Workflow
- API Reference
- Integration Guide
- Discovery Agent Setup Guide
NetScaler Troubleshooting
Installation and Registration Errors
- The service fails to start with Service Control Manager error 1069 (“The service did not start due to a logon failure”). The service account needs the local rights Log on as a service and Log on as a batch job. To check, run secpol.msc on the agent host, go to Security Settings > Local Policies > User Rights Assignment, and confirm the account is listed in both policies. On a domain-joined machine, these rights may be enforced by Group Policy; check with your Active Directory team before changing anything.
- Registration reports that the agent name is already registered (“Agent Name should be unique for each agent”). Every agent needs its own NAME in conf.ini. Change it, and register again.
- Registration fails or the service stops right after it starts. The agent stops if it cannot register. Confirm that [CERTSECURE] HOSTNAME_OR_IP is the address used to reach the CertSecure UI, that the host can reach the backend over HTTPS, and that the registration token is new and unused. Then run citrix_ns_agent_svc.exe debug as the service account and register again.
- The agent cannot read the NetScaler password after a service account change. The password is held in the Credential Manager of the account that registered the agent. Register the agent again as the account that runs the service.
- The NetScaler account does not have sufficient rights. Commands such as update ssl certKey or save ns config fail with a permission error. Confirm the account has the rights described in NetScaler Requirements.
Connectivity Errors
The Citrix NS Agent host must reach the CertSecure backend and the NetScaler on the right ports.
| What | Port |
|---|---|
| SSH and SFTP from the agent host to the NetScaler NSIP | TCP 22 |
| HTTPS from the agent host to the CertSecure backend | The port the backend runs on |
Run these commands from the agent host.
-
Port only. Confirms that the network path is open, nothing more:
Test-NetConnection -ComputerName <netscaler-nsip> -Port 22 -
SSH itself. Confirms that a real login works with the account the agent uses, not just the port:
ssh <username>@<netscaler-nsip>
Renewal Errors
Check the task history of the agent first: right-click the agent and choose View Tasks. The Details and Status columns carry the failure reason. The most common messages are listed below.
| Message | Likely cause | What to do |
|---|---|---|
| Certname <name> has no certificate information | The pair was added, but its certificate details were never saved. This message is returned when you start the renewal. | Right-click the agent, choose Update CSR Details, and click Add details for the pair. |
| Failed to bind certificate with <name> was not found | No certificate-key pair with this exact name exists on the NetScaler. | Compare the Pair Name with the output of show ssl certKey on the NetScaler. The name must match exactly. |
| SSH Error during renewal | The agent could not log in, copy the files, or run the commands. Typical causes are wrong credentials, a blocked port, SFTP being unavailable, or no write access to /nsconfig/ssl/. | Run the connectivity commands above, and check the account’s rights on the NetScaler. |
| Error updating certificate on ADC | The NetScaler rejected the update ssl certKey command. For example, the new certificate does not match the key, or the domain of the new certificate differs from the existing one. | The agent log records the NetScaler’s response. Check that the common name and SANs of the pair match the certificate currently on the NetScaler. |
| Failed to submit CSR or Error submitting CSR | The backend rejected the request, for example because of the CA, the template, or a key length below the template’s minimum. | Check the CA and template saved for the pair with Update CSR Details, and the CA connection in CertSecure. |
| Could not get certificate | The CA did not return the certificate in time. The agent waits about 75 seconds. | Check the issuance status on the CA. Queue the renewal again once the CA is responsive. |
Tasks That Do Not Progress
- A task stays PENDING. The agent is offline or busy. Check that the Status is Online and that the EC_Citrix_NS_RenewalAgent service is running. The agent processes one task at a time, and does not start a manual renewal while an expiry check is running. A scheduled task is released only shortly before its scheduled time, and is skipped while the agent is offline.
- Automatic renewal does not start. Confirm that the Automation Status switch is on and that the Renewal Period is set as intended. The agent checks the pairs every 12 hours and after each service start, and queues a renewal only when a pair is within two days of its due date. Each check, and the decision for each pair, is recorded in the agent log.
Cleaning Up
- On the NetScaler. Each renewal copies a new certificate file and key file to /nsconfig/ssl/. The files of earlier renewals remain there once the pair has been updated. You can delete files that are no longer referenced by any certificate-key pair.
- On the agent host. The key and certificate of the last renewal remain in the EC_Citrix_ADC_RA_CERTS folder inside the agent folder. Keep access to the folder restricted.
Agent Log
- The agent writes a detailed log of every action it takes, successful or not, to
EC_Citrix_ADC_Agent.login the folder set by [LOGGING] LOGDIR in conf.ini (by default the logs folder inside the agent folder). - The file rotates automatically once it passes MAXSIZE_BYTES, and NUM_BACKUP rotated files are kept.
- When the task history does not give enough detail to explain a failure, this file is the next place to look.