Upgrade an Appliance Gateway

This section describes how to upgrade gateways in the appliance and virtual appliance form factors.
This section describes how to upgrade
Layer7 API Gateway
s in the appliance and virtual appliance form factors.
This topic assumes that you have an existing operational Gateway. If you are configuring a newly purchased Gateway, see Configure the Appliance Gateway instead.
If your installation includes any custom assertions, verify with CA Support before upgrading to ensure that your particular custom assertion will not cause issues during the Gateway upgrade.
Upgrade an Appliance Gateway (fixed with no MAG)
Upgrade an Appliance Gateway (fixed with no MAG)
Step 1: Determine the Existing Version
Before upgrading, you can use the procedure below to verify the version of the
Layer7 API Gateway
currently installed. After upgrading, you can use these steps to validate that the installation packages were installed correctly.
To determine the version of the Gateway
  1. Log in as
    and open a Gateway main menu.
  2. At the command prompt, type:
    # rpm -q ssg
    The installed version of the
    Layer7 API Gateway
    is displayed.
Step 2: Disable Enterprise Service Manager
If the Enterprise Service Manager (ESM) is present, you must disable it prior to upgrading the
Layer7 API Gateway
To disable the Enterprise Service Manager:
  1. Log in as
    and select option
    (Display Enterprise Service Manager) from the Gateway main menu.
  2. Select option
    (Disable the Enterprise Service Manager) and then press
    to continue.
  3. Enter
    to confirm.
Step 3: Upgrade Thales HSM Firmware
Perform this step only if you are upgrading from a version
than version 9.1
Layer7 API Gateway
includes a Thales Hardware Security Module (HSM).
(1) Follow the directions carefully, as an incorrect firmware upgrade may render your HSM inoperable. Once an upgrade is performed, it is not possible to return to the previous version of the firmware. (2) You will need to rebuild the security world after upgrading the firmware. Consult the nShield User Guide for detailed instructions.
Support for the Thales nShield Solo+ (formerly "nCipher") HSM was restored in version 9.1 and later. If you are not upgrading from version 9.1 or later, you need to upgrade the firmware to make it compatible with the drivers in the current release.
Contact Thales for the firmware upgrade files. They are not provided by CA Technologies due to licensing restrictions. Consult the
nShield Solo User Guide
for complete instructions on upgrading the firmware.
Instead of running the
command as described in the
Thales nShield Solo User Guide
, you must prepend the command with a temporarily updated PATH environment variable. For example:
PATH="/opt/nfast/bin/:$PATH" /opt/nfast/bin/nfloadmon -m1 --automode
/2-60-1/ldb_ncx3p-26.nff /opt/ncipher-firmware-upgrade/2-61-2/ncx3p-26.nff
is the directory containing the firmware upgrade files (for example, "/opt/ncipher-firmware-upgrade").
The following steps summarize the firmware upgrade procedure (refer to the Thales documentation for details):
  1. Upload
    to this directory on the Gateway:
    to this directory:
  2. Log in to the Gateway as either
    or as a user in the group 'nfast'.
  3. Put the module into Pre-Maintenance mode and then reset the module. See "How to Change Modes" below for more details.
  4. Run the
    command to check that the module is in the Pre-Maintenance state:
    # /opt/nfast/bin/enquiry
    The HSM enters into maintenance mode when it receives a maintenance command (for example, running "loadrom" from the command line utility).
  5. Run the following command to load the new firmware and monitor:
    # PATH="/opt/nfast/bin/:$PATH" /opt/nfast/bin/nfloadmon -m1 --automode /opt/ncipher-firmware-upgrade/2-60-1/ldb_ncx3p-26.nff /opt/ncipher-firmware-upgrade/2-61-2/ncx3p-26.nff
  6. If prompted, switch the card to Pre-Initialization mode and then reset the module. See "How to Change Modes" below for more details.
  7. Run the
    command again (see step 4) to check that the module is in the Pre-Initialization state.
  8. Run the following command to initialize the module:
    # /opt/nfast/bin/initunit
  9. (Optional) To confirm that the monitor upgraded successfully, put the module into Maintenance mode and then reset the module. See "How to Change Modes" below for more details. Now if you run the
    command (see step 4), you should see that the monitor version has been upgraded to 3.21.3.
  10. Put the module into Operational mode and then reset the module. See "How to Change Modes" below for more details.
  11. Run the
    command again (see step 4) to verify that the module is in the Operational state and has the correct firmware version.
How to Change Modes
You can change modes using either of the following methods:
  • Physical mode switch:
    This involves manually moving the switch on the nShield Solo card on the back of the Gateway appliance.
    1. Move the switch to the desired mode (I, O, or M)
    2. Reset the module by doing one of the following:
      • Press the recessed reset button on the card,
      • Run the command:
        # /opt/nfast/bin/nopclearfail --clear --all
  • Remote mode switch:
    This involves remotely changing the mode of the nShield Solo card from a computer using the
    command. Note the following:
    • This is only available on nShield Solo running firmware version 2.61.2.
    • Physical mode switch on the card must be in the "O" position.
    • Physical mode override jumper on the card is set to "on", while the remote mode override jumper on the card is NOT set to "on".
    • Change the mode using the command:
      # /opt/nfast/bin/nopclearfail --[maintenance|operational|initialization]
Step 4: 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-
    .saar" and click
  2. Access the privileged shell.
  3. Navigate to
  4. Delete the file
    if it is present.
Step 5: Stop the Gateway
Stop all nodes on the
Layer7 API Gateway
  1. Access the Gateway main menu.
  2. Select option
    (Display CA API Gateway configuration menu).
  3. Select option
    (Manage CA API Gateway status)
  4. Press
    and then select the option to stop the Gateway.
Repeat these steps on each Gateway node.
Step 6: 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 CA 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.
Step 7: 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, CA_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
      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.
    If you encounter issues while uploading the patches, refer to this knowledge base article for possible solutions: https://www.ca.com/us/services-support/ca-support/ca-support-online/knowledge-base-articles.TEC0000001164.html
  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/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.
Step 8: 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 (
) privileges or grant the user with similar privileges for successful upgrade.
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
    (Display CA API Gateway configuration menu).
  3. Select option
    (Upgrade the CA API Gateway database) and follow the prompts on the screen.
For more information about the configuration menu, see Gateway Configuration Menu (Appliance)
Step 9: Restart the Gateway
You can now start the
Layer7 API Gateway
  1. Access the Gateway main menu.
  2. Select option
    (Reboot the CA API Gateway appliance).
For clustered Gateways with replication in effect, the secondary database is replicated from the primary database.
Step 10: 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 "Step 2: Disable Enterprise Service?Manager". Note that option
now reads "Enable Enterprise Service Manager".
Step 11: Post-Upgrade Update for SafeNet Luna
If your Gateway uses the SafeNet Luna HSM, make the following adjustment after upgrading Gateway to the current release:
  1. Access the privileged shell.
  2. Open the following file in a text editor:
  3. Add the following line to the file (if not already present) and then save and close the file:
    If your Luna machine has FIPS mode enabled, insert an additional line to the java.security file as follows: