Preparing for Expedited Upgrade

Expedited Upgrade Workflow
The following preparation tasks apply to both the manual upgrade procedure and the automated upgrade procedure unless explicitly stated in the description.
This does NOT apply to users who are planning to upgrade from Gateway version 10.x to 10.y (e.g., from version 10.0 to 10.1) - if this applies to your upgrade scenario, see the Standard Upgrade Procedure.
An accompanying   note indicates that the task has been fully or partially automated.
Ensure the Source Gateway is at Version 9.4
This is only required if you are using the
Automated Expedited Procedure
To use the Automated Expedited Procedure, ensure that your source Gateway is at version 9.4. Additionally, the OTK and MAG must be at versions compatible with Gateway 9.4. If you are at an earlier 9.x version (e.g., 9.3), you must upgrade your Gateway to 9.4.
HSM-Only Preparation Tasks
The following tasks are unique to Gateway users who have an HSM configuration (either Luna SA or nShield HSM):
  • Prepare a Pre-Production Environment
  • Install Correct Version of HSM Client Software as Required
  • Back Up Private Keys for the nShield HSM
Prepare a Pre-Production Environment
Broadcom Layer 7 strongly recommends that HSM users, whether they're using a Luna SA or nShield product, set up a pre-production or staging environment to test the expedited upgrade process on their Gateway-HSM configuration. If setting up such an environment for this purpose is not possible, HSM users are advised to use the standard upgrade process instead.
HSM users should contact their HSM vendor if they require assistance for any HSM hardware upgrades prior to upgrading their Gateway.
Install Correct Version of HSM Client Software As Required
Prior to performing the expedited upgrade for the Gateway, HSM users must ensure that the correct version of their HSM client software has been installed as specified in the Requirements and Compatibility page. To learn more about client software installations and updates, see one of the following pages:
Back Up Private Keys for the nShield HSM
Applies to nShield HSM users only.
Back Up Private Keys for nShield Solo
Applies only to hardware appliances using nShield Solo.
First, disable HSM, then back up the private keys.
Disable HSM
Disable HSM on the source Gateway:
  1. Access the Gateway Main Menu (Appliance) and select option 6 (Manage HSM).
  2. Select option 1 (Manage Gateway nCipher HSM status).
  3. Select option 2 (Disable Gateway use of the nCipher HSM).
Disabling HSM sets the master passphrase back to the default
. When you re-enable HSM on the target Gateway, HSM generates a new random master passphrase. The database password and the cluster passphrase are automatically re-encrypted with the new master passphrase.
Back up Encrypted Private Keys
To back up the keys, license, and other files, back up the following directory:
The upgrade procedure does not migrate these private keys. After the update is completed, manually copy these directories and files to the new Gateway 10.x installation. Be sure to delete these backups after you have verified the copy was successful.
Also, be sure to preserve key permissions and ownership by executing the following:
tar -cvp -f file.tar
Back Up Private Keys for nShield Connect/Connect XC
Prior to backing up private keys, ensure that they are all committed or synched to the RFS server.
  1. On the Gateway client, execute the following commands
    /opt/nfast/bin/rfs-sync --update /opt/nfast/bin/rfs-sync --commit
  2. Disable Gateway's use of the HSM via the Gateway Main Menu (Appliance).
    When backing up the Gateway database as described in Manual Expedited Appliance Upgrade, a separate back up of files contained in /opt/nfast/kmdata is not required as this is synched to the RFS server.
Install the New Gateway
Set up a new Gateway and new database with the latest version. This is the destination (target) Gateway for the upgrade.  For more information about how to set up a new virtual appliance see Gateway Configuration Menu (Appliance).
Create a new Cluster for the Destination Gateway
Applies to clusters.
Checklist for Clusters:
  • The cluster.hostname must be kept the same.
  • The cluster passphrase must be kept the same.
  • Master passphrase must be kept the same.
  • OS passwords for users 'ssgconfig' and 'root' must be kept the same during the upgrade. After upgrade completion, OS passwords may be updated as required.
  • Perform network configuration for new or re-imaged Gateways.
For the manual expedited procedure, follow the instructions to Configure a Gateway Cluster.
The automated expedited procedure includes roles that map to most of the manual tasks. However, it does not configure the Load Balancer. 
  • gateway_replicate_database
  • gateway_processing_node
  • gateway_common
Save Audit Events
Save your audit events from the source Gateway then purge them.
All audit events are discarded as part of this upgrade process.  For more information, see "Download Audit Events" and "Delete Audit Events" in View Gateway Audit Events.
Export Custom and Modular Assertions and Back Up Other Gateway Artifacts
The automated expedited procedure includes the migration of custom and modular assertions. However, you still must verify that the assertions are compatible with Gateway 10.
Copy any custom and modular assertions to the Destination Gateway:
# /opt/SecureSpan/Gateway/config/backup/ -image -ca -ma # scp /opt/SecureSpan/Gateway/config/backup/images/ [email protected]<destination_Gateway_Hostname>:~/
You must be a privileged (root) user to invoke Verify that your custom assertion is compatible with Gateway 10.x.
In addition to custom and modular assertions, you can also back up important configuration files (e.g., node, ssglog, and, files in the /etc folder (e.g., hosts, ntp.conf, resolv.conf, snmpd.conf, etc.), and files in the /opt/SecureSpan/Gateway/runtime/lib/ext folder. Learn how you can back up your Gateways with by referring to Back Up Gateways.
Back up PAPIM EPAgent Files and Configuration
Applies only if the Precision API Monitoring service exists.  EPAgent related files and configuration can be backed up, then restored on the new Gateway.
The solution kit polices and modular assertions are migrated with the rest of the Gateway policies. However, PAPIM EPAgent files and configuration files are not migrated. Back up the following files and directories:
  • PAPIM installation directory (default location): /opt/apm105.
  • The start script file: /etc/init.d/epagent
  • The PAPIM user directory files:  /home/apmusr/.bash_profile and /home/apmusr/.my.cnf
The automated expedited procedure includes roles that backup and restore these files:
  • gateway_papim_backup
  • gateway_papim_install
  • gateway_papim_restore_backup
The gateway_papim_install role installs the PAPIM agent in target machines in case a customer wishes to forgo backup and restore. To learn more about its installation, see CA Precision API Monitoring documentation here.
Check for MySQL 8 Upgrade Compatibility
Gateway 10.x requires MySQL 8.
Although the automated expedited procedure includes a gateway_preupgrade_analyzer role, the playbook requires MySql Shell Checker installed on the control node.
Install MySql Shell Checker:
  1. Download MySQL 8.0 Shell for Red Hat 6
  2. Install rpm on the Gateway 9.4 DB server:
    # rpm ivh mysql-shell-8.0.19-1.el6.x86_64.rpm
  3. Run the check command:
    #mysqlsh root:<DB_Root_Password>@localhost:3306 -e "util.checkForServerUpgrade();"
The report lets you know whether any fatal errors were found that would prevent an upgrade.