General Configuration and Usage

Installation

Package install/uninstall

Installing the package

  • RPM

  • DEB

  • Windows

  • Binary

Installing from the Evertrust repository

Create a /etc/yum.repos.d/horizon-cli.repo file containing the EverTrust repository info:

[horizon-cli]
enabled=1
name=Horizon Client Repository
baseurl=https://repo.evertrust.io/repository/horizon-cli-rpm/
gpgcheck=1
gpgkey=https://evertrust.io/.well-known/rpm/gpg.pub
username=<username>
password=<password>

Replace <username> and <password> with the credentials you were provided.

Make sure the Evertrust GPG key is trusted:

# rpm --import https://evertrust.io/.well-known/rpm/gpg.pub

You can then run the following to install the latest Horizon Client version:

# yum install horizon-cli

To prevent unattended upgrades when running yum update, you should pin the Horizon Client version by adding

exclude=horizon-cli

at the end of the /etc/yum.repos.d/horizon-cli.repo file after installing Horizon Client.

Installing from the package file

Download the latest RPM for Horizon Client on the Official EVERTRUST repository.

Upload the file horizon-cli-<latest>.x86_64.rpm to the server;

Access the server with an account with administrative privileges;

Install the Horizon Client package with the following command:

# yum localinstall /root/horizon-cli-<latest>.x86_64.rpm

If you wish to verify the signature of the RPM package, the EVERTRUST key can be added to your trusted keys using the following command:

# rpm --import https://evertrust.io/.well-known/rpm/gpg.pub

The signature can then be verified using the following command:

# rpm -K /root/horizon-cli-<latest>.x86_64.rpm
The Debian package is available since version 1.18.0, for the amd64 architecture only. On other architectures, install the client from the binary distribution.

Installing from the Evertrust repository

If you haven’t already, to add the EVERTRUST repository to your APT repositories, run the following commands:

  1. Install the required tools (gpg)

    # sudo apt install gnupg

  2. Download and install the EVERTRUST GPG key

    # curl https://evertrust.io/.well-known/apt/gpg.pub | sudo gpg -o /usr/share/keyrings/evertrust.gpg --dearmor

  3. Add the repository

    # echo "deb [ arch=all,amd64 signed-by=/usr/share/keyrings/evertrust.gpg ] https://repo.evertrust.io/repository/apt all main" | sudo tee /etc/apt/sources.list.d/evertrust.list

Once the repository has been added, authentication to it must be provided. To do so, edit the /etc/apt/auth.conf file and add the following lines:

machine repo.evertrust.io
login <your EVERTRUST login>
password <your EVERTRUST password>

Once the repository has been added, run the following command to update the APT repository list.

# sudo apt update

You can then run the following command to install the latest Horizon Client version:

# sudo apt install horizon-cli

To prevent unattended upgrades when running apt upgrade, you should pin the Horizon Client version by creating a /etc/apt/preferences.d/horizon-cli file:

Package: horizon-cli
Pin: version 
Pin-Priority: 1001

Installing from the package file

Download the latest DEB for Horizon Client on the Official EVERTRUST repository.

Upload the file horizon-cli_<latest>_amd64.deb to the server;

Access the server with an account with administrative privileges;

Install the Horizon Client package with the following command:

# apt install /root/horizon-cli_<latest>_amd64.deb

After installing

The package installs the client in /opt/horizon/bin/horizon-cli, which is not added to the PATH, and creates the working directories used by the client. It does not create the configuration file: run the command below to generate it.

# /opt/horizon/bin/horizon-cli install

To install the package, double click on the MSI file and follow the instructions.

The linux binary file is usable on any linux distribution, to install it follow the steps below :

  • Add the binary file to the PATH, in order to easily launch it on your shell.

  • Apply the executable permission on the binary file

# chmod +x horizon-cli.bin

Uninstalling the package

  • RPM

  • DEB

  • Windows

  • Binary

# yum remove horizon-cli
# apt remove horizon-cli

To uninstall the package, simply browse to the Applications & program menu and uninstall the program.

Remove the binary file from your system, and remove it from PATH

Command line installation & initialization

Use the command below to install the client and generate interactively your configuration file:

$ horizon-cli install

The configuration file can also be created using command line parameters:

$ horizon-cli install --endpoint https://horizon-test.com

Use the help to get the full list of available parameters.

If you did not use an installer, this command should always be run first to ensure everything is set up correctly.

Configuration Location

General parameters of Horizon Client are configured through a file placed in one of the following locations:

Global configuration :

  • /opt/horizon/etc/horizon-cli.conf

  • [C|D]:\ProgramData\EverTrust\Horizon\horizon-cli.conf

Per-user configuration :

  • ~/.horizon-cli/etc/horizon-cli.conf

  • [C|D]:\Users\<username>\AppData\Local\horizon-cli\horizon-cli.conf

In case the user running the Horizon Client is an administrator and the global configuration file is present and accessible by the user, the global configuration file will be used. Otherwise, the per-user configuration file will be used.

If the per-user configuration file is not present and the global configuration file is not accessible, the client will throw an error.

Configuration Content

Since version 1.10, the configuration was migrated from JSON to YAML, if you are upgrading from an earlier version, the configuration migration will be done automatically and should be seamless.

The configuration file is in YAML format and contains the following:

  api_id: API-ID
  api_key: API-Key
  service_account_name: Service account name
  service_account_token: Service account token
  endpoint: endpoint url. e.g. https://horizon-test.evertrust.fr
  debug: false
  timeout: 2
  proxy: proxy. e.g. http://myproxy.corp.local:3128
  root_ca: Root CA PEM Certificate(s).
  log_file: The log file of Horizon.
  external_proxy: proxy. e.g. http://myproxy.corp.local:3128
  sudo_commands:
    - command_one
    - another_command

These parameters may be instead specified or overridden using environment variables, as detailed in the table below.

Table 1. General configuration parameters
Parameter Environment variable Description

api_id

HRZ_APIID

The API ID: the identifier of a local account user defined in Horizon. Used for discovery, import modes and for the revocation in the EST module

api_key

HRZ_APIKEY

The API Key. Used together with API ID

service_account_name

HRZ_SERVICE_ACCOUNT_NAME

The name of the service account used to authenticate against Horizon. Used together with the service account token. Mutually exclusive with api_id/api_key.

service_account_token

HRZ_SERVICE_ACCOUNT_TOKEN

The token of the service account used to authenticate against Horizon. Used together with the service account name.

endpoint

HRZ_ENDPOINT

The URL of the Horizon instance, starting with http or https and without trailing "/"

debug

HRZ_DEBUG

Set to true to enable debug mode of the Horizon Client, defaults to false if unspecified.

timeout

Connection timeout in seconds, defaults to 2 seconds if unspecified.

proxy

HRZ_HTTPS_PROXY

HTTPS proxy used to reach Horizon (if any), in URL form which can contain login and password if needed.

root_ca

PEM chain of CA certificates that issued the TLS certificate exposed by Horizon. This parameter is optional, as preferred way is to put these CA certificates in the machine trust store.

log_file

HRZ_LOGFILE

Log file of horizon. This parameter is optional, but a default value is set as the Horizon Client displays useful messages on STDOUT and logs should always be kept.

external_proxy

HRZ_EXTERNAL_PROXY

HTTPS proxy used to reach Third Parties (if any), in URL form which can contain login and password if needed.

sudo_commands

HRZ_SUDO_COMMANDS

Array of commands that should be executed using sudo.

Configuration customization

Changing the configuration file location

In case you want to change the configuration file location, the HRZ_CONFIG environment variable can contain an absolute path to the configuration file and will try to read it before defaulting to the standard configuration as detailed above.

Changing all horizon-client files location

Additional files are used by the client (automation state, log files, etc). In case you want to change the path to these configurations, the HRZ_LOCAL_DATA environment variable can contain an absolute path to a folder, and will create all necessary files starting from this folder.

In order to keep backward compatibility, legacy environment variables are still available and are the same as the one above without the HRZ_ prefix. These should not be used and should be migrated to HRZ-prefixed one.

You can use the “--help” parameter to get command line help on any command or sub-command.

$ horizon-cli <command> <subcommand> --help

Authentication

The Horizon Client authenticates against the Horizon instance using either a service account or a login/password local account. These two methods are mutually exclusive: only one may be configured at a time. If both are defined, the client will return an error.

Service Account

A service account is identified by a name and a token, both defined in Horizon. When configured, the client sends these credentials to Horizon on every request.

  service_account_name: my-service-account
  service_account_token: my-service-account-token

The name and token can be set with horizon-cli install (as the --service-account-name and --service-account-token flags or through the interactive prompts), or through the HRZ_SERVICE_ACCOUNT_NAME and HRZ_SERVICE_ACCOUNT_TOKEN environment variables, which take precedence over the configuration file.

The name and token do not have to be provided at the same time: the client accepts a partial configuration (for example a name now and a token delivered later through an environment variable or a token file). Both must, however, be resolvable when a request is actually made, otherwise the request will fail.

Token formats

The token can be provided in two forms:

  • An inline value, sent to Horizon as-is.

  • A file:// reference to a token file (for example file:///etc/horizon/token). The path must be absolute. The file is read, its contents trimmed, and re-read before each request, so a token rotated by an external secret manager is always picked up without re-running install. If the file is missing, unreadable, or empty, the request will fail.

Service account authentication is not compatible with the SCEP and EST authorized enrollment modes, due to protocol limitations. To use SCEP or EST authorized, you must authenticate using a login/password local account (api_id/api_key).

Login/Password

A login/password local account is identified by an API ID and an API Key, both defined in Horizon.

  api_id: my-api-id
  api_key: my-api-key

Both api_id and api_key must be provided together. This authentication method is required for the SCEP and EST authorized enrollment modes.

No authentication

The Horizon Client can be used without authentication for certificate enrollments.

This is possible using EST/SCEP challenge or Webra Auto-Validation workflows.