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.
An accompanying   note indicates that the task has been fully or partially automated.
Upgrade the Source Gateway to 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.
Install the New Gateway
Set up a new Gateway 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.
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 Private Keys nShield HSM
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 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.
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 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.