i

Upgrading PubSub+ Cache

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

There are two ways to upgrade your PubSub+ Cache:

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

If a Cache Cluster has one cache instance only, you can't avoid losing cached messages and must use the basic PubSub+ Cache upgrade procedure. If the 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 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.

Before you start this upgrade, it's assumed that you have root access to the Linux server. The directory where PubSub+ Cache is installed is <installdir>. The version of PubSub+ Cache to be installed is <version>.

This procedure needs to be repeated on each server running PubSub+ Cache Instances, if applicable.

To perform 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 cache messages or an interruption in service. For this upgrade to work, there must be 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 below carefully to ensure this is the case.

Before you start this upgrade, it's assumed that you have root access to the Linux server. The directory where PubSub+ Cache is installed is <installdir>. The version of PubSub+ Cache to be installed is <version>. The existing version of PubSub+ Cache is <oldversion>.

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