Upgrade an Appliance Gateway

This section describes how to upgrade gateways in the appliance and virtual appliance form factors. 
gateway92
This section describes how to upgrade
Layer7 API Gateway
s in the appliance and virtual appliance form factors. 
Prerequisite:
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)
Workflow:
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
    ssgconfig
    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 
    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.
Step 3: Upgrade Thales HSM Firmware
Perform this step only if you are upgrading to version 9.2 from a version
earlier
than version 9.1
and
your
Layer7 API Gateway
includes a Thales Hardware Security Module (HSM).
IMPORTANT:
 (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, you need to upgrade the firmware to make it compatible with the drivers in 9.2.
Contact Thales for the firmware upgrade files. They are not provided by CA Technologies due to licensing restrictions. Consult the
Thales
nShield Solo User Guide
 for complete instructions on upgrading the firmware. 
 
Note:
 Instead of running the 
nfloadmon
 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
<firmware-upgrade-folder>
/2-60-1/ldb_ncx3p-26.nff /opt/ncipher-firmware-upgrade/2-61-2/ncx3p-26.nff
Where 
"<firmware-upgrade-folder>"
 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 
    ncx3p-26.nff
     to this directory on the Gateway: 
    /opt/ncipher-firmware-upgrade/2-61-2
    Upload 
    ldb_ncx3p-26.nff
     to this directory: 
    /opt/ncipher-firmware-upgrade/2-60-1
  2. Log in to the Gateway as either 
    root
     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 
    enquiry
     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 
    enquiry
     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 
    enquiry
    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 
    enquiry
     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,
        or
      • 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 
    noclearfail
     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-
    <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.
Version 9.2 provides a new "Connection Policy" feature for WebSockets. If your pre-v9.2 Inbound Policy contains logic for authenticating the clients/users, be sure to move this logic to the Connection Policy instead. This can be done after upgrade is complete. For information about the new Connection Policy feature, see Manage WebSocket Connections.
Step 5: Stop the Gateway
Stop all nodes on the
Layer7 API Gateway
:
  1. Access the Gateway main menu.
  2. Select option
    2
     (Display CA API Gateway configuration menu).
  3. Select option
    7
    (Manage CA API Gateway status)
  4. Press
    Enter
    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 Release 9.2. 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.
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.
    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
    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.
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 (
root
) privileges or grant the user with similar privileges for successful upgrade.
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 "Using the Embedded Database" in Gateway Configuration Menu (Appliance).
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 CA API Gateway configuration menu).
  3. Select option
    1
    (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).
Gateway on Docker
If your
Layer7 API Gateway
is running in a Docker container, perform the following steps to upgrade the Gateway MySQL database.
  1. Shut down the existing Gateway Docker image.
  2. Run the following command:
    docker run --link docker_mysql_1:mysql -e SSG_DATABASE_HOST=
    <db_host>
    -e SSG_DATABASE_PORT=
    <db_port>
    -e SSG_DATABASE_NAME=
    <db_name>
    -e SSG_DATABASE_USER=
    <db_user>
    -e SSG_DATABASE_PASSWORD=
    <db_password>
    -e SSG_DATABASE_ADMIN_USER=
    <db_admin_user>
    -e SSG_DATABASE_ADMIN_PASS=
    <db_admin_password>
    -i -t
    caapim/gateway:
    <version>
    /bin/bash
    Where:
    • <db_host>
      = Name of the Gateway database host (for example, "mysql")
    • <db_port>
      = Port number for the Gateway database (for example, "3306")
    • <db_name>
      = Name of the Gateway database (for example, "ssg")
    • <db_user>
      = Name of the Gateway database user (for example, "ssg")
    • <db_password>
      = Gateway database password
    • <db_admin_user>
      = Name of the Gateway administrative user (for example "admin")
    • <db_admin_password>
      = Password for the Gateway administrative user
    • <version>
      = Full Gateway version (for example, "9.2.00-9534").
    This starts a new v9.2 Gateway image in a bash prompt linked to the MySQL database.
  3. Run the database upgrade script:
    # /opt/SecureSpan/Gateway/runtime/bin/dbtool.sh --type mysql --url="jdbc:mysql://${
    <db_host>
    }:${
    <db_port>
    }/${
    <db_name>
    }" --changeLogFile=/opt/SecureSpan/Gateway/config/etc/db/ssg.xml -u "${
    <db_admin_user>
    }" --password "${
    <db_admin_password>
    }"
  4. Verify that the database upgrade succeeded by examining the contents of the MySQL database with this command:
    # mysql -h "${
    <db_host>
    }" -P "${
    <db_port>
    }" -u "$
    {
    <db_admin_user>
    }" -D "${
    <db_name>
    }" --password="${
    <db_admin_password>
    }
    " -e "select * from ssg_version"
    You should see the following:
    +-----------------+
    | current_version |
    +-----------------+
    | 9.2.00          |
    +-----------------+
  5. Exit the shell to terminate this upgrade Docker container.
  6. Start the new 9.2 Gateway image(s). For more information, see Using the Gateway Docker Appliance (OLD).
Step 9: Restart the Gateway
You can now start the
Layer7 API Gateway
:
  1. Access the Gateway main menu.
  2. Select option 
    R
     (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
2
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 to version 9.2:
  1. Access the privileged shell.
  2. Open the following file in a text editor:
    /opt/SecureSpan/JDK/jre/lib/security/java.security
  3. Add the following line to the file and then save and close the file:
    com.safenetinc.luna.provider.createExtractableKeys=true
    If your Luna machine has FIPS mode enabled, insert an additional line to the java.security file as follows:
    security.provider.10=com.safenetinc.luna.provider.LunaProvider