Automation

The horizon-cli automate command helps you automate the installation of your TLS certificates. It is designed to streamline the process of certificate enrollment, renewal, and installation. This functionality is particularly useful for managing Transport Layer Security (TLS) on web servers, ensuring secure and encrypted connections. It simplifies complex operations through its suite of subcommands, each tailored for specific aspects of certificate management.

Subcommands

To begin with Horizon CLI automation, use the --help flag with any subcommand for detailed usage information:

./horizon-cli automate <subcommand> --help
Table 1. Automation module subcommands
Subcommand Description

enroll

This command is versatile, functioning similarly to the init command on servers without certificates, while also capable of re-enrolling or taking control of servers with existing certificates.

init

This command is designed to automatically configure SSL on any newly installed web server. When executed, it seamlessly sets up a secure connection by arranging SSL certificates and enabling SSL on the default HTTPS port (usually port 443). The process includes configuring the necessary SSL settings and restarting the server with SSL enabled.

control

This command is designed to locate certificates within a web server’s configuration and offers to bring them under automation control. Taking a certificate under control involves adding necessary metadata and incorporating it into the local memory for routine management and oversight. This process ensures that the certificates are systematically monitored and managed as part of the automated workflow. Be aware that enrolling a new certificate will replace any certificate currently bound to an application running on your machine.

modify

This command allows the user to select one of the managed certs and modify its sans.

create-periodic-task

Sets up a routine task for automated certificate renewal. The task frequency can be specified, with a default period of 6 hours. This helps in automating the renewal process to ensure certificates remain valid without manual intervention.

remove-periodic-task

Removes the previously set periodic task for certificate renewal. This is useful when automated renewal is no longer needed or needs to be reconfigured.

routine

Performs a routine check on all managed certificates to assess if any need renewal. This is a part of proactive certificate management to avoid service disruptions.

list

Lists all managed certificates. This provides an overview of all certificates under management, including details like expiration dates, domains covered, etc.

remove

Removes a managed certificate or a group of certificates. The <id> parameter specifies which certificates to remove, with the option to remove all services using a keyword like 'all'.

If you’re looking for a more guided experience while using horizon-cli automate, the --prompt flag is an excellent tool. It enables interactive prompts that guide you step-by-step through the command’s options, making it easier to configure and execute your commands accurately.

./horizon-cli automate <subcommand> --prompt

Supported Services

The horizon-cli automate feature supports a variety of web server and application server services. This ensures a wide range of compatibility and flexibility for users working with different server environments. The --target flag is used within the tool to specify the specific service on which to perform automation tasks, allowing for precise and targeted configuration and management.

In order for horizon-cli to function properly, the targeted service should be started on the machine.

List of the supported services:

  • nginx (linux)

  • apache (linux)

  • tomcat (linux & windows)

  • jboss wildfly (linux)

  • lighttpd (linux)

  • microsoft iis (windows)

  • evertrust winhorizon (windows)

  • evertrust adcsconnector (windows)

  • generic (linux & windows)

Example of a standard setup on the default HTTPS port (443) for NGINX:

./horizon-cli automate init --target=nginx --automation-policy=<POLICY_NAME>

To set up SSL on a custom port (e.g., 9000), use the --PORT flag. This option allows SSL configuration on a specific port of your Nginx server.

./horizon-cli automate init --target=nginx --automation-policy=<POLICY_NAME> --PORT=9000

Generic Service Automation

The Generic Service within the Horizon Client’s automation module provides a versatile and user-friendly method for obtaining TLS certificates, eliminating the need to specify a pre-existing service or certificate file. This feature is especially beneficial in scenarios where certificates are required to be generated dynamically or for users who seek a more automated certificate management process.

Through the interactive mode:

./horizon-cli automate init --target=generic --prompt

Non-Interactive Mode: For an even more streamlined experience, certificates can be automatically generated with default parameters in non-interactive mode.

./horizon-cli automate init --target=generic --automation-policy=<POLICY_NAME> --cert=my_cert.pem --key=my_key.key --chain-file=my_chain.pem --no-interactive

Default Storage Location: Newly generated certificates are automatically stored in a default location, which is /opt/horizon/var/generic on Unix systems, and C:\ProgramData\EverTrust\Horizon\Var\Generic on Windows systems.

Configuration Folder Override: Users have the flexibility to override the default storage location using the --config-folder option. This allows for customization of the storage path as per individual requirements or organizational standards.

./horizon-cli automate init --config-folder=/path/to/folder --target=generic --automation-policy=<POLICY_NAME> --pfx=my_cert.p12 --pfx-pwd=pass123 --chain-file=my_chain.pem --no-interactive

The Generic Service’s emphasis on flexibility and user-friendliness makes it a valuable tool for a wide range of users, from those requiring on-the-fly certificate generation to those preferring a hands-off, automated approach.

Windows-Specific Features: On Windows systems, the Horizon CLI offers additional flags to specify the certificate store location:

--win-user-store: Save the certificate in the user store. This option is beneficial when certificates need to be accessible on a per-user basis.

--win-computer-store: Save the certificate in the computer store. Ideal for certificates that must be available system-wide.

These options provide flexibility in managing certificate storage, catering to different security and accessibility requirements on Windows systems.

Automation policies

Automation policies are central to the operation of the automation module in the Horizon system. These policies dictate how certificates should be enrolled and renewed, providing a customizable framework to suit various client requirements.

Before using automation policies, they must be pre-configured in the Horizon web app. Each policy is given a unique name for easy identification.

Profile Selection: Policies can be based on EST, SCEP, or ACME profiles, depending on the specific requirements of the enrollment and renewal process.

EverTrust recommends using EST for most use cases of server automation.

Execution Policy: Includes settings that define how and when the automation should be executed.

Compliance Settings: Specify which CAs are authorized for use within the policy.

Authorized Hash Algorithms: Determine which hash algorithms are acceptable.

Trust Chains: Configure the trust chains that are essential for establishing the trustworthiness of the certificates.

Parameter Specification: When performing automation operations, the relevant automation policy is specified using the --automation-policy parameter.

Existing WebServer certificates

The Horizon CLI’s automation module is equipped with a discovery feature that scans and identifies certificates on your machine. It does this by parsing configuration files of your web server or TLS service.

By default, it searches for certificates across all supported services.

./horizon-cli automate enroll --automation-policy=<POLICY_NAME>

Limit the search to specific services. Separate multiple services with commas.

./horizon-cli automate enroll --automation-policy=<POLICY_NAME> --target=apache,nginx

If you use a different config folder than the default one you can specify your custom folder using --config-folder

./horizon-cli automate enroll --automation-policy=<POLICY_NAME> --target=apache,nginx --config-folder=/path/to/folder

Perform only the discovery phase and print the results without enrolling certificates using --analyze-only:

./horizon-cli automate enroll --automation-policy=<POLICY_NAME> --target=apache,nginx --analyze-only

The --discovery parameter allows you to integrate certificate enrollment with a discovery campaign pre configured in the Horizon web app before running the CLI command. It includes additional information on the certificate’s usage and location on the host machine.

./horizon-cli automate enroll --automation-policy=<POLICY_NAME> --discovery-campaign=<DISCOVERY_CAMPAIGN_NAME>

Additional enrollment parameters

Challenge Passwords for Enrollment

The --challenge parameter is used to provide challenge passwords for EST or SCEP during the enrollment process. Challenge passwords are crucial for the authentication phase in these protocols, ensuring secure communication and identity verification.

When enrolling certificates using EST or SCEP protocols, the --challenge parameter allows you to specify one or more challenge passwords required by the enrollment server. Multiple challenge passwords can be provided, separated by commas, to support various scenarios or multiple servers enrollment.

Post-Enrollment Script Execution

The --script parameter allows the execution of a custom script upon the successful completion of a certificate enrollment process. It supports both Bash scripts in Linux environments and PowerShell scripts in Windows environments.

./horizon-cli automate enroll --automation-policy=<POLICY_NAME> --script=/home/user/post_enroll.sh

The script will receive arguments passed by Horizon Client in the following order:

  1. Issued certificate serial number

  2. Issued certificate fingerprint (SHA-1 hash of the certificate in DER format - windows store thumbprint)

  3. Issued certificate Subject DN

  4. Issued certificate Issuer DN

Below is an example of a very simple bash script:

#!/bin/sh

echo $1
echo $2
echo $3
echo $4

Below is an example of a very simple PowerShell script:

param($serial, $fingerprint, $subject, $issuer)

Write-Output $serial
Write-Output $fingerprint
Write-Output $subject
Write-Output $issuer

Metadata parameters

Add metadata to certificates during the enrollment process: These certificate information parameters enhance the management and traceability of TLS certificates. By using these optional fields, organizations can maintain better oversight and control over their certificate infrastructure.

Table 2. Metadata parameters
Parameter Description

--owner

Owner of the certificate

--contact-email

Contact email of the certificate owner

--team

Team owning the certificate

--labels

Labels to attach to the certificate, in the form key:value

ACME Account Specification for Enrollment

The --acme-account parameter is mandatory when enrolling certificates using the ACME protocol. It specifies the ACME account to be used for the enrollment process.

./horizon-cli automate enroll --acme-account=myAcmeAccount

Installation

After a successful enrollment or renewal, the certificate will be installed on your machine. The impacted services will be restarted automatically after each certificate enrollment or renewal.

In certain scenarios, you might not want the Horizon CLI to automatically install the new certificate or restart the related services.

If you wish for the client to not install your new certificate, that is, not replace the old certificate and not restart the impacted services, you can use the --no-install option. Each new file (cert, key, CA chain, keystore…​) will then be placed in the same folder as it’s predecessor, with the .new extension.

Renewal

Each time a certificate is discovered and enrolled by the automation module of the Horizon Client, its details are stored in the internal database for future reference. Each time the automate routine command is run, the client will check if any of the locally known certificates need to be renewed. Reasons for renewal can be:

  • The certificate is about to expire

  • The certificate has been revoked

  • Preferences such as key type or enrollment CA were changed in the profile or automation policy

If a certificate needs to be renewed, the client will perform the renewal according to the automation policy, and its corresponding profile.

We recommend that you run the automate routine command periodically as a cron job or scheduled task. You can use the command horizon-cli automate create-periodic-task <period> or the flag --auto-renew on the automate enroll command to help you in the process, or create it manually.

This mechanism allows for more resilient web servers, as the certificates will be renewed automatically, before any interruption of service can happen because of an expired or revoked certificate. It also helps your organisation migrate your TLS certificates to a new CA quickly, by simply changing the preferred enrollment CA in the automation policy and waiting a few hours for all your instances of the Horizon Client to execute their routine tasks.

Using --auto-renew flag will check and check the certificate every 6 hours:

./horizon-cli automate enroll --target=nginx --automation-policy=<POLICY_NAME> --auto-renew

Interactivity

Two options are available to control the interactivity of the automate enroll command:

  • The --no-interactive flag will prevent any prompt from being displayed, and will use the default values or those provided in the command line arguments. It will:

    • select all discovered certificates for enrollment

    • if a challenge is required, use the provided --challenge argument. If no challenge is provided, or the given challenge has already been used, the enrollment will fail.

    • not add any additional SANs

  • the --prompt flag will force the client to prompt the user for any missing information. If specified, any other command line arguments are optional. It will:

    • prompt the user to select which services to search for on the machine (equivalent to the --target option)

    • prompt the user for the automation policy (equivalent to the --automation-policy option)

    • prompt the user for the configuration folder (equivalent to the --config-folder option)

Certificate commands

Enroll

The enroll command can either setup a certificate and empty https configuration from scratch, or take control of certificates, reenrolling them to be compliant when necessary.

Parameters

Table 3. Enroll general parameters
Parameter Mandatory Type Description

--automation-policy

☑

string

The automation policy to link the certificate to.

--challenge

string array (comma separated)

See challenge section.

--script

string (path to file)

See script section.

--auto-renew

boolean

Configures a status check every 6 hours.

--discovery-campaign

string

Also add discovery info on the enrolled certificate on the campaign passed.

--force-enroll

boolean

Reenroll all selected certificates regardless of their compliance.

--analyze-only

boolean

Instead of executing the enrollments, only displays a summary of possible actions.

--no-interactive

boolean

Disables all interactive inputs. All parameters must then be given using cli flags.

--prompt

boolean

Enable all interactive inputs. All parameters will now be asked for, except ones given using cli flags.
Table 4. Enroll webServer configuration
Parameter Mandatory Type Description

--target

string array (comma separated)

List of services to target. If not given, all available services are targeted.

--no-install

boolean

Disables installation.

--config-folder

string (path to folder)

Explicitly point your webserver configuration folder.

--port

integer

When initializing an empty https configuration on a blank server, choose on which port to listen for https (defaults to the standard https port for the webserver 443 or 8443)

--keystore-password

string

Password of the webserver’s keystore if it cannot be deduced from configuration
Table 5. Enroll certificate configuration
Parameter Mandatory Type Description

--dnsnames

string array (comma separated)

List of DNS SANs. If not given, the machine hostname is used.

--ip

string array (comma separated)

List of IP SANs. If not given, no ips are set.

--labels

string array (comma separated, in label:value form)

Horizon labels to add to the certificate on enrollment.

--team

string

Horizon team to add to the certificate on enrollment

--owner

string

Horizon owner to add to the certificate on enrollment

--contact-email

string

Horizon contact email to add to the certificate on enrollment
Table 6. Enroll ACME options
Parameter Mandatory Type Description

--acme-account

☑ (if using ACME)

string

The identifier (email) of the ACME account to use

--http-01-port

int

The http 01 port on which to listen

--dns-01-provider

string

DNS provider script to use for ACME enrollments. ACME.sh based on Linux, Posh-ACME based on Windows

--eab-kid

string

Kid for External Account Binding

--eab-key

string

Key for External Account Binding
Table 7. Enroll ACME External options
Parameter Mandatory Type Description

--standalone

boolean

Use built in http server

--local

boolean

Use an existing http server

--document-root

string

Path of the document root where to put the well-known folder for the challenge
Table 8. Enroll generic options
Parameter Mandatory Type Description

--destination-folder

string (path to folder)

Folder to write the new certificates to. Default to /opt/horizon/var/generic on linux and C:\ProgramData\EverTrust\Horizon\Generic on windows.

--pfx

string

Name of the PKCS#12 file to write the enrolled certificate to.

--pfx-pwd

string

Password of the PKCS#12 file to write the enrolled certificate to.

--jks

string

Name of the JKS file to write the enrolled certificate to.

--jks-pwd

string

Password of the JKS file to write the enrolled certificate to.

--jks-alias

string

Alias of the JKS file to write the enrolled certificate to.

--cert

string

Name of the file to write the enrolled certificate to in PEM format.

--key

string

Name of the file to write the enrolled key to.

--der

boolean

Save the certificate and key in DER format.

--chain-file

string

Name of the file to write the enrolled certificate chain to.

--win-user-store

boolean

[Windows certificate store] Save the certificate in the windows user store.

--win-computer-store

boolean

[Windows certificate store] Save the certificate in the windows computer store (LocalMachine).

--win-store-use-tpm

boolean

[Windows certificate store] Use the Microsoft Platform Crypto Provider for certificate store storage.

--win-store-use-legacy

boolean

[Windows certificate store] Use the Microsoft Platform Crypto Provider for certificate store storage.

--win-store-set-exportable

boolean

[Windows certificate store] Set the private key as exportable from the certificate store.
Storage output for generic must choose between pfx, certificate, jks or windows store output.

Examples

Use the interactive mode
horizon-cli automate enroll --prompt
Enroll a new certificate in the default generic folder
horizon-cli automate enroll --automation-policy=<automation policy> --target=generic --cert cert.pem --key key.pem --chain-file chain.pem
Add https or control a nginx service
horizon-cli automate enroll --automation-policy=<automation policy> --target=nginx
Add https to a nginx service without interaction and with custom san values
horizon-cli automate enroll --automation-policy=<automation policy> --target=nginx --no-interactive --dnsnames="nginx.test,*.test" --ip "1.1.1.1"

Init

The init command can setup a certificate and empty https configuration from scratch.

The init command can only be used on webservers where no certificate is configured in order to avoid conflicts. See the other commands to match your use case.

Parameters

Table 9. Init general parameters
Parameter Mandatory Type Description

--automation-policy

☑

string

The automation policy to link the certificate to.

--challenge

string array (comma separated)

See challenge section.

--script

string (path to file)

See script section.

--auto-renew

boolean

Configures a status check every 6 hours.

--discovery-campaign

string

Also add discovery info on the enrolled certificate on the campaign passed.

--analyze-only

boolean

Instead of executing the enrollments, only displays a summary of possible actions.

--no-interactive

boolean

Disables all interactive inputs. All parameters must then be given using cli flags.

--prompt

boolean

Enable all interactive inputs. All parameters will now be asked for, except ones given using cli flags.
Table 10. Init webServer configuration
Parameter Mandatory Type Description

--target

string array (comma separated)

List of services to target. If not given, all available services are targeted.

--no-install

boolean

Disables installation.

--config-folder

string (path to folder)

Explicitly point your webserver configuration folder.

--port

integer

When initializing an empty https configuration on a blank server, choose on which port to listen for https (defaults to the standard https port for the webserver 443 or 8443)

--keystore-password

string

Password of the webserver’s keystore if it cannot be deduced from configuration
Table 11. Init certificate configuration
Parameter Mandatory Type Description

--dnsnames

string array (comma separated)

List of DNS SANs. If not given, the machine hostname is used.

--ip

string array (comma separated)

List of IP SANs. If not given, no ips are set.

--labels

string array (comma separated, in label:value form)

Horizon labels to add to the certificate on enrollment.

--team

string

Horizon team to add to the certificate on enrollment

--owner

string

Horizon owner to add to the certificate on enrollment

--contact-email

string

Horizon contact email to add to the certificate on enrollment
Table 12. Init ACME options
Parameter Mandatory Type Description

--acme-account

☑ (if using ACME)

string

The identifier (email) of the ACME account to use

--http-01-port

int

The http 01 port on which to listen

--dns-01-provider

string

DNS provider script to use for ACME enrollments. ACME.sh based on Linux, Posh-ACME based on Windows

--eab-kid

string

Kid for External Account Binding

--eab-key

string

Key for External Account Binding
Table 13. Init ACME External options
Parameter Mandatory Type Description

--standalone

boolean

Use built in http server

--local

boolean

Use an existing http server

--document-root

string

Path of the document root where to put the well-known folder for the challenge
Table 14. Init generic options
Parameter Mandatory Type Description

--destination-folder

string (path to folder)

Folder to write the new certificates to. Default to /opt/horizon/var/generic on linux and C:\ProgramData\EverTrust\Horizon\Generic on windows.

--pfx

string

Name of the PKCS#12 file to write the enrolled certificate to.

--pfx-pwd

string

Password of the PKCS#12 file to write the enrolled certificate to.

--jks

string

Name of the JKS file to write the enrolled certificate to.

--jks-pwd

string

Password of the JKS file to write the enrolled certificate to.

--jks-alias

string

Alias of the JKS file to write the enrolled certificate to.

--cert

string

Name of the file to write the enrolled certificate to in PEM format.

--key

string

Name of the file to write the enrolled key to.

--der

boolean

Save the certificate and key in DER format.

--chain-file

string

Name of the file to write the enrolled certificate chain to.

--win-user-store

boolean

[Windows certificate store] Save the certificate in the windows user store.

--win-computer-store

boolean

[Windows certificate store] Save the certificate in the windows computer store (LocalMachine).

--win-store-use-tpm

boolean

[Windows certificate store] Use the Microsoft Platform Crypto Provider for certificate store storage.

--win-store-use-legacy

boolean

[Windows certificate store] Use the Microsoft Platform Crypto Provider for certificate store storage.

--win-store-set-exportable

boolean

[Windows certificate store] Set the private key as exportable from the certificate store.
Storage output for generic must choose between pfx, certificate, jks or windows store output.

Examples

Use the interactive mode
horizon-cli automate init --prompt
Enroll a new certificate in the default generic folder
horizon-cli automate init --automation-policy=<automation policy> --target=generic --cert cert.pem --key key.pem --chain-file chain.pem
Add https to a nginx service
horizon-cli automate init --automation-policy=<automation policy> --target=nginx
Add https to a nginx service without interaction and with custom san values
horizon-cli automate init --automation-policy=<automation policy> --target=nginx --no-interactive --dnsnames="nginx.test,*.test" --ip "1.1.1.1"

Control

The control command can take control of an existing certificate on your machine.

The control command can only be used on known and compliant with Horizon certificates. If the certificate needs to be enrolled, see the other commands to match your use case.

Parameters

Table 15. Control general parameters
Parameter Mandatory Type Description

--automation-policy

☑

string

The automation policy to link the certificate to.

--challenge

string array (comma separated)

See challenge section.

--script

string (path to file)

See script section.

--auto-renew

boolean

Configures a status check every 6 hours.

--discovery-campaign

string

Also add discovery info on the enrolled certificate on the campaign passed.

--analyze-only

boolean

Instead of executing the control, only displays a summary of possible actions.

--no-interactive

boolean

Disables all interactive inputs. All parameters must then be given using cli flags.

--prompt

boolean

Enable all interactive inputs. All parameters will now be asked for, except ones given using cli flags.
Table 16. Control webServer configuration
Parameter Mandatory Type Description

--target

string array (comma separated)

List of services to target. If not given, all available services are targeted.

--no-install

boolean

Disables installation.

--config-folder

string (path to folder)

Explicitly point your webserver configuration folder.

--keystore-password

string

Password of the webserver’s keystore if it cannot be deduced from configuration
Table 17. Control certificate configuration
Parameter Mandatory Type Description

--labels

string array (comma separated, in label:value form)

Horizon labels to add to the certificate on enrollment.

--team

string

Horizon team to add to the certificate on enrollment

--owner

string

Horizon owner to add to the certificate on enrollment

--contact-email

string

Horizon contact email to add to the certificate on enrollment
Table 18. Control ACME options
Parameter Mandatory Type Description

--acme-account

☑ (if using ACME)

string

The identifier (email) of the ACME account to use when renewing

--http-01-port

int

The http 01 port on which to listen

--dns-01-provider

string

DNS provider script to use for ACME enrollments. ACME.sh based on Linux, Posh-ACME based on Windows
For generic control, it is as of now disabled outside the default folder (/opt/horizon/var/genric or C:\ProgramData\EverTrust\Horizon\Generic) to ensure no service interruption. Use post enrollment scripts to copy the certificate.
Table 19. Control generic options
Parameter Mandatory Type Description

--pfx

string

Name of the PKCS#12 file to control.

--pfx-pwd

string

Password of the PKCS#12 file to control.

--jks

string

Name of the JKS file to control.

--jks-pwd

string

Password of the JKS file to control.

--jks-alias

string

Alias of the JKS file to control.

--cert

string

Name of the certificate file to control.

--key

string

Name of the key file to control.

--der

boolean

If true, the certificate and key to control are in DER format.

--chain-file

string

Name of the file to write the enrolled certificate chain to.

--win-user-store

boolean

Control the certificate in the windows user store.

--win-computer-store

boolean

Control the certificate in the windows machine store.

--win-thumbprint

boolean

Thumbprint of the certificate to control. To use with --win-computer-store or --win-user-store
Input for generic must choose between pfx, certificate, jks or windows store.

Examples

Use the interactive mode
horizon-cli automate control --prompt
Control a certificate in the default generic folder
horizon-cli automate control --automation-policy=<automation policy> --target=generic --cert cert.pem --key key.pem --chain-file chain.pem
Control a certificate on an already configured nginx
horizon-cli automate control --automation-policy=<automation policy> --target=nginx

Modify

The modify command allows to select a managed certificate and reenroll it, modifying its sans.

Automation policy cannot be modified

Parameters

Table 20. Modify general parameters
Parameter Mandatory Type Description

--challenge

string array (comma separated)

See challenge section.

--script

string (path to file)

See script section.

--discovery-campaign

string

Also add discovery info on the enrolled certificate on the campaign passed.

--prompt

boolean

Enable all interactive inputs. All parameters will now be asked for, except ones given using cli flags.
Table 21. Modify webServer configuration
Parameter Mandatory Type Description

--target

string array (comma separated)

List of services to target. If not given, all available services are targeted.

--no-reload

boolean

Do not reload webservers after certificate enrollment.
Table 22. Modify certificate configuration
Parameter Mandatory Type Description

--dnsnames

string array (comma separated)

List of DNS SANs. If not given, the machine hostname is used.

--ip

string array (comma separated)

List of IP SANs. If not given, no ips are set.

--labels

string array (comma separated, in label:value form)

Horizon labels to add to the certificate on enrollment.

--team

string

Horizon team to add to the certificate on enrollment

--owner

string

Horizon owner to add to the certificate on enrollment

--contact-email

string

Horizon contact email to add to the certificate on enrollment
Table 23. Modify ACME options
Parameter Mandatory Type Description

--acme-account

☑ (if using ACME)

string

The identifier (email) of the ACME account to use.

Examples

Use the interactive mode
horizon-cli automate modify --prompt
Set sans for the generic certificates
horizon-cli automate modify --target=generic --dnsnames="nginx.test,*.test" --ip "1.1.1.1"

Backup

Each time a file is replaced by the Horizon Client, the old file is backed up. The backup files are stored in the cert/backup/<HASH(BACKUPED FILE PATH)> directory relative to the Horizon Client data folder (/opt/horizon on unix and C:/ProgramData/EverTrust/Horizon on Windows), as filename_n.ext where n is the number of the backup. Thus, the filename_0.ext is the original version, before any intervention of the Horizon Client.

Internal Database operations

The internal database is used to store the details of the certificates that are discovered and enrolled by the automation module. You can list them using the automate list command, and delete them using the automate delete command. Certificates are indexed by their bindings, which are the combination of all the services along with the hostnames and ports that use the certificate. For example, if you have a certificate that is used by Apache for all hosts on the port 443, it’s "id" in the local database will be apache-*:443.

You can choose the output format of the automate list command. By default, it outputs a string, but you can use the --json option to output a JSON object. example:

horizon-cli automate list --json | jq

The automate remove <id1> …​ <idn> command erases certificates from the local database. This command will not remove the certificate files from your machine, only remove it from the "managed certificates" local database. This way, the client will not check its status at each routine execution anymore.

You can use the automate remove all command to remove all certificates from the local database.

The --restore option of the automate remove command can be used to restore a certificate from a backup file. The backup file to be restored will always be the older one, in most cases the filename_0.ext, that is, the original file before any tampering by the Horizon Client. For certificates stored in the Windows store, the store thumbprints will be stored in a file corresponding to the server type, like iisbackups.

Routine

This command does not take any parameter. Its usage is described in the renewal section.

Management commands

Periodic task

To run the routine at specified intervals, the periodic task command can create scheduled execution on windows (scheduled task) and linux (cron).

Two commands are available, to remove and add the task.

Parameters

Table 24. Create periodic task arguments
Argument Mandatory Type Description

Period

duration

Run the routine command every period from midnight UTC. Must be superior to 1h and inferior to 24h. Defaults to 6h.
Table 25. Create periodic task parameters
Parameter Mandatory Type Description

--user

string

Linux only: The user to impersonate while running the routine. Defaults to root user.

Examples

Create a periodic task to run routine every 7h
horizon-cli automate create-periodic-task 7h
Remove the periodic task
horizon-cli automate remove-periodic-task

List

The list command lists the currently managed certificates and various information about them, notably the associated automation policy.

Parameters

Table 26. List parameters
Parameter Mandatory Type Description

--json

string

Output the current state as json instead of human readable format.

Examples

Show the currently managed certificates
horizon-cli automate list
Show the currently managed certificates as json
horizon-cli automate list --json

Remove

The remove command erases a certificate binding from the horizon-cli managed certificates.

Parameters

Table 27. Remove arguments
Argument Mandatory Type Description

id

string

Id of the services to remove. See automate list to get the id. Use all to erase every managed certificate.
Table 28. Remove parameters
Parameter Mandatory Type Description

--restore

boolean

Enables restoration of the oldest backup for the removed certificate.

Examples

Remove all currently managed certificates
horizon-cli automate remove all
Remove the certificate linked to nginx https and restore the original one
horizon-cli automate remove nginx-*:443 --restore

Examples

Enroll certificates used by nginx and apache

horizon-cli automate enroll \
  --target=nginx,apache \
  --automation-policy=<POLICY_NAME>

Enroll certificates using the generic target

horizon-cli automate enroll \
  --target=generic \
  --automation-policy=<POLICY_NAME>

Use the interactive mode

horizon-cli automate enroll --prompt

Check if the previously enrolled certificates need to be renewed

horizon-cli automate routine

Get the DN of all the certificates enrolled by the automation module

horizon-cli automate list --json | jq -r '.[] | .certificate | .subject'

Remove the certificate used by nginx on the port 443 from the automatically renewed certificates

horizon-cli automate remove nginx-*:443

Remove the certificate used by tomcat on the port 8443 from the automatically renewed certificates and restore the original certificate

horizon-cli automate remove --restore tomcat-*:8443