Patch an Appliance Gateway

This section describes how to patch gateways in the appliance and virtual appliance form factors, including Gateways running in the AWS or Azure environments. 
gateway92
This section describes how to patch
Layer7 API Gateway
s in the appliance and virtual appliance form factors, including Gateways running in the Azure environments. 
Contents:
Be sure to back up your Gateway before installing a patch, in case you need to revert back to the pre-patch state. There is no way to reverse a patch once it is installed. For more information, see Back Up Gateways.
Obtain Upgrade Patch Files
To obtain the patch files
for upgrading your Gateway:
  1. Log in to the CA Support site: https://support.ca.com
  2. Select
    Download Management
    and search for "
    ca api gateway
    ".
  3. Select your Gateway product from the results that appear. A list of DVD images is displayed.
  4. In the "Service Pack" column, '0000' indicates the base release, while a number such as '01' indicates a service pack release.
  5. Review the Release Notes to see a listing of the contents of each archive.
  6. Download the appropriate archive(s) to your hard drive and unzip them.
  7. Locate the necessary patch files in the archive and copy them to the "/home/
    <user>
    " directory on your hard drive.
    Tip:
    See  List of Update Files for the names of patch files you need.
  8. Change the permissions of the patch files to '755':
    #
    chmod 755
    <patch_files>
  9. Copy the patch files to the
    API Gateway
     appliance using the SCP command:
    scp –p
    <patch_file> ssgconfig@<your_gateway>:
Obtain All Other Patch Files
In between major releases, check the following site regularly for monthly patches or cumulative releases. You should receive proactive notification emails from CA Support when these are available.
To download monthly or cumulative release patch files for the Gateway:
Patching Using the Menu
To patch using the menu:
  1. Access the the Gateway main menu.
  2. Stop the Gateway:
    1. Select option
      2
      (Display Layer 7 Gateway configuration menu).
    2. Select option
      7
      (Manage Layer 7 Gateway status).
    3. Press
      Enter
      and then select the option to stop the Gateway.
    4. Return to the Gateway main menu
  3. Select option
    8
    from the Gateway main menu to access the Patch menu:
    This menu allows you to manage patches on the CA API Gateway Appliance What would you like to do? 1) Upload a patch to the Gateway 2) Install a patch onto the Gateway 3) Delete a patch from the Gateway 4) List the patches uploaded to the Gateway X) Exit menu Please make a selection:
  4. Install the patch file as follows (see the table below for more details about each option):
    1. Select option
      1
      (Upload a patch to the Gateway).
    2. Select option
      2
      (Install a patch onto the Gateway).
  5. Return to the Gateway main menu and select option
    R
    (Reboot the SSG appliance (apply the new configuration)).
The following table describes how to use each patch option in detail:
Option
Description
1) Upload a patch to the Gateway
This option scans the directory
/home/ssgconfig
for eligible patches and lists them on the screen:
1. Enter the number next to the patch you wish to upload to the
API Gateway
.
2. Press [
Enter
] to confirm the uploading of the patch.
3. A message will indicate that the patch was successfully registered. Press [
Enter
] to return to the previous menu.
If the patch you wish to upload is not currently
in /home/ssgconfig,
use option
S
to enter a path to the patch to use.
Uploading a patch does not install it -- you must use option
2
to do this. Placing a patch file into
/home/ssgconfig
does not make the
API Gateway
aware of it until you use the option
1
to upload it.
If you encounter issues while uploading the patches, this knowledge base article may help: https://www.ca.com/us/services-support/ca-support/ca-support-online/knowledge-base-articles.TEC0000001164.html
2) Install a patch onto the Gateway
This option installs an uploaded patch. A list of eligible patches is displayed.
  1. Enter the number next to the patch you wish to install. Note: If the patch you want is not listed, enter
    X
    to exit and then use option
    1
    to upload it first.
  2. Press [
    Enter
    ] to confirm the installation of the patch.
  3. A message will indicate that the patch was successfully installed. If further configuration is required or if a
    API Gateway
    restart is necessary, this will be noted on the screen. For example, the following text may be displayed after installing a custom assertion:
    Please check the Gateway logs and, if the observer for CA Unicenter WSDM is NOT enabled, customize the manager SOAP endpoint by editing the cluster property cawsdm.managerSoapEndpoint and then restart the Gateway
    .
  4. Press [
    Enter
    ] to return to the previous menu.
  5. If a restart was indicated, return to the Gateway main menu and use option
    R
    to restart the appliance.
    Note:
    Failure to restart the Gateway (if indicated) could result in missing functionality in the Gateway main menu.
3) Delete patches from the Gateway
This option lets you quickly delete one or more patch files from the Gateway. You may wish to delete patches after they are installed to free up space on your hard drive.
Note:
Deleting a patch file does not uninstall that patch.
Note the following when deleting patches:
  • When a patch is deleted, the .L7P and .LCK files for that patch are removed from
    /opt/SecureSpan/Controller/var/patches
    .
  • Patches uploaded to
    /home/ssgconfig
    are not deleted because they may be needed again in the future. You can remove these patches manually if you wish.
  • A deleted patch may be uploaded and installed again if necessary.
  • Deleting a patch does not "uninstall" it.
Select from the following options when deleting a patch:
  • Delete a single patch:
    A list of all patches is displayed, regardless of status. Choose the patch to delete.
  • Bulk delete all patches:
    This deletes all patches, regardless of status. A list of patches to be deleted is
    not
    displayed. Confirm the bulk deletion.
    Tip:
    The bulk delete is useful for cleaning up your existing patches prior to enabling automatic deletion. Once auto deletion is enabled, bulk delete should not be necessary.
  • Configure automatic patch deletion:
    Displays the current automatic deletion setting and allows you to change it. When enabled, patch files are automatically discarded after installation.
    Tip:
    If the patch did not install successfully for whatever reason, it is still removed if this option is enabled. Should this occur, you must upload and install the patch again.
4) List Gateway patch history
This option provides a history of the patches applied on a Gateway. It lists:
  • INSTALLED patches, ordered by date installed
  • UPLOADED patches, ordered by date uploaded
  • ERROR patches, ordered by date the error occurred
Note that only one entry is shown for each patch. Example: A patch installation failed twice and succeeded on the the third time. The only entry for this patch is the successful installation; the two failures are not listed.
For a description of the statuses, see "Understanding the Patch States" in Understand Gateway Patches.
Only patches registered using option 1 ("Upload a patch to the Gateway") are listed here. Patches simply copied to
/home/ssgconfig
are not shown.
Patching Using the Command Line
You may also patch the Gateway using the command line, once the Gateway has been stopped using the menu.
To patch using the command line:
  1. Access the the Gateway main menu.
  2. Stop the Gateway:
    IMPORTANT:
    Use the steps described here to stop the Gateway. Do
    not
    stop the Gateway using the
    service ssg stop
    command, as this causes the patching process to fail.
    1. Select option
      2
      (Display CA API Gateway configuration menu).
    2. Select option
      7
      (Manage CA API Gateway status).
    3. Press
      Enter
      and then select the option to stop the Gateway.
    4. Return to the Gateway main menu
  3. Select option
    3
    (Use a privileged shell (root)) to access the privilege shell.
  4. Upload and then install the patch by using this command:
    # /opt/SecureSpan/Controller/bin/patch.sh
    <target>
    <action>
    Where:
    • "<target>"
      is either the patch API endpoint URI or the Process Controller home directory; if not specified, the <target> defaults to:
      https://localhost:8765/services/patchServiceApi
    • "<action>"
      is an action from the table below. You must
      upload
      first, then
      install
      .
  5. Restart the Gateway:
    1. Exit the privileged shell.
    2. Return to the Gateway main menu.
    3. Select option
      R
      (Reboot the SSG appliance (apply the new configuration)).
The following table provides a reference to all the command line patching commands:
Action
Description
upload
<filename>
Uploads the patch named
<filename>
to the
API Gateway
.
install
<patch_ID>
Installs the patch with the identifier <patch_ID>. This patch must already be uploaded using the
upload
action.
The patch ID is normally the patch file name, excluding the extension.
A message will indicate that the patch was successfully installed. If further configuration is required or if a
API Gateway
restart is necessary, this will be noted on the screen. For example, the following text may be displayed after installing a custom assertion:
Please check the Gateway logs and, if the observer for CA Unicenter WSDM is NOT enabled, customize the manager SOAP endpoint by editing the cluster property cawsdm.managerSoapEndpoint and then restart the Gateway.
delete
[
<patch_ID> |
all]
Removes the specified <patch_ID> or all patches from the list of registered patches on the
API Gateway
.
Note the following when deleting a patch:
  • When a patch is deleted, the .L7P and .LCK files for that patch are removed from
    /opt/SecureSpan/Controller/var/patches
    .
  • Patches uploaded to
    /home/ssgconfig
    are not deleted because they may be needed again in the future. You can remove these patches manually if you wish.
  • A deleted patch may be uploaded and installed again if necessary.
  • Deleting a patch does not "uninstall" it.
autodelete
[true|false]
Enables or disables the automatic deletion of patches after installation. Returns the current auto deletion status if no parameter is specified.
When auto deletion is enabled, patches are removed even if the installation was unsuccessful. Should this occur, you must upload and install the patch again.
list
[-ignoredeletedpatches]
Lists all the patches currently registered on the
API Gateway
and their statuses. For a description of the states, see "Understanding the Patch States" under Understand Gateway Patches.
If "-ignoredeletedpatches" is specified, the list returned excludes patches that have been deleted (no associated .L7P file).