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:
-
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
-
Ensure that your
JAVA_HOME
environment variable is set to a supported JVM installation (at least Java 1.8). -
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 namedasinst_2
,asinst_3
, and so on. To specify a different instance name, set theINSTANCE_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.
-
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.
-
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.
-
-
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:
-
Check the Use SSL between ODSEE and Replication Gateway check box.
-
Ensure that the port you specified above is the secure port of the Oracle Directory Server Enterprise Edition server.
-
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
" withusercertifcate
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:
-
Check the Enable DSCC monitoring between ODSEE and Replication Gateway box.
-
DSCC Directory Service Manager: Enter the Directory Service Manager username.
-
DSCC Directory Service Manager Password: Enter the password for the Directory Service Manager.
-
DSCC Registry Host Name: Enter the host name or IP address for the DSCC Registry host.
-
DSCC Registry Port: Enter the port number for the DSCC Registry host.
-
-
Click Next.
The Review Replication Setting screen is displayed.
-
-
Review the ODSEE replication setup and click Next.
The Port for ODSEE Replication screen is displayed.
-
Enter the port on the replication gateway instance that will be used for Oracle Directory Server Enterprise Edition replication updates.
-
Click Next.
The Oracle Unified Directory Server Settings screen is displayed.
-
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.
-
-
Accept the certificates.
-
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.
-
-
Review the replication settings and click Next.
The Replicated Base DNs screen is displayed.
-
Select the suffixes that will be replicated between the Oracle Directory Server Enterprise Edition servers and the Oracle Unified Directory servers.
-
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.
-
Click Finish to complete the setup.
-
Execute the following command in ODSEE server host for the replication to be successful.
Where {exportedLDIFPath} is the path of the resulting LDIF file containing the replicated data.dsadm export \ -f opends-export \ <DSEE Instance1> \ <Base DN> \ {exportedLDIFPath}
-
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: