Installing PubSub+ Cache

You can access PubSub+ Cache on a PubSub+ event broker. You can:

install the PubSub+ Cache Instances that cache messages on standalone Linux systems
uninstall PubSub+ Cache Instances from standalone Linux systems

Product Key Feature Locking

By default, PubSub+ Cache isn't locked on the software event broker; however, it's locked on the appliance, and isn't configurable or displayable. When logged into an appliance, PubSub+ Cache's Solace CLI commands are visible in the CLI, but when run, they'll fail, and return an error message indicating PubSub+ Cache is locked.

To unlock PubSub+ Cache functionality on an appliance, a product key provided by Solace must be entered through the Solace CLI.

To unlock the PubSub+ Cache feature on the Designated Router, enter 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.

If a product key is removed, then a system restart is triggered, and all configuration related to the features unlocked by that key is lost.

Downloading PubSub+ Cache

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

System Requirements

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

To install PubSub+ Cache, you must use PubSub+ Messaging API for C, versions 7.24.1 or earlier. Versions 7.25.0 and later are not compatible with PubSub+ Cache.

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. When running on a Linux server, either the 32-bit or the 64-bit package may be used. For additional installation information, refer to the README file included with the installation package.

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

Installing on a Linux Server with systemd
Installing on a Linux Server with chkconfig
Installing on a Linux Server without chkconfig

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

Installing on a Linux Server with `systemd`

This example shows installation on Linux server, assuming that the package is in /tmp/solcache_Linux26-i386_opt_<version>.tar.gz and the PubSub+ Messaging API for C (PubSub+ C API solclient package) is in /tmp/solClient_Linux26-i386_opt_<version>.tar.gz. The steps below presume that you have root access on the server.

To install PubSub+ Cache, perform these steps:

Install PubSub+ Cache software, /usr/local/solace is used in this example. Choose the appropriate install directory for your server (referred to as <installdir> in the rest of the steps).
```
cd <installdir> 
tar xzf /tmp/solcache_Linux26-i386_opt_<version>.tar.gz
```

Install PubSub+ C API binaries (also in <installdir>).

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

If you're not installing in /usr/local/solace, modify <installdir>/solcache/bin/SolCache.service to change the path /usr/local/solace/ to whatever you have chosen for <installdir>.You'll need to change the lines in SolCache.service that begin with the following, as well as any other lines that contain /usr/local/solace/:
- Environment
- ExecStart
- ExecReload
- ExecStop
Add the PubSub+ Cache systemd unit file. This will allow turnkey startup/shutdown of PubSub+ Cache instances using systemd, that is systemctl start | stop solcache.
```
cp <installdir>/solcache/bin/SolCache.service /usr/lib/systemd/system
systemctl enable solcache
```
Configure cache instances. Run the following manually.
```
cd <installdir>/solcache
cp sampleConfig.txt config/instance1
vi config/instance1
```
For every config file in <installdir>/solcache/config, an instance is started by the systemctl start | stop solcache infrastructure.

Don't leave editor backups lying around in <installdir>/solcache/config as they will be treated like another config file.

Optional: Modify Environment Variables

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

To tune the environment variable, start the cache instance.

systemctl start solcache

The PubSub+ Cache Instance will restart if it dies for any reason. You must use the systemctl stop solcache command to stop all cache instances.

You can see the service status with the following command:

systemctl status solcache

Installing on a Linux Server with `chkconfig`

This example shows installation on Linux server, assuming that the package is in /tmp/solcache_Linux26-i386_opt_<version>.tar.gz and the PubSub+ C API (solclient) package is in /tmp/solClient_Linux26-i386_opt_<version>.tar.gz. You require root access on the server.

To install PubSub+ Cache, perform these steps:

Install PubSub+ Cache software, /usr/local/solace is used in this example. Choose the appropriate install directory for your server (referred to as <installdir> in the rest of the steps).
```
cd <installdir>
tar xzf /tmp/solcache_Linux26-i386_opt_<version>.tar.gz
```

Install PubSub+ C API libraries (also in <installdir>).

tar xzf /tmp/solclient_Linux26-i386_opt_<version>.tar.gz
cd <installdir>/solcache

Install the PubSub+ Cache service. This will allow turnkey startup/shutdown of PubSub+ Cache instances, that is service solcache start|stop.
```
ln -s <installdir>/solcache/bin/serviceScript /etc/init.d/solcache
chkconfig --add solcache
chkconfig --list
```
Configure the cache instances. Run the following manually.
```
cp sampleConfig.txt config/instance1
vi config/instance1
```
For every config file in <installdir>/solcache/config, an instance is started by the service solcache infrastructure.

Optional: Modify Environment Variables

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

To modify the environment variable, start the cache instance.

service start solcache

The PubSub+ Cache Instance restart if it terminates for any reason. You must use the service solcache stop command to stop all cache instances.

Installing on a Linux Server without chkconfig

To install PubSub+ Cache, perform these steps:

Install the executable.

cd <installdir>
tar xzf /tmp/solcache_Linux26-x86_64_opt_<version>.tar.gz

Install PubSub+ C API libraries (also in <installdir>).

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

Setup the environment variable.

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

Create and edit the config files.

cp sampleConfig.txt config/config1.txt
vi config/config1.txt

Start 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:

Create the following file.
```
 /etc/default/solcache
```
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.

Uninstalling a systemd Service
Uninstalling a chkconfig Service
Uninstalling from a Linux Server without chkconfig

To uninstall the corresponding PubSub+ Cache Instance object on the event broker, refer to 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 will have 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.

Stop all running PubSub+ Cache Instance processes.
```
systemctl stop solcache
```

Disable and remove the service.

systemctl disable solcache
rm /usr/lib/systemd/system/SolCache.service

Optionally, remove the executables.
```
rm <installdir>/solcache/bin/*
```
Optionally, remove the client library if no other applications using it.
```
rm -rf <installdir>/solclient
```
Optionally, remove your cache instance configuration files.
```
rm <installdir>/solcache/config/*
```

Uninstalling a chkconfig Service

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

Stop all running PubSub+ Cache Instance processes.
```
service solcache stop
```

Remove the service.

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

Optionally, remove the executables.
```
rm <installdir>/solcache/bin/*
```
Optionally, remove the client library if no other applications using it.
```
rm -rf <installdir>/solclient
```
Optionally, remove your cache instance configuration files.
```
rm <installdir>/solcache/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.

Kill all PubSub+ Cache Instances.
```
pkill -SIGINT solCacheInst
```
Optionally, remove the executables.
```
rm <installdir>/solcache/bin/*
```
Optionally, remove the client library if no other applications using it.
```
rm -rf <installdir>/solclient
```
Optionally, remove your cache instance configuration files.
```
rm <installdir>/solcache/config/*
rm /etc/default/solcache
```

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/solcache.

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

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

<installdir> is the directory 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/solcache or before running the PubSub+ Cache service script:

Environment Variables	Description
`SOLCACHE_ROOT`	The root of the product install directory. Eg: `SOLCACHE_ROOT=/usr/local/third-party/solace`
`SOLCACHE_DIR`	The PubSub+ Cache installation directory. The default is `${SOLCACHE_ROOT}/solcache`. Eg: 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 `${SOLCAGHE_ROOT}/solclient`. Eg: `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`. Eg: `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

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. e.g. `export LD_LIBRARY_PATH=/usr/local/solace/solcache/lib: \ /usr/local/solace/solclient/lib: \ $LD_LIBRARY_PATH`

LD_LIBRARY_PATH

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

e.g. 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 will set 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.

Provide feedback

Installing PubSub+ Cache

Product Key Feature Locking

Downloading PubSub+ Cache

System Requirements

Installing PubSub+ Cache Instances

Installing on a Linux Server with systemd

Installing on a Linux Server with chkconfig

Installing on a Linux Server without chkconfig

Uninstalling PubSub+ Cache

Uninstalling a systemd Service

Uninstalling a chkconfig Service

Uninstalling from a Linux Server without chkconfig

Environment Variables

Advanced Environment Tuning

Installing on a Linux Server with `systemd`

Installing on a Linux Server with `chkconfig`

Uninstalling a `systemd` Service

Uninstalling from a Linux Server without `chkconfig`