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.
Restoring the 
Layer7 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
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.
The restore process described in this topic is not used for the Container Gateway.
Container Gateways are meant to be ephemeral and short-lived, removing the need for standard backup and restore procedures. For more information, see the "Backup/Restore" entry under "Operational Differences" in Differences Between the Container Gateway and Appliance Gateway
(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 Reset Gatewaysyour Gateway.
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
    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.
  • 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
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/ -image -dbu -dbp
  • Default restore from FTP:
    # /opt/SecureSpan/Gateway/config/backup/ -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).
restore includes only specific components. A custom restore is performed when any of these switches are used:
restore the OS configuration files
(appliance Gateway only)
restore the Gateway configuration files
restore the Gateway database, excluding audit data
restore the database audits
restores the contents of the
restore the custom assertions
restore the modular assertions
You can combine any of these switches to create a custom restore from the backup image.
  • Custom restore only the database, including audit records: -image -maindb - audits -dbu -dbp
  • Custom restore only the custom assertions and modular assertions: -image -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
merged. Audits are always deleted with the "
" 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:
Restore Procedure
To restore a backup image
  1. Stop the target Gateway node.
  2. Log in to the Gateway:
    • Appliance Gateway:
      Log in as
      and then open a privileged command shell from the Gateway configuration menu.
    • Software Gateway:
      Log in either as the
  3. Run the following command:
    # /opt/SecureSpan/Gateway/config/backup/ [options]
    Refer to the following table for the available
    . 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
      (Display Gateway configuration menu). This displays options to configure the  application.
      For software Gateways, proceed to the next step.
    3. Select option
      (Upgrade the Gateway database). Follow the prompts on the screen to upgrade the database.
  5. Restart the Gateway node.
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
user, for example the default location used by the backup command:
Restoration fails if the image is in a directory that is only accessible (for example) by the
Name of the database admin user. The default user is
Password for the database admin user. The default password is
(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:
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.
Display verbose restoration progress information on the screen.
If the backup image is on an FTP host, specify the host name and optionally the port number.
Username to log onto FTP host.
Password for username on FTP host.
If the password contains special characters (for example, a semicolon), enclose the password within quotes; for example:
The following options apply to the appliance Gateway only:
The database user for the Gateway node.
The "-gdbu" option must be used when doing a restore when a Thales nShield HSM is present.
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:
The "-gdbp" option must be used when doing a restore when a Thales nShield HSM is present.
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:
Include the audit records in a custom restore. The "
" option must always accompany "-audits".
Include custom assertions and their associated property files in a custom restore.
Include the Gateway configuration files in a custom restore.
Include all files from the
directory in the backup image.
Include modular assertions in a custom restore.
Include the database configuration in a custom restore, excluding audits.
The following option can be used for a standard or custom restore:
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 "" and "omp.dat"
The following table summarizes how the configuration files
are treated after is run.
When the
is generated on the restore host, the node database username and cluster passphrase is always encrypted.
Scenario 1:
Backup image does not contain
Image does contain the files but a custom restore is performed with no "-config" component.
from the restore host is used.
Scenario 2:
Backup image contains
from the image copied to the restore host.
The treatment of
depends on whether it is present in the image:
is in the image, it is used to decrypt values from
from the image and to encrypt values when writing to the restore host.
is not in the image, then the Gateway attempts to decrypt/encrypt using the
on the restore host. This succeeds only when the omp values are the same between the image and the host.