Migration Guide for the Cisco Secure Access Control System 5.1
Troubleshooting the Migration Utility
Downloads: This chapterpdf (PDF - 226.0KB) The complete bookPDF (PDF - 6.95MB) | Feedback

Troubleshooting the Migration Utility

Table Of Contents

Troubleshooting the 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.1 Machine Does Not Respond After Import

Resolving Migration Issues

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

Migration Failed with Manually Created Super Admin

Migration Utility Messages

Downloadable ACLs

MABs

NDGs

Master Keys

Network Devices

RACs

Command Set

Shell Exec

Users

User Attributes

User Attribute Values

User Groups

VSA Vendors

VSAs

Reporting Issues to the Cisco TAC


Troubleshooting the Migration Utility


This chapter describes common problems associated with the ACS 5.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.1 Machine Does Not Respond After Import

Resolving Migration Issues

Migration Failed with Manually Created Super Admin

Migration Utility Messages

Reporting Issues to the 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

Cisco recommends 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.1 server

Network connections are enabled

ACS 5.1 services are up and running

You use a compatible ACS 5.1 license

2. Restore the ACS 5.1 database to its previous version of the database.

3. Restart the Migration Utility.

4. Rerun the Import phase.

ACS 5.1 Machine Does Not Respond After Import

Condition

ACS 5.1 machine does not respond after import.

Action

Restart ACS 5.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. Example D-1 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.

Example D-1 Overlapping 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.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. Example D-2 illustrates the resolution.

Example D-2 Resolved 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.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.1 subnet mask definition. However, not all combinations of IP addresses can be translated into an ACS 5.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,

*.*.*.*

1.2.3.13-17

The following patterns of IP addresses can be translated:

1.*.*.*

1.2.*.*

1.2.3.*


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


Step 1 Choose Network Configuration.

Step 2 Choose the NDG to which the network device belongs.

Step 3 Choose the network device.

Step 4 Edit the AAA Client IP Address field. Ensure that the AAA client has 40 or fewer IP addresses.

Step 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:


Step 1 Choose User Setup.

Step 2 Choose the user.

The Edit screen appears.

Step 3 Check the Privilege level check box of the TACACS+ Settings table and enter a value between 0 and 15.

Step 4 Click Submit.


To edit the T+ settings at the group level:


Step 1 Choose Group Setup.

Step 2 Choose the group and click Edit Settings.

Step 3 Check the Privilege level check box of the TACACS+ Settings table and enter a value between 0 and 15.

Step 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.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 on 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.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.

Refer to the User Guide for the Cisco Secure Access Control System 5.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.1. Migration failed when tried to give Admin1 as the administrator username.

Action

No action is required. ACS 5.1 supports only default superadmin acsadmin and does not support manual users.

Migration Utility Messages

The following tables describe the error and informational messages that may appear during the migration of various ACS objects. This section contains:

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 D-1 gives the detail of the errors and informational messages that may appear during the migration of the Downloadable ACLs.

Table D-1 Error and Informational Messages for Downloadable ACLs 

Phase
Type
Error
Diagnosis

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.1 database.

None


MABs

Table D-2 gives the detail of the errors and informational messages that may appear during the migration of the MABs.

Table D-2 Error and Informational Messages for MABs

Phase
Type
Error
Diagnosis

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.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 D-3 gives the detail of the errors and informational messages that may appear during the migration of the NDGs.

Table D-3 Error and Informational Messages for NDGs 

Phase
Type
Error
Diagnosis

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.1 database.

Duplicate


Master Keys

Table D-4 gives the detail of the errors and informational messages that may appear during the migration of the Master Keys.

Table D-4 Error and Informational Messages for Master Keys

Phase
Type
Error
Diagnosis

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.1 database.

None


Network Devices

Table D-5 gives the detail of the errors and informational messages that may appear during the migration of the Network Devices.

Table D-5 Error and Informational Messages for Network Devices 

Phase
Type
Error
Diagnosis

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 D-6 gives the detail of the errors and informational messages that may appear during the migration of the RACs.

Table D-6 Error and Informational Messages for RACs 

Phase
Type
Error
Diagnosis

Export

Information

RAC name after migration has been changed to: name after truncation.

Truncation

Export

Error

ACS 5.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.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.1 database.

None

Import

Fatal

An error occurred in createCapabilitiesAll(): Exception details.

Log error


Command Set

Table D-7 gives the detail of the errors and informational messages that may appear during the migration of the Command Sets.

Table D-7 Error and Informational Messages for Command Sets 

Phase
Type
Error
Diagnosis

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.1 database.

Error


Shell Exec

Table D-8 gives the detail of the errors and informational messages that may appear during the migration of the shell exec.

Table D-8 Error and Informational Messages for Shell Exec 

Phase
Type
Error
Diagnosis

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.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.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.1 database.

Error


Users

Table D-9 gives the detail of the errors and informational messages that may appear during the migration of the Users.

Table D-9 Error and Informational Messages for Users

Phase
Type
Error
Diagnosis

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

No password

Export

Error

Cannot migrate VoIP users to ACS 5.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 D-10 gives the detail of the errors and informational messages that may appear during the migration of the User attributes.

Table D-10 Error and Informational Messages for User Attributes 

Phase
Type
Error
Diagnosis

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.1 database.

Duplicate

Import

Error

Error from PI.

Error


User Attribute Values

Table D-11 gives the detail of the errors and informational messages that may appear during the migration of the User attribute values.

Table D-11 Error and Informational Messages for User Attribute Values

Phase
Type
Error
Diagnosis

Export

Error

User attribute value was not imported and user attribute values for this user were not imported.

Log error


User Groups

Table D-12 gives the detail of the errors and informational messages that may appear during the migration of the User Groups.

Table D-12 Error and Informational Messages for User Groups

Phase
Type
Error
Diagnosis

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 D-13 gives the detail of the errors and informational messages that may appear during the migration of the VSA vendors IDs.

Table D-13 Error and Informational Messages for VSA Vendors

Phase
Type
Error
Diagnosis

Export

Error

Object already exists in the ACS 5.1 database.

Duplicate

Export

Information

Vendor name conflict. ACS 5.1 vendor name: vendor name.

Name error

Import

Error

VSA vendor ID vendor id import failed. Error from PI:

Enum error


VSAs

Table D-14 gives the detail of the errors and informational messages that may appear during the migration of VSAs.

Table D-14 Error and Informational Messages for VSAs

Phase
Type
Error
Diagnosis

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.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.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.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 the Cisco TAC


Note Cisco 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.1 migration are not covered by Cisco Technical Support.
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 the 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.1 logfiles

ACS 5.1 build number

ACS 4.x build number