Replacing Solace PubSub+ Appliances

This section shows the steps required to replace operating Solace PubSub+ appliances with newer ones. Instructions are provided for standalone appliances and those operating in High Availability (HA) redundant pairs.

These procedures apply only for like-for-like replacements. If you are replacing different chassis models or NAB/ADB types, contact Solace because there could be scaling differences and a custom procedure may be required.

Replacing Standalone Appliances

This procedure shows you how to replace a single standalone appliance.

Before you begin

The procedure shown in the Steps section assumes that:

The appliance doesn't belong to a redundant HA pair.
Neither Replication nor Guaranteed VPN Bridges nor both are configured.
If these features are in use, you'll need to consult one of the following prior to performing the instructions in the Steps section:
- If only Replication is configured: refer to Additional steps when Replication is configured.
- If only Guaranteed VPN Bridges are configured: refer to Additional steps when Guaranteed VPN Bridges are configured.
- When Replication and Guaranteed VPN Bridges are both configured: refer to Additional steps when both Replication and Guaranteed VPN Bridges are configured.
If the appliance has an ADB installed, you have access from the appliance to an external file server capable of temporarily holding the configuration database and the contents of its ADB.
If the appliance contains an HBA, you must register the new appliance's HBA with the external array. For details, refer to Configuring an External Disk Array for Guaranteed Messaging.

The procedure doesn't affect the external disk-array used for message spooling as the disk-array is reused with the new hardware.

Steps

Prepare the old appliance.

Shutdown the message-backbone to ensure the event broker is not providing any services.

Enter the following commands in the Solace CLI:

solace(configure)# service
solace(configure/service)# msg-backbone
solace(configure/service/msg-backbone)# shutdown
All clients will be disconnected.
Do you want to continue (y/n)? y

If the appliance uses an ADB, its contents must be backed up it can be restored later on the new hardware.

Enter the following commands:

solace(configure)# hardware message-spool
solace(configure/hardware/message-spool)# shutdown
All message spooling will be stopped.
Do you want to continue (y/n)? y
solace(configure/hardware/message-spool)# end
solace# admin
solace(admin)# system message-spool
solace(admin/system/message-spool)# backup-adb-to-disk
On the next system startup, the backed-up ADB state on disk will overwrite the current ADB state.
Do you want to continue (y/n)? y

This creates a directory /usr/sw/adb, which needs to be moved to an external file server.

To move the directory, enter the following commands:

solace# shell "Backup adb to external file server"
login: support
Password: <password>
[support@solace ~]$ sudo su -
[sudo] password for root: <password>
[root@solace ~]# cd /usr/sw
[root@solace sw]# tar zcf /tmp/adb.<hostname>.tar.gz adb
[root@solace sw]# scp /tmp/adb.<hostname>.tar.gz <username>@<hostname>:/<path-to-remote-dir>
[root@solace sw]# exit
logout
[support@solace ~]$ exit
logout

Backup the current configuration database to an external file server.
Example:
```
copy current-config sftp://<username>@<hostname>/<path-to-remote-dir>/config_<date>.tar.gz
```
For information on how to back up a current configuration to a remote destination, refer to Backing Up and Restoring Event Broker Configurations. Pay particular attention to the need to capture product-keys and certificate files, which are not automatically included in the backup.
If the event broker hosts Solace Geneos Agent, its Solace Geneos Agent properties file (solgeneos/config/solgeneosagent.properties) must be copied to an external file server.

Swap the appliances.
1. Power-down the old appliance.
  Enter the following commands:
```
solace# power-down
                This command powers off the appliance and does not restart it afterwards
                Do you want to continue (y/n)? y
```
2. Label all cables and disconnect them from the appliance.
3. Remove the appliance from the rack and replace it with the new one. For information on how to physically install appliances, refer to the help for the type of appliance being removed (refer to Prerequisites & Installation).
4. Reconnect all cables to the new appliance.
5. Power up the new appliance, and through the management console, use the setup Config command to perform basic network parameters (refer to Initial Setup).
6. If the appliance has an HBA installed, register the HBA with the external array (refer to Configuring an External Disk Array for Guaranteed Messaging), then use the reload command to restart it.
Prepare the new appliance.
1. Get the new appliance to run the same Solace PubSub+ version the old appliance ran. This may involve either an upgrade or a downgrade depending on what is shipped on the new hardware.
  - The tasks associated with upgrading the Solace PubSub+ software on an appliance are described in Upgrade Procedures.
  - For information on downgrading appliance versions, refer to Downgrading Versions.
2. Restore the old appliance's configuration database from the external file server to the new appliance.
  Example:
```
<username>@192.168.2.xx's password: <password>
solace# copy scp://<username>@<host>/<path-to-remote-dir>/config_<date>.tar.gz
solace# reload config config_<date>.tar.gz
This command causes a reload of the system
Do you want to continue (y/n)? y
```
  Restoring a configuration from a remote destination is discussed in Backing Up and Restoring Event Broker Configurations. Pay particular attention to the need to restore product-keys and certificate files, which are not automatically included in the backup.
3. If the appliance hosts Solace Geneos Agent, install Solace Geneos Agent and restore its properties file from the external file server. For information about installing and configuring Solace Geneos Agent, refer to Solace Geneos Agent.
4. If the appliance has an ADB installed, its contents needs to be restored. Enter the following commands:
```
solace# shell "Restore adb from external file server"
login: support
Password: <password>
[support@solace ~]$ sudo su -
[sudo] password for root: <password
[root@solace ~]# cd /usr/sw
[root@solace sw]# tar xvfz /tmp/adb.<hostname>.tar.gz 
[root@solace sw]# scp <username>@<hostname>:/<path-to-remote-dir>/adb-<hostname>.tar.gz /tmp
[root@solace sw]# exit
logout
[support@solace ~]$ exit
logout
```
  For the ADB contents to take effect, the appliance must be reloaded.
  Enter the following commands:
```
solace# reload
This command causes a reload of the system
Do you want to continue (y/n)? y
```
  After the appliance restarts, log back in and enable message spooling:
```
solace(configure)# hardware message-spool
solace(configure/hardware/message-spool)# no shutdown primary
```
5. Re-enable message-backbone service:
```
solace(configure)# service
solace(configure/service)# msg-backbone
solace(configure/service/msg-backbone)# no shutdown
```

Additional steps when Replication is configured

If Replication is configured, you must perform the following steps:

Shutdown Message VPN Replication on both sites.
Shutdown Config-Sync on both sites.
Perform the procedure shown in Steps.
Re-enable Config-Sync on both sites.
Re-enable Message VPN Replication on both.

Additional steps when Guaranteed VPN Bridges are configured

If Guaranteed VPN Bridges are configured, you must perform the following steps:

Identify the other appliances that connect to the appliance that is to be replaced.
On each of those connected appliances reconfigure the remote Message VPN by removing the bridge queue.
Perform the Steps on the appliance to be replaced.
On each of the connected appliances add back the bridge queues.

Additional steps when both Replication and Guaranteed VPN Bridges are configured

On both sites involved in the Replication configuration perform the following:
- Shutdown Message VPN Replication on both sites.
- Shutdown Config-Sync on both sites.
Identify the other appliances that connect via Guaranteed VPN Bridges to the appliance that is to be replaced.
- On each of those connected appliances reconfigure the remote Message VPN by removing the bridge queue.
Perform the procedure shown in Steps on the appliance to be replaced.
On both sites involved in the Replication configuration perform the following:
- Re-enable Config-Sync on both sites.
- Re-enable Message VPN Replication on both.
On each of the other appliances connected via Guaranteed VPN Bridges add back the bridge queues.

Replacing Both Appliances in an HA Pair

This procedure covers how to replace both appliances in an HA redundant pair. To perform this procedure, you must have access from the appliances to an external file server capable of temporarily holding the appliances' configuration databases and the contents of their ADBs (if installed). This procedure does not affect the external disk array used for message spooling—the disk-array is reused with the new hardware.

Be aware that if the appliances contain HBAs, you must register the new appliances' HBAs with the external array. For details, refer to Configuring an External Disk Array for Guaranteed Messaging.

Certain steps are to be applied to one appliance or to both appliances in the pair.

Prepare the old appliances:
1. Verify Config-Sync is operationally "up" (that is, the appliances are in-sync). Use the following Solace CLI command to verify this on both event brokers:
```
solace1# show config-sync
Admin Status                      : Enabled
Oper Status                       : Up
```
  If the operational status is other than "Up" then this should be corrected before proceeding. Using ConfigSync to keep event broker configuration synchronized is fully described in Config-Sync.
2. Shutdown the message backbone to ensure that the appliances do not provide any services. Enter the following commands for both event brokers:
```
solace1(configure)# service
solace1(configure/service)# msg-backbone
solace1(configure/service/msg-backbone)# shutdown
All clients will be disconnected.
Do you want to continue (y/n)? y
```
3. Force the primary event broker to have activity. Enter the following commands in the CLI of the backup appliance:
```
solace2(configure)# redundancy
solace2(configure/redundancy)# release-activity
```
4. If the appliances use ADBs, their contents must be backed up so they can be restored later on the new hardware.
  Enter the following commands in the CLI of both appliances:
```
solace1(configure)# hardware message-spool
solace1(configure/hardware/message-spool)# shutdown
All message spooling will be stopped.
Do you want to continue (y/n)? y
```
  Then enter the following commands only in the CLI of the primary appliance:
```
solace1(configure/hardware/message-spool)# end
solace1# admin
solace1(admin)# system message-spool
solace1(admin/system/message-spool)# backup-adb-to-disk
On the next system startup, the backed-up ADB state on disk will overwrite the current ADB state.
Do you want to continue (y/n)? y
```
  This creates a directory /usr/sw/adb, which needs to be moved to an external file server.
  To move the directory, enter the following commands in a support shell on the primary appliance:
```
solace1# shell "Backup adb to external file server"
login: support
Password: <password>
[support@solace ~]$ sudo su -
[sudo] password for root: <password>
[root@solace ~]# cd /usr/sw
[root@solace sw]# tar zcf /tmp/adb.<hostname>.tar.gz adb
[root@solace sw]# scp /tmp/adb.<hostname>.tar.gz <username>@<hostname>/<path-to-remote-dir>
[root@solace sw]# exit
logout
[support@solace ~]$ exit
logout
```
1. Backup the current configuration database of both appliances to an external file server.
  Example:
```
solace1# copy current-config sftp://<username>@<hostname>/<path-to-remote-dir>/config_<date>.tar.gz
```
  For information on how to back up a current configuration to a remote destination, refer to Backing Up and Restoring Event Broker Configurations. Pay particular attention to the need to capture product-keys and certificate files, which are not automatically included in the backup.
1. If the event broker hosts Solace Geneos, its Solace Geneos properties file (solgeneos/config/solgeneosagent.properties) must be copied to an external file server.
Swap out the old appliances.
1. Power-down the old appliances.
  Enter the following commands in the CLI of both appliances:
```
solace1# power-down
This command powers off the appliance and does not restart it afterwards
Do you want to continue (y/n)? y
```
2. Label all cables and disconnect them from the appliances.
3. Remove the old appliances from the rack and replace them with the new ones.
4. Reconnect all cables to the new appliances.
5. Power up the new appliances, and through the management console, use the setup Config command to perform basic network initialization (refer to Initial Setup).
6. If the appliances have HBAs installed, register the HBAs with the external array (refer to Configuring an External Disk Array for Guaranteed Messaging), then use the reload command to restart them.
Prepare the new appliances.
1. Get the new appliance to run the same Solace PubSub+ version the old appliance ran. This may involve either an upgrade or a downgrade depending on what is shipped on the new hardware.
  - The tasks associated with upgrading the Solace PubSub+ software on an appliance are described in Upgrade Procedures.
  - For information on downgrading appliance versions, refer to Downgrading Versions.
2. Restore the old appliances' configuration databases from the external file server.
```
<username>@192.168.2.xx's password: <password>
solace# copy scp://<username>@<hostname>/<path-to-remote-directory>/config_<date>.tar.gz
solace# reload config config_<date>.tar.gz
This command causes a reload of the system
Do you want to continue (y/n)? y
```
  - Restoring a configuration from a remote destination is discussed in Backing Up and Restoring Event Broker Configurations. Pay particular attention to the need to restore product-keys and certificate files, which are not automatically included in the backup.
  - If replay logs are included in the configuration and the appliances are set up in the active-active redundancy model, you must do a second restart of the backup appliance after reloading its configuration. Set the active-standby redundancy role of the backup appliance to backup prior to the restart. After the restart, set the active-standby role back to none.
3. If the appliance hosts Solace Geneos Agent, install Solace Geneos Agent and restore its properties file from the external file server. For information about installing and configuring Solace Geneos Agent, refer to Solace Geneos Agent.
4. If the appliances use ADBs, theirs contents need to be restored. Enter the following commands in the CLI of the primary appliance:
```
solace1# shell "Restore adb from external file server"
login: support
Password: <password>
[support@solace ~]$ sudo su -
[sudo] password for root: <password>
[root@solace ~]# cd /usr/sw
[root@solace sw]# tar xvfz /tmp/adb.<hostname>.tar.gz
[root@solace sw]# scp <username>@<hostname>:/<path-to-remote-dir>/adb-<hostname>.tar.gz /tmp
[root@solace sw]# exit
logout
[support@solace ~]$ exit
logout
```
  For the ADB contents to take effect, the primary appliance must be reloaded. Enter the following commands:
```
solace1# reload
This command causes a reload of the system
Do you want to continue (y/n)? y
```
  Log back into the primary appliance and enable message spooling:
```
solace1(configure)# hardware message-spool
solace1(configure/hardware/message-spool)# no shutdown primary
```
  Then, on the backup appliance, enter the following CLI commands:
```
solace2(configure)# hardware message-spool
solace2(configure/hardware/message-spool)# no shutdown backup
```
5. Re-enable message-backbone service. Enter the following commands in the CLI of both appliances:
```
solace1(configure)# service
solace1(configure/service)# msg-backbone
solace1(configure/service/msg-backbone)# no shutdown
```
Verify Config-Sync is operationally "up" (that is, the event brokers are in-sync).
Enter the following commands in the CLI of both appliances:
```
dev2-22# show config-sync
Admin Status                      : Enabled
Oper Status                       : Up
```
If the operational status is other than "Up", then this should be corrected before proceeding. For information on how to use Config-Sync to keep event broker configurations synchronized, refer to Config-Sync.

Provide feedback