This section describes the upgrade strategies for major, minor and service pack upgrades:

It is recommended you test your upgrade strategy in at least one environment prior to applying it to your production engine.

Choosing an Upgrade Strategy

The Rhapsody installer, when run against the currently installed engine, is generally able to perform an upgrade quickly and automatically. As part of this process, the datastore is permanently modified. In Rhapsody terminology, the datastore refers to the data directory within the Rhapsody directory structure which contains all configuration, administrative information and message directories.

If there is a failure during the upgrade, the installer cannot revert any already modified directories. Therefore the risk of upgrade failure must always be taken into consideration before performing an upgrade. Risk is mitigated by performing backups of the datastore before the upgrade. If there is a failure, then a rollback can be performed using the backup.

Therefore, an upgrade strategy must be chosen, which is determined primarily by the type of backup that is performed. The type of backup is determined by factors such as:

  • The environment type, typically production or non-production (test or development).
  • The importance placed on keeping archived messages upon failure.
  • The size of the datastore. The datastore contains all configuration, administration and message data for the engine. Configuration and administrative data is a small and quick backup. However, message data might be hundreds of gigabytes in size. 
  • Allowable downtime for an upgrade. The larger the amount which is required to be backed up, the longer the downtime will be.

Rhapsody recommends two types of backups for upgrade rollbacks, either copying the entire datastore, or performing a smaller partial copy:

You can also upgrade without creating a copy of the datastore.

Rhapsody as an organization strongly advises against RLC backups and Message Store backups for upgrade rollbacks.

Types of Backups

  • Rhapsody must always be stopped before making a copy of the datastore. Not doing so would likely result in an inconsistent and damaged copy because Rhapsody frequently writes to multiple parts of the datastore, while a 'copy' operation is performed sequentially. 
  • The destination of the copy should be considered. Copying across a network to a different location may be slow.

Creating a Full Copy of the Datastore

The recommended form of backup for any Production engine, after stopping the Rhapsody engine, is to make a copy of the entire Rhapsody datastore. This backup contains all configuration, administrative and message data. 

Advantages

If a failure takes place, full functionality can be restored by simply installing the same version of the original engine, with the same memory settings, and pointing it to the copy of the datastore.

Disadvantages

The message-related directories within the Rhapsody datastore can be quite large, up to multiple hundreds of gigabytes or more. Performing a copy operation requires an equivalent amount of space to be available, and could take a while to complete - this adds to the downtime of the engine. The on-site infrastructure team should be consulted.

In order to get size and time estimates:

  • Check the size of datastore. To find the location of the datastore, refer to the InitialisationService.dataDirectory property in the rhapsody.properties file.
  • Calculate an estimate of the time to create the copy by:
    • Performing a copy of the datastore from a non-production Rhapsody engine. This is usually much smaller than production, but the overall time can be extrapolated. For example, if a non-production engine has a 10GB datastore which takes 5 minutes to copy, then a production engine with a 100GB datastore may take 25 minutes to copy.
    • Discussing this with your on-site infrastructure team.

Creating a Partial Copy of the Datastore

Rhapsody can still be started in a fully functional state without the message-related data (no in-flight or archived messages). This can be achieved by making a copy of all non-message-related sub-directories within the datastore. 

This is the recommended form of backup for any Production engine if the message-related data is considered too large to copy, or the loss of the message archive is acceptable. Any live messages within Rhapsody (traversing routes, or on any route or communication point queues) would also be lost, but these messages should be drained out of Rhapsody beforehand.

The message archive is only a rolling window of old messages and is normally only used for troubleshooting purposes. Therefore, it is often considered to be an acceptable loss.

Advantages

The non-message directories are often relatively small, and so copying these directories does not cost much in terms of space or time.

Disadvantages

Archived and live messages will be lost. The engine must be thoroughly cleared of in-flight messages before performing the backup. The time to perform this activity should be weighed against the time it may take to make a copy of the entire datastore. An alternative is to have a plan in place to be able to identify how to find and re-send messages which were in-flight when the Rhapsody engine was stopped.

Rhapsody Properties File

The rhapsody.properties file is only modified in the following ways by the upgrade process: 

  • The user has the option of updating port details during the upgrade process. If these values are updated, the corresponding values in the file are also updated.
  • New properties are appended to the end of the original file.

Thus, the placement of various properties in an upgraded rhapsody.properties file may differ substantially from a rhapsody.properties file in a fresh installation. However, the files are functionally the same.

Wrapper Files

The wrapper files are overwritten on upgrade (only the wrapper-local.conf file is backed up to wrapper-local.conf.old). Therefore, back up any wrapper files you have modified before upgrading, and manually copy the changes to the new wrapper files after the upgrade.

log4j Properties File

The log4j.properties file is overwritten on upgrade. Therefore, back up the log4j.properties file before upgrading, and manually copy any changes to the new log4j.properties file after the upgrade.

Java Security File

The java.security file is overwritten on upgrade. Therefore, back up the file before upgrading, in case you need to refer to it after the upgrade. Refer to Enabling Disabled Cipher Suites for details.