Migrate Using ssgmigrate.sh Utility

The ssgmigrate.sh utility lets you restore a Gateway backup image onto another Gateway. It is related to the ssgrestore.sh utility, which is designed to restore information back onto the same Gateway.
gateway91
The
ssgmigrate.sh
utility lets you restore a Gateway backup image onto another Gateway. It is related to the
ssgrestore.sh
utility, which is designed to restore information back onto the same Gateway.
The
ssgmigrate.sh
utility works best as a way to quickly clone a Gateway image from one machine to another. You have some control over what information to exclude, however it is recommended that you use the newer Gateway Migration Utility (GMU) for a more flexible and comprehensive migration experience.
Contents:
You can migrate system data and settings between
CA API Gateway
 environments (for example, from a testing environment to a production environment). When migrating, you can specify:
  • Tables to exclude when migrating the database, in file
    exclude_tables
  • Files to exclude when migrating the configuration files, in file
    exclude_files
    .
  • A mapping file that describes the corresponding values between source and target systems (using the "
    -mapping
    " option)
Both the
exclude_tables
and
exclude_files
files are stored in this directory:
/opt/SecureSpan/Gateway/config/backup/cfg
The
exclude_files
file is a text file that lists all the files that will not be restored after migration is complete. These files can include:
  • Gateway configuration files
    (for example, node
    .properties
    ): Add the name of the file to exclude; no path is required.
  • OS files
    (for example, any files in
    backup_manifest
    ): Add the entire file name and path of the actual file; for example, to exclude the file
    /etc/hosts
    from being copied from the backup image onto the host, add
    /etc/hosts
    as a new line in
    exclude_files
    .
  • Database files
    (for example.,
    my.cnf
    ): Same as "OS files" above.
To see a list of which files were copied or ignored, refer to the
ssgrestore*.log
files in /
opt/SecureSpan/Gateway/config/backup/logs
.
If you need to make configuration changes to a migrated
CA API Gateway
, be sure to restart the Gateway first
before
reconfiguring. Otherwise, the settings in the migrated image overwrite any configuration changes made through the Gateway Main Menu.
Prerequisites:
  • Both the source and target Gateways are configured and operational. 
  • A backup image that has these components present: Gateway Database ("-maindb") and Gateway configuration files ("-config"). For more information, see Back?Up Gateways.
  • MySQL is installed, configured, and running on the Gateway node being restored.
  • The target Gateway Database must be installed if using the "-db" flag.
The system migration script preserves the migration behavior from previous release of the Gateway If you have created scripts using "ssgrestore.sh -migrate" in the previous release and wish to reuse these scripts, simply update the name of the script:
  • from:
    ssgrestore.sh
  • to:
    ssgmigrate.sh
None of the script arguments from the previous version 
ssgrestore.sh
 need to be changed.
To migrate 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 shell.
    • Software Gateway:
      Log in either as the
      root
      or
      layer7
      user.
  3. Run the following command:
    # /opt/SecureSpan/Gateway/config/backup/ssgmigrate.sh
    [options]
    Refer to the table below for a list of 
    [options]
    . Separate each option with a space.
  4. If you are migrating a previous version:
     When migrating an image created in a previous version of the Gateway, you must upgrade the database after the migration is complete:
    1. Access the Gateway main menu.
    2. For appliance Gateways, select option 
      2
       (Display Gateway configuration menu).
      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.
In the following table, the options are written to the migrated host’s
node.properties
, or to a new
node.properties
file if one doesn’t exist: -db, -newdb, -dbh, -gdbu, -gdbp, -cp.
Option
Description
-image
<image_file_path>
Full path to the image file to migrate. The image cannot be located on an FTP server.
Note:
The image must be located in a directory accessible by the
layer7
user. Migration fails if the image is in a directory that is only accessible (for example) by the
root
user.
-mapping
<mapping_file_path>
Location of the mapping template file. This file is created by the "
-it
" option when the backup was performed. Use of this switch is optional. For more information, see "Create a Mapping File" later in this topic.
-dbu
<admin_db_username>
Name of the database admin user.
-dbp
<admin_db_password>
Password for the database admin user.
(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'
.
-dbh
<host_name>
The database server host name.
-db
<database_name>
The name of the Gateway database.
-config
Include the Gateway configuration files in the migration, excluding the database. Use of this switch is optional.
The
ssgmigrate.sh
script
never migrates a database if it is not local. The "-config" switch lets you run ssgmigrate.sh with an image containing a backed up database, without it failing when the database is attempted to be restored.
-os
(Appliance Gateway only)
Overwrite OS-level files during migration. You must restart the Gateway to complete the restoration of OS-level files. Use of this switch is optional.
The "-os" option should only be used for the same Gateway type. For example, you cannot back up a Virtual Appliance Gateway and then attempt to migrate that to a Hardware Appliance).
-cp
<passphrase>
The cluster passphrase for the resulting database.
If the passphrase contains special characters (for example, a semicolon), enclose the passphrase within quotes; for example:
'pass;phrase'
.
-gdbu
<gateway_name>
The database user for the Gateway node.
-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'
.
-newdb
<database_name>
Create a new database with the specified name. The database must not exist already.
When the migration is complete, the console displays whether the migration was a success or failure.
Technical Note: Migrate "node.properties" and "omp.dat".
If the backup image contains no configuration component or "-config" was not specified during migration AND all database command line parameters are supplied, then the following occurs:
  • If 
    node.properties
     on the migration target does not exist, it is created and a node.id is automatically generated.
  • If 
    node.properties
     on the migration target does exist, then it is updated with the command line parameters. The target host’s current 
    omp.dat
     is always used in this case
When the
node.properties
is generated on the migration target host, the node database username and cluster passphrase is always encrypted.
Migration Tips
The following tips can help reduce the overall effort when using
ssgmigrate.sh
to migrate between environments.
If your goal is to initialize a new cluster using a backup image, use the Restore Utility (ssgrestore.sh) instead. For more information, see Restore Gateways.
When migrating between environments, the backend server names and service URLs usually differ. To best handle this, avoid using explicit values in the service policies. Use context variables in the Route via HTTP(S) Assertion instead of explicit URLs. The following is an example:
  1. In the routing assertions, use the
    ${gateway.cluster_property_name}
     context variable instead of explicit hostnames or IP addresses. For example, use
    http ://${gateway.back_end_app_server}/Url/
     in the Route via HTTP(S) Assertion instead of the actual URL.
  2. Using Manage Cluster-Wide Properties, define
    back_end_app_server
    as a new cluster property with the name of the source server as its value. For example:
    DEVappserver.company.com
  3. Follow the steps in this topic to migrate the policy between the testing and production servers.
  4. When the migration is complete, update the value of the cluster property used for the routing URL in the mapping file—for example:
    QAappserver.company.com
Repeat these steps each time you need to migrate to a different environment. Using context variables and cluster properties in this manner reduce the amount of service policy editing following the migration
Create a Mapping File
When migrating an image, you can use the "
-mapping
" option to supply an XML file that describes the corresponding values between the source data (in the image being imported) and the target system.
There are two categories of information that can be mapped between source and target systems:
  • IP addresses referred to in routing assertions in the policies of published services
  • Values of cluster-wide properties
To create a mapping file
:
  1. Use the Backup Utility (ssgbackup.sh) with the "
    -it
    " option. For more information, see Back?Up Gateways.
  2. Open the mapping file in a text editor and replace
    only
    the placeholders with your values. The placeholders are indicated by "
    _add_your_value_
    " within the mapping file. Do not change anything else.
  3. After the mapping file is edited, you specify it using the "
    -mapping
    " option of the system migration script.
Sample mapping file
<?xml version="1.0" encoding="UTF-8"?>
<L7flash:ssgimportmapping xmlns:L7flash="http://www.layer7tech.com/migration/stagingmapping">
   <L7flash:backendipmapping>
      <L7flash:ipmap sourcevalue="_add_your_value_" targetvalue="_add_your_value_"/>
      <L7flash:ipmap sourcevalue="_add_your_value_" targetvalue="_add_your_value_"/>
   </L7flash:backendipmapping>
   <L7flash:globalvarmapping>
      <L7flash:varmap name="babou" sourcevalue="_add_your_value_" targetvalue="_add_your_value_"/>
   </L7flash:globalvarmapping>
</L7flash:ssgimportmapping>
If a mappable value is present in the imported image but is not referenced in the mapping file, then it is imported with its original value. Similarly, when you import without a mapping file, all values that would otherwise be mappable are imported as is.