Installing and Uninstalling Solace Cache

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

Downloading Solace Cache

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

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

System Requirements

Solace Cache has the following system requirements:

Event Brokers

Solace Cache is supported by all currently supported software event brokers and appliance event brokers.

Server

Solace 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
Solace Messaging API for C

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

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

Product Key Feature Locking

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

To unlock Solace Cache functionality on an appliance event broker, you must enter a Solace product key by running the following Solace Event Broker 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 Solace Cache Instances

A Solace Cache Instance consists of a single Solace Cache process that must be installed on a standalone Linux system and a corresponding Solace Cache Instance object on an event broker that is created through the Solace Event Broker 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 Solace Cache Instance object on the event broker, see Configuring Solace 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 Solace Cache installation package (SolaceCache_Linux26-x86_64_opt_<version>.tar.gz) and the Solace 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 Solace Cache is /usr/local/solace. The configuration of Solace 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 Solace 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 Solace Cache software:

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

  3. Install Solace C API binaries:

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

  4. The Solace Cache process expects the Solace C API files to be in a directory called solclient. Rename the Solace 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 Solace Cache systemd unit file to allow starting and stopping of Solace 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 Solace 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 Solace 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 Solace Cache installation package (SolaceCache_Linux26-x86_64_opt_<version>.tar.gz) and the Solace 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 Solace Cache is /usr/local/solace. The configuration of Solace 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 Solace 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 Solace Cache software:

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

  3. Install Solace C API binaries:

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

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

    mv solclient-<version>/ solclient

  1. Install the Solace Cache service. This allows turnkey startup/shutdown of Solace 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 Solace 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 Solace 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 Solace Cache installation package (SolaceCache_Linux26-x86_64_opt_<version>.tar.gz) and the Solace 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 Solace Cache is /usr/local/solace. The configuration of Solace 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 Solace 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 Solace Cache software:

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

  3. Install Solace C API binaries:

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

  4. The Solace Cache process expects the Solace C API files to be in a directory called solclient. Rename the Solace 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 Solace 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 Solace 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 Solace Cache

Before removing a Solace Cache Instance application, ensure that no running programs have their current directory set inside the Solace 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 Solace Cache.

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

A Solace Cache Instance (that is, the Solace Cache process) can be uninstalled from the standalone Linux system without uninstalling the corresponding Solace Cache Instance object. In this case, the Solace 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 Solace 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 Solace 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  Solace 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 Solace Cache Instance. Instructions for installing and configuring the Solace Cache Instance are included in the Installing Solace 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 Solace 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 Solace 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 Solace 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 Solace 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 Solace Cache working directory. By default this defaults to the Solace 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 Solace 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 Solace 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 Solace Cache Instance directly from the command line, then the following environment variables may be defined prior to starting up Solace Cache Instance:

Environment Variables Description
LD_LIBRARY_PATH

Standard UNIX environment variable. It must include the directory where the C-API and Solace 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 Solace Cache distribution, sets the value of LD_LIBRARY_PATH in accordance with the Installing Solace Cache Instances section above. It is not necessary to set LD_LIBRARY path if you are using the service script.