Get Started and Run GMU

This section describes how to use GMU (Gateway Migration Utility) commands for migration administration tasks.

gateway90

This section describes how to use GMU (Gateway Migration Utility) commands for migration administration tasks.

Run GMU

Go to the extracted .zip directory for GMU and run the command.

Windows

GatewayMigrationUtility.bat

Linux/Unix

./GatewayMigrationUtility.sh

GMU Command Summary

Command	Description	Input and Output Files
browse	Displays the folders, services, policies, aliases on the Gateway.
detemplate	Moves templated values into a bundle.
encodePassword	Encodes the specified password.
list	Lists entities.
manageMappings	Maps entities from a source to a target Gateway.	If specified, creates: <new_mappings >.xml
migrateIn	Imports entities into a Gateway	<results >.XML
migrateOut	Exports entities out of a Gateway (always including their dependencies).	If the folder format is specified, creates: dependencies.xml mappings.xml A folder named 'rootfolder' and dependencies If the file format is specified, creates: <bundle_name >.xml
restman	Makes a single RESTMAN call through GMU.
template	Extracts template values from a bundle, replaces with placeholder values, and saves to a template properties file.	<template >.properties

GMU Entity Types

The Gateway Migration Utility can access the following entity types:

Entity type	Entity contains...
ASSERTION_ACCESS	Policy assertion (see Policy Assertions)
CASSANDRA_CONFIGURATION	Connection configuration to a Cassandra server (see Manage Cassandra Connections)
CLUSTER_PROPERTY	Cluster property (see Manage Cluster-Wide Properties)
CUSTOM_KEY_VALUE_STORE	A key-value store is an example of a data store. A data store is an example of a service that a policy connects to. Custom key value stores are created with the Custom Assertions API (see Using the KeyValueStoreServices Object)
EMAIL_LISTENER	Email listener (see Manage Email Listeners, Email Listener Properties)
ENCAPSULATED_ASSERTION	Encapsulated assertion (see Encapsulated Assertions, Manage Encapsulated Assertions)
FIREWALL_RULE	Firewall rules (see Manage Firewall Rules)
FOLDER	Folder (see Organize Services and Policies into Folders)
GENERIC	Miscellaneous configurations that are used and managed by modular assertions. Examples of modular assertions that use the Generic entity type: MongoDB, RemoteCache, WebSocket, XMPP.
GROUP	May contain an Internal Identity Provider group, LDAP Identity Provider group, or Federated Identity Provider group.
HTTP_CONFIGURATION	Configuration used by the Gateway for HTTP/HTTPS connections (see Manage HTTP Options)
ID_PROVIDER_CONFIG	Identity provider configuration (see Identity Providers)
INTERFACE_TAG	Interface tags (see "Configuring the [Basic Settings] Tab" in Listen Port Properties, and "Management Details" in WS Management API)
JDBC_CONNECTION	JDBC connection (see Manage JDBC Connections, JDBC Connection Properties)
JMS_ENDPOINT	Endpoint for a JMS Destinatnion (see Manage JMS Destinations, JMS Destination Properties)
POLICY	Service poilicy (see Thinking in Policy, Working with Policies)
POLICY_ALIAS	Policy alias (see Policy Aliases)
POLICY_BACKED_SERVICE	Policy-backed service (see Manage Policy-Backed Services)
RBAC_ROLE	Security role (see Manage Roles, Predefined Roles and Permissions)
RESOURCE_ENTRY	Resources on the Gateway that apply globally; for example: XML schema or DTD resources (see Manage Global Resources)
REVOCATION_CHECK_POLICY	Revocation checking policy (see Edit a Revocation Checking Policy, Manage Certificate Validation, Certificate Revocation Checking Properties)
SAMPLE_MESSAGE	Sample message (see Create, Edit, Delete Sample Messages)
SCHEDULED_TASK	Schedule task (see Manage Scheduled Tasks)
SECURE_PASSWORD	Stored (secure) passwords (see Manage Stored Passwords)
SECURITY_ZONE	Security zone (see Manage Security Zones, and "Refining Access with Security Zones" in Organize Services and Policies into Folders)
SERVER_MODULE_FILE	Server module file (see Manage Server Module Files)
SERVICE	Gateway service (see Published Service Properties, Understanding Services and Policies on the Gateway)
SERVICE_ALIAS	Service alias (see Policy Aliases)
SITEMINDER_CONFIGURATION	CA Single Sign-On (see Manage CA Single Sign-On Configurations)
SOLUTION_KIT	Solution kit (see Manage Solution Kits)
SSG_ACTIVE_CONNECTOR	Active connector (see "Management Details" in WS Management API)(
SSG_CONNECTOR	Listen ports on the Gateway (see Manage Listen Ports, Listen Port Properties)
SSG_KEY_ENTRY	Private keys on the Gateway (see Manage Private Keys, Private Key Properties)
TRUSTED_CERT	Trusted certificate (see Manage Certificates, Certificate Properties)
USER	Gateway user (see Internal Identity Provider user, LDAP Identity Provider user, or Federated Identity Provider user)

Create Files for Common Arguments

A best practice is to put common GMU arguments into a single file with the format, <name
>.properties
to make it easier to pass arguments in GMU commands. Name the file appropriately so it is easily differentiated from the template.properties file.

Arguments *Required	Description
-z or --argFile	File name for passing common GMU arguments in the format: <name >.properties.
--loggingProperties	Path to the logging properties file. Default outputs to gmu.log in the working directory.
--hideProgress	Flag: hide progress bars.
--help	Print the help.
Connection Arguments
*-h or --host	Hostname of the Gateway.
-p or --port	Port of the Gateway REST Management interface. Default: 8443 .
-w or --restman	Path to the REST Management interface. Default: restman .
-u or --username	Required if using basic authentication. Username for connecting to the Gateway.
-x or --password	Encode password for connecting to the Gateway or the pkcs12 file to use for mutual authentication. Prefix with '@file:' to read the password from a file.
--clientCert	Client certificate for mutual authentication.
--plaintextPassword	Plaintext password for connecting to the Gateway or the pkcs12 file to use for mutual authentication. Prefix with '@file:' to read the password from a file.
--trustCertificate	Flag: do not check if the server certificate is trusted.
--trustHostname	Flag: trust the hostname of the server certificate.
--connectionTimeout	Maximum milliseconds to wait for a connection.
--readTimeout	Maximum milliseconds to wait for a response.

Example: Common arguments file

A common arguments file can contain any or all of the above common arguments.

host=empty81somerville.ca.com
username=migrationadmin3
password=7Bywx28jIME.jPobbMOtyGdEcqU3MLp9sA
port=9443
results=results.xml
encryptionPassphrase=WxCXwYpPWf0.CXCLNHYTxJBvUfwtSJkAjw
hideProgress

Example: Pass a common arguments file in migrateIn command

In this example, the common arguments file is named, commonarguments.properties
.

$./GatewayMigrationUtility.sh migrateIn --argFile commonarguments.properties --bundle bundle_to_import.xml

Escape Characters for GMU Commands

Avoid using special characters in folders, policies, and service names (as described in Develop Migration-Friendly Policies)
. Why? The escape characters that are required for GMU and the OS increases the complexity and likelihood of migration errors.

If you use special characters, you must be fluent using command-line escape characters for Windows or Linux/Unix command shells.

GMU escaping

A backslash (\) is used to escape slashes (\ /). For all other characters, use the command-line shell escape mechanisms.

Literal backslash:
use two backslashes
\\

Literal forward slash
: use a backslash, then a forward slash
\/

Example of
a folder
TEST/a\ under the root folder:
TEST\/a\\

Command-line shell escaping

Linux example for TEST \/a\\
:

migrateOut --folderName 'TEST\/a\\'

Windows example for TEST \/a\\
:

migrateOut --folderName TEST\/a\\

URL encoding

URL encoding is applied when creating files only during migrateOut
in the file format (migrateout --format singleFile
). Saved files are URL encoded for the folder/file names. For example, the folder,

TEST~!@#$%^&*(_+=-`,.<>?;':{}[]|)

looks like...

folder_TEST~!%40%23%24%25%5E%26*(_%2B%3D %60%2C.%3C%3E%3F%3B%27%3A%7B%7D%5B%5D%7C).xml

File names are truncated at 250 characters. If Windows file names are deeply nested in a folder, a migrateOut
command could fail with an error.

Check for Duplicate Service Names Before Migration

If you migrate a full source Gateway bundle to a target Gateway, and the target has existing services that are published with the same names but with different IDs, the services are successfully migrated. But this results in duplicate service URIs after migration. When users access a service with a duplicate resolution path, a "404 Service Not Found" error occurs. You can change the resolution name after migration to be unique, or use migrateIn using the --deactivate
argument to ensure imported service/policies are not active.

Manage Logs

GMU logs are saved by default in gmu.log. You can specify custom logging properties using the argument, --loggingProperties
.

Example: Default logging properties

handlers = java.util.logging.FileHandler
# Set the default logging level for the root logger
.level = INFO
# Set the default logging level for new ConsoleHandler instances
java.util.logging.ConsoleHandler.level = WARNING
# Set the default logging level for new FileHandler instances
java.util.logging.FileHandler.level = INFO
java.util.logging.FileHandler.pattern = gmu.log
java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter
java.util.logging.FileHandler.limit = 5000000
java.util.logging.FileHandler.append = true
java.util.logging.FileHandler.count = 1
# Set the default formatter for new ConsoleHandler instances
java.util.logging.ConsoleHandler.formatter = java.util.logging.SimpleFormatter
org.level = WARNING

Gateway Migration

Content feedback and comments

CA API Gateway 9.1

Get Started and Run GMU