Patch an Appliance Gateway

This section describes how to patch s in the appliance and virtual appliance form factors, including Gateways running in the AWS or Azure environments.

gateway91

This section describes how to patch API Gateways in the appliance and virtual appliance form factors, including Gateways running in the AWS or Azure environments.

Obtain the Patch Files

To obtain the patch files
:

Point to Download Center
and then choose Download Products
.

On the Download Center page:

Select My Products
and then choose your product from the drop-down list (if not already displayed).

Select the release number.

The Gen level
is '0000' for base releases and '01' for service pack releases.

Click Go
to see the archive files available for the release.

Review the Release Notes to see a listing of the contents of each archive.

Download the appropriate archive(s) to your hard drive and unzip them.

Locate the necessary patch files in the archive and copy them to a temporary location on your hard drive. Tip:
See List of Update Files for the names of patch files you need.

Change the permissions of the patch files to '775':

# chmod 775 <patch_files>

Copy the patch files to the API Gateway appliance using the SCP command. The recommended directory is /home/ssgconfig
, but another directory may be used if necessary.

To obtain the monthly patch files:

Point to Download Center
and then choose Download Products
.

Understanding the Patch File Nomenclature

This section helps you understand the different types of patch files and is of interest to advanced users.

There are currently five types of patch files for the CA API Gateway appliance:

Incremental Platform Update Patches (also known as "Security Patches")

This type of patch contains RPM files for the underlying operating system (OS). These files patch security vulnerabilities and include updates to the OS-level RPM files, but they are not intended to modify the behavior of the Gateway software.

These patches can be found in the Download section of the Support Portal with names that follow this syntax:

Layer7_PlatformUpdate_
<architecture>
_
<gatewayVersion>
.L7P

There are both x32 and x64 versions of each of these patches. These patches contain all the modifications since the last minor version release, effectively containing all Monthly Platform Updates from the previous version, as well as any RPM files added for the core minor version release.

Monthly Platform Updates (these are also referred to as "Security Patches")
These patches are periodic updates to the Incremental Platform Update Patches. They serve the same function, but are created to provide the most-up-to-date security for the OS pending the next major or minor release.

These patches can be found in the Download section of the Support Portal with names that follow this syntax:

Layer7_PlatformUpdate_
<architecture>
_
<GatewayVersion>-
<date>.
L7P

There are both x32 and x64 versions of each of these patches. These patches are cumulative for their version release. They do not contain the core version release patch.

Core Application Patches

The Application Patch is intended to update the CA API Gateway and the API Gateway - Enterprise Service Manager software. These patches do not contain updates for the underlying OS.

These patches can be found in the Download section of the Support Portal with names that follow this syntax:

Layer7_
<version>
.L7P

Application Update Patches

These patches are periodic updates to the Gateway application, pending the release of the next patch. They are typically used to resolve any issues that arose as a result of the deployment of the Core Application Patch. These patches provide quick responses to new security threats at the application level (for example, updating the default cipher suite list to combat CBC attacks). They also provide enhancements to functionality pending the next major/minor release.

Other Patches

These include hot fixes, extended functionality for a niche project, cumulative Platform Updates, and other items that do not fall in any of the above categories.

Patching Best Practices

We recommend the following best practices for patching your API Gateway:

Platform Update Patches (all "Security Patches")

Apply these patches as soon as possible to keep your API Gateway appliance patched against any OS-level security vulnerabilities. To do this, install the most recent Monthly Platform Updates for your API Gateway version after deploying the appliance. When new versions are released, apply the Incremental Platform Update Patch for that new version, and then keep up to date on the latest Monthly Platform Update for that version.

If you are deploying an appliance that is not the most recent version:

Install the Incremental Platform Update Patches for each version since your appliance was released in the correct order.

Install the most recent Monthly Platform Update for the newest appliance version.

When installing any platform patch, consult the Release Notes for that version to ensure that the patches are correctly deployed (for example, some patches require a mysql_upgrade
from the command line, or a similar additional action). These patches should be applied one at a time on all nodes in the cluster and require a reboot after every incremental patch is installed.

Application Patches

It is typically best practice to monitor the Release Notes for all patching information. These notes discuss any security vulnerabilities or hot fixes handled by the application patches. When deciding on when to update your API Gateway software, be sure to take into account factors such as: functionality, security features, and end-of-life timelines on the versions.

Restarting the Gateway

The Gateway needs to be restarted during the patching process. The recommended method is using the "Restart" command in the Gateway main menu, it invokes the correct sequence of commands in the background. Advanced users who understand the underlying commands may opt to use the command line.

Patching Using the Menu

To patch using the menu:

Access the the Gateway main menu.

Stop the Gateway:

Select option 2
(Display Layer 7 Gateway configuration menu).

Select option 7
(Manage Layer 7 Gateway status).

Press Enter
and then select the option to stop the Gateway.

Return to the Gateway main menu

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:

Install the patch file as follows (see the table below for more details about each option):

Select option 1
(Upload a patch to the Gateway).

Select option 2
(Install a patch onto the Gateway).

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.
2) Install a patch onto the Gateway	This option installs an uploaded patch. A list of eligible patches is displayed. 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. Press [Enter ] to confirm the installation of the patch. 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.
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. 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. Contact CA Support if you must uninstall a patch. 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:

Access the the Gateway main menu.

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.

Select option 2
(Display CA API Gateway configuration menu).

Select option 7
(Manage CA API Gateway status).

Press Enter
and then select the option to stop the Gateway.

Return to the Gateway main menu

Select option 3
(Use a privileged shell (root)) to access the privilege shell.

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
.

Restart the Gateway:

Exit the privileged shell.

Return to the Gateway main menu.

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>	Removes an uninstalled patch from the list of registered patches on the `API Gateway`. It physically deletes the patch from the internal repository, but not from the original pre-upload location. Note the following when deleting a patch: Only patches in the UPLOADED or ROLLED_BACK states can be deleted. Deleting a patch only sets its state to NONE -- the patch itself is not physically removed from the appliance. A deleted patch may be uploaded and installed again if necessary. Deleting a patch does not "uninstall" it. Contact CA Support if you must uninstall a patch.
list	Lists all the patches currently registered on the `API Gateway` and their statuses. For a description of the statuses, see "Understanding the Patch States" under Understand Gateway Patches.

View Logs for the Gateway

Patch Gateways

Content feedback and comments

CA API Gateway 9.1

Patch an Appliance Gateway