Back Up Gateways

There are two ways to back up your data in the :
gateway10
Container Gateway Users
The information described in this topic applies only if you are using an external MySQL database for your Container Gateway implementation.
There are two ways to back up your data in the
Layer7 API Gateway
:
  • Back up using a browser:
    This is a quick, one-step process that backs up to a .ZIP file: the
    Layer7 API Gateway
    database, 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).
The
Layer7 API Gateway
must be correctly configured before it can be backed up.
(1) The Backup feature of the
Layer7 API Gateway
is 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
Layer7 API Gateway
(for example, a database backup from v9.0 cannot be restored onto a v9.3 Gateway).
Contents:
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 a
    Layer7 API Gateway
    node 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.
Prerequisites:
  • The person performing the backup has the role "Administrator" (must be able to Read and Write all entity types).
  • The
    Layer7 API Gateway
    is running.
  • The appropriate listen port has "Browser-based administration" enabled (see "Configuring the [Basic Settings] Tab" in Listen Port Properties).
    The Browser-based administration option is no longer available due to the deprecation of the Policy Manager browser client. Users are advised to use RESTMAN instead to enable or disable this option. Please see this Known Issue for details.
Backup Log Files
When backing up using a browser, the backup log files are stored in the same location as the G
Layer7 API Gateway
log files. For more information, see Logging Levels.
Method 1: Back Up on Demand
To perform an on-demand backup using a web browser
:
  1. Start the browser and navigate to:
    https://<Gateway_host_name>:<port>/ssg/backup
    where the default
    "<port>"
    is 8443.
    If a user has a client certificate registered on the
    Layer7 API Gateway
    , then the user is required to use the client certificate when performing a backup.
  2. 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.
    The
    Layer7 API Gateway
    uses 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.
  3. The Gateway Backup Service page is displayed.
  4. 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.
  5. Click the button corresponding to the
    Layer7 API Gateway
    node to back up. If you are not running a cluster of
    Layer7 API Gateway
    s, 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.
  6. 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
Layer7 API Gateway
node to back up, then write a script to perform an HTTP GET at the URI.
To include audits, use this URI in the script:
https://<Gateway_host>:<port>/ssg/backup?node=<node_name>&audits=true
To exclude audits, use this URI in the script:
https://<Gateway_host>:<port>/ssg/backup?node=<node_name>&audits=false
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
wget
can 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
Layer7 API Gateway
on 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:
http_user=admin http_password=password
Back Up Using the Command Line
The command line utilities offer more configurability for backing up settings and data from a
Layer7 API Gateway
node 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
Backing up ifcfg Files with Gateway Version 10.x or Newer
If you are running API Gateway Version 10.x with CentOS 7.x , you may notice that the name of your network interface configuration file (ifcfg) may differ from the interface names given by the Gateway due to the persistent network interface naming scheme. To ensure that your network interface configurations are backed up, perform the following steps:
  1. In command shell, navigate to the network-scripts folder
    # cd /etc/sysconfig/network-scripts
  2. List all ifcfg files in the folder
    ls ifcfg*
  3. Add the full path names of the ifcfg files to
    /opt/SecureSpan/Gateway/config/backup/cfg/backup_manifest
    to ensure they'll be backed up. The full path name should look similar to
    /etc/sysconfig/network-scripts/ifcfg-ens160
    . Because the manifest does not accept folders or wildcard entries, full paths must be used.
  4. Run the backup script:
    ssgbackup.sh -image /opt/SecureSpan/Gateway/config/backup/images/backup.zip
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:
  • (software
    Layer7 API Gateway
    only)
    The operating system files
  • The database files is included only if the database is local to the node
  • Custom assertions are backed up if installed
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
(appliance
Layer7 API Gateway
s only)
-config:
back up
Layer7 API Gateway
configuration files
-maindb:
back up the
Layer7 API Gateway
database, excluding audit data
-audits:
back up the database audits
-ext:
back up the contents of the
Gateway/runtime/lib/ext
directory (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 -ia
    The correct version to include audits:
    ssgbackup.sh -image name.zip -os -config -maindb -audits
The
Layer7 API Gateway
license file is not backed up, however if the Enterprise Service Manager is included in the image, its license file
is
backed up.
Backup Log Files
Backup log files can be found in the following location:
/opt/SecureSpan/Gateway/config/backup/logs
To back up the
Layer7 API Gateway
from the command line:
  1. Log in to the
    Layer7 API Gateway
    :
    • Appliance
      Layer7 API Gateway
      :
      Log in as
      ssgconfig
      and then open a privileged command shell from the
      Layer7 API Gateway
      configuration menu.
    • Software
      Layer7 API Gateway
      :
      Log in either as the
      root
      or
      layer7
      user.
  2. Run the following command:
# /opt/SecureSpan/Gateway/config/backup/ssgbackup.sh [options]
Separate each option with a space. You must specify the "-image" switch.
Option
Description
-image
<file_name.zip >
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
/opt/SecureSpan/Gateway
/config/backup/images
A timestamp is added as a prefix to the image name to ensure uniqueness:
yyyyMMddHHmmss_imagename.zip
If backing up to an FTP server and no path is specified, then the image will be transferred to the login directory of the "
-ftp_user
".
Ensure that the
layer7
user has write permission to the directory in which the image file is being saved, otherwise the backup will fail.
-ia
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:
/opt/SecureSpan/Gateway/config/backup/logs/ssgbackup.log
-it
<output_template_file_path>
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.
-v
Display verbose backup progress information on the screen.
-halt
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.
-ftp_host
<FTP_host_machine>:[port]
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.
-ftp_user
<user_name>
Username to log onto FTP host.
-ftp_pass
<password>
Password for username on FTP host.
Using any of the following options will create a custom backup that includes only the specified components:
-audits
Include the database audit files in a custom backup. The "
-maindb
" option (include database) must always accompany "
-audits
".
The "
-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.
-ca
Include the custom assertion jar and properties files in a custom backup.
-config
Include the
Layer7 API Gateway
configuration files in a custom backup.
-ext
Include the directory
Gateway/runtime/lib/ext
in a custom backup.
-ma
Include the modular assertion jar files in a custom backup.
-maindb
Include the
Layer7 API Gateway
database in a custom backup, excluding audit data. This switch is valid only if the database is local to the node being backed up.
-os
(appliance
Layer7 API Gateway
only)
Include the operating system configuration files in a custom backup.
When the backup is complete, the console displays whether the backup was a success, partial success, or failure.