Upgrading Solace Cache

If you have a previous version of Solace Cache, you must upgrade to use all its features and benefit from all available compatibility.

You can upgrade Solace Cache in two ways::

Basic Solace Cache Upgrade
Upgrading Solace Cache While Preserving Cached Messages

If a Cache Cluster has only one Solace Cache Instance, you can't avoid losing cached messages and must use the basic Solace Cache upgrade procedure. If a Cache Clusters have two or more instances, you can upgrade Solace Cache while preserving the cached messages.

Basic Solace Cache Upgrade

If you don’t care about loss of cached messages, or if you only have a single Solace Cache Instance in a Cache Cluster, follow this procedure to upgrade Solace Cache.

All cached messages are lost when following this procedure. Solace Cache will be out of service during the procedure.

You need root access to the Linux server where Solace Cache is installed to perform the upgrade.

Repeat the following procedure on every server running Solace Cache Instances that need to be upgraded. In the steps, replace <installdir> with the name of the directory where Solace Cache is installed and replace <version> with the version number of Solace Cache that you are installing.

To perform a basic Solace Cache upgrade, follow these steps:

Copy the Solace Cache package to the server.

/tmp/SolaceCache_Linux26-x64_opt_<version>.tar.gz

Copy the C-API solclient package to the server.
```
/tmp/solclient_Linux26-x64_opt_<version>.tar.gz
```
The C API SolClient package is distributed separately from the Solace Cache package. To download the C API SolClient package, go to https://products.solace.com, select Products > APIs > CCSMP > the appropriate version.
Stop the Solace Cache service.
```
service SolaceCache stop
```
Verify that the operation status of the Solace Cache Instance is NotAvail.

Extract the Solace Cache software.

cd <installdir>
tar xfz /tmp/SolacheCache_Linux26-x64_opt_<version>.tar.gz

Extract the C API solclient software.

cd <installdir>
tar xfz /tmp/solclient_Linux26-x64_opt_<version>.tar.gz
mv solclient_<version> solclient

Start the Solace Cache software.
```
service SolaceCache start
```

Once the cache instances restart, new messages can be published to the cache and then retrieved.

Upgrading Solace Cache While Preserving Cached Messages

You can upgrade Solace Cache without loss of cached messages or an interruption in service. To do so, you must have multiple Solace Cache Instances in each Cache Cluster.

For this procedure to be successful, you must upgrade your Solace Cache Instances one at a time, so that there is always at least one Solace Cache Instance running in each Cache Cluster. Follow the steps carefully to ensure this is the case.

You need root access to the Linux server where Solace Cache is installed to perform the upgrade.

Repeat the following procedure on every server running Solace Cache Instances that need to be upgraded. In the steps, replace <installdir> with the name of the directory where Solace Cache is installed, replace <version> with the version number of Solace Cache that you are installing and replace <oldversion> with the currently installed version of Solace Cache.

To upgrade Solace Cache while preserving cached messages, follow these steps:

Copy the Solace Cache package to the server.

/tmp/SolaceCache_Linux26-x64_opt_<version>.tar.gz

Copy the C-API solclient package to the server.
```
/tmp/solclient_Linux26-x64_opt_<version>.tar.gz
```
The C API SolClient package is distributed separately from the Solace Cache package. To download the C API SolClient package, go to https://products.solace.com, select Products > APIs > CCSMP > the appropriate version.
Rename the existing SolaceCache directory. Do not stop the Solace Cache Instances before doing this.
```
cd <installdir>
mv SolaceCache SolaceCache.<oldversion>
```

Rename the existing C API solclient directory.

cd <installdir>
mv solclient solclient.<oldversion>

Extract the Solace Cache software.

cd <installdir>
tar xfz /tmp/SolaceCache_Linux26-i386_opt_<version>.tar.gz

Extract the C API solclient software.

cd <installdir>
tar xfz /tmp/solclient_Linux26-i386_opt_<version>.tar.gz
mv solclient_<version> solclient

Copy the configuration files from your old SolaceCache directory to the newly created SolaceCache directory.
```
cd <installdir>
cp SolaceCache.<oldversion>/config/* SolaceCache/config
```
The symbolic link that you created with your initial Solace Cache installation (ln –s /usr/sw/SolaceCache/bin/servicescript/etc/init.d/SolaceCache) now references the new Solace Cache service script. You must not use any service SolaceCache commands until the Solace Cache Instances have been restarted.
Stop the first Solace Cache Instance. You must use kill <pid> to stop a single Solace Cache Instance (and not a service SolaceCache stop command).

Example:

Enter the following to identify the running Solace Cache Instance:
```
ps faxw | grep SolaceCache
```
The following sample output identifies two Solace Cache Instances running on the platform. The instances are identified by the configuration files rp.ci.i1.txt and rp.c1.i2.txt:
```
ps faxw | grep SolaceCache

2541 pts/1 S+ 0:00 \_ grep -i SolaceCache
2457 pts/1 S 0:00 /usr/bin/perl -w
/usr/sw/SolaceCache/bin/keepalive SolaceCache -f /usr/sw/
SolaceCache /config/rp.c1.i1.txt
2460 pts/1 S 0:00 \_ SolaceCache -f /usr/sw/ SolaceCache
/config/rp.c1.i1.txt
2461 pts/1 S 0:00 /usr/bin/perl -w /usr/sw/
SolaceCache /bin/keepalive SolaceCache -f /usr/sw/ SolaceCache
/config/rp.c1.i2.txt
2462 pts/1 S 0:00 \_ SolaceCache -f /usr/sw/ SolaceCache
/config/rp.c1.i2.txt
```
To stop a single instance, you must signal the keepalive script that is managing the instance. For example, to stop rp.c1.i1, enter kill 2457.
Verify that the operation status of the Solace Cache Instance is NotAvail.
Restart the Solace Cache Instance. You must restart this one instance only.

Example:
```
service SolaceCache start rp.c1.i1
```
Wait for the Solace Cache Instance to completely synchronize to the other Solace Cache Instance in the Cache Cluster (In other words, the Solace Cache Instance operational state must be Up).
Repeat Steps 9 to 11 for each Solace Cache Instance on the server.
Repeat Steps 1 to 12 for each server that is running Solace Cache Instances.
When all Solace Cache Instances are upgraded and running, you can optionally remove the old versions of the Solace Cache directory and solClient library directory created in Step 3 and Step 4.

Provide feedback