Troubleshoot Migrations

This topic describes the errors you may encounter when running the Gateway Migration Utility (GMU) and how to resolve them.

gateway94

This topic describes the errors you may encounter when running the Gateway Migration Utility (GMU) and how to resolve them.

If you are currently using the Container Gateway form factor and are looking to deploy in ephemeral mode, the migration process will be simplified. Learn the benefits of treating your policy as code in a CI/CD pipeline with the Gateway Developer Plugin.

Execution Failed Errors

The following Execution Faild errors take the format:

Error: Execution failed. Reason: <reason>

GMU Fails to Connect to the Gateway

GMU fails to connect to the Gateway with the following error message:

Error: Execution failed. Reason: javax.net.ssl.SSLException: java.lang.ArrayIndexOutOfBoundsException: 64

Error: Execution failed. Reason: javax.net.ssl.SSLException: java.lang.RuntimeException: Could not generate DH keypair

Resolution
: Upgrade to Java 1.8.

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.

Server Certificate Check Fails

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
: Add the server certificate to the JDK trust store or use --trustCertificate
flag (not recommended).

Hostname Verification Fails

Error: Execution failed. Reason: javax.net.ssl.SSLHandshakeException: java.security.cert.CertificateException: No name matching <host> found

Solution
: Verify that the hostname is listed as a subject alternative name on the server certificate. Or use the --trustHostname flag (not recommended).

Private Keys are Not Exported

Error: Execution failed. Reason: Internal Server Error. Detail: Could not retrieve private key for export

Occurs on a Gateway that is configured with HSM.

Solution
: Migrating HSM keys is not supported. To work around this issue, explicitly bypass exporting private keys and use the manageMappings
command. Follow these steps using the examples that follow:

On the source Gateway, run migrateOut
with --excludeEncryptedSecrets
argument.

As a result, private keys and stored passwords are not exported.

$ ./GatewayMigrationUtility.sh migrateOut --all --excludeEncryptedSecrets --argFile source-gateway.properties --all --encryptionPassphrase @file:encrypt.txt --dest bundles/source-gateway.xml

On the target Gateway, create private keys and 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>

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).

$ ./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

On the target Gateway, run 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?

GMU Cannot read from file

Error: Execution failed. Reason: Error reading from file: <name>.xml

Solution
: GMU cannot find the bundle file. Verify that you are passing the correct bundle file.

Other Errors

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: 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: 401 Permission Denied

I try to run GMU and get this error.

Solution
: You must have sufficient privileges to access resources on the Gateway.

Error: 403 Forbidden

The following warning can occur if Restman was modified to use different user authentication than the default internal user:

WARNING: Error executing command javax.ws.rs.WebApplicationException: 403 Forbidden

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
:

Find the service that is failing.

Right-click and select Service Properties
.

Select the HTTP/FTP
tab.

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
.

Problems Not Associated with an Error Message

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 migrateOut command to migrate a specific item in a folder, I receive errors related to mismatched IDs when using 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.

Troubleshoot

Content feedback and comments

CA API Gateway 9.1

Troubleshoot Migrations