- Overview
- Reference Guide
- Setup & Architecture
- Release Notes
- Workflow
- API Reference
- Integration Guide
- Discovery Agent Setup Guide
NetScaler Setup
This section covers the prerequisites for the Citrix NS Agent host and the NetScaler appliance, and the steps to install, register, and validate the Citrix NS Agent.
Supported Targets
| Item | Supported |
|---|---|
| Appliance | Citrix NetScaler (ADC) with a management IP address (NSIP) reachable over SSH |
| Objects renewed | SSL certificate-key pairs (ssl certKey) |
| Number of appliances | One per Citrix NS Agent |
| Number of agents | One per NetScaler appliance. More than one agent can be registered. |
Citrix NS Agent Host Requirements
The Citrix NS Agent runs as a Windows service on a host in your network. It does not need to run on the NetScaler.
- A Windows Server host (Windows Server 2016 or later).
- A dedicated service account. The account needs full control over the installation directory and the local rights Log on as a service and Log on as a batch job.
- Outbound HTTPS access (TCP, on the port the backend is running) to the CertSecure Manager backend.
- Outbound SSH access (TCP 22) to the NetScaler management IP (NSIP).
Good to know:
- The agent stores the NetScaler password and its authentication token in the Windows Credential Manager of the account that registers it. Register the agent as the same account that runs the service.
NetScaler Requirements
- SSH access. TCP 22 must be reachable from the agent host to the NetScaler NSIP.
- An account with sufficient rights. The agent runs show ssl certKey, update ssl certKey, and save ns config over SSH, and copies the renewed certificate and key into /nsconfig/ssl/ over SFTP. The account needs a command policy that allows these SSL configuration and save commands, plus write access to /nsconfig/ssl/. In practice, this means an administrator-level account. A reduced-privilege role may not work properly.
- The certificate-key pair already exists. The SSL certificate-key object must exist on the NetScaler under the exact name you enter as the Pair Name, and must already be bound wherever it needs to be. CertSecure only refreshes its certificate material. It does not create the object or bind it to a virtual server.
- High availability. If you run a NetScaler HA pair, point the agent at the management IP (NSIP) of the primary node. NetScaler’s own HA configuration sync carries the change to the other node after save ns config runs, so nothing extra is needed for the second node.
CertSecure Requirements
- A Certificate Authority and a Template must be configured in CertSecure for each certificate-key pair. For DigiCert, an Organization ID and an Order Validity are also required.
- Your user account needs the Manage Renewal Agents permission.
Installation and Registration
- Download the installer. Go to Utilities > Integrations > Load Balancers, click the NetScaler tile, and click Download.
- Extract the package to a folder on the agent host, for example C:\EC_Citrix_NS_Agent. Make sure the service account has full control over this folder.
- Open conf.ini in the folder and set the values described in the Configuration File table. At a minimum, set the CertSecure backend address under [CERTSECURE] and the NetScaler NSIP under [CITRIX_NS]. If you register more than one agent, give each a unique NAME.
-
Install the service. Open an administrator Command Prompt in the agent folder and run:
citrix_ns_agent_svc.exe --username "DOMAIN\ServiceUser" --password "YourPassword" --startup=auto install - In CertSecure, go to Utilities > Integrations > Load Balancers and click Registration Token to generate a one-time token.
-
Register the agent. Open a Command Prompt as the service account (the same account used in the previous step), go to the agent folder, and run:
citrix_ns_agent_svc.exe debug - When prompted, enter the registration token, the NetScaler username, and the NetScaler password. Wait for the agent to register, and then press Ctrl+C to leave debug mode.
- Start the service. Open services.msc, select EC_Citrix_NS_RenewalAgent, and click Start.
Configuration File
| Section | Key | Default | Description |
|---|---|---|---|
| [INFO] | NAME | Citrix_NS_Agent | The name of this agent in CertSecure. It must be unique for each agent. Use a name that identifies the appliance. |
| [INFO] | RENEWAL_AGENT_TAG | Default | A tag used to group agents in CertSecure. |
| [CERTSECURE] | HOSTNAME_OR_IP | (empty) | Required. Hostname or IP address of the CertSecure backend. Use the same address you use in the browser. |
| [CITRIX_NS] | HOSTNAME_OR_IP | (empty) | Required. The NetScaler management IP (NSIP) this agent manages. |
| [LOGGING] | LOGDIR | logs | Folder for the agent log. |
| [LOGGING] | MAXSIZE_BYTES | 100000000 | Size at which the log file rotates. |
| [LOGGING] | NUM_BACKUP | 10 | Number of rotated log files kept. |
Validation
- Go to Utilities > Integrations > Load Balancers and click the NetScaler tile.
- Confirm that the agent is listed with the Status Online. A newly registered agent has the default Renewal Period of 200 days and Automation Status off.
- Your environment is now ready for certificate-key pairs. See the UI Guide to add a pair and renew it.
