Upgrade Procedures

In this section, you'll find the procedures you need to upgrade Solace PubSub+ software event brokers to 10.0.1 or earlier supported versions.

You may upgrade any release that is in full support or technical support to any newer release that is in full support. You may upgrade to a Preview Release until such Preview Release is replaced by its Production Release. For more information, see solace.com/support.

Downgrading a software event broker is not supported.

Before you begin

If you are upgrading from version 9.0 or earlier to version 9.1 or later, certain subscriptions may cause the upgrade to fail to complete. In particular:

  • MQTT subscriptions or ACL exceptions beginning with $ or #
  • SMF subscriptions or ACL exceptions beginning with #

The reason for this is that MQTT topics beginning with $ and # are reserved and SMF topics beginning with # are reserved. Applications must not use these reserved topics—the broker started enforcing this requirement in version 9.1.

If you are upgrading brokers from version 9.5 or older that are part of a DMR network, do not add any new DMR cluster links anywhere in the network until all brokers in the network have been upgraded to version 9.6 or newer. Links that existed before the upgrade will continue to function properly.

In versions of SolOS prior to 9.12, the storage-elements were typically externalized to separate storage volumes and mounted to the container using multiple mount points. In version 9.12 and later, the storage-group is now mapped to a single mount point. For details about how to convert from storage-elements to the single storage-group, refer to Converting from Multiple Mount Points to a Single Mount Point

Upgrading Containers to Version 9.4.0 or Later

Consider the following information before upgrading your software event broker to version 9.4.0 or later.

Before the 9.4.0 release, the default user ID (UID) for containers was 0 (root). Running containers as root is not recommended according to security best practices, so the default UID has changed to 1000001 as of the 9.4.0 release. Because containers must be run as root to use privileged ports (0-1023), the default listen ports have also changed for new installations of the software event broker as of the 9.4.0 release. These changes are listed in the following table:

Port Description Old Default Port
(Versions Below 9.4.0)
New Default Port
(Versions 9.4.0 and Later)
Web Transport 80 8008
Web Transport TLS 443 1443
SEMP TLS 943 1943

The upgrade process does not change the default port assignments. If your container uses privileged listen ports (0-1023) and you are upgrading to the 9.4.0 release or later, do one of the following:

  • Before upgrading, modify the event broker configuration to use non-privileged listen ports (1024 and above). If you are using bridge networking, you can recreate the container and change the port mappings to point to the new ports. If you are using host networking, you must to modify either your applications or the external network devices they connect through, such as load balancers, to point to the new ports.
  • Although not recommended according to security best practices, you can still run the container as root and continue to use the privileged listen ports. To do this, when you create a new container using docker create, you must set the UID to 0 with the --user option and add the NET_BIND_SERVICE capability with the --cap-add option.

Because the default UID has changed, you must pay special attention to the file permissions of the storage elements. By default, only the container user has read and write access to files created by the event broker. This permission setup works as long as no other processes require read access to those files. However, many log aggregation tools require read access to the software event broker log files. To provide access to the log files, the umask configuration key should be set to give read access to other processes. The default umask is 0077. A typical umask for log files is 0022. You can find examples of setting the umask in the upgrade procedures. For additional information, see Other Environment Variables.

What's your image type?

There are different upgrade procedures depending on whether you are upgrading a Machine or Docker Image. To determine which type is running on your host, do the following:

  1. Login to the host.
  2. Enter the following command: cat /etc/solace-release.
  3. If the file exists, it's a Machine Image; otherwise it's a Docker Image.

Do you have enough free space?

You need to verify there's enough free space on all event brokers that you're going to upgrade.

The minimum system resource requirements for the software event broker have changed in version 9.7.0. Carefully review the System Resource Requirements and ensure adequate resources are available before beginning the upgrade procedure. In particular, system memory and storage requirements have increased for software event brokers configured to support 100,000 concurrent client connections.

During a Docker image upgrade, installing the new PubSub+ software event broker will not succeed if sufficient thin pool minimum free space is not available. Executing the docker info command in the Docker host will show both Space Available and Thin Pool Minimum Free Space. Refer to the Docker documentation for more information on managing available space in Docker.

To free up disk space, consider the following options:

  • Unspool some spooled messages
  • Delete some spooled messages (messages cannot be recovered once deleted)
  • Migrate to a larger message-spool

To check the amount of free space available, perform one of the following procedures:

To check free space using the CLI or SEMP:

  1. Issue the following CLI command: show storage-element *
  2. Verify that the spool storage-element reports at least 2.2 Mi in the available column.

    solace> show storage-element *
    Last Refreshed   : Dec 04 2017 21:50:15
    Storage Element    1K-blocks    Used         Available    Use% 
    ------------------ ------------ ------------ ------------ -----
    root                 6.0 Mi     939.9 Ki       5.1 Mi     15%
    spool                9.8 Mi       1.6 Mi       8.2 Mi     16%
    var                  9.8 Mi       1.6 Mi       8.2 Mi     16%
    jail                 9.8 Mi       1.6 Mi       8.2 Mi     16%
    diagnostics          9.8 Mi       1.6 Mi       8.2 Mi     16%
    adb-backup           9.8 Mi       1.6 Mi       8.2 Mi     16%
    adb                  9.8 Mi       1.6 Mi       8.2 Mi     16%

To check free space using solacectl (available in machine images only):

  1. Issue the following command: sudo solacectl storage ls. This command requires root level access. The sysadmin user has been granted sudo access for this command. All other users require root credentials to execute the command.
  2. Verify that the internalSpool storage volume reports at least 2.2G in the available column.

    [sysadmin@solace ~]# sudo solacectl storage ls
    Block Devices:
    Name                                              Size      Note
    vda                                               30.0G     Main device
    └─vda1                                            0.2G
    └─vda2                                            29.8G
    vdb                                               29.3G
    └─vdb1                                            29.3G
    Storage Volumes:
    Name                                              Size      Used      Available Path
    /dev/mapper/vg01-root                             9.8G      1.2G      8.6G      /
    /dev/mapper/vg01-solace                           9.8G      2.5G      7.4G      /var/lib/docker/volumes
    ├─adb                                             9.8G      2.0G      7.4G      /var/lib/docker/volumes/adb/_data
    ├─adbBackup                                       9.8G      0         7.4G      /var/lib/docker/volumes/adbBackup/_data
    ├─etc                                             9.8G      8.0K      7.4G      /etc/solace/solace-container.d├─internalSpool                                  9.8G      391M      7.4G      /var/lib/docker/volumes/internalSpool/_data
    └─var                                             9.8G      25M       7.4G      /var/lib/docker/volumes/var/_data
    /dev/vdb1                                         30G       45M       30G       /mnt/vmr
    ├─diagnostics                                     30G       0         30G       /mnt/vmr/diagnostics
    └─jail                                            30G       13M       30G       /mnt/vmr/jail
    Image Pool:
    Name                                              Size      Used      Available
    Image pool                                        8.905GB   1.26GB    7.645GB