Install the Universal Orchestrator on Linux

To install the Keyfactor Universal OrchestratorClosed The Keyfactor Universal Orchestrator, one of Keyfactor's suite of orchestrators, is used to interact with Windows servers (a.k.a. IIS certificate stores) and FTP capable devices for certificate management, run SSL discovery and management tasks, and manage synchronization of certificate authorities in remote forests. With the addition of custom extensions, it can run custom jobs to provide certificate management capabilities on a variety of platforms and devices (e.g. F5 devices, NetScaler devices, Amazon Web Services (AWS) resources) and execute tasks outside the standard list of certificate management functions. It runs on either Windows or Linux. on Linux, copy the zip file containing installation files to a temporary working directory on the Linux server and unzip it.

To begin the installation:

  1. On the Linux machine on which you wish to install the orchestratorClosed Keyfactor orchestrators perform a variety of functions, including managing certificate stores and SSH key stores., in a command shell change to the temporary directory where you placed the installation files.

  2. Use the chmod command to make the install.sh script file executable. The file ships in a non-executable state to avoid accidental execution. For example:

    sudo chmod +x install.sh

  3. In the command shell, run the install.sh script as root using the following parameters to begin the installation:

    This is the URL to the Agent Services endpointClosed An endpoint is a URL that enables the API to gain access to resources on a server. on the Keyfactor Command server running the Keyfactor Command Agent Services role, which is installed as part of the Keyfactor Command Services role. If you installed all the Keyfactor Command server roles together, this is the URL for your Keyfactor Command server with /KeyfactorAgents after the server's IP or FQDN (e.g. https://keyfactor.keyexample.com/KeyfactorAgents). If you choose to use SSLClosed TLS (Transport Layer Security) and its predecessor SSL (Secure Sockets Layer) are protocols for establishing authenticated and encrypted links between networked computers. to connect to the Keyfactor Command server, you’ll need to enter a URL that contains a hostnameClosed The unique identifier that serves as name of a computer. It is sometimes presented as a fully qualified domain name (e.g. servername.keyexample.com) and sometimes just as a short name (e.g. servername). that is found in the SSL certificate.

    This parameterClosed A parameter or argument is a value that is passed into a function in an application. sets the local orchestrator application setting AgentsServerUri to the specified value.

    This parameter is required.

    Tip:  If your Keyfactor Command server was configured with an alternate virtual directory for the Keyfactor Command Agents Services endpoint, you will need to enter that in the URL rather than /KeyfactorAgents.

    The Keyfactor Universal Orchestrator supports authenticating to the Keyfactor Command server using either standard authentication (Basic authentication) or client certificate authentication. When you configure the orchestrator, you should configure either standard authentication (username and password) or configure client certificate authentication (client-auth-certificate and client-auth-certificate-password). You cannot configure both types of authentication together.

    One of the following authentication methods is required:

    • username and password
    • client-auth-certificate and client-auth-certificate-password
    Important:  Choosing to use client certificate authentication for the orchestrator may require additional configuration on your Keyfactor Command server. For more information, see Install the Main Keyfactor Command Components on the Keyfactor Command Server(s) in the Keyfactor Command Server Installation Guide and Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication with Certificates Stored in Active Directory, Appendix - Set up the Universal Orchestrator to Use Client Certificate Authentication via a Reverse Proxy: Citrix ADC.
    Tip:  For information about rotating passwords and client authentication certificates, see Change Service Account Passwords.

    This is the Keyfactor Command connect service account that the orchestrator uses to communicate with Keyfactor Command that you created as per Create Service Accounts for the Universal Orchestrator. It may be entered either as username@domain (e.g. svc_kyforch@keyexample.com) or DOMAIN\\username (e.g. KEYEXAMPLE\\svc_kyforch).

    This parameter is required if Basic authentication will be used.

    This parameter cannot be used in conjunction with the client-auth-certificate and client-auth-certificate-password parameters.

    This is the password for the Keyfactor Command connect service account that the orchestrator uses to communicate with Keyfactor Command specified with the username parameter.

    Important:  The password for the Keyfactor Command connect service account is stored in clear text in the orchestratorsecrets.json file in the configuration directory under the installation directory for the orchestrator. By default, this file is granted read/write permissions for the Universal Orchestrator service account running the service on the Linux machine (keyfactor-orchestrator by default) and no permissions for any other users. Access to this file should be strictly controlled.

    If you prefer to avoid the use of a password in a file, consider using client certificate authentication.

    This parameter is required if the username parameter is specified.

    Tip:  If you prefer to avoid providing the password at the command line (and storing it in command history), use an input file instead as follows:
    1. Create a file that contains just your password. For example:
      vi my_password_file
    2. When using the password parameter, reference the file. For example:
      --password $(cat my_password_file)
    3. Delete the password file after the install is complete. For example:
      rm my_password_file

    The path and file name on the orchestrator of a PKCS12 file containing the client authentication certificate used to authenticate to Keyfactor Command created as per Acquire a Certificate for Client Certificate Authentication (Optional). The certificate must have a Client Authentication EKU.

    The account under which the Universal Orchestrator service will run (see --service-user) needs read and write permissions on the PKCS12 file you specify with this parameter.

    This parameter requires that client-auth-certificate-password also be specified.

    Specifying this parameter sets the local orchestrator application setting CertPath to the specified value.

    This parameter cannot be used in conjunction with the username and password parameters.

    The password for the PKCS12 file specified with the client-auth-certificate parameter.

    Specifying this parameter requires that client-auth-certificate also be specified.

    This parameter cannot be used in conjunction with the username and password parameters.

    Tip:  If you prefer to avoid providing the password for the certificate file at the command line (and storing it in command history), use an input file instead as follows:
    1. Create a file that contains just your password. For example:
      vi cert_password_file
    2. When using the password parameter, reference the file. For example:
      --password $(cat cert_password_file)
    3. Delete the password file after the install is complete. For example:
      rm cert_password_file

    This parameter is used to specify the capabilities the orchestrator will support if a capability set other than the default set is desired. Supported options are:

    • all

      All the capabilities supported by the orchestrator will be enabled and reported to Keyfactor Command.

    • none

      The orchestrator will be installed with no capabilities and will not be registered with Keyfactor Command. This is primarily used for implementations that will support only custom capabilities (see Installing Custom-Built Extensions and Configuring Script-Based Certificate Store Jobs).

    • ssl

      Only the SSL discovery and monitoring capability will be enabled and reported to Keyfactor Command.

    If the in-place parameter is specified, this parameter must be set to all.

    If this parameter is not specified, the default set of capabilities for the orchestrator will be used. For the Linux orchestrator, the default capability set is FTP and LOG (log fetching).

    Important:  The Linux orchestrator does not support the CAClosed A certificate authority (CA) is an entity that issues digital certificates. Within Keyfactor Command, a CA may be a Microsoft CA or a Keyfactor gateway to a cloud-based or remote CA. (remote CA management) or IIS (Windows server certificate store) capabilities due to the Windows-specific nature of the authentication requirements for these methods.

    This parameter specifies a location in which to install the orchestrator that is other than the default. The default installation location is:

    /opt/keyfactor/orchestrator

    This parameter cannot be used in conjunction with the in-place parameter.

    Specifying this parameter causes the installation to warn and continue on certain potential problems, including:

    • The local Universal Orchestrator service account does not exist. The default user will be created if force is specified.

    • The local application settings (appsettings.json) file does not exist. A new one will be created if force is specified.

    • A service with either the default service name or the service name specified with the service-suffix parameter already exists. The service will be overwritten if force is specified.

    • Either the default installation location or the location specified with the location parameter is not empty. The install will occur to the specified or default location anyway and files may be overwritten if force is specified.

    If this parameter is not specified and any of these problems are encountered, the installation will terminate prematurely. See also the what-if parameter.

    This parameter is used to indicate that the installation should occur in the current directory where the install files are located and no files should be copied to another location on the machine.

    This parameter cannot be used in conjunction with the destination parameter. This parameter is only supported if the capabilities parameter is set to all.

    This parameter is used to indicate that the revocation status (CRLClosed A Certificate Revocation List (CRL) is a list of digital certificates that have been revoked by the issuing Certificate Authority (CA) before their scheduled expiration date and should no longer be trusted.) of the SSL certificate on the Keyfactor Command server should not be checked when connecting to Keyfactor Command.

    Specifying this parameter sets the local orchestrator application setting CheckServerCertificateRevocation to false. The default for this parameter is true (CRL checking will be done).

    This parameter is used to indicate that no service should be created and added to the server's service control manager. The orchestrator will be installed but will need to be started manually or added to the server's service control manager manually.

    This parameter cannot be used in conjunction with the service-suffix or service-user parameter.

    Specifying this parameter allows you to override the name the orchestrator would by default use to register itself in Keyfactor Command.

    Specifying this parameter sets the local orchestrator application setting OrchestratorName to the specified value.

    By default, the orchestrator uses the results from a hostname lookup for the orchestrator's name.

    This parameter is used to add a suffix to the root service name of keyfactor-orchestrator (e.g. instance1 for a resulting service name of keyfactor-orchestrator-instance1). This is used primarily for implementations where the orchestrator will be installed multiple times on the same server.

    This parameter cannot be used in conjunction with the no-service parameter.

    If this parameter is not specified, the default service name of keyfactor-orchestrator-default will be used.

    This is the local Linux Universal Orchestrator service account that the service will run as (see Create Service Accounts for the Universal Orchestrator. It should be entered as just the user name. Entry of a password for this service account is not required. You may either create this account prior to running the installation script (or use an existing account) or use the force parameter to generate the account automatically during the installation process.

    This parameter cannot be used in conjunction with the no-service parameter.

    If this parameter is not specified, the default service account name of keyfactor-orchestrator will be used.

    Specify this parameter to point to a directory containing the installation files other than the directory in which the install.sh file is found. This parameter is used primarily if a copy of the install.sh file is made in an alternate directory, updated with some customizations, and then used for installation without being copied back to the directory where the remaining installation files are located.

    This parameter is used to test the installation command without actually installing in order to see any errors that might arise and correct them before installing.

    Installation example with expected output using basic authentication:

    vi my_password_file

    sudo ./install.sh --url https://keyfactor.keyexample.com/KeyfactorAgents --username svc_kyforch@keyexample.com --password $(cat my_password_file) --orchestrator-name appsrvr16-ssl.keyexample.com --capabilities all --force

    Creating user keyfactor-orchestrator
Copying files from /tmp/KeyfactorOrchestrator to /opt/keyfactor/orchestrator
Saving app settings
Setting file permissions
Installing systemd service keyfactor-orchestrator-default
Created symlink /etc/systemd/system/multi-user.target.wants/keyfactor-orchestrator-default.service → /etc/systemd/system/keyfactor-orchestrator-default.service.
Starting systemd service keyfactor-orchestrator-default

    Installation example with expected output using client certificate authentication:

    vi cert_password_file

    sudo ./install.sh --url https://keyfactor.keyexample.com/KeyfactorAgents --client-auth-certificate /opt/certs/kyforch.p12 --client-auth-certificate-password $(cat cert_password_file) --orchestrator-name appsrvr16-ssl.keyexample.com --capabilities all --force

    Creating user keyfactor-orchestrator
Copying files from /tmp/KeyfactorOrchestrator to /opt/keyfactor/orchestrator
Saving app settings
Setting file permissions
Installing systemd service keyfactor-orchestrator-default
Created symlink /etc/systemd/system/multi-user.target.wants/keyfactor-orchestrator-default.service → /etc/systemd/system/keyfactor-orchestrator-default.service.
Starting systemd service keyfactor-orchestrator-default
  4. Review the output from the installation to confirm that no errors have occurred.

The script creates a directory, /opt/keyfactor/orchestrator by default, and places the orchestrator files in this directory. Log files are found in /opt/keyfactor/orchestrator/logs by default, though this is configurable (see Configure Logging for the Universal Orchestrator).

The orchestrator service, by default named keyfactor-orchestrator-default.service, should be automatically started at the conclusion of the install and configured to restart on reboot unless you have selected the no-service parameter.

Tip:  Once the installation of the orchestrator is complete, you need to use the Keyfactor Command Management Portal to approve the orchestrator and configure certificate stores or SSL jobs as per the Keyfactor Command Reference Guide: