1. Installing Oracle Unified Directory
  2. Setting Up Oracle Unified Directory as a Replication Gateway

5 Setting Up Oracle Unified Directory as a Replication Gateway

The replication gateway enables replication between Oracle Directory Server Enterprise Edition and Oracle Unified Directory. Its main purpose is to facilitate migration from an Oracle Directory Server Enterprise Edition deployment. You can use either the graphical user interface or the command-line utility to set up an Oracle Unified Directory replication gateway.

Topics:

5.1 Before You Set Up the Replication Gateway

Review these conditions before you set up a replication gateway instance.

Note the following:

  • The Oracle Unified Directory servers in the topology must be configured so that inconsistencies between the Oracle Directory Server Enterprise Edition configuration and the Oracle Unified Directory configuration are taken into account.

    Run the ds2oud command to configure the Oracle Unified Directory directory servers to coexist with Oracle Directory Server Enterprise Edition servers in a replicated topology. See Replicating Between Oracle Directory Server Enterprise Edition and Oracle Unified Directory in Administering Oracle Unified Directory.

  • The Oracle Directory Server Enterprise Edition servers that will be connected to the replication gateway must be configured for replication and must be master replicas.

    Replication must be enabled in Oracle Directory Server Enterprise Edition on the suffix that will be replicated. This is the case even if there is only one Oracle Directory Server Enterprise Edition server in the topology.

  • The replication gateway setup attempts to contact the Oracle Unified Directory server and the Oracle Directory Server Enterprise Edition server. These servers must therefore be up and running.

5.2 Setting Up the Replication Gateway Using the Graphical User Interface (GUI)

The GUI setup uses a Java-based graphical installer that enables you to set up and configure the replication gateway.

Note:

The OUD instance creation GUI wizard is deprecated in Oracle Unified Directory 12c (12.2.1.4.0). Oracle recommends use of the command-line (CLI) to create an instance. See Setting Up the Replication Gateway Using the Command-Line Interface (CLI).

To set up a replication gateway server instance using the graphical user interface:

  1. When you have installed the software, change to the OUD_HOME subdirectory.

    On UNIX and Linux systems:

    $ cd OUD-base-location/$OUD_HOME

    On Windows systems:

    C:\> cd OUD-base-location/$OUD_HOME

  2. Ensure that your JAVA_HOME environment variable is set to a supported JVM installation (at least Java 1.8).

  3. Run the oud-replication-gateway-setup command to configure the replication gateway installation.

    On UNIX and Linux systems:

    $ oud-replication-gateway-setup

    On Windows systems:

    C:\> oud-replication-gateway-setup.bat

    The utility launches the graphical installer and creates the replication gateway instance in OUD-base-location/instance-dir.

    The default instance directory name is asinst_1, with subsequent instances on the same server named asinst_2, asinst_3, and so on. To specify a different instance name, set the INSTANCE_NAME environment variable before you run the setup, for example: 

    $ export INSTANCE_NAME=my-oud-instance

    Note:

    The instance is created directly under OUD-base-location by default. However, Oracle strongly recommends that you create your Oracle Unified Directory instance outside of the Oracle home directory.

  4. On the Welcome screen, click Next.

    A confirmation message is displayed, requesting you to confirm that you have configured the Oracle Unified Directory directory servers to coexist with Oracle Directory Server Enterprise Edition servers in a replicated topology. If you have done this configuration, click Yes. If you have not, click No, exit the installer, and run the ds2oud command to perform the required configuration before you install the replication gateway.

    See Replicating Between Oracle Directory Server Enterprise Edition and Oracle Unified Directory in Administering Oracle Unified Directory.

    The Replication Gateway Administration screen is displayed.

  5. Enter the following information:

    • Host Name: Enter the host name or IP address for this replication gateway instance.

      The default is the local host name.

    • Administration Connector Port: Enter the port that will be used for administration traffic.

      The default administration port is 4444. See Managing Administration Traffic to the Server in Administering Oracle Unified Directory.

    • Root User DN: Enter the Root User DN, or keep the default, cn=Directory Manager.

    • Password: Enter the root user bind password.

    • Password (confirm): Retype the root user bind password.

    Click Next.

    The ODSEE Server Settings screen is displayed.

  6. Enter the following information:

    • Host Name: Enter the ODSEE directory server's host name or IP address.

      The default is the local host name.

    • Port: Enter the LDAP port for the ODSEE directory server.

    • Bind DN: Enter the Bind DN that will be used to access the Oracle Directory Server Enterprise Edition server, or keep the default, cn=Directory Manager.

    • Password: Enter the bind password.

    • If the Oracle Unified Directory servers are read-only servers, uncheck the first check box. Otherwise, leave it checked.

    • To secure the traffic between the gateway and the Oracle Directory Server Enterprise Edition server:

      1. Check the Use SSL between ODSEE and Replication Gateway check box.

      2. Ensure that the port you specified above is the secure port of the Oracle Directory Server Enterprise Edition server.

      3. Check the Use Client Authentication check box and click Change to configure the certificate.

        If you have selected this check box, then it indicates that you want to use secured communication between Oracle Unified Directory and ODSEE (vice versa). For secure communication, the certificate based authentication mechanism used during replication from ODSEE to Oracle Unified Directory further depends on the SASL and certificate mapper configuration.

        Note:

        Observe the following points from ODSEE configuration point of view. Make sure that the configuration has been done before proceeding with the replication gateway setup.

        • Ensure that the certificate is exchanged properly if there are more than one ODSEE instances.

        • Ensure replication agreements are enabled with the help of SSL port.

        • Modify certmap.conf present in the <ODSEE INST>/alise with correct details according to your certificate.

          This file indicates how certificate is mapped to the LDAP entry. Also modify "cn=replication manager, cn=replication, cn=config" and add binary format of the certificate.

        Observe the following points from Oracle Unified Directory configuration point of view. Make sure that the following configuration is performed after the replication gateway setup is done.

        • Setup the Replication gateway.

          After gateway installation is done, follow the displayed post commands. Some of them are explained below.

        • Export the replication gateway certificate and add it to the respective ODSEE instance which must be replicated.

        • Modify DN "cn=replication manager, cn=replication, cn=config" with usercertifcate attribute which contains the ODSEE instance certificate in binary form.

        If you do not want certificate based authentication process, leave the check box unchecked and proceed with the gateway replication.

    • To set up replication monitoring with registration into the ODSEE Directory Service Control Center Registry, provide the following information:

      1. Check the Enable DSCC monitoring between ODSEE and Replication Gateway box.

      2. DSCC Directory Service Manager: Enter the Directory Service Manager username.

      3. DSCC Directory Service Manager Password: Enter the password for the Directory Service Manager.

      4. DSCC Registry Host Name: Enter the host name or IP address for the DSCC Registry host.

      5. DSCC Registry Port: Enter the port number for the DSCC Registry host.

    • Click Next.

    The Review Replication Setting screen is displayed.

  7. Review the ODSEE replication setup and click Next.

    The Port for ODSEE Replication screen is displayed.

  8. Enter the port on the replication gateway instance that will be used for Oracle Directory Server Enterprise Edition replication updates.

  9. Click Next.

    The Oracle Unified Directory Server Settings screen is displayed.

  10. Enter the following information:

    • Host Name: Enter the directory server's host name or IP address.

      The default is the local host name.

    • Administration Connector Port: Enter the port that is used for administration traffic.

      The default administration port is 4444. See Managing Administration Traffic to the Server in Administering Oracle Unified Directory.

    • Global Administrator User ID: Enter the name of the global administrator that has been defined to manage replication on the Oracle Unified Directory instance.

      If no global administrator has been defined, enter the root user bind DN.

    • Enter the password of the Global Administrator.

    Click Next.

  11. Accept the certificates.

  12. If the Oracle Unified Directory server was not previously configured for replication, perform the following steps:

    • Enter the replication port number for this directory server.

    • Provide a UID and password for the new global administrator.

  13. Review the replication settings and click Next.

    The Replicated Base DNs screen is displayed.

  14. Select the suffixes that will be replicated between the Oracle Directory Server Enterprise Edition servers and the Oracle Unified Directory servers.

  15. On the Review screen, verify the final topology and click Finish to complete the installation.

    The Show Summary menu item in the drop down list displays a textual summary of the resulting topology.

    The Show Topology menu item displays a graphical summary of the topology, and can be useful for obtaining a physical idea of the resulting topology.

    The Show Equivalent Command Line menu item displays all of the commands that are executed in configuring the replication gateway. This item also provides information about the next steps that are required to start replication between the two servers. See Replicating Between Oracle Directory Server Enterprise Edition and Oracle Unified Directory in Administering Oracle Unified Directory.

  16. Click Finish to complete the setup.

  17. Execute the following command in ODSEE server host for the replication to be successful.

    dsadm export \
          -f opends-export \
          <DSEE Instance1> \
          <Base DN> \
          {exportedLDIFPath}
    Where {exportedLDIFPath} is the path of the resulting LDIF file containing the replicated data.

  18. Execute the following commands in Oracle Unified Directory server for the replication to be successful.

    • Execute dsreplication pre-external-initialization command. 

      asinst/OUD/bin/dsreplication pre-external-initialization \
          --hostname <OUD hostname> \
          --port <OUD Admin port> \
          --adminUID <Provide Admin UID> \
          --adminPasswordFile <Password file> \
          --baseDN <Base DN> \
          --trustAll \
          --no-prompt \
          --noPropertiesFile

    • Execute import-ldif command. Copy the LDIF file generated in the first step in a directory accessible by the Oracle Unified Directory servers and run the following command for every Oracle Unified Directory server that contains data to be replicated: 

      asinst/OUD/bin/import-ldif \
          --hostname <OUD Hostname> \
          --port <OUD Admin port> \
          --bindDN <Bind DN> \
          --bindPasswordFile <Password file> \
          --includeBranch <Base DN> \
          --ldifFile {exportedLDIFPath} \
          --clearBackend \
          --trustAll \
          --noPropertiesFile

    • Execute dsreplication post-external-initialization command. 

      asinst/OUD/bin/dsreplication post-external-initialization \
          --hostname <OUD Hostname> \
          --port <OUD Admin Port> \
          --adminUID <Provide Admin UID> \
          --adminPasswordFile <Password file> \
          --baseDN <Base DN> \
          --trustAll \
          --no-prompt \
          --noPropertiesFile

5.3 Setting Up the Replication Gateway Using the Command-Line Interface (CLI)

The command-line setup is either interactive or non-interactive. The non-interactive setup enables you to configure the server without user intervention. The interactive setup prompts you for any required information before the configuration begins.

Note:

The command-line setup is complex and is recommended for scripting purposes only. Oracle recommends that you use the GUI to set up the replication gateway.

To set up the replication gateway using the command line:

$ oud-replication-gateway-setup --cli

Note:

The instance is created directly under OUD-base-location by default. However, Oracle strongly recommends that you create your Oracle Unified Directory instance outside of the Oracle home directory.

In interactive command-line mode, you are prompted to provide the required configuration details, for example:

$ oud-replication-gateway-setup --cli
OUD Instance location successfully created - /local/OUD_BASE/Oracle_OUD1/../asinst_4
The migration utility ds2oud must be run to configure the OUD servers before
setting up the replication gateway.
If you have executed ds2oud type 'yes' to continue, type 'no' otherwise. (yes
/ no) [yes]: yes
 
Oracle Unified Directory 11.1.2.1.0
Please wait while the replication gateway setup program initializes ..... Done.
 
====================================================================
Replication gateway administration settings
====================================================================
 
You must provide the fully-qualified name of the host where the replication
gateway will be installed.  The ODSEE server and Oracle Unified Directory
servers in the replication topology must be able to access this host name
[server1]:
 
What would you like to use as the initial root user DN for the replication
gateway? [cn=Directory Manager]:

To facilitate scripting, you can also set up the replication gateway in non-interactive mode, by using the --no-prompt option. The following example shows a typical replication gateway setup in non-interactive mode: 

$ oud-replication-gateway-setup --cli --hostname localhost \
  --adminConnectorPort 4444 --replicationPortForLegacy 2389 \
  --rootUserDN "cn=Directory Manager" --rootUserPasswordFile pwd-file \
  --baseDN dc=example,dc=com --hostNameLegacy ODSEE-host \
  --portLegacy 1389 --doNotUpdateTrustStoreWithLegacyCertsArg \
  --bindDNLegacy "cn=Directory Manager" --bindPasswordFileLegacy pwd-file \
  --hostNameNg OUD-host --portNg 4444 --adminUID admin \
  --adminPasswordFile pwd-file --trustAll --no-prompt \
  --noPropertiesFile --doNotMonitorUsingDsccLegacy

The following example shows a typical replication gateway setup in non-interactive mode with registration into the ODSEE Directory Service Control Center Registry. This configuration is useful when you want to monitor replicated changes using the ODSEE monitoring interface.

$ oud-replication-gateway-setup --cli --hostname localhost \
  --adminConnectorPort 4444 --replicationPortForLegacy 2389 \
  --rootUserDN "cn=Directory Manager" --rootUserPasswordFile pwd-file \
  --baseDN dc=example,dc=com --hostNameLegacy ODSEE-host \
  --portLegacy 1389 --doNotUpdateTrustStoreWithLegacyCertsArg \
  --bindDNLegacy "cn=Directory Manager" --bindPasswordFileLegacy pwd-file \
  --hostNameNg OUD-host --portNg 4444 --adminUID admin \
  --adminPasswordFile pwd-file --trustAll --no-prompt --noPropertiesFile \
  --dsccHostLegacy  gnb10492 --dsccPortLegacy 3998 --dsccAdminUidLegacy admin \
  --dsccPasswordFileLegacy pwd-file

See oud-replication-gateway-setup in Administering Oracle Unified Directory.

5.4 Verifying the Replication Gateway Setup

To verify that the replication gateway has been set up and is working correctly, add an entry on the Oracle Unified Directory server. Verify that the newly added entry has been successfully replicated to the Oracle Directory Server Enterprise Edition server.

The following example adds a user entry on the Oracle Unified Directory server: 

$ ldapmodify -a -h oud-host -p 1389 -D "cn=directory manager" -j pwd-file 
dn: uid=bjensen,ou=People,dc=example,dc=com 
objectclass: top 
objectclass: person 
objectclass: organizationalPerson 
objectclass: inetorgPerson 
uid: bjensen 
givenName: Barbara 
sn: Jensen 
cn: Babs Jensen 
telephoneNumber: (408) 555-3922 
facsimileTelephoneNumber: (408) 555-4000 
mail: bjensen@example.com 
userPassword: secret 
 
Processing ADD request for uid=bjensen,ou=People,dc=example,dc=com
ADD operation successful for DN uid=bjensen,ou=People,dc=example,dc=com

The following example searches for that user entry on the Oracle Directory Server Enterprise Edition server: 

$ ldapsearch -h odsee-host -p 1389 -D "cn=directory manager" -j pwd-file -b "ou=people,dc=example,dc=com" ("uid=bjensen")

version: 1
dn: uid=bjensen, ou=People, dc=example,dc=com
cn: Barbara Jensen
cn: Babs Jensen
sn: Jensen
givenName: Barbara
objectClass: top
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
ou: Product Development
ou: People
l: Cupertino
uid: bjensen
mail: bjensen@example.com
telephoneNumber: +1 408 555 1862
facsimileTelephoneNumber: +1 408 555 1992
roomNumber: 0209
userPassword: {SSHA}rDLnCHlFRhyAcBM7GZpby0MrwfxzTlIEdG7WYA==

5.5 Setting Up the Replication Gateway Using the WebLogic Scripting Tool

You can use the WebLogic Scripting Tool (WLST) to set up the replication gateway server. Execute the oud_createInstance with the oud-replication-gateway-setup script to set up a replication gateway server instance using the WLST.

Before you set up a replication gateway instance, the following must be in place:

  • The Oracle Unified Directory servers in the topology must be configured so that inconsistencies between the Oracle Directory Server Enterprise Edition configuration and the Oracle Unified Directory configuration are taken into account. See Replicating Between Oracle Directory Server Enterprise Edition and Oracle Unified Directory in Administering Oracle Unified Directory.

    Run the ds2oud command to configure the Oracle Unified Directory directory servers to coexist with Oracle Directory Server Enterprise Edition servers in a replicated topology. See ds2oud in Administering Oracle Unified Directory.

  • The Oracle Directory Server Enterprise Edition servers that will be connected to the replication gateway must be configured for replication and must be master replicas.

    Replication must be enabled in Oracle Directory Server Enterprise Edition on the suffix that will be replicated. This is the case even if there is only one Oracle Directory Server Enterprise Edition server in the topology.

  • The replication gateway setup attempts to contact the Oracle Unified Directory server and the Oracle Directory Server Enterprise Edition server. These servers must therefore be up and running.

To set up a replication gateway server instance using the WLST:

  1. Set the PRODUCT_HOME and DOMAIN_HOME environment variables before launching WLST.
    export PRODUCT_HOME=/scratch/user/middleware/oracle_home
export DOMAIN_HOME=/scratch/user/middleware/oracle_home/user_projects/domains/base_domain

    PRODUCT_HOME is similar to ORACLE_HOME. It points to the directory where a user provides at the time of product installation. However, DOMAIN_HOME points to the directory where domains that you configure are created.

  2. Launch the WLST:

    On UNIX and Linux systems:

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

    On Windows systems:

    C:\> ORACLE_HOME\oracle_common\common\bin\wlst.cmd

    ORACLE_HOME is the Oracle home directory you specified at installation.

  3. Execute the oud_createInstance command with script name oud-replication-gateway-setup to create the replication gateway instance.
    oud_createInstance(scriptName='oud-replication-gateway-setup',instanceName='oud_repl',hostname='localhost', 
adminConnectorPort=7444,replicationPortForLegacy=2989,rootUserDN='cn=Directory\ Manager',
rootUserPasswordFile='/scratch/user/work/password.txt',baseDN='dc=example,dc=com',hostNameLegacy='localhost',portLegacy=4389, 
bindDNLegacy='cn=Directory\ Manager',bindPasswordFileLegacy='/scratch/user/work/password.txt', 
adminPasswordFile='/scratch/user/work/password.txt',hostNameNg='localhost',portNg=4444,bindDNNg='cn=Directory\ Manager', 
bindPasswordFileNg='/scratch/user/work/password.txt',dsccHostLegacy='localhost',dsccPortLegacy=3998,dsccAdminUidLegacy='admin', 
dsccPasswordFileLegacy='/scratch/user/work/password.txt',trustAll='')

    scriptName indicates the setup script based on the flavor of OUD. The value for this parameter can be any one from [oud-setup, oud-proxy-setup, oud-replication-gateway-setup].

    instanceName indicates the name of the instance. For example, oud_repl.

    Note:

    Arguments that cannot have a value like trustAll, noPropertiesFile, and so on, can also be used with the custom WLST commands. You must pass an empty value for these arguments. For example, trustAll='' or noPropertiesFile=''.

    Gateway instance is created between Oracle Directory Server Enterprise Edition (ODSEE) and Oracle Unified Directory instances. Hence, you must also provide the Oracle Directory Server Enterprise Edition server options while creating a gateway instance.

    See oud-replication-gateway-setup in Administering Oracle Unified Directory for the rest of the parameters and their descriptions.

    Output:

    Initializing basic replication gateway configuration ..... Done.
The replication gateway will be started now temporarily to be configured
Starting Replication Gateway ....... Done.
Updating Registration Information ..... Done.
Configuring Oracle Unified Directory server localhost:4444 ..... Done.
Initializing Registration Information ..... Done.
Configuring Replication Gateway ..... Done.
Configuring ODSEE server localhost:4389 ..... Done.
Stopping Replication Gateway ............... Done.

The replication gateway setup has completed successfully
Successfully created OUD instance