Bootstrapping a Directory in Oracle Directory Integration Platform

11 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 the Oracle back-end directory. Because the synchronization process can handle the migration of data between a connected directory and the Oracle back-end 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.

Topics:

11.1 Overview of Directory Bootstrapping Using syncProfileBootstrap

Use the syncProfileBootstrap utility to bootstrap between a connected directory and the Oracle back-end directory.

For more information, see syncProfileBootstrap Utility syncProfileBootstrap Utility.

Note:

To bootstrap between a connected Oracle Database and the Oracle back-end directory, configure the export profile dbexport.cfg and bootstrap with that profile. See Configure the Additional Configuration Information File for more information.

Topics:

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

11.1.2 About How to Use a Parameter File to Bootstrap

You can use the parameter file to bootstrap between a connected directory and the Oracle back-end directory.

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.

11.1.3 Bootstrapping from an LDAP File to an LDIF File

This section describes how to bootstrap from an LDAP file to an LDIP 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:

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.
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/conf. Make sure that binary attributes are specified as binary in the SrcAttrType field.
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.
Examine the diagnostic log file for any error at the following location:
```
(UNIX) DOMAIN_HOME/servers/server_name/logs
(Windows) DOMAIN_HOME\servers\server_name\logs
```
The default name of the log file is server-name-diagnostic.log.

11.1.4 Bootstrapping Using an LDIF File

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

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

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.
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.
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.
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 -h HOST -p PORT -D wlsuser -profile profile_name -loadParallelism threads -loadRetry retries
```
For more information, see syncProfileBootstrap Utility.
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
```
For more information, see manageSyncProfiles Utility.

11.1.4.2 Bootstrapping from an LDIF File Using the syncProfileBootstrap Command to Load Data into the Back-end Directory

To use this method:

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.
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.
Create the properties file with the source specified as LDIF and the destination specified as LDAP.
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/conf.
Examine the diagnostic log file for any error at the following location:
```
(UNIX) DOMAIN_HOME/servers/server_name/logs
(Windows) DOMAIN_HOME\servers\server_name\logs
```
The default name of the log file is server-name-diagnostic.log.
To continue synchronization and update the last change number, use the manageSyncProfiles updatechgnum command:
```
manageSyncProfiles updatechgnum -h HOST -p PORT -D wlsuser \
-profile my_Import_Profile
```

11.1.5 Bootstrapping Directly Using the Default Integration Profile

Bootstrapping relies on an existing integration profile configured for synchronization. This configuration information is used to connect to the other 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 the Oracle back-end directory. If the profile is an export profile, then footprints of the required objects from the Oracle back-end 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 server-name-diagnostic.log file located in the DOMAIN_HOME/servers/server_name/logs directory.

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

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

Enter the following command:

syncProfileBootstrap -h HOST -p PORT -D wlsuser -profile iPlanetImport -loadParallelism 5 -loadRetry 3

Examine the diagnostic log file for any error at the following location:
```
(UNIX) DOMAIN_HOME/servers/server_name/logs
(Windows) DOMAIN_HOME\servers\server_name\logs
```
The default name of the log file is server-name-diagnostic.log.

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

11.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 the Oracle back-end directory, the connected directory, or both the Oracle back-end 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.

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.

Note:

Oracle Directory Integration Platform 12c supports Transport Layer Security (TLS) v1.2 protocol for communication between a connected directory and the Oracle back-end directory. See Transport Layer Security Protocol and Cipher Suites.

Complete the following before starting the bootstrap in SSL mode.

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>
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>
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. Invoke the WLST command:
```
(UNIX) ORACLE_HOME/oracle_common/common/bin/wlst.sh
(Windows) ORACLE_HOME\oracle_common\common\bin\wlst.cmd
```
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")
```
  Note:
  Oracle Directory Integration Platform provides you the option to add cipher suites used by the connected directories, which is not available out-of-box. See Adding Cipher Suites into Oracle Directory Integration Platform

11.3 syncProfileBootstrap Utility

Use the syncProfileBootstrap utility, located in the ORACLE_HOME/bin directory, to bootstrap between a connected directory and the Oracle back-end directory.

Note:

The syncProfileBootstrap command enables you to bootstrap using either a parameter file or a completely configured integration profile. This topic discusses both approaches.
To bootstrap between a connected Oracle Database and the Oracle back-end directory, configure the export profile dbexport.cfg and bootstrap with that profile. See Configure the Additional Configuration Information File for more information.
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.

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]

Arguments for syncProfileBootstrap

The following table describes the arguments for syncProfileBootstrap utility.

Table 11-1 syncProfileBootstrap utility Arguments

Argument	Description
-h \| -host	Oracle WebLogic Server 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 `dipStatus` from a script, you can redirect input from a file containing the Oracle WebLogic Server 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. For more information, see "Configuring SSL" in Oracle Fusion Middleware Securing Oracle WebLogic Server.
-pwd \| -pwdOverNonSSL	Forces the synchronization of the `userPassword` attribute over Non-SSL mode.
-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	Indicates that loading to the Oracle back-end 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 the Oracle back-end 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 usage help for the command.

Tasks and Examples for syncProfileBootstrap

syncProfileBootstrap -h myhost.mycompany.com -p 7005 -D login_ID \
  -pf myProfile -lp 5

syncProfileBootstrap -h myhost.mycompany.com -p 7005 -D login_ID \
  -f /opt/ldap/odip/bootstrap.properties -lr 3  

syncProfileBootstrap -h myhost.mycompany.com -p 7005 -D weblogic -fp ImportProfile -pwd