Install the Java Agent on Linux

The Java AgentClosed The Java Agent, one of Keyfactor's suite of orchestrators, is used to perform discovery of Java keystores and PEM certificate stores, to inventory discovered stores, and to push certificates out to stores as needed. installation script offers the option to install the Java Agent directly or use the installation script to build an RPM package that you can then use to install the Java Agent on multiple machines.

Note:  If you have a previously installed version of the Keyfactor Java Agent on this server, you need to uninstall it (see Uninstall the Java Agent) before installing a new version.

To begin the Java Agent installation on Linux, unzip the installation files and place them in a temporary working directory.

  1. On the Linux machine on which you wish to install the Java Agent or build the package, at a command shell change to the temporary directory where you placed the installation files.

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

    sudo chmod +x cms-java-agent-installer.sh

  3. In the command shell, run the cms-java-agent-Installer.sh script as root to begin the installation. You will be prompted to answer several questions:

    This is the service account on the Keyfactor Command server side of the fence you created as per Create Service Accounts for the Java Agent. It should be entered in the format DOMAIN\username.

    This is the password for the service account on the Keyfactor Command server side of the fence.

    This is the FQDN or IP address of 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 FQDN or IP address of your Keyfactor Command server.

    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 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). at this prompt that is found in the SSL certificate.

    If you're using a non-standard port for IIS on your Keyfactor Command server, enter that here as part of your hostname or IP address (e.g. keyfactor.keyexample.com:444).

    Press Enter to accept the default of KeyfactorAgents. Only enter an alternate virtual directory if your Keyfactor Command server was configured with an alternate virtual directory for the Keyfactor Command Agents service.

    Press Enter to accept the default of Yes or enter No. The following instructions assume that you answered Yes.

    If your Keyfactor Command server is using a publicly rooted certificate, the server most likely already trusts the certificate issuer, and you can press Enter here.

    If the certificate on the Keyfactor Command server was internally generated, you will need to enter the full path and file name pointing to a file on the local server containing the PEMClosed A PEM format certificate file is a base64-encoded certificate. Since it's presented in ASCII, you can open it in any text editor. PEM certificates always begin and end with entries like ---- BEGIN CERTIFICATE---- and ----END CERTIFICATE----. PEM certificates can contain a single certificate or a full certifiate chain and may contain a private key. Usually, extensions of .cer and .crt are certificate files with no private key, .key is a separate private key file, and .pem is both a certificate and private key.-encoded root certificate for the certificate authorityClosed 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. chain that issued the certificate (see Configure Certificate Root Trust for the Java Agent).

    The root certificate will be saved in a Java keystore file called trust.jks located in the Java Agent’s install directory (/opt/keyfactor-java-agent by default). The default keystore password is changeit. Please contact Keyfactor technical support for assistance in changing the default password, if desired.

    This question will not appear if you answered no to the question about using SSL.

    Press Enter to accept the default of “Yes”. The Java Agent will attempt to connect to the Keyfactor Command server using the credentials provided to confirm that the server name, agents URL, root trust, and provided credentials are valid. Enter “No” to skip this validation if you don't have connectivity to the Keyfactor Command server at the time of installation.

    Tip:  If the installer terminates after this question without an error or with an error writing the trust.jks file, it can be an indication that the path to the root certificate you provided in the previous question was incorrect in some way (e.g. the path is not valid, the root certificate doesn't match the certificate on the Keyfactor Command server, etc.)

    The options at this prompt are “local” or “rpm”. If you press enter to accept “local”, the Java Agent will be installed locally. If you enter “rpm”, the script will generate an rpm after all of the questions have been answered. You can use this to install the Java Agent on other Linux systems with the installation questions already answered. The subsequent questions differ depending on the answer given to this question. The following instructions include both local and rpm questions. You will not see all of these questions.

    If you select “rpm”, the Java agent will not be installed locally.

    Press Enter to accept the default installation directory of /opt/keyfactor-java-agent or enter an alternate path if desired. This question does not appear when generating an rpm.

    This is the service account for the Java Agent side of the fence you created as per Create Service Accounts for the Java Agent. It should be entered as just the user name. Entry of the password for this service account is not required. The username is entered at this time to allow permissions to be configured appropriately.

    Press Enter to accept the default of the local machine's hostname as determined by a reverse DNSClosed The Domain Name System is a service that translates names into IP addresses. lookup or, failing that, the value of the local environment variable for the computer name. If desired, you can enter an alternative value to use as the hostname. This is the identifier for the server on which you are installing the Java agent. This identifier can be in the form of a hostname or FQDN, but you can use another unique identifier, if desired. This identifier appears in the Keyfactor Command Management Portal on the orchestrators page. This question does not appear when generating an rpm.

    Press Enter to accept the default path of /temp under the current directory or enter an alternate path if desired. This is a temporary location the build process will use while the package is being created. This is not the directory where the final RPM file will be placed. This question does not appear when installing locally.

    Note:  Ensure the path does not contain spaces. Any space in the java agent path causes issues when building an rpm.
    Tip:  The RPM file will be generated in a subdirectory (rpmbuild/RPMS) of the home directory of the user running the cms-java-agent-Installer.sh script. If you run the script as root, this will be root’s home directory, so you may choose to run the script as a non-root user if you plan to create an RPM.

    Press Enter to accept the default installation directory of /opt/keyfactor-java-agent or enter an alternate path if desired. This question does not appear when installing locally.

    Press Enter to accept the default as determined by the machine on which the RPM is being generated or enter an alternate architecture if desired. A separate RPM needs to be generated with each required machine architecture. This question does not appear when installing locally.

    Press Enter to accept the default log directory of /opt/cms-java-agent/logs or enter an alternate path if desired.

    Press Enter to accept the default of 7 log files or enter an alternate number if desired. Older files are automatically deleted once more files than this have been generated.

    Press Enter to accept the default log file size of 3 MB or enter an alternate value if desired.

    Press Enter to accept the default value and begin the installation. If you would like to install one or more Any Agent implementations, enter yes. In this case, you’ll be presented with a list of custom certificate store types for which to provide an implementation. After choosing each one, you’ll need to enter the path to the .jar file that implements the certificate store type. That .jar file will be copied to the installation directory, under the libs folder. You’ll need to manually copy any other dependent .jar files to that location as well. Enter “Done” when you’ve finished listing agent implementations. Note that this option is only available when the JavaAgent is installed locally.

  4. After answering the log file size question, the installation begins. Review the output to be sure that no errors have occurred.

    Figure 469: Keyfactor Java Agent Local Installation on Linux

  5. Keyfactor provides scripts that can be used to configure the Keyfactor Java Agent to start automatically. These can be used on systems using startups based on SysV style (init.d) or systemd. Other startup systems will need to be configured manually. If your machine has neither of these startup systems, you will not be able to use these scripts to configure the Keyfactor Java Agent to start automatically. The appropriate startup script to use depends on whether you are doing a local install or installing from a previously generated RPM file.

    1. In the command shell, change to the directory in which you installed the Java Agent. The default install directory is:

      /opt/keyfactor-java-agent

    2. Select the appropriate installation script for your startup system. The two available scripts for local installs are:

      install-init-service.sh
      install-systemd-service.sh
      Tip:  The scripts with -with-configured-hostname in their names (e.g. install-systemd-service-with-configured-hostname.sh) are for use with installations from RPM packages and should not be used for local installs.

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

      sudo chmod +x install-systemd-service.sh

    4. Run the appropriate shell script as root. This will add the keyfactor-java-agent as a service, which you can then stop and start using the standard service stop and start commands. For example:

      service keyfactor-java-agent restart
      systemctl restart keyfactor-java-agent.service

    1. Locate the RPM file on the machine on which it was generated and copy it to the machine on which you wish to install the Java agent.

      Tip:  The RPM file is generated in a subdirectory (rpmbuild/RPMS) of the home directory of the user running the cms-java-agent-Installer.sh script. If you run the script as root, this will be root’s home directory.

    2. Execute the RPM as root. For example:

      sudo rpm -ivh keyfactor-java-agent-8.6.0-1.i686.rpm

    3. In the command shell, change to the directory in which you installed the Java Agent. The default install directory is:

      /opt/cms-java-agent

    4. There are four possible installation scripts for installation from RPM packages:

      install-init-service.sh
      install-init-service-with-configured-hostname.sh
      install-systemd-service.sh
      install-systemd-service-with-configured-hostname.sh

      Select the appropriate installation script type for your startup system (init or systemd). The versions of the scripts that contain a reference to with-configured-hostname in the file name allow you to enter a custom agent name (see Hostname the agent will connect to Keyfactor as (Local)). The versions without this reference will use the system hostname as the agent name.

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

      sudo chmod +x install-systemd-service-with-configured-hostname.sh

    6. Run the appropriate shell script as root. You will be prompted to answer questions specific to the machine on which the Java agent is being installed—the hostname or other identifier for the machine (see Hostname the agent will connect to Keyfactor as (Local)) if you used a with-configured-hostname script and the username and password for the service account that will connect the agent to Keyfactor Command (see Username the Java Agent will connect as).

    7. Change the ownership on the file containing the startup credentials to the local user that the agent will run as. This file is found in the config directory under the installed directory and is called install.creds. For example:

      sudo chown kyfuser /opt/cms-java-agent/config/install.creds

    8. The install shell script adds the keyfactor-java-agent as a service, which you can then stop and start using the standard service stop and start commands. You may need to restart the service after changing the ownership on the credentials file. For example:

      service keyfactor-java-agent restart
      systemctl restart keyfactor-java-agent.service

Tip:  If desired, you can pass the responses to the questions the installer asks in from a file. For example, for a full install (not working from an RPM file you previously created), create a file that contains values something like this (notice lines 2 and 3 match—the installer requires entry of the password twice):
Copy
KEYEXAMPLE\svc_kyfjava
MyVerySecurePassword
MyVerySecurePassword
keyfactor.keyexample.com
KeyfactorAgents
Yes
/tmp/CorpRoot.crt
Yes
local
/opt/keyfactor-java-agent
kyfuser
jvagnt162.keyexample.com
/opt/keyfactor-java-agent/logs
7
"3 MB"
No

Note that the values needed in your input file will vary depending on how you answer some of the questions. For example, the first Yes shown above will go in response to the question of whether to use SSL for the connection to Keyfactor Command. If you answer No here, you will not receive the question about needing a root certificate, and so the path to a root certificate shown after this will not correctly match the next question. The script will fail.

Place the file in the same directory as the install script. Then, execute the install script like this:

Copy
sudo ./cms-java-agent-installer.sh < myinputfile.txt