8 Bootstrapping a Directory in Oracle Directory Integration Platform

This chapter discusses directory bootstrapping, which refers to the initial migration of data between a connected directory and Oracle Internet Directory. Because the synchronization process can handle the migration of data between a connected directory and Oracle Internet Directory, you are not required to perform directory bootstrapping. However, relying on the synchronization process to perform the initial migration can be a time-consuming process, especially for large amounts of data. For this reason, you should perform directory bootstrapping when you first deploy Oracle Directory Integration Platform.

This chapter contains these topics:

See Also:

The chapter on data migration from other directories and data repositories in Oracle Fusion Middleware Administrator's Guide for Oracle Internet Directory

8.1 Directory Bootstrapping Using syncProfileBootstrap

Use the syncProfileBootstrap utility, located in the ORACLE_HOME/bin directory, to bootstrap between a connected directory and Oracle Internet Directory.

Notes:

  • The syncProfileBootstrap command enables you to bootstrap using either a parameter file or a completely configured integration profile. This topic discusses both approaches.

  • Best security practice is to provide a password only in response to a prompt from the command.

  • You must set the WLS_HOME and ORACLE_HOME environment variables before executing any of the Oracle Directory Integration Platform commands

  • The Oracle WebLogic Managed Server where Oracle Directory Integration Platform is deployed must be configured for SSL to execute this command in SSL mode. Refer to the Configuring SSL chapter in Oracle Fusion Middleware Securing Oracle WebLogic Server for more information.

This topic includes the following sections:

8.1.1 Syntax for syncProfileBootstrap

syncProfileBootstrap

syncProfileBootstrap -h HOST -p PORT -D wlsuser {-file FILENAME |-profile
-PROFILE_NAME} [-ssl -keystorePath PATH_TO_KEYSTORE -keystoreType TYPE]
[-loadParallelism INTEGER] [-loadRetry INTEGER][-help]

8.1.2 Arguments for syncProfileBootstrap

-h | -host

Oracle WebLogic Server host where Oracle Directory Integration Platform is deployed.

-p | -port

Listening port of the Oracle WebLogic Managed Server where Oracle Directory Integration Platform is deployed.

-D | wlsuser

Oracle WebLogic Server login ID

Note:

You will be prompted for the Oracle WebLogic Server login password. You cannot provide the password as a command-line argument. Best security practice is to provide a password only in response to a prompt from the command. If you must execute syncProfileBootstrap from a script, you can redirect input from a file containing the Oracle WebLogic Server login password. Use file permissions to protect the file and delete it when it is no longer necessary.

-f | -file

Bootstrap properties file.

-pf | -profile

The name of the synchronization profile to use when performing the operation.

-ssl

Executes the command in SSL mode.

Note:

The Oracle WebLogic Managed Server where Oracle Directory Integration Platform is deployed must be configured for SSL to execute this command in SSL mode. Refer to the Configuring SSL chapter in Oracle Fusion Middleware Securing Oracle WebLogic Server for more information.

-keystorePath

The full path to the keystore.

-keystoreType

The type of the keystore identified by -keystorePath. For example: -keystorePath jks or -keystorePath PKCS12

-lp | -loadParallelism

Indicator that loading to Oracle Internet Directory is to take place in parallel by using multiple threads. For example, -loadparallelism 5 means that 5 threads are to be created, each of which tries to load the entries in parallel to Oracle Internet Directory.

-lr | -loadRetry

The number of times the retry should be made (when the load to the destination fails) before marking the entry as bad entry.

-help

Provides command usage help.

8.1.3 Tasks and Examples for syncProfileBootstrap

manageSyncProfileBootstrap -h myhost.mycompany.com -p 7005 -D login_ID \
  -pf myProfile -lp 5
manageSyncProfileBootstrap -h myhost.mycompany.com -p 7005 -D login_ID \
  -f /opt/ldap/odip/bootstrap.properties -lr 3  

8.1.4 Recommended Bootstrapping Methodology

If the source directory from which you are loading data contains a large number of entries, the quickest and easiest method to bootstrap the target directory is by using an LDIF file. Bootstrapping with an integration profile is not recommended in this case because connection errors may occur when reading and writing between the source and target directories. Using an LDIF file is also recommended if the DNs contain special characters, which may not be escaped properly when bootstrapping with an integration profile.

8.1.5 Bootstrapping Using a Parameter File

The parameters in this file specify:

  • Source and destination interface types (LDIF and LDAP)

  • Connection details and credentials (valid only for LDAP)

  • Mapping rules

You can bootstrap using an LDIF file by using directory-dependent tools to read from the source directory.

During installation, the following sample parameter files are copied to the $ORACLE_HOME/ldap/odi/conf/ directory:

  • Ldp2ldp.properties

  • Ldp2ldf.properties

  • Ldf2ldp.properties

  • Ldf2ldf.properties

The preceding files describe the significance of each of the parameters in bootstrapping. When you run the tools for bootstrapping, be sure that the ORACLE_HOME and NLS_LANG settings are correct.

Bootstrapping can be performed between services with or without one or more intermediate files. However, for large directories, an intermediate LDIF file is required.

8.1.5.1 Bootstrapping Without Using an LDIF File

Oracle recommends this method for smaller directories where the entries are:

  • Relatively few in number

  • In a flat structure

  • Not interdependent—that is, the creation of one entry does not depend on the existence of another as, for example, when the creation of a group entry depends on the existence of user member entries

To use this method:

  1. Create the mapping file with appropriate mapping rules. The mapping file is one of the properties in the bootstrap file. Be sure that it is compatible with the mapping rules defined for synchronization.

  2. Create the parameter file with the required details specifying the source as LDAP and the destination type as LDIF. A sample parameter file, ldp2ldf.properties, is available in $ORACLE_HOME/ldap/odi/samples. Make sure that binary attributes are specified as binary in the SrcAttrType field.

  3. Execute the syncProfileBootstrap command with a configuration file that contains:

    • The source is specified as an LDAP directory.

    • The destination type is specified as an LDIF.

  4. Check the NAME_OF_MANAGED_SERVER-diagnostic.log file for any errors. This file can be found in the following location: MW_HOME/user_projects/domains/DOMAIN_NAME/servers/NAME_OF_MANAGED_SERVER/logs/NAME_OF_MANAGED_SERVER-diagnostic.log

  5. Use bulkload.sh or the ldapadd command to upload the data to Oracle Internet Directory.

  6. To continue synchronization, use the updatechgnum operation of the manageSyncProfiles command to update the last change number, as follows:

    manageSyncProfiles updatechgnum -h HOST -p PORT -D wlsuser \
    -profile my_Import_Profile
    

8.1.5.2 Bootstrapping Using an LDIF File

This section describes the following two ways to bootstrap a directory by using an LDIF file:

Bootstrapping from an LDIF File Using Directory-Dependent Tools to Read the Source Directory

Oracle recommends that you use this method for large directories. To use this method:

  1. Download the data from the directory to an LDIF file. The tool you use depends on the directory from which you are loading the data. If you are bootstrapping from a Microsoft Active Directory, then use the ldifde command to load the data. Be sure to load all the required attributes for each entry.

  2. Create the mapping file with appropriate mapping rules. When you want to do further synchronization, be sure that the mapping file is the same as the one used for synchronization.

  3. Create the parameter file with source and destination as LDIF and other details. A sample parameter file is available in:

    $ORACLE_HOME/ldap/odi/conf/ldf2ldf.properties.

  4. Use the syncProfileBootstrap command with a parameter file in which the source is specified as LDIF and the destination type is specified as LDIF. This converts the source data and creates a new LDIF as required by Oracle Internet Directory. Run the syncProfileBootstrap command as follows:

    syncProfileBootstrap -profile profile_name -loadParallelism threads -loadRetry retries
    
  5. Check the NAME_OF_MANAGED_SERVER-diagnostic.log file for any errors. This file can be found in the following location: MW_HOME/user_projects/domains/DOMAIN_NAME/servers/NAME_OF_MANAGED_SERVER/logs/NAME_OF_MANAGED_SERVER-diagnostic.log

  6. Use bulkload.sh or the ldapadd command to upload the data to Oracle Internet Directory.

  7. To continue synchronization, use the updatechgnum operation of the manageSyncProfiles command to update the last change number, as follows:

    manageSyncProfiles updatechgnum -h HOST -p PORT -D wlsuser \
    -profile my_Import_Profile
    

Bootstrapping from an LDIF File Using the syncProfileBootstrap Command to Load Data into Oracle Internet Directory

To use this method:

  1. Download the data from the directory to an LDIF file. The tool you use depends on the directory from which you are loading the data. If you are bootstrapping from a Microsoft Active Directory, then use the ldifde command to load the data. Be sure to load all the required attributes for each entry.

  2. Prepare the mapping file with appropriate mapping rules. When you want to do further synchronization, be sure that the mapping file is the same as the one used for synchronization.

  3. Create the properties file with the source specified as LDIF and the destination specified as LDAP.

  4. Use the syncProfileBootstrap command with a parameter file in which the source is specified as the LDIF file, the destination type is specified as LDAP, and the destination specified as Oracle Internet Directory. This converts the source data and creates entries in Oracle Internet Directory as required. A sample properties file, ldf2ldp.properties, is available in $ORACLE_HOME/ldap/odi/samples.

  5. Check the NAME_OF_MANAGED_SERVER-diagnostic.log file for any errors. This file can be found in the following location: MW_HOME/user_projects/domains/DOMAIN_NAME/servers/NAME_OF_MANAGED_SERVER/logs/NAME_OF_MANAGED_SERVER-diagnostic.log

  6. To continue synchronization, use the updatechgnum operation of the manageSyncProfiles command to update the last change number, as follows:

    manageSyncProfiles updatechgnum -h HOST -p PORT -D wlsuser \
    -profile my_Import_Profile
    

8.1.6 Bootstrapping Directly Using the Default Integration Profile

Bootstrapping relies on an existing integration profile configured for synchronization. The configuration information used to connect to the third-party directory.

While using this method, put the source directory in read-only mode.

If the profile is an import profile, then footprints of the required objects in the connected directory are created in Oracle Internet Directory. If the profile is an export profile, then footprints of the required objects from Oracle Internet Directory are created in the connected directory.

While creating these entries, the distinguished name and object-level mappings as specified in the integration profile are used. If there is a failure uploading the entries, then the information is logged in the NAME_OF_MANAGED_SERVER-diagnostic.log file located in the MW_HOME/user_projects/domains/DOMAIN_NAME/servers/NAME_OF_MANAGED_SERVER/logs directory.

For example, for bootstrapping from Oracle Directory Server Enterprise Edition (previously Sun Java System Directory Server) to Oracle Internet Directory, you would do the following:

  1. Customize the default integration profile iPlanetImport, which is created as part of the installation by following the instructions in "Configuring Advanced Integration with Oracle Directory Server Enterprise Edition".

  2. Enter the following command:

    syncProfileBootstrap -h HOST -p PORT -D wlsuser -profile iPlanetImport -loadParallelism 5 -loadRetry 3
    
  3. Check the NAME_OF_MANAGED_SERVER-diagnostic.log file for any errors. This file can be found in the following location: MW_HOME/user_projects/domains/DOMAIN_NAME/servers/NAME_OF_MANAGED_SERVER/logs/NAME_OF_MANAGED_SERVER-diagnostic.log

If you use the syncProfileBootstrap command, following the bootstrapping process the lastchangenumber attribute is initialized for further synchronization.

8.2 Bootstrapping in SSL Mode

You can use either a parameter file or an integration profile to bootstrap in SSL mode. When you bootstrap in SSL mode, either Oracle Internet Directory, the connected directory, or both Oracle Internet Directory and the connected directory can be running SSL mode.

To bootstrap in SSL mode from a parameter file, you must assign values of either true or false to the odip.bootstrap.srcsslmode and odip.bootstrap.destsslmode arguments in the parameter file.

When you bootstrap from an integration profile, the value assigned to the default integration profile's odip.profile.condirurl is used to establish an SSL connection to the connected directory.

8.2.1 Adding a Trusted Certificate to the DIP Keystore

When bootstrapping in SSL mode, Directory Integration Platform needs to have the trusted certificate of the third party directory in its keystore. DIP will connect to the third party directory using SSL Server-Auth mode.

8.2.1.1 To Add a Trusted Certificate to the DIP Keystore

Complete the following before starting the bootstrap in SSL mode.

  1. Create a new Java Key Store using the keytool command in some physical location and add the third party directory trusted certificate into this keystore.

    keytool -importcert -noprompt -trustcacerts -alias <ALIAS_NAME> -file <PATH_TO_CERTIFICATE_FILE> -keystore <PHYSICAL_LOCATION_OF_KEYSTORE> -storepass <KEYSTORE_PASSWORD>

  2. Configure the Java Key Store (JKS) location (created in the previous step) in the Directory Integration Platform application.

    In the following command, WLS stands for WebLogic Server.

    $OH/bin/manageDIPServerConfig set -attr keystorelocation -val <FULL_PATH_TO_KEYSTORE> -h <WLS_HOST> -p <WLS_MANAGED_SERVER_PORT> -wlsuser <WLS_USER>

  3. Create a CSF (Credential Store Framework) password credential so that DIP can read the password from CSF and open the keystore for validating the certificates.

    1. Run the following command:

      $MW_HOME/oracle_common/common/bin/wlst.sh

    2. Run the following command:

      connect('%WLSUSER%','%WLSPWD%', 't3://%HOST%:%ADMINSERVER_PORT%')

    3. Run the following WLST command to create a credential:

      createCred(map="dip", key="jksKey", user="cn=odisrv,cn=Registered Instances,cn=Directory Integration Platform,cn=products,cn=oraclecontext", password="<JKS_PASSWORD>", desc="DIP SSL JKS")