| Oracle® Database Enterprise User Administrator's Guide 10g Release 2 (10.2) Part Number B14269-01 |
|
|
View PDF |
| Oracle® Database Enterprise User Administrator's Guide 10g Release 2 (10.2) Part Number B14269-01 |
|
|
View PDF |
This chapter describes the User Migration Utility. You can use it to perform bulk migrations of database users to an LDAP directory, where they can be stored and managed centrally as enterprise users. It contains the following topics:
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, typically deployed where end-to-end SSL is required
Enhanced security through more timely maintenance and fewer user passwords
The centralization of user information inherent in the enterprise user model makes it easier to manage. Security administrators can perform necessary maintenance changes to user information immediately, thereby maintaining better control over access to critical network resources. In addition, users find the enterprise user model easier to use because they have fewer passwords to remember. So, they are less likely to choose easily guessed passwords or to write them down where others can copy them.
See Also:
"Introduction to Enterprise User Security" for detailed conceptual information about enterprise user securityThe User Migration Utility is a command-line utility that enables enterprise user administrators to move their users from a local database model to an enterprise user model. You can easily 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. The utility connects to the database using the Oracle JDBC OCI driver.
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 user schemas.
Note:
After external users are migrated, their external authentication and authorization mechanisms are replaced by directory-based mechanisms. New passwords are randomly generated for migrated users if they are mapped to newly created directory entries.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. Enterprise user administrators then verify that the information is accurate before completing the migration with Phase Two, which commits the changes to the database and the directory. The process is described in the following steps:
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.
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.
After the interface table user information is checked, Phase Two begins. 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.
See Also:
"User Migration Utility Parameters" for a list of command-line options and their descriptionsThis 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.
Caution:
The
ORCL_GLOBAL_USR_MIGRATION_DATA interface table contains very sensitive information. Access to it should be tightly controlled using database privileges.The table columns are listed in Table A-1.
Table A-1 ORCL_GLOBAL_USR_MIGRATION_DATA Table Schema
After running phase one of the utility, if necessary, enterprise user administrators can change the interface table columns listed in Table A-2.
Table A-2 Interface Table Column Values That Can Be Modified Between Phase One and Phase Two
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 A-3 summarizes the effects of setting the MAPSCHEMA and CASCADE parameters.
Table A-3 Effects of Choosing Shared Schema Mapping with CASCADE Options
| MAPSCHEMA Parameter Setting | CASCADEParameter Setting | User MigrationSuccessful? | User SchemaObjects Dropped? |
|---|---|---|---|
| PRIVATE | NO (default setting) | Yes | No |
| SHARED | NO | YesFoot 1 | No |
| SHARED | YES | YesFoot 2 | Yes |
See Also:
"User Migration Utility Parameters" for detailed information about theMAPSCHEMA, CASCADE, and other parameters that can be used with this utilityEnterprise users are defined and managed in the directory and can be authenticated to the database either with a password or with a certificate. Users who authenticate with a password require an Oracle Database password, which is stored in the directory. Users who authenticate with a certificate must have a valid X.509 v3 certificate.
This utility performs the following steps during migration:
Selects the users from the database for migration.
Creates corresponding user entries or uses existing entries in the directory.
Creates new database passwords and copies the corresponding verifiers to the directory for migrating users.
Puts the schema mapping information for the migrating users' entries in the directory. (optional)
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 were required to reset their Oracle Database passwords. User wallets are not created as part of this process.See Also:
The chapter about Oracle Wallet Manager in Oracle Database Advanced Security Administrator's Guide for information about creating, managing, and using Oracle walletsThe 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.
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.
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
Perform the following steps before using the User Migration Utility:
Ensure that the directory server is running with SSL enabled for no authentication.
Ensure that the database server is running with encryption and integrity enabled.
Ensure that the database listener has a TCP listening end point.
Create an identity management realm in the directory, if it does not already exist.
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 orclcommonusercreatebase subtree in the common container in the Oracle Context.
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:
Chapter 3, "Enterprise User Security Configuration Tasks and Troubleshooting" for detailed information about setting up enterprise user authentication after the user migration is finished
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 A-1 shows the syntax used to run the utility through both phases of the bulk user migration process.
Example A-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 KREALM=ACME.COM
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
Note:
If the enterprise user administrator does not specify the mandatory parameters on the command line, then the utility will prompt the user for those parameters interactively.See Also:
"User Migration Utility Parameters" for a complete list of all available parameters and detailed information about them
"User Migration Utility Usage Examples" for examples of typical utility uses
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 run.
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.
| Attribute | Description |
|---|---|
| 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 run a command, set the value to NO, or do not specify a value for the parameter to accept the default. |
| Restrictions: | None |
| Attribute | Description |
|---|---|
| Valid Values: | ONE or TWO (These values are not case-sensitive.) |
| Default Setting: | ONE |
| Syntax Examples: | PHASE=ONE
|
| 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 |
| Attribute | Description |
|---|---|
| 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: |
|
| Attribute | Description |
|---|---|
| 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. |
| Attribute | Description |
|---|---|
| Valid Values: | username:password |
| Default Setting: | No default setting |
| Syntax Examples: | DBADMIN=system:manager |
| Description: | User name and password for the database administrator with the required privileges for connecting to the database |
| Restrictions: |
|
| Attribute | Description |
|---|---|
| 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. |
| Attribute | Description |
|---|---|
| Valid Values: | value1:value2...
Values can be:
This parameter takes multiple values. Separate values with a colon (:). (These values are not case-sensitive.) |
| Default Setting: | No default setting |
| Syntax Examples: |
|
| 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. |
| Attribute | Definition |
|---|---|
| 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 specified with the USERS parameter. |
| Restrictions: | This optional parameter is effective only when LIST is specified with the USERS parameter. |
| Attribute | Definition |
|---|---|
| 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 specified with the USERS parameter. |
| Restrictions: | This optional parameter is effective only when FILE is specified with the USERS parameter. |
| Attribute | Description |
|---|---|
| Valid Values: | kerberos realm |
| Default Setting: | No default setting |
| Syntax Examples: | KREALM=ACME.COM |
| Description: | Kerberos REALM for external kerberos users, which will usually be the domain name of the database server.If this parameter is not specified, then all external users who are considered for migration are assumed to be non-Kerberos. |
| Restrictions: |
|
| Attribute | Description |
|---|---|
| Valid Values: | schema_type:schema_name
Schema type can be:
(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: |
|
| Attribute | Description |
|---|---|
| Valid Values: | mapping_type:mapping_level
Mapping type can be: Mapping level can be: 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 the 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. |
See Also:
"About Using the SUBTREE Mapping Level Option" for more information about using this mapping level option| Attribute | Description |
|---|---|
| Valid Values: |
(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. |
| Attribute | Description |
|---|---|
| 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: | Value set in orclCommonUserCreateBase attribute under cn=Common of Oracle Context
Refer to Figure 1-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 valid only for phase one. |
| Attribute | Description |
|---|---|
| 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 |
| Attribute | Description |
|---|---|
| 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 containing a list of parameters intended for use in a user migration. Each parameter must be listed on a separate line in the file. If a parameter is specified both in the parameter file and on the command line, then the one specified on the command line takes precedence. |
| Restrictions: | None |
The following sections contain examples of the syntax for some typical uses of this utility.
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, retaining their old schemas, to the directory at c=Users, c=us with the newly generated database and directory passwords, use the syntax shown in Example A-2.
Note:
All external users being migrated are considered non-Kerberos by default. For existing Kerberos users, you can have the utility set their Kerberos principal name attribute in Oracle Internet Directory after migration. To do this, specify theKREALM parameter on the command line by using the Kerberos REALM value. For example, if the Kerberos REALM value is ACME.COM, then you would enter KREALM=ACME.COM. Once you do this, those users with names of the form user@kerberos_realm are considered Kerberos users. In Oracle Internet Directory, their Kerberos principal names are set by using their database user names.
See Also: "Keyword: KREALM"
Example A-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 is completed 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.
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 A-3 to run the migration process with MAPSCHEMA set to SHARED.
Example A-3 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 is completed 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.
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.
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.
See Also:
Example A-3 for a syntax example to map users to a shared schema withCASCADE set to NO. Note that because NO is the default setting for CASCADE, this parameter does not have to be specified in the utility command syntaxIf 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 A-4 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 A-4 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 is completed 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.
Caution:
If you set theCASCADE parameter to YES, then Oracle recommends that enterprise user administrators back up the database or take an export dump of the users being migrated before running this utility. Then, if migrated users want their old database objects, then they can retrieve them from the export dump.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 mapping type and 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, 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, 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, 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 A-5 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 A-5 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
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.
See Also:
"Managing Enterprise Domain Database Schema Mappings" for information about using Enterprise Security ManagerIt 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 that 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 A-6 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 A-6 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 A-7 shows the syntax for a typical users list text file.
Example A-7 Users List Text File (usrs.txt) to Use with the USERSFILE Parameter
user1 user2 user3
To run Phase One of the migration process with these parameters and users list text files, use the syntax shown in Example A-8.
Example A-8 Migrating Users Using the PARFILE, USERSFILE, and LOGFILE Parameters
umu PHASE=ONE
DBADMIN=system:manager PARFILE=par.txt LOGFILE=errorfile2
Note:
Although theLOGFILE parameter is specified twice, once in the parameter text file as errorfile1 (shown in Example A-6) and once on the command line as errorfile2 (shown in Example A-8), command-line parameters take precedence over those specified inside the parameter file. Consequently, in Example A-8, the log file will be written to errorfile2 because that value is specified on the command line.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.
See Also:
"Summary of User Migration Utility Error and Log Messages" for an alphabetical listing of error and log messages and links to where they are described in this sectionWhen 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:
The following error messages may be displayed while the utility is running either Phase One or Phase Two of the migration:
Check the database status to determine whether it is configured for encryption and integrity.
Check the privileges and credentials of the enterprise user administrator who is running the utility.
See Also:
Oracle Database Error Messages for information about resolving database error messagesCheck the directory server status to determine whether the directory server port is configured for SSL with no authentication.
Check the privileges and credentials of the enterprise user administrator who is running the utility.
See Also:
Oracle Internet Directory Administrator's Guide information about resolving error messages for Oracle Internet DirectoryWhile the utility is running Phase One of the migration, syntax or other types of errors may occur. The following error messages may be displayed while the utility is running Phase One of the migration:
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>
Check to ensure that the file exists.
Check to ensure that the file has the correct permissions so the utility can read it.
Check to ensure that the file exists.
Check to ensure that the file has the correct permissions so the utility can read it.
DBLOCATION and DIRLOCATION parameters.
See Also:
for information about how to use these parameters
SYS schema.DBADMIN parameter.
See Also:
for information about using the command-line syntax for this utility
DBLOCATION parameter.USERSFILE parameter.USERSFILE parameter contains the user who is running the migration utility.DBLOCATION parameter.USERSLIST parameter.USERSLIST parameter contains the user who is running the migration utility.USERSLIST parameter.Check to ensure that the log file exists.
Check to ensure that the log file has the correct permissions so the utility can write information to it.
CONTEXT entry is not present in the directory.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.
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:
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.
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:
While the utility is running Phase One of the migration, messages that indicate that 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 >
While the utility is running Phase Two of the migration, messages that indicate that 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:
Database object missing : : SHARED-SCHEMA = < shared_schema >
Invalid value : : <interface_table_column_name> = < interface_table_column_value >
Invalid value::<column_name>=<column_value>.orclPassword attribute.DBPASSWORD_EXIST_FLAG column in the interface table for a T/F value that correctly reflects whether a database password exists for this user.Invalid value::<column_name>=<column_value>.orclPassword attribute of this user's entry has a null value.DBPASSWORD_EXIST_FLAG column in the interface table for a T/F value that correctly reflects whether a database password exists for this user.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.
Invalid value::<column_name>=<column_value>.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::<column_name>=<column_value>.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.Table A-4 and Table A-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 A-4 Alphabetical Listing of User Migration Utility Error Messages
Table A-5 Alphabetical Listing of User Migration Utility Log Messages
