CA API Gateway 9.1

9.4 9.1

Restore Gateways

Restoring the gateway recovers the entire Gateway environment. It is useful for initializing a new cluster node or to recover data back to an existing cluster node after a major error.
gateway91
Restoring the 
CA API Gateway
 recovers the entire Gateway environment. It is useful for initializing a new cluster node or to recover data back to an existing cluster node after a major error.
Ensure that your
/tmp/
 directory has sufficient disk space to unpack the contents prior to restore. For example, if there is 2GB free space, but the unpacked contents required 6GB, you will receive "insufficient disk space" errors and the restore process is rolled back.
(1) There is currently a known issue that may occur after restoring a Gateway. If you have issues with the Gateway, see "Problem: Gateway is not running properly after a restore" in Troubleshoot. (2) You cannot use the restore procedures described in this topic to roll back a Monthly Platform Patch. For Virtual Appliances, you can restore a VM snapshot or use some other third-party tool. For Appliance Gateways, you may need to Reset Gatewaysyour Gateway.
Contents:
You can choose to restore the entire image or only select components within the backup image. Restoration can be to the same Gateway node or to a different node. Each item in the backup image file can be restored independently. The backup image file may reside locally or on an FTP server.
The Gateway being restored must be the same version as the Gateway on which the backup was made.
When restoring an appliance Gateway, note the following (these do not apply to software Gateways):
  • If you need to restore but do not have a backup image, you can revert your Gateway to a "as shipped from the factory" state (reimage). For more information, see "Appendix K - Gateway System Recovery" in the
    CA API Gateway Administrators Manual
    .
  • If you need to make configuration changes to a restored Gateway, be sure to restart the Gateway first
    before
     reconfiguring. Otherwise, the settings in the restored image overwrite any configuration changes made through the Gateway main menu.
  • If your Gateway includes a Thales nShield HSM, ensure that you know the database password and cluster passphrase. You will need to enter these after restoring.
Prerequisites:
  • MySQL must be installed and configured and running on the Gateway node being restored.
  • The target Gateway RPM files must be installed, but they do not need to be configured. This assumes the backup image contains all required files to recover the configuration.
Full Restore Versus Custom Restore
A
full
 restore restores all applicable components found in the backup image. To perform a full restore, use any of the following combinations:
  • Default restore:
    # /opt/SecureSpan/Gateway/config/backup/ssgrestore.sh -image -dbu -dbp
  • Default restore from FTP:
    # /opt/SecureSpan/Gateway/config/backup/ssgrestore.sh -image -ftp_host -ftp_user -ftp_pass -ftp_dir -dbp  -dbu
When no information is found for a particular component during a full restore, this is logged as an INFO log event and does not affect the restore. For example, if no modular assertions are present in the image, a full restore will log the fact that modular assertions are not being restored because none were present in the image. This also applies when a component found in the image is not applicable (for example, OS data is found but the target is a software Gateway).
A
custom
 restore includes only specific components. A custom restore is performed when any of these switches are used:
-os:
 restore the OS configuration files
(appliance Gateway only)
-config:
 restore the Gateway configuration files
-maindb:
 restore the Gateway database, excluding audit data
-audits:
 restore the database audits
-ext:
 restores the contents of the
Gateway/runtime/lib/ext
directory
-ca:
 restore the custom assertions
-ma:
 restore the modular assertions
You can combine any of these switches to create a custom restore from the backup image.
Examples:
  • Custom restore only the database, including audit records:
    ssgrestore.sh -image name.zip -maindb - audits -dbu -dbp
  • Custom restore only the custom assertions and modular assertions:
    ssgrestore.sh -image name.zip -ca -ma
When no information is found for a requested component in a custom restore, this is logged as a WARNING audit and is displayed on the screen. If the "-halt" switch is used, the restore stops.
When restoring the database, the image completely overwrites the destination Gateway's database -- data is
not
 merged. Audits are always deleted with the "
-maindb
" switch. In particular, the license on the target node will need to be reinstalled after a restore of the database component since the license file is not included in the backup image.
Location of Log Files
Restore log files are stored in this location:
/opt/SecureSpan/Gateway/config/backup/logs
Restore Procedure
To restore a backup image
:
  1. Stop the target Gateway node.
  2. Log in to the Gateway:
    • Appliance Gateway:
       Log in as
      ssgconfig
       and then open a privileged command shell from the Gateway configuration menu.
    • Software Gateway:
       Log in either as the
      root
       or
      layer7
       user.
  3. Run the following command:
    # /opt/SecureSpan/Gateway/config/backup/ssgrestore.sh [options]
    Refer to the following table for the available
    [options]
    . Separate each option with a space.
  4. Restoring a previous version of the Gateway:
     If restoring an image created in a previous version of the Gateway, you must upgrade the database after the restore is complete. To do this:
    1. Start the Gateway main menu.
    2. For appliance Gateways, select option
      2
       (Display Gateway configuration menu). This displays options to configure the  application.
      For software Gateways, proceed to the next step.
    3. Select option
      1
       (Upgrade the Gateway database). Follow the prompts on the screen to upgrade the database.
  5. Restart the Gateway node.
Option
Description
-image
<image_file_path>
Full path to the image file to be restored. The path can be relative to the working directory.
When restoring from an FTP server, this is the path and name of the file to download.
Note: The image must be located in a directory accessible by the
layer7
 user, for example the default location used by the backup command:
/opt/SecureSpan/Gateway/config/backup/images/
Restoration fails if the image is in a directory that is only accessible (for example) by the
root
 user.
-dbu
<admin_db_username>
Name of the database admin user. The default user is
root
.
-dbp
<admin_db_password>
Password for the database admin user. The default password is
7layer
(1) The "-dbp" option is not required if the admin database password is blank. (2) If the password contains special characters (for example, a semicolon), enclose the password within quotes; for example:
'pass;word'
.
-halt
Fail the restore when the first error is encountered. This results in a partially restored system. If the error was caused by requesting a component that was not present in the backup image, run the restore again with the correct options.
The Restore Utility always attempts each component independently. If "-halt" is not specified, a failure of one component does not affect other components from being tried.
Failed components are displayed on the screen.
-v
Display verbose restoration progress information on the screen.
-ftp_host
<FTP_host_machine>:[port]
If the backup image is on an FTP host, specify the host name and optionally the port number.
-ftp_user
<user_name>
Username to log onto FTP host.
-ftp_pass
<password>
Password for username on FTP host.
If the password contains special characters (for example, a semicolon), enclose the password within quotes; for example:
'pass;word'
.
The following options apply to the appliance Gateway only:
-gdbu
<gateway_name>
The database user for the Gateway node.
The "-gdbu" option must be used when doing a restore when a Thales nShield HSM is present.
-gdbp
<gateway_password>
The password for the database user for the Gateway node.
If the password contains special characters (for example, a semicolon), enclose the password within quotes; for example:
'pass;word'
.
The "-gdbp" option must be used when doing a restore when a Thales nShield HSM is present.
-os
Overwrite OS-level files during restore. You must restart the Gateway appliance to complete the restoration of OS-level files.
Applies only to appliance Gateways.
The "-os" option should only be used for the same Gateway type (for example, do not back up a VMware Gateway and then attempt to restore to a hardware appliance).
The following options are used to perform a custom restore:
-audits
Include the audit records in a custom restore. The "
-maindb
" option must always accompany "-audits".
-ca
Include custom assertions and their associated property files in a custom restore.
-config
Include the Gateway configuration files in a custom restore.
-ext
Include all files from the
Gateway/runtime/lib/ext
directory in the backup image.
-ma
Include modular assertions in a custom restore.
-maindb
Include the database configuration in a custom restore, excluding audits.
The following option can be used for a standard or custom restore:
-esm
Include the Enterprise Service Manager (ESM) in the restore.
When the restore is complete, the console displays whether the restoration was a success or failure.
Advanced Tip Restoration of "node.properties" and "omp.dat"
The following table summarizes how the configuration files
node.properties
 and
omp.dat
 are treated after ssgrestore.sh is run.
Note:
When the
node.properties
 is generated on the restore host, the node database username and cluster passphrase is always encrypted.
Scenario
Result
Scenario 1:
 Backup image does not contain
node.properties
 or
omp.dat
.
OR
Image does contain the files but a custom restore is performed with no "-config" component.
The
node.properties
 and
omp.dat
 from the restore host is used.
Scenario 2:
 Backup image contains
node.properties
.
The
node.properties
from the image copied to the restore host.
The treatment of
omp.dat
 depends on whether it is present in the image:
If
omp.dat
 is in the image, it is used to decrypt values from
node.properties
 from the image and to encrypt values when writing to the restore host.
If
omp.dat
 is not in the image, then the Gateway attempts to decrypt/encrypt using the
omp.dat
 on the restore host. This succeeds only when the omp values are the same between the image and the host.

Content feedback and comments