Get Started and Run GMU

This section describes how to use GMU (Gateway Migration Utility) commands for migration administration tasks. 
gateway92
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
 
manageSolutionKits
 
Helps to manage solutions kits in the gateway.
 
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  Email Listener Properties)
ENCAPSULATED_ASSERTION
Encapsulated assertion (see  Manage Encapsulated Assertions)
FIREWALL_RULE
Firewall rules (see  Manage Firewall Rules)
FOLDER
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
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  WS Management API)
JDBC_CONNECTION
JMS_ENDPOINT
Endpoint for a JMS Destinatnion (see  JMS Destination Properties)
POLICY
Service policy (see  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  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  Certificate Revocation Checking Properties)
SAMPLE_MESSAGE
SCHEDULED_TASK
Schedule task (see  Manage Scheduled Tasks)
SECURE_PASSWORD
Stored (secure) passwords (see  Manage Stored Passwords)
SECURITY_ZONE
SERVER_MODULE_FILE
Server module file (see  Manage Server Module Files)
SERVICE
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  Listen Port Properties)
SSG_KEY_ENTRY
Private keys on the Gateway (see  Private Key Properties)
TRUSTED_CERT
Trusted certificate (see  Certificate Properties)
USER
Create Files for Common Arguments
Best_Practice_GMU4
Best_Practice_GMU4
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
Best_Practice_GMU5
Best_Practice_GMU5
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
Best_Practice_GMU6
Best_Practice_GMU6
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