Installing & Upgrading Solace Geneos Agent

This section describes how to install a Solace Geneos Agent on an event broker. The procedure can also be used to upgrade the version of a Solace Geneos Agent that is already installed on an event broker.

Prerequisites

Solace PubSub+ appliances:
  • Perform the installation as root, with root user’s environment, on the target appliance.
  • As of appliance release 8.2.0, operations below that state they can only be performed by root, can now also be performed by a Sysadmin User. For information on configuring Sysadmin Users, refer to Configuring Multiple Linux Shell Users.
  • Stop any running instances of Solace Geneos Agent on the target appliance.
  • If SolGeneos is not currently using the pre-installed Java Runtime Environment (JRE) and is not using a JRE version 1.8 or newer, refer to Updating a Java Runtime Environment.
Solace PubSub+ software event brokers:
  • Perform the installation and running of Solace Geneos, the JRE, and NetProbe on the Linux host shell as the root user, which is accessible on ssh port 22 (port 2222 for software event broker releases prior to 8.5.0) as the sysadmin user.
  • For a default installation, create the /usr/sw directory if it does not exist.
  • This prerequisite applies to Solace PubSub+ software event broker 9.4.0 or higher only. As part of the Solace Geneos Agent upgrade and installation, umask must be set to 0022. For software event broker Machine image, permission settings must be configured to provide Solace Geneos Agent access to read the system.log file. See, Preparing Software Event Broker for Solace Geneos Agent Installation for more information.
  • If SolGeneos is not currently using a JRE version 1.8 or newer, refer to Updating a Java Runtime Environment.

Updating a Java Runtime Environment

For Solace PubSub+ appliances version 9.5.0 and older, if the JRE version used by SolGeneos is older than 1.8, perform the following steps as the root user to start using the pre-installed JRE:

  1. Remove the /usr/sw/java softlink.

    rm -rf /usr/sw/java

  2. Create a /usr/sw/java softlink to the pre-installed JRE.

    Solace PubSub+ appliances version 9.0.1.7 and older:

    ln -s /usr/java/latest /usr/sw/java

    Solace PubSub+ appliances version 9.0.1.30 and newer:

    ln -s /etc/alternatives/jre_1.8.0_openjdk /usr/sw/java

For the software event broker, perform only step 1 above and continue to Installing a Java Runtime Environment.

Installing a Java Runtime Environment

A JRE is pre-installed on appliances, so installing a JRE is not required. For the software event broker, you should use JRE 1.8 or later.

The following example shows you how to install JRE on the software event broker. The example assumes JRE 1.8 is to be installed.

  1. Download the JRE Linux archive file from here and place it under the directory /usr/sw.
  2. Change the permission of the file you downloaded to be executable.
  3. Run the self-extracting binary from /usr/sw. For example:

    4. tar -xzf ./jre-8u60-linux-i586.tar.gz

  4. The JRE will be extracted under /usr/sw/jre1.8.0_60.
  5. Create a /usr/sw/java softlink to the directory where JRE is installed:

    6. ln -s /usr/sw/jre1.8.0_60 /usr/sw/java

Preparing Software Event Broker for Solace Geneos Agent Installation

When installing or upgrading Solace Geneos Agent on PubSub+ software event broker 9.4.0 release or higher, umask must be set to 0022. By default, only the container user has read and write access to software event broker Docker container files. This permission setup works as long as no other processes require read access to those files. However, Solace Geneos Agent require read access to the software event broker's log files for log aggregation.

For the software event broker Docker image, you can set the umask=0022 during container creation. If you are doing an instance replacement, you can use cloud-init to configure the umask. For software event broker Machine image, you will need to perform few additional steps described below.

To prepare your software event broker Machine image for Solace Geneos Agent installation, perform the following steps on the Linux Host shell:

  1. Disable the Solace PubSub+ service.

    2. solacectl service stop

  2. Remove the Solace PubSub+ software message broker Docker container.

    3. docker rm solace

  3. In solace-container.env.conf file located in /etc/solace/solace-container.env.conf, add umask=0022.
  4. Find host path to jail volume by running the docker volume inspect jail command. In the next step, we will use the host path to jail volume to set permissions for Solace Geneos Agent to access the system.log file.
    In the example below, the host path to the jail volumes are the Mountpoint and devicedirectories. If you have the device directory configured, use that as the host path to jail volume. If you don't have the device directory configured then use the Mountpoint directory.

    5. docker volume inspect jail
    [
          {
                "CreatedAt": "2019-10-23T14:11:49Z",
                "Driver": "local",
                "Labels": {},
                "Mountpoint": "/var/lib/docker/volumes/jail/_data",
                "Name": "jail",
                "Options": {
                "device": "/mnt/vmr/jail",
                "o": "bind",
                "type": "none"
                },
                "Scope": "local"cons
          }
    ]

  5. Run the following chmod command to update permissions for Solace Geneos Agent to access the software message broker's system.log file.

    6. chmod -R u+rwX,go+rX <host path of jail volume>

  6. Re-enable the Solace PubSub+ service.

    7. solacectl service enable

  7. Restart the Solace PubSub+ application.

    8. solacectl service start

You can now start the procedure to install and upgrade Solace Geneos Agent on your software event broker Machine image.

Procedure

To install or upgrade a Solace Geneos Agent in PubSub+ software event broker, do the following:

  1. Copy sol-geneosagent-<version>.tar.gz to /usr/sw and extract it in the same directory.

    If successful, a new directory solgeneos is created under /usr/sw.

  2. Change directory to /usr/sw/solgeneos/loads/solgeneos_<version>/bin, and enter the following command to run the installation script:

    ./setup.sh install

    Before the installation begins, the installation script stops and removes any existing Solace Geneos Agent service. The script will also add a SysV or systemd service definition compatible with the current Solace PubSub+ version.

  3. If the installation script detects that the configuration directory is empty (which could be the case when upgrading from a version of Solace Geneos Agent earlier than 5.5.1), it provides an option to convert to the new configuration. In this case, when prompted to enter Managed Entity name, input the Managed Entity that has been configured on the NetProbe.

    When the installation has successfully completed, a completion message displays at the command prompt.