Sectigo.com
Shop Enterprise Partners Resources

Using the connector

To list all possible options for the connector, run it with the --help option.

python3 citrixagent.py --help

If you used a Python virtual environment during installation, make sure to activate it every time you open a terminal to run the connector by executing source .venv/bin/activate.

Enroll a certificate

You can enroll certificates for all appliances or specific appliances.

If you’re using an external credentials file, specify the path to the file by using the -c or --credentials option. When you run the connector for the first time, you can automatically accept or reject EULA by passing the --accept-eula or --reject-eula option, correspondigly.

If you’d like to log the passphrase for the private key to retrieve it later, pass the --log-passphrase option when you enroll a certificate.

  • All appliances

  • Specific appliances

To enroll certificates for all certificate profile files, run the following command.

python3 citrixagent.py <path_to_cert_configs>/*.yaml [-c <citrix_creds>.yaml] [--log-passphrase]

To enroll certificates for specific certificate configuration files, run the following command.

python3 citrixagent.py <cert_config1>.yaml [, <cert_config2>.yaml] [-c <citrix_creds>.yaml] [--log-passphrase]

If you store certificate configuration files in /etc/sectigo, run the following command which provides backwards compatibility with earlier versions of the connector (the ACME connector).

python3 citrixagent.py [-c <citrix_creds>.yaml] [--log-passphrase]

To disable passphrase logging, use the --no-log-passphrases option.

Verify SSL enablement

To view the provisioned certificate in the Citrix certificate store, navigate to the Configuration tab, and then select Traffic Management  SSL  All certificates.

Citrix certificate store

The associated private keys can be accessed on the SSL  SSL Files page.

Citrix SSL files

Renew a certificate

You can renew certificates for all appliances or specific appliances.

If a certificate is within the renewal period specified in the expiry_window parameter in <cert_config1>.yaml, the connector requests a new certificate. The old certificate remains valid in SCM unless revoked manually.

  • All appliances

  • Specific appliances

To enroll certificates for all certificate profile files, run the following command.

0 0 * * 7 python3 /opt/sectigo/sectigo-citrix-agent_<version>/citrixagent.py <path_to_cert_configs>/*.yaml [-c <citrix_creds>.yaml] [--log-passphrase]

To enroll certificates for specific certificate configuration files, run the following command.

0 0 * * 7 python3 /opt/sectigo/sectigo-citrix-agent_<version>/citrixagent.py <cert_config1>.yaml [, <cert_config2>.yaml] [-c <citrix_creds>.yaml] [--log-passphrase]

If you store the certificate profile files in /etc/sectigo, run the following command which provides backwards compatibility with earlier versions of the connector (the ACME connector).

0 0 * * 7 python3 /opt/sectigo/sectigo-citrix-agent_<version>/citrixagent.py [-c <citrix_creds>.yaml] [--log-passphrase]

The connector calls the SCM REST API to auto-renew the certificate if the certificate is expired or within the renewal period specified in the <cert_config>.yaml certificate profile file:

  • If the certificate specified in the profile file exists and is in the expiry window, then the connector renews the certificate. When a certificate is renewed, Citrix install plugin automatically installs the new certificate to the appliances.

  • If the certificate specified in the profile file doesn’t exist, then that certificate is requested and issued by the Sectigo CA server.

Enable auto-renewal

You can create a cronjob that will invoke the connector on a schedule (see crontab for cron schedule expressions) to check whether the certificate is eligible for renewal:

  1. Run crontab -e on the terminal.

  2. Select an editor.

  3. Add a cronjob that will trigger the connector.

    The following example will trigger citrixagent.py every week.

    • All appliances

    • Specific appliances

    To enroll certificates for all certificate profile files, add the following cronjob.

    0 0 * * 7 python3 /opt/sectigo/sectigo-citrix-agent_<version>/citrixagent.py <path_to_cert_configs>/*.yaml [-c <citrix_creds>.yaml] [--log-passphrase]

    To enroll certificates for specific certificate configuration files, add the following cronjob.

    0 0 * * 7 python3 /opt/sectigo/sectigo-citrix-agent_<version>/citrixagent.py <cert_config1>.yaml [, <cert_config2>.yaml] [-c <citrix_creds>.yaml] [--log-passphrase]

    If you store the certificate profile files in /etc/sectigo, add the following cronjob which provides backwards compatibility with earlier versions of the connector (the ACME connector).

    0 0 * * 7 python3 /opt/sectigo/sectigo-citrix-agent_<version>/citrixagent.py [-c <citrix_creds>.yaml] [--log-passphrase]

  4. Save the changes and exit.

Revoke and replace a certificate

Certificate revocation is done manually in SCM. If a certificate is revoked in SCM, then during the next connector execution, the Sectigo CA server issues a new certificate, unless the certificate profile file has been removed. The connector will install the new certificate on the appliance.

Retrieve the passphrase

By default, the connector generates a secure random passphrase for the private key, but doesn’t store it locally. Since private keys are generated and stored in Citrix (Traffic  Management  SSL  SSL Files), the connector doesn’t have the private key and passphrase (only Citrix knows how to decrypt the private key).

If you’d like to log the passphrase for later retrieval (for example, to manually download the private key and certificate, and deploy it elsewhere), pass the --log-passphrase option when you enroll a certificate.

To retrieve the passphrase for the private key, run the following command on the machine that hosts the connector.

cat ~/.sectigo-citrix/logs/* | grep <private_key_filename_on_citrix>

View the logs

The log files are stored in the ~/.sectigo-citrix/logs/ directory. Logs are rotated on a daily basis (for example, log.txt.2022-07-15). For the log files, the logging level is DEBUG, which records all events.

You can change the logging level for the terminal output only, using the -l or --log-level option with one of the following values: INFO, WARNING, DEBUG, or ERROR. The default value is INFO.

python3 citrixagent.py --log-level WARNING
Sample log file
2022-07-29 14:37:30,572 - INFO:root: loading cert config files
2022-07-29 14:37:30,572 - DEBUG:root: reading file: /home/born/projects/citrix/281936/citrix_creds.yaml
2022-07-29 14:37:30,572 - DEBUG:root: read
2022-07-29 14:37:30,572 - DEBUG:root: the file is encrypted. using sops to read
2022-07-29 14:37:30,599 - INFO:certconfig: loading '/home/born/projects/citrix/281936/example_cert_config.yaml'
2022-07-29 14:37:30,599 - DEBUG:root: reading file: /home/born/projects/citrix/281936/example_cert_config.yaml