Upgrading PubSub+ Cache

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

You can upgrade PubSub+ Cache in two ways::

Basic PubSub+ Cache Upgrade
Upgrading PubSub+ Cache While Preserving Cached Messages

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

Basic PubSub+ Cache Upgrade

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

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

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

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

To perform a basic PubSub+ Cache upgrade, follow these steps:

Copy the PubSub+ 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 PubSub+ Cache package. To download the C API SolClient package, go to https://products.solace.com, select Products > APIs > CCSMP > the appropriate version.
Stop the PubSub+ Cache service.
```
service SolaceCache stop
```
Verify that the operation status of the PubSub+ Cache Instance is NotAvail.

Extract the PubSub+ 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 PubSub+ Cache software.
```
service SolaceCache start
```

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

Upgrading PubSub+ Cache While Preserving Cached Messages

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

For this procedure to be successful, you must upgrade your PubSub+ Cache Instances one at a time, so that there is always at least one PubSub+ 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 PubSub+ Cache is installed to perform the upgrade.

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

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

Copy the PubSub+ 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 PubSub+ 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 PubSub+ 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 PubSub+ 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 PubSub+ Cache installation (ln –s /usr/sw/SolaceCache/bin/servicescript/etc/init.d/SolaceCache) now references the new PubSub+ Cache service script. You must not use any service SolaceCache commands until the PubSub+ Cache Instances have been restarted.
Stop the first PubSub+ Cache Instance. You must use kill <pid> to stop a single PubSub+ Cache Instance (and not a service SolaceCache stop command).

Example:

Enter the following to identify the running PubSub+ Cache Instance:
```
ps faxw | grep SolaceCache
```
The following sample output identifies two PubSub+ 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 PubSub+ Cache Instance is NotAvail.
Restart the PubSub+ Cache Instance. You must restart this one instance only.

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

Provide feedback