Standard Upgrade Procedure

The standard upgrade procedure uses platform patches to move from one version to the next. You cannot skip versions.
You cannot use the Standard Upgrade Procedure described on this page to upgrade virtual or hardware appliance form factors from Gateway version 9.x to Gateway 10.x. Only Appliance Gateway customers already running on 10.0 or higher can can upgrade to 10.x via the standard patching process.
If your installation includes any custom assertions built with Gateway 10.0 or older, you may need to recreate them using the latest Java 11-compatible Gateway Custom Assertion Software Development Kit. Verify with Broadcom Support before upgrading to ensure that your particular custom assertion will not cause issues during the Gateway upgrade.
If your Gateway configuration includes a Hardware Security Module (HSM), note that some of the HSM-specific steps covered in the upgrade workflow are intended to provide general guidance only. For detailed HSM configuration procedures, see Configure Hardware Security Modules (HSM).
Determine the Current Version
Before upgrading, verify the current version of the Gateway to ensure that the correct upgrade patch is used.
To determine the version of the Gateway:
  1. Log in as
    and open a Gateway main menu.
  2. Navigate to Option 3 (Use a privileged shell (root)) and login as root.
  3. At the command prompt, type:
    # rpm -q ssg
    The installed version is displayed.
Disable the HSM
This step applies only to Gateways configured with the Luna SA HSM OR nShield HSM. Prior to stopping the Gateway and the following the rest of the upgrade steps, ensure that the HSM is disabled as a keystore:
  • For Luna SA users, navigate to the Policy Manager's Manage Keystore function to disable the Luna HSM as the keystore.
  • For nShield users, navigate to the API Gateway Menu and then select option 6 to view the Manage Gateway nShield Status menu. Select option 1 from that menu to disable the nShield HSM.
After disabling the HSM, stopping the Gateway (see next step) will default the keystore back to 'Software DB'.
Stop the Gateway
Stop all nodes on the
Layer7 API Gateway
  1. Access the Gateway main menu.
  2. Select option
    Layer7 API Gateway
    configuration menu).
  3. Select option
    Layer7 API Gateway
  4. Press
    and then select the option to stop the Gateway.
Repeat these steps on each Gateway node.
Download the Update Files
Refer to List of Update Files for the files required to upgrade the
Layer7 API Gateway
to the current release. Note that the platform updates are not cumulative. This means more updates are required if upgrading from older versions.For information about how to download the archive files from the Support site, see "Obtain the Patch Files" in Patch an Appliance Gateway.
To see the operating system for your Appliance Gateway, access the Gateway Main Menu (Appliance). The operating system name and version number are listed at the top. This helps you determine the correct patch files to download.
Install the Update Files
When you have downloaded all the required update files, install them using the following steps.
To install the Gateway update files:
  1. For clustered Gateways, if replication is in effect, stop the slave in MySQL on all database nodes in the cluster:
    1. Log in as
      and open a Gateway main menu.
    2. Open MySQL:
      # mysql
    3. At the MySQL command prompt, type:
      stop slave;
      Exit the MySQL command prompt.
  2. Back up the Gateway. For more information, see Back Up Gateways.
  3. Upload the patch files retrieved in Patch an Appliance Gateway.
  4. Install all platform updates first, rebooting the Gateway appliance after each update (use option
    from the main menu). For more information, see option 2 "Install a patch onto the Gateway" in Patch an Appliance Gateway.
  5. Install the application update and then reboot the Gateway appliance again.
  6. Replication should restart automatically after restarting the Gateway. To verify this:
    1. Open a privileged shell and log in to the MySQL client:
      # mysql
    2. Once logged into MySQL, run this command:
      show slave status\G;
      You should see the following lines:
      Slave_IO_Running: Yes
      Slave_SQL_Running: Yes
    3. If replication did not restart, manually start it by running this script:
      # /opt/SecureSpan/Appliance/bin/
      Technical Tip:
      Restarting replication on virtual appliances is slightly slower. The
      vmware-tools_reconf_once s
      ervice takes a moment to prepare the VMware tools for the new OS kernel.
Upgrade the HSM
This step applies to Gateway configurations that include a Hardware Security Module. At the minimum, HSM users must ensure that their HSM client software is updated per the latest specification described in Requirements and Compatibility. Additional changes to configuration files such as are also required.
Restart the Gateway
After installing the
Layer7 API Gateway
 updates and before upgrading the database, you must restart the Gateway:
  1. Access the Gateway main menu.
  2. Select option
    (Reboot the
    Layer7 API Gateway
Upgrade the Gateway Database
Upgrade the database next. The upgrade method depends on whether you are running the standard MySQL database or the built-in embedded database.
If you are upgrading the database after Gateway patch installation, ensure that you either have the Administrative Database user (
) privileges or grant the user with similar privileges for successful upgrade.
If you are using an external MySQL database and need to upgrade it, see
Upgrade Gateway with MySQL Database
section in Install Upgrade Files for RHEL/CentOS.
If you see any mysql warning messages after the upgrade, execute the
command to resolve incompatibilities with the upgraded MySQL server.
Embedded Database
If your Gateway uses the embedded database, the database is updated automatically when you restart the Gateway. Nothing further needs to be done. For information about the embedded database, see About the Gateway Embedded Database.
MySQL Database
The MySQL database is most commonly used in the Gateway. To update this database:
  1. Access the Gateway main menu.
  2. Select option
    Layer7 API Gateway
    configuration menu).
  3. Select option
    (Upgrade the
    Layer7 API Gateway
    database) and follow the prompts on the screen.
For more information about the configuration menu, see Gateway Configuration Menu (Appliance)
Re-enable the HSM
This step applies to Gateway configurations that include a Hardware Security Module. Prior to completing the Gateway upgrade, you'll need to re-enable the HSM. See one of the following topics for more information:
After re-enabling the HSM, it's a best practice to verify that the HSM is now being used by the Gateway as the keystore in Manage Private Keys of the Policy Manager after you've enabled it.