Standalone Appliance

Use these procedures to upgrade a standalone appliance to SolOS-TR 10.10.0.

These upgrade procedures only apply to the latest version of the Solace PubSub+ appliance. Refer to the version-specific documentation to upgrade to versions before SolOS-TR 10.10.0.

With Guaranteed Messaging

Use this procedure to upgrade a standalone appliance, that uses guaranteed messaging, to SolOS-TR 10.10.0.

Before you begin

Perform the following steps to ensure the system is in the correct state before upgrading.

  1. Review the appliance upgrade notices.

    Before upgrading to version 10.2.0 or later, ensure there are no queue, client-profile, or acl-profile objects configured whose name begins with #telemetry-. As a general rule, no objects should be configured that start with # since Solace uses such object names for internal use.

    The following upgrade paths are not supported:

    • Direct upgrades from SolOS 9.11.0 or earlier to SolOS 10.9.1 or later.

    For unsupported upgrade paths, you must follow the upgrade procedure to the last SolOS-TR version that is part of a supported upgrade path from the source version, before following the upgrade procedure to the destination version.

    Upgrades to or from SolOS Early Availability (EA) loads are not supported. All configuration and spooled messages may be lost during the upgrade.

    Faulty or noisy serial connections can result in the appliance not booting correctly following an upgrade or restart. Ensure either serial connections are fully functional, or disconnect all serial cables from the Solace appliance prior to upgrading.

    Solace recommends upgrading SolAdmin and SolGeneos to the most recent versions before upgrading the appliance to a new major or minor version.

    On upgrade, some appliances that have ADB version ADB-04210M-01 will require additional message-spool disk space to support the higher scaling capabilities of this software release. This additional disk space persists and will reduce the amount of disk space available for spooling messages.

    3560 appliances with ADB version ADB-04210M-01 will have 10 GB of additional space consumed on each disk partition (primary and backup).

    In mixed release replication configurations between this SolOS version and older SolOS versions, config-sync may not work correctly. Running mixed release replication configurations with older SolOS versions is not recommended for extended periods of time. Once the releases are the same, the config-sync issues will clear, so upgrading both replications to the same version should be done as soon as possible. For additional information, contact Solace.

    Upgrades that require changing the underlying version of SolBase will not preserve files in the root partition of the appliance’s internal file system.

    Configuration changes should not be made while performing any in-service upgrade. This includes avoiding the use of administrative config-sync commands.

    Before upgrading standalone appliances that use the Replication feature, follow the Performing a Controlled Failover procedure to fail over to Message VPNs at the alternate replication site.

    If the message-spool is enabled as backup but no mate-router-name is configured, the event broker will fail to boot following the upgrade. Prior to upgrading, ensure that either a mate-router-name is configured or the message-spool is not enabled as backup.

    The screen output examples shown in this section reflect the software release to which you are upgrading. In the steps that occur before the upgrade, the screen outputs may be formatted differently, or contain slightly different information, depending on the software release from which you are upgrading.

    Before upgrading to version 10.9.1 or later, remove any LAG interface that was erroneously configured without a mode of lacp or active-backup. Such interfaces were always non-functional, however, if they are not removed the event broker will fail to boot following the upgrade.

  2. Ensure that the internal disks are in a redundant state.

    solace-primary> show disk
Reload required:               No

Attribute                                 Disk 1                        Disk 2
------------------ ----------------------------- -----------------------------
Device Model                         ST3250820NS                   ST3250820NS
Capacity (MB)                             238475                        238475
Admin State                              enabled                       enabled
Operational State                             up                            up

RAID in fully redundant state: Yes

    If the displayed output shows the RAID disk 1 and disk 2 drives to be in a non-redundant state (see example below), contact Solace and stop this software upgrade procedure immediately to prevent software corruption on the appliance.

    Some appliances contain slots for disk 3 and disk 4, however, these slots are not presently used, and the redundancy state for disk 3 and disk 4 should be ignored.

    solace-primary> show disk 
Reload required:               No

Attribute                                 Disk 1                        Disk 2
------------------ ----------------------------- -----------------------------
Device Model                         ST3250820NS                   ST3250820NS
Capacity (MB)                             238475                        238475
Admin State                              enabled                       enabled
Operational State                         failed                            up

RAID in fully redundant state: No

  3. Ensure that a redundancy interface is configured on the appliance:

    solace-primary> show redundancy

...

Interface        Primary Address Status Backup Address  Status
---------------- --------------- ------ --------------- ------
1/1/lag1         192.168.160.132 Up                      

                               Primary Virtual Router  Backup Virtual Router
                               ----------------------  ----------------------
Activity Status                Local Active            Shutdown
VRRP VRID                                              
Redundancy Interface Status                            
VRRP Status                                            
  1/1/lag1                                             
VRRP Priority                                          
Message Spool Status                                   
Priority Reported By Mate

    If no interface is configured, run the following commands to set one up:

    solace-primary> enable
solace-primary# config
solace-primary(configure)# redundancy
solace-primary(configure/redundancy)# vrrp
solace-primary(configure/redundancy/vrrp)# interface <phy-interface>
solace-primary(configure/redundancy/vrrp)# exit						
solace-primary(configure/redundancy)# exit
solace-primary(configure)# exit

    Where:

    <phy-interface> is an ASCII string specifying the Ethernet interface port or LAG to be assigned. Valid values are eth<port> (for example, eth1); <cartridge>/<slot>/<port> (for example, 1/1/8); <cartridge>/<slot>/lag<N> (for example, 1/1/lag1). There is no default value.

  4. Copy the latest SolOS software from an external file server (using either SFTP or SCP) to the /loads subdirectory on the appliance.

    solace-primary# copy sftp://[<username>@]<ip-addr>/<remote-pathname> /loads
solace-primary# copy scp://[<username>@]<ip-addr>/<remote-pathname> /loads

    Where:

    <username>, <ip-addr>, and <remote-pathname> correspond to the access information of where the new SolOS software is located.

  5. Copy the correct SolBase software for the latest SolOS version (the correct SolBase software is packaged with each SolOS version) from an external file server (using either SFTP or SCP) to the /loads subdirectory on the appliance.

    solace-primary# copy sftp://[<username>@]<ip-addr>/<remote-pathname> /loads
solace-primary# copy scp://[<username>@]<ip-addr>/<remote-pathname> /loads

    Where:

    <username>, <ip-addr>, and <remote-pathname> correspond to the access information of where the new SolBase software is located.

Before upgrading the appliance, SolAdmin may also need to be upgraded. In addition, after the upgrade, SolGeneos Agent may also need to be upgraded. See Appliance Upgrade Notices for more information.

Procedure

  1. Follow all the steps in Before you begin. Don't proceed if you can't confirm that the system is in the correct state.

  2. Make a copy of the current SolOS configuration in the /configs subdirectory:

    solace-primary> enable
solace-primary# copy current-config /configs/<old_version>_preUpgradeCfg

    Where:

    <old_version> is the version number of current SolOS software as seen in the output of the show version command.

  3. If multi-node routing is enabled, shut it down:

    solace-primary# configure
solace-primary(configure)# routing
solace-primary(configure/routing)# multi-node-routing
solace-primary(configure/routing/multi-node-routing)# shutdown
solace-primary(configure/routing/multi-node-routing)# end

  4. Shut down the Msg-Backbone service:

    solace-primary# configure
solace-primary(configure)# service msg-backbone
solace-primary(configure/service/msg-backbone)# shutdown
All SMF, WEB, and REST clients will be disconnected.
Do you want to continue (y/n)? y
solace-primary(configure/service/msg-backbone)# end

  5. If the Solace appliance is using transacted sessions, wait until all transacted sessions time out and the count drops to 0:

    solace-primary# show message-spool detail

                           Currently Used   Max Allowed
                           --------------   -----------
Transacted Sessions:                    0         16000

    This will take up to 3 minutes.

  6. Shut down the message spool:

    solace-primary# configure
solace-primary(configure)# hardware message-spool
solace-primary(configure/hardware/message-spool)# shutdown
All message spooling will be stopped.
Do you want to continue (y/n)? y
solace-primary(configure/hardware/message-spool)# end

    If you are using MQTT retained messages in your deployment, the next step clears the contents of each retain cache. If this content is stored somewhere else in the network, for example another DMR or MNR node, the content will be retrieved when this node comes back online.

  7. Upgrade the appliance:

    solace-primary# boot <new-version>

  8. Respond to prompts and then wait for the appliance to restart using the new SolOS software. This may take several minutes. You will be disconnected from the CLI and have to reconnect to the appliance. The appliance restarts, using the new SolOS software.

  9. Once reconnected, confirm that the appliance has started using the new software version:

    solace-primary> enable
solace-primary# show version

  10. Start the message spool that was shut down:

    solace-primary# configure
solace-primary(configure)# hardware message-spool
solace-primary(configure/hardware/message-spool)# no shutdown primary
solace-primary(configure/hardware/message-spool)# end

  11. Start the Msg-Backbone service that was shut down:

    solace-primary# configure
solace-primary(configure)# service msg-backbone
solace-primary(configure/service/msg-backbone)# no shutdown
solace-primary(configure/service/msg-backbone)# end

  12. If routing or multi-node routing was shut down in step 3, start multi-node routing:

    solace-primary# configure
solace-primary(configure)# routing
solace-primary(configure/routing)# multi-node-routing
solace-primary(configure/routing/multi-node-routing)# no shutdown
solace-primary(configure/routing/multi-node-routing)# end

You have completed this procedure.

Without Guaranteed Messaging

Use this procedure to upgrade a standalone appliance, that doesn't use guaranteed messaging, to SolOS-TR 10.10.0.

Before you begin

Perform the following steps to ensure the system is in the correct state before upgrading:

  1. Review the appliance upgrade notices.

    Before upgrading to version 10.2.0 or later, ensure there are no queue, client-profile, or acl-profile objects configured whose name begins with #telemetry-. As a general rule, no objects should be configured that start with # since Solace uses such object names for internal use.

    The following upgrade paths are not supported:

    • Direct upgrades from SolOS 9.11.0 or earlier to SolOS 10.9.1 or later.

    For unsupported upgrade paths, you must follow the upgrade procedure to the last SolOS-TR version that is part of a supported upgrade path from the source version, before following the upgrade procedure to the destination version.

    Upgrades to or from SolOS Early Availability (EA) loads are not supported. All configuration and spooled messages may be lost during the upgrade.

    Faulty or noisy serial connections can result in the appliance not booting correctly following an upgrade or restart. Ensure either serial connections are fully functional, or disconnect all serial cables from the Solace appliance prior to upgrading.

    Solace recommends upgrading SolAdmin and SolGeneos to the most recent versions before upgrading the appliance to a new major or minor version.

    On upgrade, some appliances that have ADB version ADB-04210M-01 will require additional message-spool disk space to support the higher scaling capabilities of this software release. This additional disk space persists and will reduce the amount of disk space available for spooling messages.

    3560 appliances with ADB version ADB-04210M-01 will have 10 GB of additional space consumed on each disk partition (primary and backup).

    In mixed release replication configurations between this SolOS version and older SolOS versions, config-sync may not work correctly. Running mixed release replication configurations with older SolOS versions is not recommended for extended periods of time. Once the releases are the same, the config-sync issues will clear, so upgrading both replications to the same version should be done as soon as possible. For additional information, contact Solace.

    Upgrades that require changing the underlying version of SolBase will not preserve files in the root partition of the appliance’s internal file system.

    Configuration changes should not be made while performing any in-service upgrade. This includes avoiding the use of administrative config-sync commands.

    Before upgrading standalone appliances that use the Replication feature, follow the Performing a Controlled Failover procedure to fail over to Message VPNs at the alternate replication site.

    If the message-spool is enabled as backup but no mate-router-name is configured, the event broker will fail to boot following the upgrade. Prior to upgrading, ensure that either a mate-router-name is configured or the message-spool is not enabled as backup.

    The screen output examples shown in this section reflect the software release to which you are upgrading. In the steps that occur before the upgrade, the screen outputs may be formatted differently, or contain slightly different information, depending on the software release from which you are upgrading.

    Before upgrading to version 10.9.1 or later, remove any LAG interface that was erroneously configured without a mode of lacp or active-backup. Such interfaces were always non-functional, however, if they are not removed the event broker will fail to boot following the upgrade.

  2. Ensure that the internal disks are in a redundant state:

    solace-primary> show disk 
Reload required:               No

Attribute                                 Disk 1                        Disk 2
------------------ ----------------------------- -----------------------------
Device Model                         ST3250820NS                   ST3250820NS
Capacity (MB)                             238475                        238475
Admin State                              enabled                       enabled
Operational State                             up                            up

RAID in fully redundant state: Yes

    If the displayed output shows the RAID disk 1 and disk 2 drives to be in a non-redundant state (see example below), contact Solace and stop this software upgrade procedure immediately to prevent software corruption on the appliance.

    Some appliances contain slots for disk 3 and disk 4, however, these slots are not presently used, and the redundancy state for disk 3 and disk 4 should be ignored.

    solace-primary> show disk 
Reload required:               No

Attribute                                 Disk 1                        Disk 2
------------------ ----------------------------- -----------------------------
Device Model                         ST3250820NS                   ST3250820NS
Capacity (MB)                             238475                        238475
Admin State                              enabled                       enabled
Operational State                         failed                            up

RAID in fully redundant state: No

  3. Copy the latest SolOS software from an external file server (using either SFTP or SCP) to the /loads subdirectory on the appliance:

    solace-primary# copy sftp://[<username>@]<ip-addr>/<remote-pathname> /loads
solace-primary# copy scp://[<username>@]<ip-addr>/<remote-pathname> /loads

    Where:

    <username>, <ip-addr>, and <remote-pathname> correspond to the access information of where the new SolOS software is located.

  4. Copy correct SolBase software for the latest SolOS version (the correct SolBase software is packaged with each SolOS version) from an external file server (using either SFTP or SCP) to the /loads subdirectory on the appliance:

    solace-primary# copy sftp://[<username>@]<ip-addr>/<remote-pathname> /loads
solace-primary# copy scp://[<username>@]<ip-addr>/<remote-pathname> /loads

    Where:

    <username>, <ip-addr>, and <remote-pathname> correspond to the access information of where the new SolBase software is located.

Before upgrading the appliance, SolAdmin and SolGeneos Agent may also need to be upgraded. See Appliance Upgrade Notices for more information.

Procedure

  1. Follow all the steps in Before you begin. Don't proceed if you can't confirm that the system is in the correct state.

  2. Make a copy of the current SolOS configuration in the /configs subdirectory:

    solace-primary> enable
solace-primary# copy current-config /configs/<old_version>_preUpgradeCfg

    Where:

    <old_version> is the version number of current SolOS software as seen in the output of the show version command.

  3. Shut down the Msg-Backbone service:

    solace-primary# configure
solace-primary(configure)# service msg-backbone
solace-primary(configure/service/msg-backbone)# shutdown
All SMF, WEB, and REST clients will be disconnected.
Do you want to continue (y/n)? y
solace-primary(configure/service/msg-backbone)# end

    If you are using MQTT retained messages in your deployment, the next step clears the contents of each retain cache. If this content is stored somewhere else in the network, for example another DMR or MNR node, the content will be retrieved when this node comes back online.

  4. Upgrade the appliance:

    solace-primary# boot <new-version>

  5. Respond to prompts and then wait for the appliance to restart using the new SolOS software. This may take several minutes. You will be disconnected from the CLI and have to reconnect to the appliance. The appliance restarts, using the new SolOS software.

  6. Once reconnected, confirm that the appliance has started using the new software version:

    solace-primary> enable
solace-primary# show version

  7. Start the Msg-Backbone service that was shut down:

    solace-primary# configure
solace-primary(configure)# service msg-backbone
solace-primary(configure/service/msg-backbone)# no shutdown
solace-primary(configure/service/msg-backbone)# end

You have completed this procedure.