4.14 ldifmigrator

The Oracle Internet Directory Data Migration Tool (ldifmigrator) is used to convert LDIF files output from other directories or application-specific repositories into a format recognized by Oracle Internet Directory. The Data Migration Tool takes as input an LDIF file containing substitution variables, and outputs an LDIF file suitable for loading into Oracle Internet Directory.

See "LDIF Format for Migrating Entries" for the correct format of the LDIF input file for this tool.

4.14.1 Syntax for ldifmigrator

ldifmigrator "input_file=filename" "output_file=filename"  [-lookup -h oid_hostname -D "binddn" -w password [-p ldap_port] [subscriber=subscriberDN]] ["s_VariableName1=replacement_value" "s_VariableName2=replacement_value"...] [-load -reconcile SAFE|SAFE_EXTENDED|NORMAL]

4.14.2 Arguments for ldifmigrator

"input_file=filename"

The full path and file name of the LDIF file that contains directory entry data and one or more substitution variables.

"output_file=filename"

The full path and file name of the output file produced by the ldifmigrator tool.

-lookup

If this flag is specified, then values of certain substitution variables will be obtained by looking up the correct values in the directory server. See "Substitution Variables for Migration Input Files" for a list of substitution variables that can be looked up.

-h oid_hostname

Required if the -lookup flag is used. The host name or IP address of the Oracle Internet Directory server.

-D "binddn"

Required if the -lookup flag is used. The DN of the Oracle Internet Directory user needed to bind to the directory (for example, cn=orcladmin).

-w password

Required if the -lookup flag is used. The user password needed to bind to the directory.

-p ldap_port

Optional if the -lookup flag is used. The port number used to connect to the Oracle Internet Directory server. Defaults to port 389.

subscriber=subscriberDN

Optional. The subscriber whose attribute values will be used in place of the substitution variables. If not specified, then the default identity management realm specified in the Root Oracle Context will be used.

"s_VariableName=replacement_value"

Optional. You can specify a value for a substitution variable on the command-line. See "Substitution Variables for Migration Input Files" for instructions on adding a substitution variable to the input LDIF file. The ldifmigrator tool will replace all occurrences of the variable with the value you specify.

-load

Optional. Loads the data output by the ldifmigrator tool directly into Oracle Internet Directory. If an entry is already present in the directory then that directory entry will be logged to the file. The addition of the directory entries could fail for other reasons as well, for instance not enough permission to add or parent entry not being present.

-reconcile SAFE | SAFE_EXTENDED | NORMAL

Optional. The -reconcile option enables you to specify different modes if the tool tries to load data for entries that already exist, or modify attributes of entries that may have conflicts. The following modes are available:

SAFE - This mode only adds new entries that don't exist or appends new attributes to existing entries.
SAFE-EXTENDED - This mode only adds new entries that don't exist or appends new attributes to existing entries. If you try to add a new value for existing attributes, then it will add it to the existing set of values.
NORMAL - This mode applies all directives as intended, overwriting any conflicting attributes or entries with the data specified in the ldifmigrator output.

See "Reconcile Options for Migrated Entries" for more information about LDIF directives supported by the -reconcile option.

4.14.3 Tasks and Examples for ldifmigrator

Using the ldifmigrator command-line tool, you can perform the following tasks:

Using the Data Migration Tool in Lookup Mode
Overriding Data Migration Values in Lookup Mode
Using the Data Migration Tool by Supplying Your Own Values
Loading and Reconciling Data Using the Data Migration Tool

See "LDIF Format for Migrating Entries" for examples of correctly formatted LDIF input files for use with the Data Migration Tool.

4.14.3.1 Using the Data Migration Tool in Lookup Mode

In this example, Oracle Internet Directory server is present in the environment, and the migration tool will lookup the directory server to figure out certain substitution variables specified in the LDIF input file.

Example:

$ldifmigrator "input_file=sample.dat" "output_file=sample.ldif" \
               -lookup "host=ldap.acme.com" "subscriber=acme" \
               "s_UserOrganization=Development"

4.14.3.2 Overriding Data Migration Values in Lookup Mode

In some cases, you want to use the lookup mode but would also like to override the values of one or more of the pre-defined substitution variables. This can be done by specifying the override value in the command-line. The following command line shows how one can set the UserNickNameAttribute to cn overriding the default of uid:

Example:

$ldifmigrator "input_file=sample.dat" "output_file=sample.ldif" \
              -lookup "host=ldap.acme.com" "subscriber=acme" \
             "s_UserOrganization=Development" "s_UserNicknameAttribute=cn"

4.14.3.3 Using the Data Migration Tool by Supplying Your Own Values

The following example shows how you can specify your own values for substitution variables found in the LDIF input file, rather than using lookup mode.

Example:

$ldifmigrator "input_file=sample.dat" "output_file=sample.ldif"  \
              "s_UserContainerDN=cn=Users,o=Acme,dc=com" \
              "s_UserNicknameAttribute=uid" "s_UserOrganization=Development"

4.14.3.4 Loading and Reconciling Data Using the Data Migration Tool

The Data Migration Tool gives your the option of loading the data directly into Oracle Internet Directory. Use the -load and -reconcile options to load data and safely reconcile any conflicts.

Example:

$ldifmigrator "input_file=sample.dat" "output_file=sample.ldif" \
               -lookup "host=ldap.acme.com" "subscriber=acme" \
               "s_UserOrganization=Development"
               -load -reconcile SAFE

4.14.4 Related Command-Line Tools for ldifmigrator

4.14.5 Error Messages for ldifmigrator

The Data Migration Tool can display these error messages:

Table 4-1 Error Messages of the Data Migration Tool

Message	Reason	Remedial Action
Environment variable ORACLE_HOME not defined	ORACLE_HOME is not defined.	Set the environment variable ORACLE_HOME
Error while parsing the input parameters. Please verify	Not all the required parameters are provided. The required parameters are Input_File, Output_File and at least one substitution variable	Specify the input parameters properly. Use the `-help` option to print the usage.
Input_File parameter not specified. Please specify	Input_File parameter is a mandatory parameter.	Specify the input parameters properly. Use the `-help` option to print the usage.
Output_File parameter not specified. Please specify	Output_File parameter is a mandatory parameter.	Specify the input parameters properly. Use the `-help` option to print the usage.
The specified input file does not exist	The specified file location is invalid.	Check the input file path
Check the input file. Zero byte input file	The input file does not contain any entries.	Provide a valid file with pseudo LDIF entries
Cannot create the output file. Output file already exists	The output file already exists	Check the Output_File flag
Access denied, cannot read from the input file	The specified input file does not have read permission	Check the read permission of the input file.
Access denied, cannot create the output file	You do not have permission to create the output file.	Check the permission of the directory under which the output file needs to be created.
Directory server name not specified. When -lookup option is used the host parameter should be specified	When the `-lookup` option is specified, the host parameter is mandatory.	Specify the host parameter.
Bind Dn parameter name not specified. When -lookup option is used the dn parameter should be specified	When the `-lookup` option is specified, the DN parameter is mandatory.	Specify the DN parameter.
The port number specified is invalid	The port number should be a numeric value.	Check the port number parameter
Unable to establish connection to directory. Please verify the input parameters: host, port, dn & password	The directory server may not be running on the specified host and port, or credentials may be invalid.	Check the host, port, DN and password parameters. Check `$ORACLE_HOME/ldap/install/LDIFMig_YYYY_MM_DD_HH_SS.log file`.
Naming exception occurred while retrieving the subscriber information from the directory. Please verify the input parameters	The specified identity management realm does not exist in the directory	Check the realm parameter
Not all the substitution variables are defined in the directory server specified	If the identity management realm entry does not contain the required attributes, then this error occurs.	Check the realm entry in the directory
Error occurred while migrating LDIF data to Oracle Internet Directory	This might occur if something goes wrong in the middle of a process—for example, a failure of the directory server or disk.	Report the error message to the administrator

When an error condition occurs, the log messages are logged to this file: ORACLE_HOME/ldap/install/LDIFMig_YYYY_MM_DD_HH_SS.log.