Troubleshoot Migrations

This topic describes the errors you may encounter when running the Gateway Migration Utility (GMU) and how to resolve them.
gateway83
This topic describes the errors you may encounter when running the Gateway Migration Utility (GMU) and how to resolve them.
4
Error: Execution failed. Reason:
<reason>
GMU fails to connect to the 
API Gateway
 with the following error message:
  • Execution failed. Reason: javax.net.ssl.SSLException: java.lang.ArrayIndexOutOfBoundsException: 64
  • Execution failed. Reason: javax.net.ssl.SSLException: java.lang.RuntimeException: Could not generate DH keypair
Solution
: Java 1.7 does not support Diffie–Hellman primes over 1024 bits. You have HTTPS listen ports that are configured with TSL 1.1 and a cipher suite that uses a Diffie–Hellman (DH) key exchange. Upgrade to Java 1.8. 
Error: Execution failed. Reason: javax.net.ssl.SSLHandshakeException: sun.security.validator.ValidatorException: PKIX path building failed: sun.security.provider.certpath.SunCertPathBuilderException: unable to find valid certification path to requested target
Solution
: The server certificate check failed. Add the server certificate to the JDK trust store or use 
--trustCertificate
 flag (not recommended).
Error: Execution failed. Reason: javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No name matching <host> found
Solution
: Hostname verification failed. Verify that the hostname is listed as a subject alternative name on the server certificate. Or use the --trustHostname flag (not recommended).
Error: Folder not found or Malformed path string
Solution
: You may have used improper escaping (GMU and or OS) in folders or paths and migration cannot find the target folder/path. For help, see 
Get Started and Run GMU
.
Error: Execution failed. Reason: Internal Server Error. Detail: Could not retrieve private key for export
I am using a Gateway that is configured with HSM. When I migrateOut, HSM private keys are not exported. 
Solution
: Migrating HSM keys are not supported in this release. To work around this issue, explicitly bypass exporting private keys and use the
manageMappings
command. Follow these steps using the examples that follow:
  1. On the source Gateway, run
    migrateOut
     with 
    --excludeEncryptedSecrets
    argument.
    As a result, private keys and stored passwords are not exported.
  2. On the target Gateway, create private keys and stored passwords.
  3. On the computer running GMU, create a mapping file that maps source Gateway references of private keys and stored passwords, to the target Gateway private keys and stored passwords (created in the previous step).
  4. On the target Gateway, run
    migrateIn
    with
    --map <mapping.xml>
    argument.
Step 1 example
:
migrateOut with --excludeEncryptedSecrets argument
$ ./GatewayMigrationUtility.sh migrateOut --all --excludeEncryptedSecrets --argFile source-gateway.properties --all --encryptionPassphrase @file:encrypt.txt --dest bundles/source-gateway.xml
Step 2 example: manageMappings command for mapping stored passwords
$ ./GatewayMigrationUtility.sh manageMappings --bundle bundles/source-gateway.xml --outputFile bundles/mapping.xml --type SECURE_PASSWORD --srcName <Source Stored Password Name> --targetName <Target Stored Password Name>
Step 3 example: manageMappings command for mapping private keys
$ ./GatewayMigrationUtility.sh manageMappings --bundle bundles/source-gateway.xml --outputFile bundles/mapping.xml --type SSG_KEY_ENTRY --srcId 00000000000000000000000000000004:<source key alias> --targetId 00000000000000000000000000000004:<target key alias>
0000000000000000000000000000000
4
corresponds to hardware keystore Id
0000000000000000000000000000000
2
corresponds to software keystore Id
Step 4 example: migrateIn with --map <mapping.xml> argument
$ ./GatewayMigrationUtility.sh migrateIn --argFile target-gateway.properties --encryptionPassphrase @file:encrypt.txt --bundle bundles/source-gatewayl.xml --map bundles/mapping.xml --results bundles/results.xml?
Error: Test migrate in failed: Bad Request the specified maximum data size limit would be exceeded
Solution
: The migration bundle is too large to import on the target 
API Gateway
.
  • Republish the REST Management Service to use the new cluster property, 
    restman.request.message.maxSize
     for large migrations, and reimport the bundle. For help, see 
    Configure GMU and Gateways for Migrations
    .
    Or if you have already republished...
  • Increase the byte size (default=50 MB) of the cluster property 
    restman.request.message.maxSize
    Tasks, Manage Cluster-Wide Properties
    ,
     Add
    .
Error: Incorrect mapping instructions: Given a user or group mapping without the associated user or group item reference
Solution
: Virtual FIPs groups cannot be migrated. You probably have a policy or service that references a virtual FIPs group using the assertion, 
Authenticate User or Group
.  Add users to another group on the target 
API Gateway
.
Error: Property Key=Error message "(name)" must be unique
When I migrateIn, the <
results
>.xml file gives me this mapping error. 
Solution
: The entity name that you are trying to migrate is not unique. Use the 
manageMappings
 command to map to a different name, or map to an entity with the same name.
Error: Property Key=Error message, Incorrect mapping instructions: Could not delete entity. Mappings are likely out of order
I am using the delete command to delete entities from the Gateway. I get the following error in results.xml. What is going on? 
Solution
: Entities are processed from the top to bottom in the mapping file. To delete entities, reverse the order of the mappings and try again. For example, delete from 'z' to 'a' (rather than a-z).
Error: UnknownAssertion, Code not available for assertion: CustomAssertion
Solution
: Custom and modular assertions cannot be migrated. Manually add the files as follows and rerun migration:
  • Modular assertions (.aar files)
    : /opt/SecureSpan/Gateway/runtime/modules/assertions
  • Custom assertions (.jar files)
    : /opt/SecureSpan/Gateway/runtime/modules/lib
Error: Execution failed. Reason: Error reading from file: <name>.xml
A GMU command failed with this error. 
Solution
: GMU cannot find the bundle file. Verify that you are passing the correct bundle file.
Error: 401 Permission Denied
I try to run GMU and get this error.
Solution
: You must have sufficient privileges to access resources on the
Layer7 API Gateway
.
Error: 404 Service Not Found
After migrating services to the target Gateway, an existing service fails with a 404 error.
Solution
: One of the services from the source Gateway has a conflicting URI with an existing service on the target Gateway. Use either of the following options:
1) Change the resolution name to be unique after migration
:
  1. Find the service that is failing.
  2. Right-click and select
    Service Properties
    .
  3. Select the
    HTTP/FTP
    tab.
  4. In the field, 
    Custom Resolution Path
     change the service path.
2) Use migrateIn with the --deactivate argument to ensure imported service/policies are not active
Problem: Detemplate command did not detemplatize all of my template properties
Solution
: Detemplate only detemplatizes properties in the template file. Ensure that you are specifying the correct template file, and that all template properties are in the template file. 
Problem: I ran the list command and I get an empty list or partial list of entities
Solution
: You must have full read privileges on the entity type to get a complete list for that entity. 
Problem: Entities are not correctly updating on the target 
Solution
: The most common problems are:
  • Some entities cannot be migrated. See 
    Manage
     
    Migration Limitations
     for guidance.
  • You may be using the default mapping action, 
    NewOrExisting
    . Entities on the target Gateway are updated only when you explicitly change the default mappings to 
    NewOrUpdate
    , or you update the mappings using the 
    manageMappings
     command.
Problem: Only 50 LDAP users are displayed in a list command
Solution
: The list command returns only the first 50 matched users. 
Problem: A list command shows blank user logins for FIPs users
When I run the list command, some FIPs (Federated Identity Provider) users show empty logins. 
Solution
: Empty login values for FIPs users mean that the users were not configured with logins. Only IDs are displayed when users are not configured with logins.
Problem: Entity names and GUIDs are not changed using template/detemplate
I want to change an entity name or GUID, and templatizing does not change them as expected.
Solution
: Templating cannot be used to change the names or GUIDs of these entities. This restriction is enforced because references to the entity could break on the bundle import. Use the
 manageMappings
 commands to change the names or GUIDs of these entities. 
Example
Change a JDBC Connection name from "DEV-JDBC"  (source) to "QA-JDBC" (target)
$ ./GatewayMigrationUtility.sh manageMappings --bundle bundle.xml --type JDBC_CONNECTION --srcName DEV-JDBC -N QA-JDBC
Example
Ch
ange an encapsulated assertion GUID to 'c079fc4f-3e04-4231-b2e9-9834ef7bceb1'
$ ./GatewayMigrationUtility.sh manageMappings --bundle rename.xml --type ENCAPSULATED_ASSERTION --srcName MyEncass --targetGuid c079fc4f-3e04-4231-b2e9-9834ef7bceb1
Problem: After migration, I cannot log in to Policy Manager with my Admin default login
When I migrate a full bundle, the default Admin *(#00000000000000000000000000000003)* login is changed on the target.
Solution
: When you migrate a full bundle from source to target, the default Administrator is mapped by ID*(#00000000000000000000000000000003). If Administrators share the same login on source and target, there is no discrepancy after migration. If Administrators have different logins (for example,
 admin/password 
on source, but 
pmadmin/password123 
on target) the source default Administrator is mapped to the target (
pmadmin/password123
), and you must use the target username to log in to the Policy Manager (
pmadmin/password123
).
Use the 
manageMappings
 command to map the Administrator login.
Problem: Unable to connect to the Gateway when setting up GMU
I am getting this error message, even after trying the recommended solutions of establishing server trust and using the "–trustCertificate" option:
Execution failed. Reason: Unable to establish trust with the Gateway. To resolve, either: ? Establish server trust and try again (more info: search "establish server trust" in the Gateway documentation), OR ? Re-run command with the "--trustCertificate" parameter to bypass trust requirement.
Solution:
If the suggested solutions do not work, you can try changing the TLS version to "1.1" for the listen port associated with the GMU. To do this: Manage Listen Ports > open properties for the GMU port >  SSL/TLS Settings tab > select
TLS 1.1
.
Problem: Entity IDs on the source Gateway do not match the entity IDs on the target Gateway
When I use the migrateIn command.
Solution:
See the example workflows #1 and #2 in manageMappings command on how to map by path or URI to overcome mismatched entity GOIDs.