G
Using the User Migration Utility

This chapter describes the User Migration Utility, which can be used to perform bulk migrations of database users to an LDAP directory where they are stored and managed as enterprise users. It contains the following topics:

• Benefits of Migrating Local or External Users to Enterprise Users
• Introduction to the User Migration Utility
• Prerequisites for Performing Migration
• User Migration Utility Command Line Syntax
• Accessing Help for the User Migration Utility
• User Migration Utility Parameters
• User Migration Utility Usage Examples
• Troubleshooting Using the User Migration Utility

Benefits of Migrating Local or External Users to Enterprise Users

Migrating from a database user model to an enterprise user model provides solutions to administrative, security, and usability challenges in an enterprise environment. In an enterprise user model, all user information is moved to an LDAP directory service.

Enterprise user security provides the ability to easily and securely manage enterprise-wide users by providing the following benefits:

• Centralized storage of user credentials, roles, and privileges in an LDAP version 3-compliant directory server
• Provides the infrastructure to enable single sign-on using X.509v3-compliant certificates, which is typically deployed where end-to-end SSL is required
• Enhanced security

  Because an enterprise user model is easier to manage, security administrators can perform necessary maintenance changes to user information immediately so they have better control over access to critical network resources. In addition, an enterprise user model is easier for users to use because they have fewer passwords to remember so they are less likely to choose easily guessed passwords or write them down where others can copy them.

  See Also: "Introduction to Enterprise User Security" for detailed conceptual information about enterprise user security.

Introduction to the User Migration Utility

The User Migration Utility is a command-line utility that is used when enterprise user administrators decide to move their users from a local database model to an enterprise user model. This utility makes it easy to migrate thousands of local and external database users to an enterprise user environment in an LDAP directory where they can be managed from a central location. It uses the Oracle JDBC OCI driver to connect to the database.

Enterprise user administrators can select for migration any combination of the following user subsets in a database:

• List of users specified on the command line or in a file
• All external users
• All global users

In addition, enterprise user administrators can specify values for utility parameters that determine how the users are migrated such as

• Where to put the migrated users in the LDAP directory tree
• Map a user with multiple accounts on various databases to a single directory user entry

The following sections explain the migration process and the changes that occur to users' schemas.

Bulk User Migration Process Overview

Bulk user migration is a two-phase process. In phase one, you start the migration process by populating user information into an interface database table, where enterprise user administrators can verify that the information is accurate before committing the changes to the database and the directory in phase two. The process is described in the following steps:

• Step 1: Phase One Preparing for the Migration
• Step 2: Verify User Information
• Step 3: Phase Two Completing the Migration

Step 1: Phase One Preparing for the Migration

In the first part of the migration process, the utility checks if the ORCL_GLOBAL_USR_MIGRATION_DATA interface table exists in the enterprise user administrator's schema. If it exists, then the administrator can choose to reuse the table (clearing its contents), reuse the table and its contents, or re-create the table. Phase one can be run multiple times, each time adding to the interface table. If the table does not exist, then the utility creates it in the administrator's schema. The interface table is populated with information about the migrating users from the database and the directory. The command line options used determine what information populates this table.

Step 2: Verify User Information

This is an intermediate step to allow the enterprise user administrator to verify that the user information is correct in the interface table before committing the changes to the database and the directory.

Step 3: Phase Two Completing the Migration

After the interface table user information is checked, then in phase two the utility retrieves the information from the table and updates the directory and the database.

Depending on whether directory entries exist for migrating users, the utility creates random passwords as follows:

• If migrating users are being mapped to newly created directory entries, then the utility generates random passwords, which are used as credentials for both the database and directory.
• If migrating users are being mapped to existing directory entries with unset database passwords, then the utility generates random database passwords only.

In either case, after generating the required random passwords, the utility then stores them in the DBPASSWORD and DIRPASSWORD interface table columns. The enterprise user administrator can read these passwords from the interface table and inform migrating users.

About the ORCL_GLOBAL_USR_MIGRATION_DATA Table

This is the interface table which is populated with information about the migrating users during phase one of the bulk user migration process. The information that populates this table is pulled from the database and checked against existing entries in the directory. If there is corresponding information in the directory, then that is marked in the table for that user. After enterprise user administrators verify the information in this table, changes are made to the directory and the database in phase two.

The table columns are listed in Table G-1.

Table G-1  ORCL_GLOBAL_USR_MIGRATION_DATA Table Schema

Column Name	DataType	Null	Description
USERNAME (Primary Key)	VARCHAR2(30)	NOT NULL	Database user name.
OLD_SCHEMA_TYPE	VARCHAR2(10)	-	Old schema type in the database before migration.
PASSWORD_VERIFIER	VARCHAR2(30)	-	Not used
USERDN	VARCHAR2(4000)	-	Distinguished Name (DN) of the user in the directory (new or existing).
USERDN_EXIST_FLAG	CHAR(1)	-	Flag indicating whether the DN already exists in the directory.
SHARED_SCHEMA	VARCHAR2(30)	-	Shared schema name, if users are to be mapped to a shared schema during phase two.
MAPPING_TYPE	VARCHAR2(10)	-	Mapping type (database or domain).
MAPPING_LEVEL	VARCHAR2(10)	-	Mapping level (entry or subtree).
CASCADE_FLAG	CHAR(1)	-	Cascade flag used when dropping a user (for shared schema mapping only).
DBPASSWORD_EXIST_FLAG	CHAR(1)	-	Flag indicating whether the database password verifier already exists in the directory for this user.
DBPASSWORD	VARCHAR2(30)	-	Randomly generated database password verifiers that are to be stored in the directory.
DIRPASSWORD	VARCHAR2(30)	-	Randomly generated directory password for new entries.
PHASE_COMPLETED	VARCHAR2(10)	-	Information about the phase that has completed successfully.
NEEDS_ATTENTION_FLAG	CHAR(1)	-	Flag indicating whether the row contains abnormalities that require administrator attention.
ATTENTION_DESCRIPTION	VARCHAR2(100)	-	Textual hint for the administrator if the attention flag is set.

Which Interface Table Column Values Can Be Modified between Phase One and Phase Two?

After running phase one of the utility, if necessary, enterprise user administrators can change the interface table columns that are listed in Table G-2.

Table G-2  Interface Table Column Values That Can Be Modified between Phase One and Phase Two

Column Name	Valid Values	Restrictions
USERDN	DN of user	If this value is changed, then the administrator should verify that the USERDN_EXIST_FLAG and the DBPASSWORD_EXIST_FLAG values are set accordingly.
USERDN_EXIST_FLAG	T/F	If the USERDN column value changes, then this column value should also change to reflect the new USERDN status.
DBPASSWORD_EXIST_FLAG	T/F	If the USERDN column value changes, then this column value should also change to reflect whether a database password exists for the new USERDN.
SHARED_SCHEMA	Shared schema name	Specify only if a shared schema exists in the database.
MAPPING_TYPE	DB/DOMAIN	Set this value only if SHARED_SCHEMA is not set to NULL.
MAPPING_LEVEL	ENTRY/SUBTREE	Set this value only if SHARED_SCHEMA is not set to NULL.
CASCADE_FLAG	T/F	Set this value only if SHARED_SCHEMA is not set to NULL. If this column is set to true (T), then the users' schema objects are forcibly deleted. If this column is set to false (F), then the administrator must delete all user schema objects before running phase two.
PHASE_COMPLETED	ZERO/ONE/TWO	If the administrator can resolve the conflicts or ambiguities that are specified with the NEEDS_ATTENTION_FLAG, then this column value can be changed to ONE so phase two can be run with the utility.

Migration Effects on Users' Old Database Schemas

If shared schema mapping is not used, then users retain their old database schemas. If shared schema mapping is used, then users' local schemas are dropped from the database and they are mapped to a shared schema that the enterprise user administrator creates for this purpose before performing the migration. When migrated users own database objects in their old local database schemas, administrators can specify that the schema and objects are not to be dropped by setting the CASCADE parameter to NO. When the CASCADE parameter is set to NO, users who own database objects in their old local schemas do not migrate successfully so their objects are not dropped.

If some users want to retain the objects in their local database schemas and be mapped to a shared schema, then the administrator can manually migrate those objects to the shared schema before performing the bulk user migration. However, when objects are migrated to a shared schema, they are shared among all users who share that new schema.

Table G-3 summarizes the effects of setting the MAPSCHEMA and CASCADE parameters.

Table G-3 Effects of Choosing Shared Schema Mapping with CASCADE Options

MAPSCHEMA Parameter Setting	CASCADE Parameter Setting	User Migration Successful?	User Schema Objects Dropped?
PRIVATE	NO (default setting)	Yes	No
SHARED	NO	YesFoot 1	No
SHARED	YES	YesFoot 2	Yes

1 Users migrate successfully only if they do not own objects in their old database schemas; otherwise, they fail. 2 Users migrate successfully and their old database schemas are dropped.

Migration Process

Enterprise users, those that are defined and managed in the directory, can be authenticated to the database either with a password or with a certificate. Users that authenticate with a password require an Oracle database password, which is stored in the directory. Users that authenticate with a certificate must have a valid X.509 v3 certificate.

This utility performs the following steps during migration:

1. Selects the users from the database for migration.
2. Creates corresponding user entries or uses existing entries in the directory.
3. Creates new database passwords and copies the corresponding verifiers to the directory for migrating users.
4. Puts the schema mapping information for the migrating users' entries in the directory. (optional)
5. Drops or alters the migrating users' local database schemas. (optional)

   Note: In the current release, the utility migrates users with certificate-based authentication and makes them ready for password authentication. Previously SSL-based authenticated users should reset their Oracle database passwords. User wallets are not created as part of this process.

   See Also: Chapter 8, "Using Oracle Wallet Manager" for information about creating, managing, and using Oracle wallets.

Prerequisites for Performing Migration

The User Migration Utility is automatically installed in the following location when you install Oracle Database Client:

$ORACLE_HOME/rdbms/bin/umu

The following sections describe what programs must be running and what user privileges are required to successfully migrate users with the User Migration Utility.

Required Database Privileges

To successfully use this utility, enterprise user administrators must have the following database privileges:

• ALTER USER
• DROP USER
• CREATE TABLE
• SELECT_CATALOG_ROLE

These privileges enable the enterprise user administrator to alter users, drop users, look at dictionary views, and create the interface table that is used by this utility.

Required Directory Privileges

In addition to the required database privileges, enterprise user administrators must have the directory privileges which allow them to perform the following tasks:

• Create entries in the directory under the specified user base and Oracle context location
• Browse the user entries under the search bases

Required Setup to Run the User Migration Utility

Perform the following steps before using the User Migration Utility:

1. Ensure that the directory server is running with SSL enabled for no authentication.
2. Ensure that the database server is running with encryption and integrity enabled.
3. Ensure that the database listener has a TCP listening endpoint.
4. Create an identity management realm in the directory, if it does not already exist.
5. Create the parent context for the user entries in the directory, if it does not already exist. The default (and recommended) location is in the cn=users subtree in the identity management realm.
6. Set up directory access for the database Oracle home by using Oracle Net Configuration Assistant to create an ldap.ora file. Note that the ldap.ora file must include the identity management realm DN so the utility can locate the correct administrative context. The utility searches for this file under $LDAP_ADMIN, $ORACLE_HOME/ldap/admin, $TNS_ADMIN, $ORACLE_HOME/network/admin, and, finally, the Domain Name System (DNS) server, if you are using DNS discovery. (See Oracle Internet Directory Administrator's Guide for information about DNS server discovery.)

   Note: If you plan to use shared schema mapping when migrating users, then you must create the shared schema before running this utility. The same ldap.ora file must be used for both phase one and phase two of a user migration.

   See Also: Oracle Internet Directory Administrator's Guide Chapter 12, "Enterprise User Security Configuration Tasks and Troubleshooting" for detailed information about setting up enterprise user authentication after the user migration is finished.

User Migration Utility Command Line Syntax

To perform a bulk migration of database users to enterprise users, use the following syntax:

umu parameter1 parameter2 ...

For parameters that take a single value use the following syntax:

keyword=value

For parameters that take multiple values, use a colon (:) to separate the values as in the following syntax:

keyword=value1:value2:...

Example 13-1 shows the syntax used to run the utility through both phases of the bulk user migration process.

Example 13-1 User Migration Utility Command Line Syntax

umu PHASE=ONE

DBADMIN=dba_username:password
ENTADMIN=enterprise_admin_DN:password
USERS=[ALL_GLOBAL | ALL_EXTERNAL | LIST | FILE]
DBLOCATION=database_host:database_port:database_sid
DIRLOCATION=ldap_directory_host:ldap_directory_port
USERSLIST=username1:username2:username3:...
USERSFILE=filename
MAPSCHEMA=[PRIVATE | SHARED]:schema_name
MAPTYPE=[DB | DOMAIN]:[ENTRY | SUBTREE]
CASCADE=[YES | NO]
CONTEXT=user_entries_parent_location
LOGFILE=filename
PARFILE=filename

umu PHASE=TWO

DBADMIN=dba_username:password
ENTADMIN=enterprise_admin_DN:password
DBLOCATION=database_host:database_port:database_sid
DIRLOCATION=ldap_directory_host:ldap_directory_port
LOGFILE=filename
PARFILE=filename

Accessing Help for the User Migration Utility

To display the command-line syntax for using the User Migration Utility, enter the following command at the system prompt:

umu HELP=YES

While the HELP parameter is set to YES, the utility cannot execute.

User Migration Utility Parameters

The following sections list the available parameter keywords and the values that can be used with them when running this utility. The keywords are not case-sensitive.

Keyword: HELP

Valid Values:	YES or NO (These values are not case-sensitive.)
Default Setting:	NO
Syntax Examples:	HELP=YES
Description:	This keyword is used to display help for the utility. YES displays the complete command-line syntax. To execute a command, set the value to NO, or do not specify a value for the parameter to accept the default.
Restrictions:	None

Keyword: PHASE

Valid Values:	ONE or TWO (These values are not case-sensitive.)
Default Setting:	ONE
Syntax Examples:	PHASE=ONE PHASE=TWO
Description:	Indicates the phase for the utility. If it is ONE, then the utility populates the interface table with the information specified in the command-line arguments and the existing user entries in the directory. If it is TWO, then the utility uses the information that is available in the interface table and updates the directory and the database.
Restrictions:	None

Keyword: DBLOCATION

Valid Values:	host:port:sid
Default Setting:	No default setting.
Syntax Examples:	DBLOCATION=my_oracle.us.oracle.com:7777:ora902
Description:	Provides the host name, port number, and SID for the database instance.
Restrictions:	This parameter is mandatory. The value for this parameter must be the same for both phase one and phase two. The database should be configured for encryption and integrity.

Keyword: DIRLOCATION

Valid Values:	host:port
Default Setting:	This value is automatically populated from the ldap.ora file by default.
Syntax Examples:	DIRLOCATION=my_oracle.us.oracle.com:636
Description:	Provides the host name and port number for the directory server where the LDAP server is running on SSL with no authentication.
Restrictions:	The value for this parameter must be the same for both phase one and phase two.

Keyword: DBADMIN

Valid Values:	username:password
Default Setting:	No default setting.
Syntax Examples:	DBADMIN=system:manager
Description:	Username and password for the database administrator with the required privileges for connecting to the database.
Restrictions:	This parameter is mandatory. The username value for this parameter must be the same for both phase one and phase two.

Keyword: ENTADMIN

Valid Values:	userDN:password
Default Setting:	No default setting.
Syntax Examples:	ENTADMIN=cn=janeadmin,dc=acme,dc=com:welcome
Description:	User Distinguished Name (UserDN) and the directory password for the enterprise directory administrator with the required privileges for logging in to the directory. UserDN can also be specified within double quotation marks ("...").
Restrictions:	This parameter is mandatory.

Keyword: USERS

Valid Values:	value1:value2... Values can be: ALL_EXTERNAL to select all external users, including those who use Kerberos and RADIUS authentication ALL_GLOBAL to select all global users LIST to specify users on the command line with the "Keyword: USERSLIST" USERSFILE for selecting users from the file that is specified with the "Keyword: USERSFILE" This parameter takes multiple values. Separate values with a colon (:). (These values are not case-sensitive.)
Default Setting:	No default setting.
Syntax Examples:	USERS=ALL_EXTERNAL:ALL_GLOBAL This usage instructs the utility to migrate all external users and all global users. USERS=ALL_EXTERNAL:FILE This usage instructs the utility to migrate all external users and all users that are specified in the USERSFILE.
Description:	Specifies which users are to be migrated. If multiple values are specified for this parameter, then the utility uses the union of these sets of users.
Restrictions:	This parameter is mandatory for phase one only, and it is ignored in phase two.

Keyword: USERSLIST

Valid Values:	user1:user2:... Separate user names with a colon (:).
Default Setting:	No default setting.
Syntax Examples:	USERSLIST=jdoe:tchin:adesai
Description:	Specifies a list of database users for migration. The users in this list are migrated with other users that are specified with the USERS parameter.
Restrictions:	This optional parameter is effective only when LIST is specified with the USERS parameter.

Keyword: USERSFILE

Valid Values:	File name and path.
Default Setting:	No default setting.
Syntax Examples:	USERSFILE=/home/orahome/userslist/hr_users.txt
Description:	Specifies a file that contains a list of database users (one user listed for each line) for migration. The users in this file are migrated with other users that are specified with the USERS parameter.
Restrictions:	This optional parameter is effective only when FILE is specified with the USERS parameter.

Keyword: MAPSCHEMA

Valid Values:	schema_type:schema_name Schema type can be: PRIVATE Retains users' old local schemas. Schema name is ignored when schema type is PRIVATE. No mapping entries are created in the directory. SHARED Maps users to a shared schema. Mapping entries are created in the directory. Schema name specifies the shared schema name. During shared schema mapping, whether users' local schemas are dropped from the database is determined by the "Keyword: CASCADE" setting. (These values are not case-sensitive.)
Default Setting:	PRIVATE
Syntax Examples:	MAPSCHEMA=SHARED:HR_ALL
Description:	Specifies whether the utility populates the interface table with schema mapping information.
Restrictions:	See the SHARED option under Valid Values. This parameter is only valid for phase one.

Keyword: MAPTYPE

Valid Values:	mapping_type:mapping_level Mapping type can be: DB DOMAIN Mapping level can be: ENTRY SUBTREE Separate mapping type from mapping level with a colon (:). (These values are not case-sensitive.)
Default Setting:	DB:ENTRY
Syntax Examples:	MAPTYPE=DOMAIN:SUBTREE
Description:	Specifies the type of schema mapping that is to be applied when "Keyword: MAPSCHEMA" is set to SHARED. If DB is specified as the mapping type, then the utility creates a mapping in directory for the database. If DOMAIN is specified as the mapping type, then the utility creates a mapping in the directory for the domain containing the database. For domain mapping, the utility determines the domain that contains the database by an LDAP search in the relevant Oracle context.
Restrictions:	This parameter is effective only when MAPSCHEMA is set to SHARED.

Keyword: CASCADE

Valid Values:	NO When users are mapped to a shared schema, the utility tries to drop their local schemas from the database. If this parameter is set to NO, then users are migrated only if they do not own objects in their local schema. Users who own objects in their old local schemas do not migrate and produce an error message in the migration log file. YES If this parameter is set to YES, then all users' schema objects are dropped along with their local schemas when they are migrated. Privileges and roles that were previously granted to the users are also revoked. (These values are not case-sensitive.)
Default Setting:	NO
Syntax Examples:	CASCADE=YES
Description:	Specifies whether a user's local schema is dropped when the user is mapped to a shared schema.
Restrictions:	This parameter is effective only when MAPSCHEMA is set to SHARED.

Keyword: CONTEXT

Valid Values:	Distinguished Name (DN) of the parent for user entries. This is the same as the user search base or user create base in an Oracle Internet Directory identity management realm. Parent DN can also be specified within double quotation marks ("...").
Default Setting:	This value is automatically populated from the DEFAULT_ADMIN_CONTEXT setting in the ldap.ora file by default. This places new user entries directly under the Oracle Context's parent entry. In 10g Release 1 (10.1), this is not the preferred location for user entries, so do not use the default setting for this parameter unless it is specifically desired. Instead, Oracle recommends that you use "cn=Users, <realm_DN>" as your default. Refer to Figure 11-3, "Related Entries in a Realm Oracle Context" for a directory information tree diagram that shows an Oracle Context.
Syntax Examples:	CONTEXT="c=Users, c=us"
Description:	Specifies the DN of the parent entry under which user entries are created in the directory if there is no directory entry that matches the userID for the user.
Restrictions:	This parameter is only valid for phase one.

Keyword: LOGFILE

Valid Values:	File name and path.
Default Setting:	$ORACLE_HOME/network/log/umu.log
Syntax Examples:	LOGFILE=home/orahome/network/log/filename.log
Description:	Specifies the log file where details about the migration for each user are written.
Restrictions:	None

Keyword: PARFILE

Valid Values:	File name and path.
Default Setting:	No default setting.
Syntax Examples:	PARFILE=home/orahome/network/usr/par.txt
Description:	Specifies a text file which contains a list of these parameters that are intended to be used in a user migration. Each parameter must be listed on a separate line in the file. If a parameter is specified in both the parameter file and on the command line, then the one specified on the command line takes precedence.
Restrictions:	None

User Migration Utility Usage Examples

The following sections contain examples of the syntax for some typical uses of this utility.

Migrating Users While Retaining Their Own Schemas

To migrate users while retaining their old database schemas, set the MAPSCHEMA parameter to PRIVATE, which is the default setting. For example, to migrate users scott1, scott2, and all external database users, while retaining their old schemas, to the directory at c=Users, c=us with the newly generated database and directory passwords, the syntax shown in Example 13-2 is used.

Example 13-2 Migrating Users with MAPSCHEMA=PRIVATE (Default)

umu PHASE=ONE

DBLOCATION=machine1:1521:ora_sid
DBADMIN=system:manager
USERS=ALL_EXTERNAL:LIST
USERSLIST=scott1:scott2
DIRLOCATION=machine2:636
CONTEXT="c=Users,c=us"
ENTADMIN="cn=janeadmin":welcome

umu PHASE=TWO

DBLOCATION=machine1:1521:ora_sid
DBADMIN=system:manager
DIRLOCATION=machine2:636
ENTADMIN="cn=janeadmin":welcome

After phase one completes successfully, the interface table is populated with the user migration information. Then the enterprise user administrator can review the table to confirm its contents. Because no value was specified for the MAPSCHEMA parameter, the utility runs phase one using the default value, PRIVATE, so all users' old database schemas and objects are retained.

Migrating Users and Mapping to a Shared Schema

To migrate users and map them to a new shared schema, dropping their old database schemas, set the MAPSCHEMA parameter to SHARED. The shared schema must already exist or the enterprise user administrator must create it before running the utility with this parameter setting. In the following example, users scott1, scott2, and all external database users are migrated to the directory at c=Users, c=us with newly generated database and directory passwords, while mapping all migrated users to a new shared schema in the database.

Use the syntax shown in Example G-1 to run the migration process with MAPSCHEMA set to SHARED.

Example G-1 Migrating Users with MAPSCHEMA=SHARED

umu PHASE=ONE

DBLOCATION=machine1:1521:ora_sid
DBADMIN=system:manager
USERS=ALL_EXTERNAL:LIST
USERSLIST=scott1:scott2
MAPSCHEMA=SHARED:schema_32
DIRLOCATION=machine2:636
CONTEXT="c=Users, c=us"
ENTADMIN="cn=janeadmin":welcome

umu PHASE=TWO

DBLOCATION=machine1:1521:ora_sid
DBADMIN=system:manager
DIRLOCATION=machine2:636
ENTADMIN="cn=janeadmin":welcome

After phase one completes successfully, the interface table is populated with the user migration information. Then the administrator can review the table to confirm its contents. Users scott1, scott2, and the external users are assigned new randomly generated database and directory passwords. Because no value was specified for the CASCADE parameter, the utility runs phase one using the default value, NO, which means that migrating users who own database objects in their old database schemas will fail and their schemas will not be automatically dropped. To determine which users have failed, review the log file that is located at $ORACLE_HOME/network/log/umu.log by default.

Mapping Users to a Shared Schema Using Different CASCADE Options

The CASCADE parameter setting determines whether users' old database schemas are automatically dropped when mapping to a shared schema during migration. CASCADE can be used only when MAPSCHEMA is set to SHARED.

Mapping Users to a Shared Schema with CASCADE=NO

By default, the CASCADE parameter is set to NO. This setting means that when mapping migrating users to a shared schema, users who own database objects in their old schemas are not migrated. For users who do not own database objects, their old database schemas are automatically dropped and they are mapped to the new shared schema.

Mapping Users to a Shared Schema with CASCADE=YES

If it is known that no migrating users own database objects or want to retain the objects that they own in their old database schemas, then setting the CASCADE parameter to YES automatically drops all users' schemas and schema objects and maps them to the new shared schema. Example G-2 shows the syntax to use when setting CASCADE to YES. In this example, users scott1, scott2, and all external database users are migrated to the directory at c=Users, c=us, while mapping all migrating users to a new shared schema in the database.

Example G-2 Migrating Users with Shared Schema Mapping and CASCADE=YES

umu PHASE=ONE

DBLOCATION=machine1:1521:ora_sid
DBADMIN=system:manager
USERS=ALL_EXTERNAL:LIST
USERSLIST=scott1:scott2
MAPSCHEMA=SHARED:schema_32
CASCADE=YES
DIRLOCATION=machine2:636
CONTEXT="c=Users, c=us"
ENTADMIN="cn=janeadmin":welcome

umu PHASE=TWO

DBLOCATION=machine1:1521:ora_sid
DBADMIN=system:manager
DIRLOCATION=machine2:636
ENTADMIN="cn=janeadmin":welcome

After phase one completes successfully, the interface table is populated with the user migration information. Then the administrator can review the table to confirm its contents. Because the CASCADE parameter is set to YES, all migrated users' old database schemas are automatically dropped, including those who own database objects.

Mapping Users to a Shared Schema Using Different MAPTYPE Options

When MAPSCHEMA is set to SHARED, the mapping type can be set by specifying a value for the MAPTYPE parameter. This parameter takes two values, which are the mapping type and the mapping level.

Mapping type can be set at DB, for database, or DOMAIN, for enterprise domain. When mapping type DB is specified, the mapping is applied only to the database where the shared schema is stored. When DOMAIN is specified as the mapping type, then the mapping is applied to the enterprise domain that contains the database where the shared schema is stored and also applies to all databases in that domain.

Mapping level can be set to ENTRY or SUBTREE. When ENTRY is specified then users are mapped to the shared schema using their full distinguished name (DN). This results in one mapping for each user. When SUBTREE is specified then groups of users who share part of their DNs are mapped together. This results in one mapping for user groups already grouped under some common root in the directory tree. Example G-3 shows the syntax to use when using the MAPTYPE parameter. In this example, users scott1, scott2, and all external database users are migrated to the directory at c=Users, c=us, while mapping all migrated users to a new shared schema in the database. In this example, the mapping will apply to the enterprise domain that contains the database and the mapping will be performed at the entry level, resulting in a mapping for each user.

Example G-3 Migrating Users with Shared Schema Mapping Using the MAPTYPE Parameter

umu PHASE=ONE

DBLOCATION=machine1:1521:ora_sid
DBADMIN=system:manager
USERS=ALL_EXTERNAL:LIST
USERSLIST=scott1:scott2
MAPSCHEMA=SHARED:schema_32
MAPTYPE=DOMAIN:ENTRY
DIRLOCATION=machine2:636
CONTEXT="c=Users, c=us"
ENTADMIN="cn=janeadmin":welcome

umu PHASE=TWO

DBLOCATION=machine1:1521:ora_sid
DBADMIN=system:manager
DIRLOCATION=machine2:636
ENTADMIN="cn=janeadmin":welcome

About Using the SUBTREE Mapping Level Option

If a user (scott, for example) who is being migrated will have future user entries in a subtree under it, then it makes sense to create a subtree level mapping from this user entry (cn=scott) to a schema. However, the database does not interpret the user to be in the subtree so the mapping does not apply to scott himself. For example, if you are migrating the user scott with the DN cn=scott,o=acme, and you choose SUBTREE as the mapping level when you run the utility, then a new mapping is created from cn=scott,o=acme to the shared schema, but the user scott is not mapped to that schema. Only new users who are created under the scott directory entry are mapped to the shared schema. Consequently, the SUBTREE mapping level should only be specified when user directory entries are placed under other user directory entries, which would be an unusual directory configuration.

If you want an arbitrary subtree user to be mapped to a single shared schema with only one mapping entry, then you must use Enterprise Security Manager to create that mapping.

Migrating Users Using the PARFILE, USERSFILE, and LOGFILE Parameters

It is possible to enter user information and User Migration Utility parameters into a text file and pass the information and parameters to the utility using the PARFILE and USERSFILE parameters. The LOGFILE parameter sets the directory path for the log file where details about the migration for each user are written.

The PARFILE parameter tells the utility where a text file is located that contains the parameters for a bulk user migration. The USERSFILE parameter works like the PARFILE parameter, except it contains database users instead of parameters. The parameters and users lists contain one parameter or user for each line. The LOGFILE parameter tells the utility where to write the system events that occur during a user migration, such as errors. Use the USERSFILE parameter during phase one of the migration process. The PARFILE and LOGFILE parameters can be used in both phases.

Example G-4 shows the syntax for a typical parameter text file to migrate users scott1, scott2, and all external database users, while retaining their old schemas, to the directory at c=Users, c=us. In this example a log of migration events is written to the file errorfile1 in the directory where the utility is run. If another location is desired, then include the path with the file name.

Example G-4 Parameter Text File (par.txt) to Use with the PARFILE Parameter

DBLOCATION=machine1:1521:ora_sid
DBADMIN=system:manager
USERS=ALL_EXTERNAL:LIST:FILE
USERSLIST=scott1:scott2
USERSFILE=usrs.txt
DIRLOCATION=machine2:636
CONTEXT="c=Users, c=us"
ENTADMIN="cn=janeadmin":welcome
LOGFILE=errorfile1

Example G-5 shows the syntax for a typical users list text file.

Example G-5 Users List Text File (usrs.txt) to Use with the USERSFILE Parameter

user1
user2
user3

To execute phase one of the migration process with these parameters and users list text files, use the syntax shown in Example G-6.

Example G-6 Migrating Users Using the PARFILE, USERSFILE, and LOGFILE Parameters

umu PHASE=ONE

DBADMIN=system:manager
PARFILE=par.txt
LOGFILE=errorfile2

Troubleshooting Using the User Migration Utility

Migration failures are reported to the enterprise user administrator with error messages and log messages. The following sections describe common error and log messages and what administrators can do to resolve them.

Common User Migration Utility Error Messages

When the utility encounters any error while running, it displays an error message and stops running. The following sections describe these messages and explain how to resolve the errors:

• Resolving Error Messages Displayed for Both Phases
• Resolving Error Messages Displayed for Phase One

Resolving Error Messages Displayed for Both Phases

The following error messages may display while the utility is running either phase one or phase two of the migration:

• Attribute value missing : : orclCommonNicknameAttribute
• Database connection failure
• Database error: < database_error_message >
• Database not in any domain : : DB-NAME = < database_name >
• Database not registered with the directory : : DB-NAME = < dbName >
• Directory connection failure
• Directory error : : < directory_error_message >
• Multiple entries found : : uniqueMember = < database_DN >

Attribute value missing : : orclCommonNicknameAttribute

Cause: The nickname attribute is not set in the directory in the root identity management realm.

Action: Use Enterprise Security Manager Console to set the nickname attribute for the identity management realm.

Database connection failure

Cause: The utility was unable to connect to the database.

Action: Perform these steps:

1. Check the database status to determine whether it is configured for encryption and integrity.
2. Check the privileges and credentials of the enterprise user administrator who is running the utility.

Database error: < database_error_message >

Cause: The utility encountered a database error.

Action: Check the database error message details for the database.

See Also: Oracle Database Error Messages for information about resolving database error messages.

Database not in any domain : : DB-NAME = < database_name >

Cause: The database is not a member of any enterprise domain.

Action: Use Enterprise Security Manager to add the database to an enterprise domain in the directory.

Database not registered with the directory : : DB-NAME = < dbName >

Cause: There is no entry for the database in the Oracle context that the ldap.ora file points to.

Action: Use Database Configuration Assistant or Enterprise Security Manager to register the database in the directory.

Directory connection failure

Cause: The utility was unable to connect to the directory.

Action: Perform these steps:

1. Check the directory server status to determine whether the directory server port is configured for SSL with no authentication.
2. Check the privileges and credentials of the enterprise user administrator who is running the utility.

Directory error : : < directory_error_message >

Cause: The utility encountered a directory error.

Action: Check the directory error message details for the directory.

See Also: Oracle Internet Directory Administrator's Guide for information about resolving error messages for Oracle Internet Directory.

Multiple entries found : : uniqueMember = < database_DN >

Cause: The database belongs to more than one enterprise domain in the directory.

Action: Use Enterprise Security Manager or Oracle Directory Manager to ensure that the database belongs to only one enterprise domain.

Resolving Error Messages Displayed for Phase One

While the utility is running phase one of the migration, syntax or other types of errors may occur. The following error messages may display while the utility is running phase one of the migration:

• Argument missing or duplicated : : < parameter >
• Database object missing : : SHARED-SCHEMA = <shared_schema_name >
• Error reading file : : < file_name > : : < io_error_message >
• Error reading file : : PARFILE = < file_name > : : < io_error_message>
• Getting local host name failed
• Interface table creation in SYS schema not allowed
• Invalid argument or value : : < argument >
• Invalid arguments for the phase
• Invalid value : : < user > [ USERSFILE ]
• Invalid value : : < user > [ USERSFILE ] { = = DBADMIN }
• Invalid value : : < user > [ USERSLIST ]
• Invalid value : : < user > [ USERSLIST ] { = = DBADMIN }
• Logging failure : : < io_error_message >
• No entry found : : CONTEXT = < context >

Argument missing or duplicated : : < parameter >

Cause: Syntax error. A parameter is missing or has been entered multiple times.

Action: Check the usage syntax.

Database object missing : : SHARED-SCHEMA = <shared_schema_name >

Cause: The shared schema is not present in the database.

Action: Create the shared schema.

Error reading file : : < file_name > : : < io_error_message >

Cause: Syntax error. The utility cannot read the file that contains the users list that is specified in the USERSFILE parameter.

Action: Perform these steps:

1. Check to ensure that the file exists.
2. Check to ensure that the file has the correct permissions so the utility can read it.

Error reading file : : PARFILE = < file_name > : : < io_error_message>

Cause: Syntax error. The utility cannot read the file that contains the list of parameters that is specified in the PARFILE parameter.

Action: Perform these steps:

1. Check to ensure that the file exists.
2. Check to ensure that the file has the correct permissions so the utility can read it.

Getting local host name failed

Cause: Syntax error. The utility is unable to read the local host name for the database location or the directory location.

Action: Explicitly enter the hostname information with the DBLOCATION and DIRLOCATION parameters.

See Also: "Keyword: DBLOCATION" "Keyword: DIRLOCATION" For information about how to use these parameters.

Interface table creation in SYS schema not allowed

Cause: The interface table cannot be created in the SYS schema.

Action: Specify another user in the DBADMIN parameter.

See Also: "Keyword: DBADMIN" for information about setting the DBADMIN parameter.

Invalid argument or value : : < argument >

Cause: Syntax error. The argument name or value has been entered incorrectly.

Action: Check the usage syntax.

See Also: "User Migration Utility Command Line Syntax" "Accessing Help for the User Migration Utility" "User Migration Utility Parameters" For information about using the command line syntax for this utility.

Invalid arguments for the phase

Cause: Syntax error. This occurs when you have used a command line argument that is only intended for phase one, but you are running phase two.

Action: Check the usage syntax.

Invalid value : : < user > [ USERSFILE ]

Cause: Syntax error. The user that is specified in this error message is invalid because they are not a user in the database that is specified in the DBLOCATION parameter.

Action: Remove the invalid user from the file that is specified with the USERSFILE parameter.

Invalid value : : < user > [ USERSFILE ] { = = DBADMIN }

Cause: Syntax error. The file that is specified in the USERSFILE parameter contains the user who is running the migration utility.

Action: Remove that user from the file.

Invalid value : : < user > [ USERSLIST ]

Cause: Syntax error. The user that is specified in this error message is invalid because they are not a user in the database that is specified in the DBLOCATION parameter.

Action: Remove the invalid user from the USERSLIST parameter.

Invalid value : : < user > [ USERSLIST ] { = = DBADMIN }

Cause: Syntax error. The USERSLIST parameter contains the user who is running the migration utility.

Action: Remove that user from the USERSLIST.

Logging failure : : < io_error_message >

Cause: Syntax error. The utility cannot find the log file or it cannot open the file to write to it.

Action: Perform these steps:

1. Check to ensure that the log file exists.
2. Check to ensure that the log file has the correct permissions so the utility can write information to it.

No entry found : : CONTEXT = < context >

Cause: The CONTEXT entry is not present in the directory.

Action: Perform one of the following options:

• Use the directory management tool or the LDAP command line utility to create an entry in the directory for the context value.
• Specify another valid context value.

Resolving Error Messages Displayed for Phase Two

Most of the error messages that you encounter while running this utility occur in phase one. After phase one has completed successfully, and while phase two is running, the following error may occur:

Database object missing : : TABLE = ORCL_GLOBAL_USR_MIGRATION_DATA

Cause: The utility cannot find the interface table.

Action: Perform one of the following options:

• Run phase one of the utility to create the interface table.
• Check to ensure that the user who is specified in the DBADMIN parameter is the same user who was specified for that parameter for phase one.

Common User Migration Utility Log Messages

Typically, log messages are written to the log file for each user who is migrated, whether the user was migrated successfully or not. The following sections describe these messages and explain how to resolve the errors:

Common Log Messages for Phase One

While the utility is running phase one of the migration, messages that indicate a user's information has not been successfully populated in the interface table may be written to the log file. After the utility completes phase one, review the log file to check for the following messages:

• Multiple entries found : : < nickname_attribute > = < username >
• No entry found : : < nickname_attribute > = < username > : : Entry found : DN = < dn >

Multiple entries found : : < nickname_attribute > = < username >

Cause: The nickname attribute matches multiple users or the user matches with multiple nickname attributes.

Action: Resolve the multiple matches and run the utility again for the users whose log file entry displayed this message.

No entry found : : < nickname_attribute > = < username > : : Entry found : DN = < dn >

Cause: No entry was found for the nickname matching, but an entry already exists for the DN in the directory.

Action: Specify a different DN for the user.

Common Log Messages for Phase Two

While the utility is running phase two of the migration, messages that indicate a user has not successfully migrated may be written to the log file. After the utility completes phase two, review the log file to check for the following messages:

• Attribute exists : : orclPassword
• Attribute value missing : : orclPassword
• Database object missing : : SHARED-SCHEMA = < shared_schema >
• Entry found : : DN = < user_DN >
• Invalid value : : <interface_table_column_name> = < interface_table_column_value >
• No entry found : : DN = < user_DN >

Attribute exists : : orclPassword

This message typically occurs with the message Invalid value::<column_name>=<column_value>.

Cause: The entry already contains a value for the orclPassword attribute.

Action: Check the DBPASSWORD_EXIST_FLAG column in the interface table for a T/F value that correctly reflects whether a database password exists for this user.

Attribute value missing : : orclPassword

This message typically occurs with the message Invalid value::<column_name>=<column_value>.

Cause: The orclPassword attribute of this user's entry has a null value.

Action: Check the DBPASSWORD_EXIST_FLAG column in the interface table for a T/F value that correctly reflects whether a database password exists for this user.

Database object missing : : SHARED-SCHEMA = < shared_schema >

Cause: The shared schema that was specified for this user does not exist in the database.

Action: Perform one of the following options:

• Check to ensure that the correct shared schema was specified for this user. If the shared schema name was incorrectly specified, then edit the SHARED_SCHEMA column of the interface table and run phase two of the utility for this user again.
• Create the shared schema in the database and run phase two of the utility for this user again.

Entry found : : DN = < user_DN >

This message typically occurs with the message Invalid value::<column_name>=<column_value>.

Cause: An entry already exists for the specified user DN.

Action: Check the USERDN_EXIST_FLAG column in the interface table for a T/F value that correctly reflects whether a user entry already exists in the directory for this DN.

Invalid value : : <interface_table_column_name> = < interface_table_column_value >

Cause: The value in the interface table column for this user is invalid. Typically, this message is accompanied by additional log messages for this user.

Action: Check to ensure that the correct value has been entered for this user.

No entry found : : DN = < user_DN >

This message typically occurs with the message Invalid value::<column_name>=<column_value>.

Cause: The entry for the DN is missing in the directory.

Action: Check the USERDN_EXIST_FLAG column in the interface table for a T/F value that correctly reflects whether a user entry already exists in the directory for this DN.

Summary of User Migration Utility Error and Log Messages

Table G-4 and Table G-5 list all of the error and log messages in alphabetical order and provides links to the section in this chapter that describes the message and how to resolve it.

Table G-4  Alphabetical Listing of User Migration Utility Error Messages

User Migration Utility Error Message	Phase
Argument missing or duplicated : : < parameter >	1
Attribute value missing : : orclCommonNicknameAttribute	Both
Database connection failure	Both
Database error: < database_error_message >	Both
Database not in any domain : : DB-NAME = < database_name >	Both
Database not registered with the directory : : DB-NAME = < dbName >	Both
Database object missing : : SHARED-SCHEMA = <shared_schema_name >	1
Database object missing : : TABLE = ORCL_GLOBAL_USR_MIGRATION_DATA	2
Directory connection failure	Both
Directory error : : < directory_error_message >	Both
Error reading file : : < file_name > : : < io_error_message >	1
Error reading file : : PARFILE = < file_name > : : < io_error_message>	1
Getting local host name failed	1
Interface table creation in SYS schema not allowed	1
Invalid argument or value : : < argument >	1
Invalid arguments for the phase	1
Invalid value : : < user > [ USERSFILE ]	1
Invalid value : : < user > [ USERSFILE ] { = = DBADMIN }	1
Invalid value : : < user > [ USERSLIST ]	1
Invalid value : : < user > [ USERSLIST ] { = = DBADMIN }	1
Logging failure : : < io_error_message >	1
Multiple entries found : : uniqueMember = < database_DN >	Both
No entry found : : CONTEXT = < context >	1

Table G-5 Alphabetical Listing of User Migration Utility Log Messages

User Migration Utility Log Message	Phase
Attribute exists : : orclPassword	2
Attribute value missing : : orclPassword	2
Database object missing : : SHARED-SCHEMA = < shared_schema >	2
Entry found : : DN = < user_DN >	2
Invalid value : : <interface_table_column_name> = < interface_table_column_value >	2
Multiple entries found : : < nickname_attribute > = < username >	1
No entry found : : DN = < user_DN >	2
No entry found : : < nickname_attribute > = < username > : : Entry found : DN = < dn >	1