Migrate System Data
You can migrate system data and settings between gateway environments (for example, from a testing to a production environment).
gateway92
You can migrate system data and settings between
CA API Gateway
environments (for example, from a testing to a production environment). Use this topic to migrate an entire Gateway image from one machine to another. You have some control over what information to exclude, but the entire Gateway database is always included or excluded. Use the newer Gateway Migration Utility (GMU) for greater flexibility in migrating your database. You can create bundles for specific entities. The GMU cannot migrate system data such as
system.properties
and host.properties
.Contents:
When migrating, you can specify:
- Tables to exclude when migrating the database, in fileexclude_tables.
- Files to exclude when migrating the configuration files, in fileexclude_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 inbackup_manifest): Add the entire file name and path of the actual file; for example, to exclude the file/etc/hostsfrom being copied from the backup image onto the host, add/etc/hostsas a new line inexclude_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
:- Stop the target Gateway node.
- Log in to the Gateway:
- Software Gateway:Log in either as therootorlayer7user.
- 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.
- 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:
- Access the Gateway main menu.
- For appliance Gateways, select option2(Display Gateway configuration menu).For software Gateways, proceed to the next step.
- Select option1(Upgrade the Gateway database). Follow the prompts on the screen to upgrade the database.
- 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 does not 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 (for example, MySQL connection details and master cluster passphrase), but exclude the database. Use of this switch is optional. This switch is useful for migrating Gateways where the database is not local. The ssgmigrate.sh utility cannot migrate non-local databases and this prevents errors later on when you attempt to restore a Gateway. |
-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 can 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:- Ifnode.propertieson the migration target does not exist, it will be created and a node.id will be automatically generated.
- Ifnode.propertieson the migration target does exist, then it is updated with the command line parameters. The target host’s currentomp.datis always used in this case
When the
node.properties
is generated on the migration target host, the node database username and cluster passphrase will always be 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 back-end 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:
- In the routing assertions, use the${gateway.cluster_property_name}context variable instead of explicit hostnames or IP addresses. For example, usehttp ://${gateway.back_end_app_server}/Url/in the Route via HTTP(S) Assertion instead of the actual URL.
- Using Manage Cluster-Wide Properties, defineback_end_app_serveras a new cluster property with the name of the source server as its value. For example:DEVappserver.company.com
- Follow the steps in this topic to migrate the policy between the testing and production servers.
- 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
:- Use the Backup Utility (ssgbackup.sh) with the "-it" option. For more information, see Back Up Gateways.
- Open the mapping file in a text editor and replaceonlythe placeholders with your values. The placeholders are indicated by "_add_your_value_" within the mapping file. Do not change anything else.
- 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.