Upgrade Procedures

In this section, you'll find procedures needed for upgrading Solace PubSub+ software event brokers to 9.7.0 or earlier supported versions.

:  Downgrading a software event broker using these procedures 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 until all brokers in the network have been upgraded to version 9.6 or newer.

Considerations when Upgrading to 9.4.0+

You should 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 Docker image containers was 0 (root). Running containers as root is not recommended according to security best practices, so starting with the 9.4.0 release, the default UID is 1000001.
  • As containers must be run as root to use privileged ports (0-1023), the default listen ports in the 9.4.0 release have changed as follows:

    Port Description Old Default Port for versions below 9.4.0 New Default Port for 9.4.0+
    Web Transport 80

    8008

    Web Transport TLS 443

    1443

    SEMP TLS 943 1943
  • If you are upgrading a Docker image (this does not apply to the Machine image ) to the 9.4.0 release that uses privileged listen ports (0-1023), the following options are available:

    • Before upgrading, you can 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 using host networking, you will need 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, it is still possible to run the container as root and continue to use the privileged listen ports. To do this, when creating a new container with 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.

  • As 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 would be 0022. You can find examples of setting the umask in the upgrade procedures. For additional information, refer to 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.

Upgrades crossing versions 8.6.0 and 8.7.0 (that is, from version 8.6.0 or older, and to version 8.7.0 or newer) require at least 2.2GB of free message-spool space. In this upgrade path, the upgrade will not be blocked from proceeding if there is not enough space available.

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