Back Up Gateways

There are two ways to back up your data in the :
gateway93
There are two ways to back up your data in the 
API Gateway
:
  •  
    Back up using a browser:
     This is a quick, one-step process that backs up to a .ZIP file: the 
    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.
The backup 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
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 
API Gateway
 must be correctly configured before it can be backed up.
 (1) The Backup feature of the 
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 
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 
    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 
    API Gateway
     is 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 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 
    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 
    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 
    API Gateway
     node to back up. If you are not running a cluster of 
    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 
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 
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 
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
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 
    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
  • 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 
(appliance 
API Gateway
s only)
-config:
 back up 
API Gateway
 configuration files
-maindb:
 back up the 
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 
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 
API Gateway
 from the command line:
  1. Log in to the 
    API Gateway
    :
    • Appliance 
      API Gateway
      :
       Log in as 
      ssgconfig
       and then open a privileged command shell from the 
      API Gateway
       configuration menu.
    • Software 
      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 
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 
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 
API Gateway
 only)
 Include the operating system configuration files in a custom backup.
 
The following option can be used for a standard or custom backup:
 
 
-esm
 
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.