Troubleshooting the Migration Utility
This chapter describes common problems associated with the ACS 5.8.1 Migration Utility:
■Unable to Restore the ACS 4.x Database on the Migration Machine
■Remote Desktop Connection Not Supported for the Migration Utility
■Migrating Objects from Large-Scale Databases
■Import Phase Only Adds Partial Data
■ACS 5.8.1 Machine Does Not Respond After Import
■Resolving Migration Issues
■Migration Failed with Manually Created Super Admin
■Migration Utility Messages
■Reporting Issues to Cisco TAC
Unable to Restore the ACS 4.x Database on the Migration Machine
Condition
Unable to restore the ACS 4.x database on the migration machine.
Action
Verify and ensure that the ACS 4.x production machine (for which a backup was created) and the ACS 4.x migration machine (on which backup was restored) have identical versions of the system software. The problem might be caused by a missing patch level.
Remote Desktop Connection Not Supported for the Migration Utility
Condition
You cannot use Remote Desktop Connection (RDC) to run the Migration Utility.
Action
Use Virtual Network Computing (VNC) to run the Migration Utility on the migration machine.
Migrating Objects from Large-Scale Databases
You might encounter several issues when you attempt to migrate objects from a large database.
Condition
Performance problems can occur when you attempt to migrate a large number of objects from an ACS 4.x database.
Action
We recommend that you run the Migration Utility for each object group. For example, from the Migration Utility, enter 2 to choose option 2, AllUsersObjects. In this example, you would only run the Migration Utility against the Users object.
Import Phase Only Adds Partial Data
Condition
Import only adds partial data.
Action
1. Ensure that:
■Migration interface is enabled on the ACS 5.8.1 server.
■Network connections are enabled.
■ACS 5.8.1 services are up and running.
■You use a compatible ACS 5.8.1 license.
2. Restore the ACS 5.8.1 database to its previous version of the database.
3. Restart the Migration Utility.
4. Rerun the Import phase.
ACS 5.8.1 Machine Does Not Respond After Import
Condition
The ACS 5.8.1 machine does not respond after import.
Action
Restart ACS 5.8.1.
Resolving Migration Issues
These sections discuss manual methods for resolving migration issues. The following migration issues are discussed:
■Overlapping IP Addresses
■Untranslatable IP Addresses
■Network Devices with More Than 40 IP Addresses
■Invalid TACACS+ Shell Privilege Level
■TACACS+ Custom Attributes Are Not Migrated
■Shell Command Authorization Set Not Associated with User or Group
Overlapping IP Addresses
The Analysis phase might report overlapping IP addresses for network devices in ACS 4.x. ExampleOverlapping IP Addresses shows that the IP address in the AA network device overlaps with the IP address in the BB network device, and each network device belongs to a different NDG. From the ACS 4.x perspective, these are two separate objects.
ExampleOverlapping IP Addresses
The following Network Devices are overlapped:
Network device: AA, IP Address = 23.8.23.*, 45.67.*.8, protocol =RADIUS, Group= HR
Network device: BB, IP Address = 45.*.6.8, 1.2.3.4, protocol =TACACS, Group = Admin
However, ACS 5.8.1 defines TACACS+ and RADIUS as one object.
The solution is to use the ACS 4.x application to redefine the network devices to have identical IP addresses and ensure that they belong to the same NDG. ExampleResolved IP Addresses illustrates the resolution.
ExampleResolved IP Addresses
Network device: CC, IP Address = 1.2.3.*, protocol =RADIUS, Group= HR
Network device: DD, IP Address = 1.2.3.*, protocol =TACACS, Group = HR
In this example, you consolidate the RADIUS and TACACS+ network devices; the IP addresses are identical and both network devices are part of the same NDG. You can export CC and DD as one object named CC+DD.
Untranslatable IP Addresses
The IP address definition in ACS 4.x can include wildcards and ranges. In ACS 5.8.1, the IP address definition is in the form of a subnet mask. The analysis phase identifies network groups with untranslatable IP addresses.
You can use the ACS 4.x application to modify the IP address ranges to an ACS 5.8.1 subnet mask definition. However, not all combinations of IP addresses can be translated into an ACS 5.8.1 subnet mask definition. For example:
Network device: AA, IP Address =23.8.23.12-221 protocol =RADIUS, Group= HR
In this example, the IP address contains a range, 12-221, and cannot be translated into a subnet mask definition.
You cannot migrate IP addresses that contain wildcards (*) or ranges (x-y) in the middle of the address. You cannot migrate the following pattern of IP addresses:
■1.*.2.*,
■*.*.*.1,
■*.*.*.*
The following patterns of IP addresses can be translated:
■1.*.*.*
■1.2.*.*
■1.2.3.*
■1.2.3.13-17
Note: Migration supports IP ranges from 0 to 255.
Network Devices with More Than 40 IP Addresses
Condition
Network devices in ACS 4.x have more than 40 IP addresses. ACS 5.8.1 does not migrate network devices that have more than 40 IP addresses.
Action
Use the ACS 4.x application on the migration machine and edit the network device settings. To do this:
1. Choose Network Configuration.
2. Choose the NDG to which the network device belongs.
3. Choose the network device.
4. Edit the AAA Client IP Address field. Ensure that the AAA client has 40 or fewer IP addresses.
5. Click Submit + Apply.
Rerun the Migration Utility (Analyze and Export phase and Import phase).
Invalid TACACS+ Shell Privilege Level
Condition
TACACS+ (T+) shell privilege level not in the range 0 to 15.
Action
Use the ACS 4.x application on the migration machine and edit T+ settings. Ensure that the T+ privilege level is in the range 0 to 15.
To edit the T+ settings at the user level:
1. Choose User Setup.
2. Choose the user.
The Edit screen appears.
3. Check the Privilege level check box of the TACACS+ Settings table and enter a value between 0 and 15.
4. Click Submit.
To edit the T+ settings at the group level:
1. Choose Group Setup.
2. Choose the group and click Edit Settings.
3. Check the Privilege level check box of the TACACS+ Settings table and enter a value between 0 and 15.
4. Click Submit + Restart.
Rerun the Migration Utility (Analyze and Export phase and Import phase).
TACACS+ Custom Attributes Are Not Migrated
Condition
T+ custom attributes are defined for users and groups in ACS 4.x. ACS 5.8.1 does not support TACACS+ custom attributes.
Action
No action is required. All the other T+ shell exec attributes that are defined for users and groups are not migrated. T+ custom attributes are dropped.
Shell Command Authorization Set Not Associated with User or Group
Condition
Shell command authorization sets are assigned to users and user groups in ACS 4.x. After migration, the association between the shell command authorization set and the User or Group is lost.
Action
Use the ACS 5.8.1 application to:
1. Access the migrated command sets. See Command Set Migration, for more information.
2. Create a policy for the users and identity groups.
See the User Guide for Cisco Secure Access Control System 5.8.1 for more information on creating policies.
Migration Failed with Manually Created Super Admin
Condition
User Admin1 is created under System Administration > Administrators > Accounts, with the role as a super admin in ACS 5.8.1. Migration fails when Admin1 is used as the administrator username.
Action
Check if the migration steps are correct. ACS 5.8.1 now supports migration with any ACS administrator account assigned with recovery superadmin role.
Migration Utility Messages
The following tables describe the error and informational messages that may appear during the migration of various ACS objects.
■Downloadable ACLs
■MABs
■NDGs
■Master Keys
■Network Devices
■RACs
■Command Set
■Shell Exec
■Users
■User Attributes
■User Attribute Values
■User Groups
■VSA Vendors
■VSAs
Downloadable ACLs
Table 1 gives the detail of the errors and informational messages that may appear during the migration of the Downloadable ACLs.
Table 1 Error and Informational Messages for Downloadable ACLs
|
|
|
|
Export |
Information |
Shared DACL name after migration has been changed to: name after truncation. |
Truncation |
Export |
Error |
Cannot migrate a shared DACL with a name that contains any of the following characters: illegal characters for the object. |
Name error |
Import |
Error |
Error from PI. For example, object already exists in the ACS 5.8.1 database. |
None |
MABs
Table 2 gives the detail of the errors and informational messages that may appear during the migration of the MABs.
Table 2 Error and Informational Messages for MABs
|
|
|
|
Export |
Information |
MAB name after migration has been changed to: name after truncation. |
Truncation |
Export |
Information |
Cannot migrate a MAB with a name that contains any of the following characters: illegal characters for the object. |
Name error |
Export |
Information |
Invalid MAC ID. |
Untranslatable |
Import |
Error |
Error from PI. For example, Object already exists in the ACS 5.8.1 database. |
None |
Import |
Error |
Group ID: group ID referenced object was not imported. |
No reference import |
Import |
Error |
Group could not be found for: MAB name Group ID: group ID. |
Log error |
NDGs
Table 3 gives the detail of the errors and informational messages that may appear during the migration of the NDGs.
Table 3 Error and Informational Messages for NDGs
|
|
|
|
Export |
Information |
Network device name after migration has been changed to: name after truncation. |
Truncation |
Export |
Information |
Cannot migrate an NDG with a name that contains any of the following characters: illegal characters for the object. |
Name error |
Export |
Information |
NDG has a shared key password. |
Password included |
Import |
Error |
Error from PI. For example, failed to add object: NDG root name in function: method name. |
None |
Import |
Information |
Object already exists in the ACS 5.8.1 database. |
Duplicate |
Master Keys
Table 4 gives the detail of the errors and informational messages that may appear during the migration of the Master Keys.
Table 4 Error and Informational Messages for Master Keys
|
|
|
|
Export |
Information |
Fatal Error: Authority ID is null - Import Failed. |
None |
Import |
Error |
Error from PI. For example, object already exists in the ACS 5.8.1 database. |
None |
Network Devices
Table 5 gives the detail of the errors and informational messages that may appear during the migration of the Network Devices.
Table 5 Error and Informational Messages for Network Devices
|
|
|
|
Export |
Information |
Network device name after migration has been changed to: name after truncation. |
Truncation. |
Export |
Information |
Network Device has shared key password. |
Password included. |
Export |
Information |
NDG referenced NDG unified with Name of the Network device overlapped with from NDG NDG name. |
Unified NDG: Referenced NDG. |
Export |
Error |
Cannot migrate an NDG with a name that contains any of the following characters: Illegal characters for the object. |
Name error. |
Export |
Error |
NDG referenced object was not exported. |
No reference object exported. |
Export |
Error |
NDG: referenced NDG there are number of subnets subnets in the following IP address IP address. |
Over subnet limit. |
Export |
Error |
Unable to translate network device IP address. |
Untranslatable NDG: Referenced NDG. |
Export |
Error |
NDG referenced NDG : Network device IP address overlaps the same device. |
Overlapping NDG: Referenced NDG. |
Export |
Error |
Network device has been discarded as it is unified with: unified NDG. |
Unified partner NDG: Referenced NDG. |
Export |
Error |
Network device IP is overlapping with other device. |
Overlapping NDG: Referenced NDG. |
Export |
Error |
Overlaps with: Network device name from NDG: NDG name. |
Overlapping NDG: Referenced NDG IP address: IP address. |
Import |
Error |
NDG referenced object was not imported. |
No reference import. |
Import |
Error |
Error from PI. For example, Object already exists in the ACS 5.x database. |
None. |
RACs
Table 6 gives the detail of the errors and informational messages that may appear during the migration of the RACs.
Table 6 Error and Informational Messages for RACs
|
|
|
|
Export |
Information |
RAC name after migration has been changed to: name after truncation. |
Truncation |
Export |
Error |
ACS 5.8.1 does not support this attribute: vid= vendor ID, att= attribute value. No other attributes in RAC will be migrated. |
Unsupported vendor |
Export |
Error |
RAC does not contain any supported attributes. |
No value |
Export |
Error |
Cannot migrate an RAC with a name that contains any of the following characters: Illegal characters for the object. |
Name error |
Export |
Error |
Wrong enum value for attribute: attribute name. No other attributes in RAC will be migrated. |
Error |
Export |
Error |
Invalid value for attribute: VSA attribute name. No other attributes in RAC will be migrated. |
Error |
Export |
Information |
The following attribute was not migrated: attribute name. |
Unsupported vendor |
Export |
Error |
ACS 5.8.1 does not support this attribute: vid= vendor ID, att= attribute value, name= attribute name. No other attributes in RAC will be migrated. |
Unsupported vendor |
Import |
Error |
RAC exception, for example, Invalid attribute number. |
None |
Import |
Error |
Error from PI. For example, Object already exists in the ACS 5.8.1 database. |
None |
Import |
Fatal |
An error occurred in createCapabilitiesAll(): Exception details. |
Log error |
Command Set
Table 7 gives the detail of the errors and informational messages that may appear during the migration of the Command Sets.
Table 7 Error and Informational Messages for Command Sets
|
|
|
|
Export |
Information |
Command set name after migration has been changed to: name after truncation. |
Truncation |
Export |
Information |
Identical objects cannot be migrated: identical object name. |
Consolidated |
Export |
Information |
Command set value: Invalid Command Set value. |
Untranslatable |
Export |
Information |
Cannot migrate a command set with a name that contains any of the following characters: Illegal characters for the object. |
Name error |
Export |
Information |
Command set name was not imported and shell exec and command set for this user/group were not imported. |
Name error |
Export |
Information |
Shared command sets name cannot contain apostrophes or curly braces. |
Name error |
Export |
Information |
Command Set name contains a duplicate argument. |
With duplicate argument |
Export |
Information |
The selected network device NDG is not supported. |
Unsupported option |
Export |
Error |
Translation failed. The argument does not start with Unmatched. |
Log error |
Export |
Error |
Translation failed. An equals sign (=) is missing after Unmatched |
Log error |
Export |
Fatal |
Translation failed since Unmatched is not set to permit or deny: unmatched value. |
Log error |
Export |
Error |
Group T+ shell command translation failed: exception details. |
Log error |
Export |
Error |
Group T+ shell command translation failed. The argument is not a prefix with permit/deny: argument action value. |
Log error |
Export |
Error |
Command name Group T+ command set translation failed: exception details. |
Log error |
Export |
Error |
Command description, Exception details. |
Log error |
Import |
Error |
Referenced object was not imported. |
No reference import |
Import |
Error |
Error from PI. For example, object already exists in the ACS 5.8.1 database. |
Error |
Shell Exec
Table 8 gives the detail of the errors and informational messages that may appear during the migration of the shell exec.
Table 8 Error and Informational Messages for Shell Exec
|
|
|
|
Export |
Information |
Command set name after migration has been changed to: name after truncation. |
Truncation |
Export |
Information |
Identical objects cannot be migrated: identical object name. |
Consolidated |
Export |
Information |
Shell Exec value Invalid shell exec value. No other T+ shell exec attributes will be migrated. |
Untranslatable |
Export |
Information |
Parsing error. No other T+ shell exec attributes will be migrated. |
Untranslatable |
Export |
Information |
Cannot migrate a command set with a name that contains any of the following characters: Illegal characters for the object. No other T+ shell exec attributes will be migrated. |
Name error |
Export |
Information |
Shell Exec name was not imported and shell exec and command set for this user/group were not imported. No other T+ shell exec attributes will be migrated. |
Name error |
Export |
Information |
ACS 5.8.1 does not support custom attributes present in T+ shell exec. No other T+ shell exec attributes will be migrated. |
Inset |
Export |
Information |
T+ shell exec not defined for user or user group. No other T+ shell exec attributes will be migrated. |
Inset |
Export |
Information |
Idle time for shell exec should be in the range of 0-9999. No other T+ shell exec attributes will be migrated. |
Invalid idle time |
Export |
Information |
Time out for shell exec should be in the range of 0-9999. No other T+ shell exec attributes will be migrated. |
Invalid timeout |
Export |
Information |
T+ shell priv-lvl is invalid value. No other T+ shell exec attributes will be migrated. |
Invalid privilege level |
Export |
Information |
T+ shell priv-lvl value is higher than max-priv-lvl max value. No other T+ shell exec attributes will be migrated. |
Invalid privilege level |
Export |
Information |
ACS 5.8.1 does not support custom attributes present in T+ shell exec. |
Unsupported option |
Export |
Error |
Group T+ shell exec translation failed: exception details. |
Log error |
Export |
Error |
An error occurred while retrieving the max privilege: exception details. |
Log error |
Import |
Error |
Referenced object was not imported. |
No reference import |
Import |
Error |
Error from PI. For example, object already exists in the ACS 5.8.1 database. |
Error |
Users
Table 9 gives the detail of the errors and informational messages that may appear during the migration of the Users.
Table 9 Error and Informational Messages for Users
|
|
|
|
Export |
Information |
User name after migration has been changed to: name after truncation. |
Truncation |
Export |
Error |
Cannot migrate users with names that contain any of the following characters: Illegal characters for the object. |
Name error |
Export |
Error |
Cannot migrate users whose password does not conform to the ACS 5 password policy. Passwords should be between 4 and 32 characters in length. |
Password error |
Export |
Error |
Cannot migrate users with empty password to ACS 5.8.1. |
No password |
Export |
Error |
Cannot migrate VoIP users to ACS 5.8.1. |
VoIP group |
Export |
Error |
A problem occurred while reading the expiry data for the user. |
Log error |
Import |
Error |
Referenced object was not imported. |
No reference import |
Import |
Error |
Group could not be found for: MAB name Group ID: group ID. |
Log error |
User Attributes
Table 10 gives the detail of the errors and informational messages that may appear during the migration of the User attributes.
Table 10 Error and Informational Messages for User Attributes
|
|
|
|
Export |
Information |
User attribute after migration has been changed to: name after truncation. |
Truncation |
Export |
Information |
Cannot migrate a user attribute with a name that contains any of the following characters: Illegal characters for the object. |
Name error |
Export |
Information |
User attribute name User-defined name is not unique. It will be disambiguated for import by appending a suffix. |
Repeated |
Import |
Information |
Attribute added with warning: Object already exists in the ACS 5.8.1 database. |
Duplicate |
Import |
Error |
Error from PI. |
Error |
User Attribute Values
Table 11 gives the detail of the errors and informational messages that may appear during the migration of the User attribute values.
Table 11 Error and Informational Messages for User Attribute Values
|
|
|
|
Export |
Error |
User attribute value was not imported and user attribute values for this user were not imported. |
Log error |
User Groups
Table 12 gives the detail of the errors and informational messages that may appear during the migration of the User Groups.
Table 12 Error and Informational Messages for User Groups
|
|
|
|
Export |
Error |
Group has no users. |
Without users |
Export |
Error |
Cannot migrate a user group with a name that contains any of the following characters: Illegal characters for the object. |
Name error |
Import |
Information |
Error from PI. |
Duplicate |
Import |
Error |
Error from PI. |
Error |
VSA Vendors
Table 13 gives the detail of the errors and informational messages that may appear during the migration of the VSA vendors IDs.
Table 13 Error and Informational Messages for VSA Vendors
|
|
|
|
Export |
Error |
Object already exists in the ACS 5.8.1 database. |
Duplicate |
Export |
Information |
Vendor name conflict. ACS 5.8.1 vendor name: vendor name. |
Name error |
Import |
Error |
VSA vendor ID vendor id import failed. Error from PI : |
Enum error |
VSAs
Table 14 gives the detail of the errors and informational messages that may appear during the migration of VSAs.
Table 14 Error and Informational Messages for VSAs
|
|
|
|
Export |
Error |
VSA ID attribute id value has attribute profile conflicts: In ACS 4.x, it is name for the profile, but in ACS 5.0, it is direction value. |
Profile error |
Export |
Error |
VSA ID (attribute id) has attribute name conflicts: In ACS 4.x, it is attribute name, but in ACS 5.8.1, it is attribute name. |
Name error |
Import |
Error |
VSA ID attribute id has attribute type conflicts: In ACS 4.x, it is attribute type, but in ACS 5.0, it is ACS 5.8.1 attribute type value. |
Type error |
Export |
Error |
There is a problem with the VSA ID attribute id enum values (see log for details) |
Enum error |
Export |
Error |
Object already exists in the ACS 5.8.1 database. |
None |
Import |
Error |
VSA attribute id enum import failed. Error from PI: |
Enum error |
Import |
Information |
VSA attribute ID enabling log failed. |
None |
Import |
Error |
VSA attribute ID attribute import failed. Error from PI. |
Unsupported attribute |
Import |
Error |
VSA attribute ID vendor ID vendor ID import failed. Error from PI. |
No reference import |
Reporting Issues to Cisco TAC
Note: Technical Support for ACS is limited to standard Cisco product installation, configuration, and operational troubleshooting. Questions and support issues related to ACS 4.x to 5.8.1 migration are not covered by Cisco Technical Support.
Note: The Cisco Technical Assistance Center (TAC) does not offer any support for migrating from Cisco Secure ACS for Windows or Solutions Engine to ACS 5.x. Contact your account team for assistance.
Include information about the following when you report a case to Cisco TAC:
■Backup of the ACS 4.x database (.dmp file)
■Migration logfile (...migration/bin/migration.log)
■All the reports in the config folder (...migration/config)
■ACS 5.8.1 logfiles
■ACS 5.8.1 build number
■ACS 4.x build number