Standard Upgrade Procedure

The standard upgrade procedure uses platform patches to move from one version to the next. You cannot skip versions.
The Standard Upgrade Procedure cannot be used to upgrade from Gateway 9.4 to 10.0. To upgrade to Gateway version 10.0, use the Manual or Automated Expedited Upgrade Procedure.
If your installation includes any custom assertions, verify with Support before upgrading to ensure that your particular custom assertion will not cause issues during the Gateway upgrade.
Workflow:
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
    ssgconfig
    and open a Gateway main menu.
  2. 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'.
Disable Enterprise Service Manager
If the Enterprise Service Manager (ESM) is present, you must disable it prior to upgrading the  Gateway.
To disable the Enterprise Service Manager:
  1. Log in as
    ssgconfig
    and select option
    7
    (Display Enterprise Service Manager) from the Gateway main menu.
  2. Select option
    2
    (Disable the Enterprise Service Manager) and then press
    Enter
    to continue.
  3. Enter
    y
    to confirm.
Remove Old WebSocket Components
If your Gateway installation contains any WebSocket components from v9.1 or earlier, delete these components before upgrading.
To remove old WebSocket components:
  1. Select the entry named "websocket" with description "WebSocketAssertion-
    <version>
    .saar" and click
    Delete
    .
  2. Access the privileged shell.
  3. Navigate to
    /opt/SecureSpan/Gateway/runtime/modules/assertions/
  4. Delete the file
    WebSocketAssertion.aar
    if it is present.
Stop the Gateway
Stop all nodes on the
Layer7 API Gateway
:
  1. Access the Gateway main menu.
  2. Select option
    2
    (Display
    Layer7 API Gateway
    configuration menu).
  3. Select option
    7
    (Manage
    Layer7 API Gateway
    status)
  4. Press
    Enter
    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.
Prior to upgrading Gateway, you will need to install the kernel patch, Layer7_API_PlatformUpdate_64bit_vKernel-2018-10-05.L7P. The patch installation is a one-time requirement for each Gateway upgrade attempt. An upgrade attempt consists of the installation of one or more platform upgrade patches and ends with the installation of a single Gateway upgrade patch.
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
      ssgconfig
      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
    R
    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/restart_replication.sh
      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 java.security are also required.
Upgrade the Gateway Database
After you update the
Layer7 API Gateway
, 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 (
root
) 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
mysql_upgrade
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
    2
    (Display
    Layer7 API Gateway
    configuration menu).
  3. Select option
    1
    (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)
Restart the Gateway
You can now start the
Layer7 API Gateway
:
  1. Access the Gateway main menu.
  2. Select option
    R
    (Reboot the
    Layer7 API Gateway
    appliance).
For clustered Gateways with replication in effect, the secondary database is replicated from the primary database.
Re-enable the Enterprise Service Manager
If the
Layer7 API Gateway
- Enterprise Service Manager is present, re-enable it now by repeating the steps under Disable Enterprise Service Manager. Note that the menu option
2
now reads "Enable Enterprise Service Manager".
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.