Installing and Uninstalling PubSub+ Cache

Each PubSub+ Cache Instance runs on a standalone Linux server. This section describes how to install, configure, and uninstall PubSub+ Cache. For more information, see:

Downloading PubSub+ Cache

The PubSub+ Cache installation package is available for download. Contact Solace if you do not have access to the download site.

The PubSub+ Cache application is provided for Linux systems as a 64-bit executable. PubSub+ Cache requires a 64-bit version of the PubSub+ Messaging API for C (solclient package) to be installed as well. The PubSub+ C API is distributed and installed separately.

System Requirements

PubSub+ Cache has the following system requirements:

Event Brokers

PubSub+ Cache is supported by all currently supported PubSub+ software event brokers and appliances.

Server

PubSub+ Cache requires a Linux x86 64 bit computer platform or VM running a version of Red Hat Enterprise Linux (RHEL) or Ubuntu that is in active support and has the available security patches. The server core requirements are:

  • Minimum: Two cores
  • For high-performance use cases without the Ingress Message Plug-In, four cores are recommended
  • For high-performance use cases with the Ingress Message Plug-In, five or six cores are recommended
PubSub+ Messaging API for C

PubSub+ Cache version 1.0.11 and later support all versions of the PubSub+ Messaging API for C that are in active support.

PubSub+ Cache versions earlier than 1.0.11 require a supported version of PubSub+ Messaging API for C no later than 7.24.1.4 to install and run. However, you can use any supported version of the PubSub+ Messaging API for C in your applications, including to make cache requests.

Product Key Feature Locking

By default, PubSub+ Cache is unlocked on the software event broker. However, it is locked on the appliance, and its settings can't be configured or displayed. If you are logged in to an appliance, you can see PubSub+ Cache commands in the CLI, but if you run them they fail and return an error message indicating that PubSub+ Cache is locked.

To unlock PubSub+ Cache functionality on an appliance, you must enter a Solace product key by running the following Solace CLI commands:

solace> enable
solace# admin
solace(admin)# product-key <key-value>

Where:

<key-value> is the product key provided by Solace.

Removing a product key triggers a system restart, resulting in the loss of all configuration related to the features unlocked by that key.

Installing PubSub+ Cache Instances

A PubSub+ Cache Instance consists of a single PubSub+ Cache process that must be installed on a standalone Linux system and a corresponding PubSub+ Cache Instance object on an event broker that is created through the Solace CLI. For additional installation information, see the README file included with the installation package.

Use the links below to navigate to the appropriate installation procedure.

To configure the corresponding PubSub+ Cache Instance object on the event broker, see Configuring PubSub+ Cache Instances.

Installing on a Linux Server with systemd

If you are using Red Hat Enterprise Linux (RHEL) 8 or above, before performing the steps below, create a logical link from Python3 to Python by running the following command:

 sudo ln -s /usr/bin/python3 /usr/bin/python

This procedure assumes that:

  • the PubSub+ Cache installation package (SolaceCache_Linux26-x86_64_opt_<version>.tar.gz) and the PubSub+ C API solclient package (solclient_Linux26-x86_64_opt_<version>.tar.gz) are both in the /tmp directory

  • you have root access on the Linux server

The usual installation directory for PubSub+ Cache is /usr/local/solace. The configuration of PubSub+ Cache assumes that this is the installation directory, so if you choose a different location, ensure that you follow the optional steps to modify your configuration accordingly. You might need to create the /usr/local/solace directory on your system.

To install PubSub+ Cache, perform the following steps, where <installdir> is the installation directory (usually /usr/local/solace):

  1. Change to the installation directory:

    cd <installdir>

  2. Install PubSub+ Cache software:

    tar xzf /tmp/SolaceCache_Linux26-x86_64_opt_<version>.tar.gz

  3. Install PubSub+ C API binaries:

    tar xzf /tmp/solclient_Linux26-x86_64_opt_<version>.tar.gz

  4. The PubSub+ Cache process expects the PubSub+ C API files to be in a directory called solclient. Rename the PubSub+ C API directory accordingly:

    mv solclient-<version>/ solclient

  1. Optional: If your installation directory is not /usr/local/solace, modify <installdir>/SolaceCache/bin/SolaceCache.service to update the path /usr/local/solace/ to the installation directory you have chosen. You must update any lines that begin with the following text as well as any other lines that contain /usr/local/solace/:

    • Environment

    • ExecStart

    • ExecReload

    • ExecStop

  2. Run the following commands to add the PubSub+ Cache systemd unit file to allow starting and stopping of PubSub+ Cache Instances using systemd:

    cp <installdir>/SolaceCache/bin/SolaceCache.service /usr/lib/systemd/system
    systemctl enable SolaceCache

  3. Copy the sample configuration to the config directory (in this example, we name it instance1)

    cd <installdir>/SolaceCache
    cp sampleConfig.txt config/instance1

    For every configuration file in <installdir>/SolaceCache/config, an instance is started by the systemctl start | stop SolaceCache infrastructure.

    Don't leave editor backups in <installdir>/SolaceCache/config because they are treated like additional configuration files.

  4. Uncomment and update the appropriate lines in the configuration file according to the inline instructions:

    vi config/instance1

Optional: Modify Environment Variables

For a description of the environment variables that may be tuned for your PubSub+ Cache installation, see Environment Variables. If you have selected an <installdir> location that is different from /usr/local/solace/ then you MUST set environment variables or create the /etc/default/SolaceCache environment variable file.

To tune the environment variables, start the cache instance.

systemctl start SolaceCache

The PubSub+ Cache Instance restarts if it stops for any reason. You must use the systemctl stop SolaceCache command to stop all cache instances.

You can see the service status with the following command:

systemctl status SolaceCache

Installing on a Linux Server with chkconfig

This procedure assumes that:

  • the PubSub+ Cache installation package (SolaceCache_Linux26-x86_64_opt_<version>.tar.gz) and the PubSub+ C API solclient package (solclient_Linux26-x86_64_opt_<version>.tar.gz) are both in the /tmp directory

  • you have root access on the Linux server

The usual installation directory for PubSub+ Cache is /usr/local/solace. The configuration of PubSub+ Cache assumes that this is the installation directory, so if you choose a different location, ensure that you follow the optional steps to modify your configuration accordingly. You might need to create the /usr/local/solace directory on your system.

To install PubSub+ Cache, perform the following steps, where <installdir> is the installation directory (usually /usr/local/solace):

  1. Change to the installation directory:

    cd <installdir>

  2. Install PubSub+ Cache software:

    tar xzf /tmp/SolaceCache_Linux26-x86_64_opt_<version>.tar.gz

  3. Install PubSub+ C API binaries:

    tar xzf /tmp/solclient_Linux26-x86_64_opt_<version>.tar.gz

  4. The PubSub+ Cache process expects the PubSub+ C API files to be in a directory called solclient. Rename the PubSub+ C API directory accordingly:

    mv solclient-<version>/ solclient

  1. Install the PubSub+ Cache service. This allows turnkey startup/shutdown of PubSub+ Cache Instances, that is service SolaceCache start | stop.

    ln -s <installdir>/SolaceCache/bin/serviceScript /etc/init.d/SolaceCache
    chkconfig --add SolaceCache
    chkconfig --list

  2. Copy the sample configuration to the config directory (in this example, we name it instance1)

    cd <installdir>/SolaceCache
cp sampleConfig.txt config/instance1

    For every configuration file in <installdir>/SolaceCache/config, an instance is started by the service SolaceCache infrastructure.

  3. Uncomment and update the appropriate lines in the configuration file according to the inline instructions:

    vi config/instance1

Optional: Modify Environment Variables

For a description of the environment variables that may be tuned for your PubSub+ Cache installation, see Environment Variables. If you have selected an <installdir> location that is different from /usr/local/solace/ then you MUST set environment variables or create the /etc/default/SolaceCache environment variable file.

To modify the environment variable, start the cache instance.

service start SolaceCache

The PubSub+ Cache Instance restarts if it stops for any reason. You must use the service SolaceCache stop command to stop all cache instances.

Installing on a Linux Server without chkconfig

This procedure assumes that:

  • the PubSub+ Cache installation package (SolaceCache_Linux26-x86_64_opt_<version>.tar.gz) and the PubSub+ C API solclient package (solclient_Linux26-x86_64_opt_<version>.tar.gz) are both in the /tmp directory

  • you have root access on the Linux server

The usual installation directory for PubSub+ Cache is /usr/local/solace. The configuration of PubSub+ Cache assumes that this is the installation directory, so if you choose a different location, ensure that you follow the optional steps to modify your configuration accordingly. You might need to create the /usr/local/solace directory on your system.

To install PubSub+ Cache, perform the following steps, where <installdir> is the installation directory (usually /usr/local/solace):

  1. Change to the installation directory:

    cd <installdir>

  2. Install PubSub+ Cache software:

    tar xzf /tmp/SolaceCache_Linux26-x86_64_opt_<version>.tar.gz

  3. Install PubSub+ C API binaries:

    tar xzf /tmp/solclient_Linux26-x86_64_opt_<version>.tar.gz

  4. The PubSub+ Cache process expects the PubSub+ C API files to be in a directory called solclient. Rename the PubSub+ C API directory accordingly:

    mv solclient-<version>/ solclient

  1. Setup the environment variable.

    export LD_LIBRARY_PATH=<installdir>/solclient/lib:<installdir>/SolaceCache/lib:$LD_LIBRARY_PATH

  2. Copy the sample configuration to the config directory (in this example, we name it instance1)

    cd <installdir>/SolaceCache
cp sampleConfig.txt config/instance1

  3. Uncomment and update the appropriate lines in the configuration file according to the inline instructions:

    vi config/instance1

  4. Start the process.

    bin/solCacheInstance -f config/config1.txt &

Starting as a service without chkconfig

The PubSub+ Cache service script can be adapted to many Linux service environments easily. Consult with your system administrator for the exact procedures required for your Linux system.

On any standalone server, you must have root access. Then after completing the Installing PubSub+ Cache Instances and installing the service script as appropriate for your OS, do the following:

  1. Create the following file.

     /etc/default/SolaceCache

  2. Add a SOLCACHE_ROOT line to reflect the <installdir> chosen above:

      SOLCACHE_ROOT=<installdir>

Uninstalling PubSub+ Cache

Before removing a PubSub+ Cache Instance application, ensure that no running programs have their current directory set inside the PubSub+ Cache installation directories while uninstalling. Any files in the installation directories that were not part of the original install process are not removed. You must remove them manually before running the uninstall process.

Use the links below to navigate to the appropriate procedure to uninstall PubSub+ Cache.

To uninstall the corresponding PubSub+ Cache Instance object on the event broker, see Configuring PubSub+ Cache Instances.

A PubSub+ Cache Instance (that is, the PubSub+ Cache process) can be uninstalled from the standalone Linux system without uninstalling the corresponding PubSub+ Cache Instance object. In this case, the PubSub+ Cache Instance object has a Down administrative state.

Uninstalling a systemd Service

This example shows how to uninstall a service that uses systemd. The steps require that you have root access.

  1. Stop all running PubSub+ Cache Instance processes.

    systemctl stop SolaceCache

  2. Disable and remove the service.

    systemctl disable SolaceCache
    rm /usr/lib/systemd/system/SolaceCache.service

  3. Optionally, remove the executables.

    rm <installdir>/SolaceCache/bin/*

  4. Optionally, remove the client library if no other applications are using it.

    rm -rf <installdir>/solclient

  5. Optionally, remove your cache instance configuration files.

    rm <installdir>/SolaceCache/config/*

Uninstalling a chkconfig Service

This example shows how to uninstall a service that uses chkconfig. The steps require that you have root access.

  1. Stop all running PubSub+ Cache Instance processes.

    service SolaceCache stop

  2. Remove the service.

    chkconfig --del SolaceCache
    rm /etc/init.d/SolaceCache

  3. Optionally, remove the executables.

    rm <installdir>/SolaceCache/bin/*

  4. Optionally, remove the client library if no other applications are using it.

    rm -rf <installdir>/solclient

  5. Optionally, remove your cache instance configuration files.

    rm <installdir>/SolaceCache/config/*

Uninstalling from a Linux Server without chkconfig

This example shows how to uninstall a service without chkconfig. The steps require that you have root access.

  1. Kill all  PubSub+ Cache Instances.

    pkill -SIGINT solCacheInst

  2. Optionally, remove the executables.

    rm <installdir>/SolaceCache/bin/*

  3. Optionally, remove the client library if no other applications are using it.

    rm -rf <installdir>/solclient

  4. Optionally, remove your cache instance configuration files.

    rm <installdir>/SolaceCache/config/*
    rm /etc/default/SolaceCache

Environment Variables

The installation package includes a service script that sets the environment variables necessary for running PubSub+ Cache Instance. Instructions for installing and configuring the PubSub+ Cache Instance are included in the Installing PubSub+ Cache Instances section and in the README file included with the installation package.

You may need to create the environment file /etc/default/SolaceCache.

If you have changed the default installation directory you must create /etc/default/SolaceCache.

If you have set <installdir> to something other than /usr/local/solace, add the following line to /etc/default/SolaceCache: SOLCACHE_ROOT=<installdir>

<installdir> is the directory that contains both the PubSub+ Cache and solclient subdirectories, for example: SOLCACHE_ROOT=/usr/local/third-party/solace.

Advanced Environment Tuning

The following environment variables may be set in /etc/default/SolaceCache or before running the PubSub+ Cache service script:

Environment Variables Description
SOLCACHE_ROOT

The root of the product install directory.

For example: SOLCACHE_ROOT=/usr/local/third-party/solace
SOLCACHE_DIR

The PubSub+ Cache installation directory. The default is ${SOLCACHE_ROOT}/solcache.

For example: SOLCACHE_DIR=/usr/local/solace/solcache_v6.2.0.1
SOLCLIENT_DIR

The installation directory of the PubSub+ Messaging API for C. The default is ${SOLCACHE_ROOT}/solclient.

For example: SOLCLIENT_DIR=/usr/local/solace/solclient_v6.2.0.1
SOLCACHE_WD The PubSub+ Cache working directory. By default this defaults to the PubSub+ Cache installation directory, $(SOLCACHE_DIR). If 'backup-cached-messages' is used then the subdirectory solCache_backups/ is created in ${SOLCACHE_WD}.
SOLCACHE_CONFIG

The directory containing all PubSub+ Cache configuration files. It is unlikely this needs to change. The default is ${SOLCACHE_DIR}/config.

For example: SOLCACHE_DIR=/home/bob/cacheConfigs
SOLACE_SOLCACHEINSTANCE_CPU_MASK

The hex CPU mask of permitted CPUs that PubSub+ Cache Instance is allowed to run on.

Setting this mask may be done in conjunction with setting the CPU affinity of the individual cache instances in their configuration files (see CACHE_CPU_AFFINITY attribute in the configuration file). i.e. An individual cache-instance can be confined to one CPU by setting the CACHE_CPU_AFFINITY in the configuration file.

If you are running PubSub+ Cache Instance directly from the command line, then the following environment variables may be defined prior to starting up PubSub+ Cache Instance:

Environment Variables Description
LD_LIBRARY_PATH

Standard UNIX environment variable. It must include the directory where the C-API and PubSub+ Cache plugin library are found.

For example: export LD_LIBRARY_PATH=/usr/local/solace/solcache/lib: \ /usr/local/solace/solclient/lib: \ $LD_LIBRARY_PATH

Note that the service script, which is bundled with the PubSub+ Cache distribution, sets the value of LD_LIBRARY_PATH in accordance with the Installing PubSub+ Cache Instances section above. It is not necessary to set LD_LIBRARY path if you are using the service script.