Automation

The automate command for Microsoft IIS will enroll or renew a certificate, store it in the Windows Machine Store using the software backend, and bind it to the specified host and port.

The automate command for Apache works exactly the same as the est client, except that it will restart your Apache server after the certificate has been installed.

The automate command for Nginx works exactly the same as the est client, except that it will restart your Nginx server after the certificate has been installed.

The new automation module relies on automation policies to know how the certificates should be enrolled and renewed. Automation policies are configurable in the Horizon web app, contain an EST, SCEP or ACME profile and other options, like preferred enrollment CA and hash algorithm. For each automation operation, an automation policy needs to be specified using the --automation-policy parameter.

The new automation module will discover certificates on your machine by parsing your webserver’s or TLS service’s configuration files. Supported services are:

By default, the automate enroll command will try to search for all supported services. If you want to limit the search to a specific list of services, you can use the --target option.

You can use the --analyze-only flag to only perform the discovery phase, print results and exit.

Once the discovery phase is done, you will be presented with a list of certificates that can be enrolled. You can then select the certificates you want to enroll, and enrollments will be performed according to the automation policy and it’s corresponding profile.

For example, if your automation policy specifies an EST profile with challenge password validation, the client will enroll the certificate using the EST protocol, and you will be prompted for the challenge password.

The enrollment is meant to be somewhat intelligent, in that it does not enroll certificates that are already known by Horizon and compliant to your automation policy. For example, if you have initially enrolled your web server’s certificate using the EST, SCEP or ACME client on the same profile, and you run the automate enroll command, the client will not try to enroll the certificate again, but will simply update its internal database with the new information. If you want to re-enroll the certificates anyway, you can use the --force-enroll option.

After a successful enrollment or renewal, the certificate will be installed on your machine. The installation process will depend on the services that use the certificate, and the storage backend that was used to store the certificate. For example, if the certificate was used by Tomcat and was stored as a PKCS#12 file, then this file will be overwritten, with the same password. The old PKCS#12 file will be backed up by the client.

The impacted services will be restarted automatically after each certificate enrollment or 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:

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

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.

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.

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. We found this to be a human-readable way of uniquely identifying a local certificate.

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.

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.

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