Back Up Gateways
There are two ways to back up your data in the :
There are two ways to back up your data in the
- Back up using a browser:This is a quick, one-step process that backs up to a .ZIP file: theAPI Gatewaydatabase, all configuration files, custom and modular assertions, and optionally audits. You can optionally create a script that triggers the backup.
- Back up using the command line:This offers greater flexibility in specifying what to back up.
Backups are specific to a node. To back up all nodes in a cluster, run the backup on each individual node (if using the command line) or click the button for each node (if using a browser).
API Gatewaymust be correctly configured before it can be backed up.
(1) The Backup feature of the
API Gatewayis intended to capture information from a typical deployment. Third-party applications, unsupported use of utilities, and some OS-level customization will not be captured by default. These customizations include but are not limited to: custom Ethernet rules and routes, and use of the extended OS-level authentication features. (2) A backup can only be restored to the same version of the
API Gateway(for example, a database backup from v9.0 cannot be restored onto a v9.3 Gateway).
Back Up Using a Browser
There are two ways to use the browser-based Backup Service:
- Method 1:Run a backup on demand using a web browser. With this method, you can back up aAPI Gatewaynode at any time.
- Method 2:Perform a backup using a script. With this method, the backup is performed every time the script is run.
All backup attempts using the browser are recorded in the audit log.
The backup is stored in an unencrypted zip file and contains sensitive information such as passwords and passphrases. It is highly recommended that you store the backup in a secure location.
- The person performing the backup has the role "Administrator" (must be able to Read and Write all entity types).
- TheAPI Gatewayis running.
- The appropriate listen port has "Browser-based administration" enabled (see "Configuring the [Basic Settings] Tab" in Listen Port Properties).
Backup Log Files
When backing up using a browser, the backup log files are stored in the same location as the G
API Gatewaylog files. For more information, see Logging Levels.
Method 1: Back Up on Demand
To perform an on-demand backup using a web browser:
- Start the browser and navigate to:https://<Gateway_host_name>:<port>/ssg/backupwhere the default"<port>"is 8443.If a user has a client certificate registered on theAPI Gateway, then the user is required to use the client certificate when performing a backup.
- Enter the user name and password when prompted. Be aware that names and passwords containing non-English characters may not authenticate successfully for performing a backup, even though they can be used to log in to the Policy Manager.TheAPI Gatewayuses the charset ISO-8859 when decoding basic authentication. Characters from other character sets will be accepted only when encoded according to the rules of RFC-2047.
- The Gateway Backup Service page is displayed.
- Select the [Include Audits] check box to include audit records in the backup.Including audits will increase the time to complete the backup and may greatly increase the size of the backup .ZIP file.
- Click the button corresponding to theAPI Gatewaynode to back up. If you are not running a cluster ofAPI Gateways, only one button is displayed.The database is only included in the backup of the node hosting the database. For example, if there are three nodes in the cluster and all three are backed up, then only one backup image will contain a database (and audits) in the backup.
- Select "Save to Disk" and then specify a name and location for the backup file when prompted.
Method 2: Back up Using a Script
The backup process can be invoked from a script. You will need to obtain the URI of the
API Gatewaynode to back up, then write a script to perform an HTTP GET at the URI.
To include audits, use this URI in the script:
To exclude audits, use this URI in the script:
The script will need the user name and password to access the Backup Service. To maintain security, you should write the script in such a way as to not expose the password to other users.
Best Practices When Using a Script
The backup service was designed to be available remotely via HTTP with a standard tool such as
wget,or via a scriptable command line tool. This means the backup can be automated by using a cron job or with any other scheduling tool.
When using a script, care must be taken to ensure information security. Tools like
wgetcan have credentials passed on the command line. These credentials may be exposed in UNIX systems if someone uses the "ps" command to view the process status. To prevent passwords from being revealed, store them in ".wgetrc" or ".netrc" and protect those files with the "chmod" command.
For example, the following cron job entry securely backs up the
API Gatewayon a daily basis (the entry should be all on one line):
O2 4 * * * /usr/bin/wget --tries=10 --output-document=Gateway1.zip --output-file=backup.log https://<host>:<port>/ssg/backup?node=Gateway1
In this script, the username and password are saved in ~/.wgetrc in the format:
Back Up Using the Command Line
The command line utilities offer more configurability for backing up settings and data from a
API Gatewaynode compared to backing up using a browser.
There are two ways to perform a backup using the command line:
- Standard backup:most inclusive; used most often
- Custom backup:lets you select which components to back up
Performing a Standard Backup
A standard backup will back up every applicable component except for audits (which may be included using the "
-ia" switch). The following components may not be applicable for a standard backup:
- (softwareThe operating system filesAPI Gatewayonly)
- The database files is included only if the database is local to the node
- Custom assertions are backed up if installed
- The Enterprise Service Manager can be included if the "-esm" switch is used
Examples of a standard backup:
- A standard backup:ssgbackup.sh -image name.zip
- A standard backup including audit records:ssgbackup.sh -image name.zip -ia
Performing a Custom Backup
A custom backup includes only specific components. A custom backup is created when any of these switches are used:
-os:back up OS configuration files
API Gateways only)
API Gatewayconfiguration files
-maindb:back up the
API Gatewaydatabase, excluding audit data
-audits:back up the database audits
-ext:back up the contents of the
Gateway/runtime/lib/extdirectory (Note: The backup will exclude files in the "ext" directory if both the following conditions apply: (1) the file begins with the characters "jms" and (2) the file is owned by an rpm which starts with the letters "ssg".)
-ca:back up custom assertions
-ma:back up modular assertions
You can combine any of these switches to create a custom backup containing exactly what you want.
Examples of a custom backup:
- Custom backup of only the database components:ssgbackup.sh -image name.zip -maindb -audits
- For custom backups, the "-ia" switch is not used, so this command will not include audits:ssgbackup.sh -image name.zip -os -config -maindb -iaThe correct version to include audits:ssgbackup.sh -image name.zip -os -config -maindb -audits
API Gatewaylicense file is not backed up, however if the Enterprise Service Manager is included in the image, its license file
Backup Log Files
Backup log files can be found in the following location:
To back up the
API Gatewayfrom the command line:
- Log in to theAPI Gateway:
- ApplianceLog in asAPI Gateway:ssgconfigand then open a privileged command shell from theAPI Gatewayconfiguration menu.
- SoftwareLog in either as theAPI Gateway:rootorlayer7user.
- Run the following command:
# /opt/SecureSpan/Gateway/config/backup/ssgbackup.sh [options]
Separate each option with a space. You must specify the "-image" switch.
Save the backup to the specified image file. Be sure to add the zip extension as the backup image is a zip file. If saving to an FTP server, this is the name of the image on the FTP server and any path information is relative to the FTP server.
If the path is not specified, the image is saved to
A timestamp is added as a prefix to the image name to ensure uniqueness:
If backing up to an FTP server and no path is specified, then the image will be transferred to the login directory of the "
Ensure that the
layer7user has write permission to the directory in which the image file is being saved, otherwise the backup will fail.
Include audit tables in the image. By default, audit tables are not included during backups because of the space they may consume.
If the backup process determines that there is insufficient disk space to include audit records, the backup will halt and an error will be logged. Be sure to consult the log file at:
Create a template mapping file. You then edit the template to populate it with the appropriate values to create the final mapping file.
You should use the "
-it" option only if you also intend to use the backup image for migration purposes.
Display verbose backup progress information on the screen.
Fail the entire backup when the first failure is encountered. This prevents an incomplete backup from being created.
If this option is not specified, the backup script will attempt to back up each component separately. Components that failed to back up will be noted in the log and on the console. For a custom backup, "-halt" also means to fail if a requested component is not applicable.
In this example, if an applicable component fails to backup, the backup image will contain everything else which successfully backed up:
ssgbackup.sh - image name.zip
In this example, if any applicable component fails to backup, the entire backup will fail:
ssgbackup.sh -image name.zip -halt
In this example, the backup image will contain all components which completed successfully. If the database is not local, it will not be included:
ssgbackup.sh -image name.zip -maindb -os -config
In this example, the entire backup will fail if the database is not local. Reason: A component was explicitly requested which was not applicable and the "-halt" switch was used.
ssgbackup.sh -image name.zip -maindb -os -config -halt
Failed components are displayed on the screen.
Create the backup image on the specified FTP host; can optionally specify a port number.
Secure FTP (FTPS) is not supported. Protocol must be FTP.
Username to log onto FTP host.
Password for username on FTP host.
Using any of the following options will create a custom backup that includes only the specified components:
Include the database audit files in a custom backup. The "
-maindb" option (include database) must always accompany "
-audits" option differs from the "
-ia" switch, which includes the audit records but does not cause a custom backup. If both switches are present, the "-audits" option takes precedence and a custom backup will be created.
Include the custom assertion jar and properties files in a custom backup.
API Gatewayconfiguration files in a custom backup.
Include the directory
Gateway/runtime/lib/extin a custom backup.
Include the modular assertion jar files in a custom backup.
API Gatewaydatabase in a custom backup, excluding audit data. This switch is valid only if the database is local to the node being backed up.
(applianceInclude the operating system configuration files in a custom backup.
The following option can be used for a standard or custom backup:
Include the Enterprise Service Manager (ESM) in the backup, if present. The ESM must be installed on the same node and not currently running.
When the backup is complete, the console displays whether the backup was a success, partial success, or failure.