This chapter tells you how to monitor and manage replication in Oracle Internet Directory. For more information about replication configuration attributes, see Chapter 42, "Managing Replication Configuration Attributes."
This chapter contains the following sections:
Section 43.1, "Introduction to Managing and Monitoring Replication"
Section 43.2, "Managing and Monitoring Replication by Using ODSM and Fusion Middleware Control"
Section 43.3, "Managing and Monitoring Replication by Using the Command Line"
Section 43.4, "Comparing and Reconciling Inconsistent Data by Using oidcmprec"
Note:
Some changes do not take effect until the replication server is restarted.
After you have installed and configured replication, you can view or modify the default values for replication-related attributes. The attributes and their containers are described in Chapter 42, "Managing Replication Configuration Attributes."
See Also:
This introduction includes the following topics:
In LDAP-based partial replication, you can change what is or is not replicated by modifying replica naming context objects. The parameters for these objects are stored in entries that have this DN:
cn=namingcontext_ID,cn=replication namecontext, orclAgreementID=numeric_identifier_of_replication_agreement, orclReplicaId=unique_identifier_of_replica, cn=replication configuration
Note:
Because the directory replication server reads replica naming context objects from the agreement located at the supplier, you must apply all modifications against naming context objects at the supplier and, optionally, at the consumer.
See Section 43.2.3, "Viewing and Modifying Replica Naming Context Objects" and Section 43.3.6, "Modifying Replica Naming Context Object Parameters by Using ldapmodify."
The replication server is a multithreaded process. You can control the number of worker threads per supplier that are dedicated to:
Transporting the changelogs from supplier to consumer
Applying the transported changelogs at consumer
You can set the number of transport threads and the number of apply threads per supplier. Alternatively, you can configure the replication server to auto tune, that is, to dynamically vary the number of threads assigned to these two tasks based on load. If you set the server to auto tune, you must specify the number of maximum number of threads to be shared between these tasks.
Table 43-1 shows the Oracle Enterprise Manager Fusion Middleware Control parameters and configuration attributes that control worker threads. These are attributes of the replication configuration set.
Table 43-1 Configuration Attributes Controlling Worker Threads
| Fusion Middleware Control Parameter | Configuration Attribute |
|---|---|
|
Number of Apply Threads Per Supplier |
|
|
Number of Transport Threads per Supplier |
You must tune these numbers based on load. In Oracle Enterprise Manager Fusion Middleware Control, you configure threads by using the Shared Properties page, Replication tab. From the command line, you use ldapmodify.
Oracle Internet Directory records each change as an entry in the change log store. Each entry has a unique change number. The consumer keeps track of the change number of the last change it applied, and it retrieves from the supplier only those changes with numbers greater than that of the last change it applied.
In an LDAP-based replication agreement, change log processing consists of two phases, transporting the change log and applying the change log. For each LDAP-based agreement, there are two change log processing statuses, one for the each phase. The directory replication server stores the last change number it transported in the transport subtype of the orlcllastappliedchangenumber attribute of the replication agreement entry. The directory replication server stores the last change number it applied in the apply subtype of the orllclastappliedchangenumber attribute of the replication agreement entry. The format of the orlcllastappliedchangenumber attribute is shown in Section 42.1.3.1, "Attributes of the Replication Agreement Entry."
In a replication agreement based on Oracle Database Advanced Replication, the directory replication server stores the last change number it transported in the changenumber attribute of the changestatus entry. The changenumber attribute looks like this:
changenumber=last_applied_change_number, supplier=supplier_node, consumer=consumer_node
For example, if the last change a consumer applied had a number of 250, then subsequent changes it retrieves from that supplier would need to have numbers greater than 250.
When a multivalued attribute is modified, Oracle Internet Directory normally generates a change log containing all the values of that attribute, even if the modification added only one new value. However, for member and uniquemember, which might contain millions of values, this behavior would cause performance issues. Instead, for member and uniquemember, Oracle Internet Directory generates a change log containing only the values added or deleted. This behavior is controlled by the DSE attribute orclsimplemodchglogattributes.
Change logs are purged by the garbage collector after they have been consumed by the replication server.
Section D.5, "The Replication Process" describes the roles of the human intervention queue, the purge queue, and the retry queue in replication. Section 43.1.6, "Conflict Resolution in Oracle Replication" provides information about the role of these queues in conflict resolution.
The human intervention queue tools, ManageHiq.retry and ManageHiq.purge, enable you to move changes from the human intervention queue to the retry queue or the purge queue, respectively. See Section 43.3.9, "Managing the Human Intervention Queue."
You can view queue statistics by using the replication wizard in Oracle Enterprise Manager Fusion Middleware Control or the command line. See Section 43.2.10, "Viewing Queue Statistics by Using Fusion Middleware Control"and Section 43.3.2, "Viewing Change Logs by Using ldapsearch."
If the number of entries in the Human Intervention Queue is greater than the maximum number of changelogs the replication server can process at a time, some entries are never processed.
The maximum number of changelogs the replication server can process at a time is the minimum of two configuration attributes:
orclsizelimit in the instance-specific configuration entry of the OID component where replication is active
The default value of orclsizelimit in the replication configuration set is 1000. If you set it to 0, it takes the default value of 1000.
The orclsizelimit attribute in the Oracle Internet Directory instance-specific entry specifies the maximum number of entries to be returned by a search. (Its default value is 10000.
To increase the number of changelogs processed at a time, you must set both attributes to the same value, a value greater than 1000.
See Also:
Setting the Oracle Internet Directory server instance attribute orclsizelimit very high impacts server performance, because orclsizelimit in the Oracle Internet Directory server instance also controls the maximum number of entries to be returned by a search.
Pilot mode is used to test an application before deploying it in production. Typically, you set pilot mode on the local node, with one-way replication from the production node. While the replica is in pilot mode, all the LDAP changes occurring at the local node are tracked. When you end pilot mode, those changes are written to an LDIF file. When the application is deployed in production, all the entries added or modified in the pilot replica can be added to the production node using the ldif file.
Oracle Database Advanced Replication-based replication and two-way and multimaster LDAP-based replication enable updates to multiple directory servers. Conflicts occur whenever the directory replication server attempts to apply remote changes from a supplier to a consumer and, for some reason, fails.
Conflicts usually stem from differences in the timing of changes arising from the occasional slowness or transmission failure over wide area networks. Also, an earlier inconsistency might continue to cause conflicts if it is not resolved in a timely manner.
In partial replication, when a naming context is changed from included to excluded, the replication server deletes the naming context at the consumer. Similarly, if the naming context is changed from excluded to included, the replication server synchronizes the entire naming context from supplier to consumer.
LDAP operations that can lead to conflicts include:
Addition
Deletion
Modification
Modification of either an RDN or a DN
There are two types of conflicts:
Entry-level conflicts
Attribute-level conflicts
Table 43-2 Types of Replication Conflict
| Level of Replication Conflict | Description |
|---|---|
|
Entry-level conflicts |
Caused when the directory replication server attempts to apply a change to the consumer. One of the following types of changes to the consumer could occur:
These conflicts can be difficult to resolve. For instance, it may be impossible to resolve a conflict because:
If an entry exists and it should not, then it may be because it was added earlier, or that it recently underwent a modifydn operation. |
|
Attribute-level conflicts |
Caused when two directories are updating the same attribute with different values at different times. If the attribute is single-valued, then the replication process resolves the conflict by examining the timestamps of the changes involved in the conflict and the attribute version number. The attribute |
In 11g Release 1 (11.1.1), you can enable automatic conflict resolution. When this feature is enabled, conflicts in the Human Intervention Queue are automatically moved to the purge queue if the supplier's schema and consumer's schema match.
You can use either Oracle Enterprise Manager Fusion Middleware Control or the ldapmodify command to enable or disable automatic conflict resolution. To use Oracle Enterprise Manager Fusion Middleware Control, change the replication configuration parameter Automatically Resolve Replication Conflicts. on the Replication tab of the Shared Properties page. To use the command line, change the value of orclconflresolution in the replication configuration set.
The directory replication server attempts to resolve all conflicts that it encounters by following this process:
The conflict is detected when a change is applied.
The replication process attempts to reapply the change a specific number of times or repetitively for a specific amount of time after a specific waiting period.
If the replication process reaches the retry limit without successfully applying the change, it flags the change as a conflict, which it then tries to resolve. If the conflict cannot be resolved according to the resolution rules (described in the next section), the change is moved to a low-priority, human intervention queue. Changes are then applied according to the time unit specified in the orclHIQSchedule parameter in the replication agreement. Before it moves the change, the directory replication server writes the conflict into a log file for the system administrator.
Note:
There is no conflict resolution of schema, catalog, and group entries during replication. This is because attempting resolution of such large multivalued attributes would have a significant negative impact on performance. Be careful to avoid updating such entries from more than one master at a time.
See Also:
Appendix D, "How Replication Works"for descriptions of how the multimaster replication process adds, deletes, and modifies entries, and how it modifies DNs and RDNs.
"Oracle Identity Management LDAP Schema Reference" in Oracle Fusion Middleware Reference for Oracle Identity Management for schema questions
The catalog command-line tool reference in Oracle Fusion Middleware Reference for Oracle Identity Management for catalog questions
The section on managing group entries in Oracle Identity Management Guide to Delegated Administration in the 10g (10.1.4.0.1) library for group entry questions
You can manage and monitor replication by using Oracle Enterprise Manager Fusion Middleware Control. This section contains the following topics:
Section 43.2.1, "Enabling or Disabling Change Log Generation by Using Fusion Middleware Control"
Section 43.2.2, "Viewing the Local Change Logs by Using Oracle Directory Services Manager"
Section 43.2.3, "Viewing and Modifying Replica Naming Context Objects"
Section 43.2.4, "Viewing or Modifying a Replication Setup by Using the Replication Wizard"
Section 43.2.5, "Deleting an LDAP-Based Replication Agreement by Using the Replication Wizard"
Section 43.2.6, "Configure Replication Attributes by Using Fusion Middleware Control"
Section 43.2.7, "Activating or Inactivating a Replication Server by Using Fusion Middleware Control"
Section 43.2.8, "Configuring the Replication Debug Level by Using Fusion Middleware Control"
Section 43.2.9, "Configuring Replica Details by Using Fusion Middleware Control"
Section 43.2.10, "Viewing Queue Statistics by Using Fusion Middleware Control"
Section 43.2.11, "Managing Changelog Processing by Using Fusion Middleware Control"
Section 43.2.12, "Monitoring Conflict Resolution Messages by Using Fusion Middleware Control"
You can enable and disable change log generation by using Oracle Enterprise Manager Fusion Middleware Control, as follows:
Choose Administration, then Server Properties from the Oracle Internet Directory menu.
Choose the Performance tab.
Select or deselect Enable Change Log Generation.
After changing the configuration, choose Apply.
Oracle Directory Services Manager enables you to view the last 500 changes you performed, listing them by change log number, the type of operation—namely, add, modify, or delete—in which each occurred, and the entry on which each was made. It allows you select a particular change to see more specific details about it.
You can view change logs by using Oracle Directory Services Manager, as follows:
From the task selection bar, select Advanced.
Expand Change Log if it is not already expanded. The left panel lists the last 500 changes, beginning with the most recent.
Select a change to view its properties.
Table 43-3 lists the properties shown on the Change Log page and the corresponding attributes of the change log entry.
Table 43-3 Properties on the Change Log Page
| Property | Change Log Attribute |
|---|---|
|
Change Number |
|
|
Operation |
|
|
TargetDN |
|
|
Changes |
|
|
Global Unique Identifier (GUID) |
|
|
Parent GUID |
|
|
Change Retry Count |
|
|
Modifier's Name |
|
|
Operation Time |
|
|
Server Name |
|
To add, delete, view, and modify parameters for replica naming context objects, use the Replication Wizard in Oracle Enterprise Manager Fusion Middleware Control:
From the Oracle Internet Directory menu on the home page, select Administration, then Replication Management.
You are prompted to log into the replication DN account. Provide the host, port, replication DN, and replication DN password.
The Replication Agreements page lists information about each replication agreement: name, type, supplier, consumer, and status. Select the name of the replication agreement you want to edit and click the Edit icon. Three tabs appear at the bottom of the screen.
On the Scope tab, you can change the scope settings.
To add a primary naming context, click the Create button above the Primary Naming Context field.
To change the primary naming context, click the Edit button above the Primary Naming Context field and select a different container.
To exclude a secondary naming context, select it in the Secondary Naming Contexts field and click Exclude to move it to the Excluded Secondary Naming Contexts field.
To include a secondary naming context, select it in the Excluded Secondary Naming Contexts field and click Include to move it to the Secondary Naming Contexts field.
To exclude an attribute, select it in the Attributes field and click Exclude to move it to the Excluded Attributes field.
To include an attribute, select it in the Excluded Attributes field and click Include to move it to the Attributes field.
To apply your changes, click Apply.
To effect the changes you have made, you must start or restart the replication server. For one-way replication, you must restart it on the consumer. For a two-way or multimaster replication agreement, you must restart the replication server on each of the nodes in the replication agreement. To do this, select the Oracle Internet Directory node in the navigation tree and select Control from the Oracle Internet Directory menu.
When you set up replication, you create a replication agreement and replica subentry. You can view or modify the setup by using the Replication Wizard in Oracle Enterprise Manager Fusion Middleware Control, as follows.
From the Oracle Internet Directory menu on the home page, select Administration, then Replication Management.
You are prompted to log into the replication DN account. Provide the host, port, replication DN, and replication DN password.
To view queue statistics for a replication agreement, select the replication agreement, select Queue Statistics and proceed as described in Section 43.2.10, "Viewing Queue Statistics by Using Fusion Middleware Control."
To view or edit a replication agreement, select the name of the replication agreement you want to edit and click the Edit icon. At the bottom of the screen, three tabs appear.
To view or edit the replication configuration, select the Replication Configuration tab.
Note:
Always inactivate replication before you delete or modify a replication agreement. See Section 43.2.7, "Activating or Inactivating a Replication Server by Using Fusion Middleware Control."
In the LDAP Connection field, select Keep Alive if you want the replication server to use same connection for performing multiple LDAP operations. Select Always Use New Connection if you want the server to open a new connection for each LDAP operation.
Enter the Replication Frequency.
Enter the Human Intervention Queue Schedule. This is the interval, in seconds, at which the directory replication server repeats the change application process.
Click Apply to apply your changes, or click Cancel to discard your changes.
To view or change the Scope settings, click the Scope tab. Proceed as described in Section 43.2.3, "Viewing and Modifying Replica Naming Context Objects."
To view the type, host, port, and user name for each node, click the Replicas tab of the Edit Replication Definition page.
To view or edit Replica Primary URI, Replica Secondary URI, or Replica State for a node:
Select the Replicas tab and click the "+" next to the supplier or consumer.
Make desired changes to the Replica Primary URI or Replica Secondary URI fields.
Select a Replica State from the list.
Click Apply to apply your changes, or click Cancel to discard your changes.
To make a node the primary node in a multimaster replication group:
Click the Replicas tab, select the node, and
Click the Make Primary Node icon.
Click Apply to add the node to the existing directory replication group or click Cancel to discard your changes.
To add a node to a multimaster replication group:
Select the Replicas tab.
Click the Create icon.
In the popup window, provide the host, port and replication DN password details for the new node. Click Add.
Click Apply to add the node to the existing directory replication group or click Cancel to discard your changes.
To delete a node from a multimaster replication group containing three or more nodes:
Select the Replicas tab.
Click the replica you want to delete from the multimaster replication deployment. The Delete icon becomes enabled.
Click Delete.
Click Apply to delete the node from the directory replication group (DRG)
You delete a one-way, two-way, or multimaster LDAP replica by using the Replication Wizard in Oracle Enterprise Manager Fusion Middleware Control.
Note:
Always inactivate replication before you delete or modify a replication agreement. See Section 43.2.7, "Activating or Inactivating a Replication Server by Using Fusion Middleware Control."
From the Oracle Internet Directory menu on the home page, select Administration, then Replication Management. The Replication Agreements page lists information about each replication agreement: name, type, supplier, consumer, and status.
You are prompted to log into the replication DN account. Provide the host, port, replication DN, and replication DN password.
To delete a replication agreement, select the agreement and click the Delete icon. When the Delete Popup appears, click Delete.
You can configure most replication configuration set attributes by using the Replication tab of the Shared Properties page of Fusion Middleware Control. Select Administration, then Shared Properties from the Oracle Internet Directory menu, then select Replication. After changing the configuration, choose Apply. Table 43-4 shows the correspondence between the fields on the Replication Configset section of the Shared Properties page. See Table 42-5 for detailed information about these attributes.
Table 43-4 Replication Configset Attributes on Shared Properties, Replication Tab
| Field or Heading | Configuration Attribute |
|---|---|
|
Number of Transport Threads per Supplier |
|
Restart the server after changing Autotune Replication or Generate Stack Dump.
See Also:
Table 42-4, "Replication Configuration Set Attributes" for a description of the attributes.
Section 43.2.8, "Configuring the Replication Debug Level by Using Fusion Middleware Control" for more information on setting Debug Level.
When you set up replication using the Replication Wizard, the replication server is automatically activated on the Oracle Internet Directory instances where you configured it. If necessary, you can inactivate replication and activate it again without changing your configuration. You can also inactivate replication on one instance and activate it on another Oracle Internet Directory instance that is sharing the same database. To disable or enable replication by using Oracle Enterprise Manager Fusion Middleware Control, use the Replication Server Status section of the Replication tab of the Shared Properties page of Fusion Middleware Control
Configure the attributes as follows:
Select Administration, then Shared Properties from the Oracle Internet Directory menu, then select Replication.
In the Replication Server Status section of the page, select the Oracle Internet Directory component that you want to activate or inactivate from the Activate Replication on list. This list displays all the Oracle Internet Directory components in a WebLogic Server domain that share the same database.
If the replication status of the selected Oracle Internet Directory component is inactive, you can click Activate to activate it. If the replication status is active, you can click Inactivate to activate it. You do not need to click anything else. Activating replication on one instance automatically inactivates it on the instance where it was previously active.
Note:
The Revert and Apply buttons at the top of the page have no effect upon the replication server status.
Table 43-5 shows the correspondence between the fields in the Replication Server Status section of the page and the configuration attributes. See Section 42.1.6, "Replication Configuration Set Attributes" for more information about these attributes.
You can configure the replication debug level by using the Debug Level section of the Replication tab of the Shared Properties page of Fusion Middleware Control.
See Table 42-4, "Replication Configuration Set Attributes" for information about the orcldebuglevel attribute.
Configure the debug level as follows:
Select Administration, then Shared Properties from the Oracle Internet Directory menu, then select Replication.
Select any combination of Replication Process, Trace Function Calls, Replication Performance Log, and Heavy Trace Debugging.
Choose Apply.
You can change replica details by using the Replica Details section of the Replication tab of the Shared Properties page of Fusion Middleware Control.
Table 43-6 shows the correspondence between the fields in the Replica Details section and the attributes of the replica subentry. See Table 42-1, "Attributes of the Replica Subentry" for more information about these attributes.
See Section D.4, "LDAP Replica States" for information about the values of orclreplicastate.
Table 43-6 Replica Details on Shared Properties, Replication Tab
| Field or Heading | Configuration Attribute in the Replica Subentry |
|---|---|
To configure the replica details, select Administration, then Shared Properties from the Oracle Internet Directory menu, then select Replication. After changing the configuration, choose Apply.
The choices for Replica State are Bootstrap, Online and DB Copy AddNode.
The choices for Replica Type are ReadWrite, Read Only, and Pilot.
You view statistics for an LDAP replica by using the Oracle Enterprise Manager Fusion Middleware Control replication wizard, as follows.
From the Oracle Internet Directory menu on the home page, select Administration, then Replication Management.
You are prompted to log into the replication DN account. Provide the host, port, replication DN, and replication DN password.
The Replication Agreements page lists information about each replication agreement. Click the name of the replication agreement for which you want to view the queue statistics, then click the Queue Statistics icon.
The bottom of the page lists the following statistics:
New Changes
Retry Changes
Purge Changes
HIQ Changes
Last Applied Change
Last Transported Change
To increase the number of changelogs processed at a time, you must set orclsizelimit in the replication configuration set and orclsizelimit in the server instance where replication is running to the same value, a value greater than 1000.
To change orclsizelimit in the replication configuration set by using Fusion Middleware Control:
Select Administration, then Shared Properties from the Oracle Internet Directory menu
Select Replication.
Change the parameter Maximum Number of Entries to Process per Replication Cycle.
Choose Apply.
To change orclsizelimit in a server instance by using Oracle Enterprise Manager Fusion Middleware Control:
Select Administration, then Server Properties from the Oracle Internet Directory menu.
Select General.
Change the value of Maximum number of entries to be returned by a search.
Choose Apply.
Setting the Oracle Internet Directory server instance parameter orclsizelimit very high impacts server performance, because orclsizelimit also controls the maximum number of entries to be returned by a search.
You can view conflict resolution messages in the Replication Log by using Oracle Enterprise Manager Fusion Middleware Control, as follows:
From the Oracle Internet Directory menu, select Monitoring, then Logs. The Log Messages page appears.
Click Log Files. The Log Files page appears.
Select Replication Log.
See Also:
Section 24.2.1, "Viewing Log Files by Using Fusion Middleware Control"for detailed information about viewing log files in Oracle Enterprise Manager Fusion Middleware Control.
Section 43.3.8, "Monitoring Conflict Resolution Messages by Using the Command Line" for detailed infomation about conflict resolution messages.
This section contains the following topics
Section 43.3.1, "Enabling and Disabling Change Log Generation by Using the Command Line"
Section 43.3.3, "Configuring Attributes of the Replica Subentry by Using ldapmodify"
Section 43.3.4, "Specifying Pilot Mode for a Replica by Using remtool"
Section 43.3.5, "Configuring Replication Agreement Attributes by Using ldapmodify"
Section 43.3.6, "Modifying Replica Naming Context Object Parameters by Using ldapmodify"
Section 43.3.7, "Configuring Attributes of the Replication Configuration Set by Using ldapmodify"
Section 43.3.8, "Monitoring Conflict Resolution Messages by Using the Command Line"
Section 43.3.11, "Viewing Queue Statistics and Verifying Replication by Using remtool"
Section 43.3.12, "Managing the Number of Entries the Human Intervention Queue Tools Can Process"
Section 43.3.13, "Changing the Replication Administrator's Password for Advanced Replication"
You can enable and disable change log generation by using ldapmodify to change the value of orclgeneratechangelog, which is an instance-specific attribute. You enable change log generation by setting the value to 1 and disable it by setting the value to 0. The command is:
ldapmodify -D cn=orcladmin -q -p portNum -h hostname -f ldifFile
The LDIF file for changing the value of the orclgeneratechangelog attribute in the instance-specific entry to 1 looks like this:
dn: cn=componentname,cn=osdldapd,cn=subconfigsubentry
changetype: modify
replace: orclgeneratechangelog
orclgeneratechangelog: 1
To view change logs from the command line, you use ldapsearch. Specify in the search filter the change number or range of change numbers of the change logs you want to view. If you want to view change logs that have been transported from a supplier to the local host, also specify the replica ID of the supplier in the search filter.
For example, to view a range of change logs that have been transported from the supplier to the local node, type:
ldapsearch -D cn=orcladmin -p port -q -b "cn=changelogs" -s one \
"(&(objectclass=changeLogEntry)(servername=SUPPLIER_REPLICAID)\
(changeNumber>=FROMCHGNO)(changeNumber<=TOCHGNO))"
To view a single change log that has been transported from the supplier to the local node, type:
ldapsearch -D cn=orcladmin -p port -q -b "cn=changelogs" -s one \
"(&(objectclass=changeLogEntry)(servername=SUPPLIER_REPLICAID)\
(changeNumber=CHGNO))"
To view a range change logs that have been generated at the local node, type:
ldapsearch -D cn=orcladmin -p port -q -b "cn=changelogs" -s one \
"(&(objectclass=changeLogEntry)(changeNumber>=FROMCHGNO)(changeNumber<=TOCHGNO))"
To view a single change log that has been generated at the local node, type:
ldapsearch -D cn=orcladmin -p port -q -b "cn=changelogs" -s one \
"(&(objectclass=changeLogEntry)(changeNumber=CHGNO))"
Some lines in the output might contain the string <@! !@> as a separator.
Table 43-7 lists the important attributes in the change log.
Table 43-7 Important Attributes in the Change Log
| Attribute | Description |
|---|---|
|
|
Change Number |
|
|
Operation |
|
|
Target DN |
|
|
Changes |
|
|
Global Unique Identifier (GUID) |
|
|
Parent GUID |
|
|
Change Retry Count |
|
|
Modifier's Name |
|
|
Operation Time |
|
|
Server Name |
|
|
Additional change log information, such as the value of the client IP address For example: |
The replica subentry has the DN
orclreplicaid=Replica _ID,cn=replication configuration
Table 43-8 lists the attributes of the replica subentry that you can modify with ldapmodify. The command line syntax is:
ldapmodify -D cn=orcladmin -q -p portNum -h hostname -f ldifFile
Table D-1, "LDAP Replica States" describes the values of orclreplicastate in detail. You can set 0, 1 the values, 2, 6, or 8. The other orclreplicastate values listed in Table D-1 are read-only values set by the replication server during bootstrap.
To set orclreplicastate to zero, you would use the following LDIF file:
dn: orcclreplicaid=Replica _ID,cn=replication configuration
changetype: modify
replace: orclreplicastate
orclreplicastate: 0
Before you deploy a replica as part of your enterprise, you might want to test it in pilot mode. You use the remtool command to begin and end pilot mode. The syntax is:
remtool -pilotreplica begin -bind hostname:ldap_port
remtool -pilotreplica end -bind hostname:ldap_port [-bkup file_name]
When you run remtool -pilotreplica begin:
When you run remtool -pilotreplica end
orclpilotmode is set to 0
Do not attempt to modify these attributes directly with ldapmodify.
See Also:
The remtool command reference in Oracle Fusion Middleware Reference for Oracle Identity Management for more information about the -pilotreplica option to remtool.
The replication agreement has the DN:
orclagreementid=Agreement_ID,orclreplicaid=Replica_ID,cn=replication configuration
Table 43-9 lists the replication agreement attributes that you can modify by using ldapmodify. See Table 42-2, "Attributes of the Replication Agreement Entry" for more information.
Note:
Always inactivate replication before you delete or modify a replication agreement. See Section 43.2.7, "Activating or Inactivating a Replication Server by Using Fusion Middleware Control."
Table 43-9 Replication Agreement Options
The following LDIF file changes the human intervention queue schedule by changing the value of the orclHIQSchedule attribute in the replication agreement to 900 minutes:
dn: orclagreementid=Agreement_ID,orclreplicaid=Replica_ID,cn=replication configuration changetype: modify replace: orclhiqschedule orclhiqschedule: 900
It is possible to change the replication scope from the command line. To do so, you must create or modify the naming context object entries under the replication naming context container entry. See
See Also:
To change the replication scope, you would use a command line such as:
ldapadd -p port_number -h host -f file.ldif
with an LDIF file to set the scope for an agreement.
For example, you would use the following LDIF file to set the replication scope to cn=oraclecontext:
dn: cn=includednamingcontext000001,cn=replication namecontext,orclagreementid=agreementid,orclreplicaid=replicaid,cn=replication configurationobjectclass: orclreplnamectxconfig orclincludednamingcontexts: cn=oraclecontext cn: includednamingcontext000001
You would use the following file to exclude EMEA and APAC groups and exclude the attributes userpassword and authpassword from the replication scope
dn: cn=includednamingcontext000002,cn=replication namecontext,orclagreementid=agreementid,orclreplicaid=replicaid,cn=replication configuration objectclass=orclreplnamectxconfig orclincludednamingcontexts: dc=com orclexcludednamingcontexts: cn=groups,l=emea,dc=xyz,dc=com orclexcludednamingcontexts: cn=groups,l=apac,dc=xyz,dc=com orclExcludedAttributes: userpassword orclExcludedAttributes: authpassword cn: includednamingcontext000002
Replica naming context object parameters are listed and described under Replication Schema Elements in Oracle Fusion Middleware Reference for Oracle Identity Management.
Note:
The replication server reads naming context objects from the supplier replica.
Example 43-1 Adding a Naming Context Object for an LDAP-Based Replica
This example creates a naming context object that does the following:
Replicates the naming context ou=Americas,cn=mycompany
Excludes from replication the naming context cn=customer profile, ou=Americas,cn=mycompany
Excludes from replication the attribute userpassword
The steps are:
Edit the example file mod.ldif as follows:
dn: cn=naming_context_identifier, cn=replication namecontext, orclagreementid=replication_agreement_identifier, orclreplicaid=supplier_replica_identifier,cn=replication configuration orclincludednamingcontexts: ou=Americas,cn=mycompany orclexcludednamingcontexts: cn=customer profile, ou=Americas, cn=mycompany orclexcludedattributes: userpassword objectclass: top objectclass: orclreplnamectxconfig
Use ldapadd to add the partial replication naming context object to the supplier.
ldapadd -D "cn=orcladmin" -q -h supplier_host \ -p port_number -f mod.ldif
Example 43-2 Deleting a Naming Context Object
To delete the naming context object created in Example 43-1, type:
ldapdelete -D "cn=orcladmin" -q \ -h supplier_host -p supplier_host_port_number \ "cn=naming_context_identifier, cn=replication namecontext, \ orclagreementid=replication_agreement_identifier, \ orclreplicaid=supplier_replica_identifier, \ cn=replication configuration"
Example 43-3 Modifying the orclIncludedNamingContexts Attribute for a Replica Naming Context Object
The directory replication server uses the orclIncludedNamingcontexts attribute value of the replica naming context object to specify the top-level subtree included in partial replication.
In this example, the included naming context is set to c=us, which means that c=us is to be included in partial replication.
Edit the example file mod.ldif as follows:
DN:cn=naming_context_identifier,cn=replication namecontext, orclagreementid=replication_agreement_identifier, orclreplicaid=supplier_replica_identifier,cn=replication configuration Changetype:modify Replace: orclIncludedNamingcontexts orclIncludedNamingcontexts: c=us
Use ldapmodify to update the replication agreement orclupdateschedule attribute.
ldapmodify -D "cn=orcladmin" -q -h supplier_host -p port -f mod.ldif
Restart the directory replication server.
Example 43-4 Modifying the orclExcludedNamingContexts Attribute for a Replica Naming Context Object
The directory replication server uses the orclExcludedNamingcontexts attribute value of the replica naming context object to specify the top-level subtrees excluded from partial replication.
In this example, the excluded naming contexts are set to ou=Europe,c=us and ou=Americas,c=us, which means that these two naming contexts are to be excluded from partial replication.
Edit the example file mod.ldif as follows:
DN:cn=naming_context_identifier, cn=replication namecontext, orclagreementid=replication_agreement_identifier, orclreplicaid=supplier_replica_identifier,cn=replication configuration Changetype:modify Replace: orclExcludedNamingcontexts orclExcludedNamingcontexts: ou=Europe, c=us orclExcludedNamingcontexts: ou=Americas, c=us
Use ldapmodify to update the replication agreement orclupdateschedule attribute.
ldapmodify -D "cn=orcladmin" -q -h supplier_host -p port -f mod.ldif
Restart the directory replication server.
Note:
A subtree specified in the orclexcludednamingcontexts attribute must also be a subtree of the specified includednamingcontext of the same replica naming context object.
Example 43-5 Modifying the orclExcludedAttributes Attribute for a Replica Naming Context Object
You can specify that certain changes made to the included naming context be excluded, at attribute level, from partial replication. To determine which attributes are to be excluded, the directory replication server uses the value of the orclExcludedAttributes attribute of the replica naming context object.
In this example, the telephonenumber and title attributes of the naming context specified in the orclincludednamingcontexts attribute are excluded from replication.
Edit the example file mod.ldif as follows:
DN:cn=naming_context_identifier, cn=replication namecontext, orclagreementid=replication_agreement_identifier, orclreplicaid=supplier_replica_identifier,cn=replication configuration Changetype:modify Replace: orclExcludedAttributes orclExcludedAttributes: telephonenumber orclExcludedAttributes: title
Use ldapmodify to update the replication agreement orclupdateschedule attribute.
ldapmodify -D "cn=orcladmin" -q -h my_host -p port -f mod.ldif
The replication configuration set has the DN:
cn=configset0,cn=osdrepld,cn=subconfigsubentry
Table 43-10 lists the replication configuration set attributes that you can modify with ldapmodify.
Table 43-10 Replication Configuration Attributes
| Description | Configuration Attribute | Default Value |
|---|---|---|
|
10 |
||
|
20 |
||
|
(Restart server after changing.) |
1 |
|
|
|
5 |
|
|
Number of Transport Threads per Supplier |
1 |
|
|
1000 |
||
|
1 |
||
|
(Restart server after changing.) |
||
|
none |
||
|
1 |
||
|
100 |
||
|
0 |
||
|
0 |
For example, the following LDIF file enables SASL for replication binds by adding and setting the orclreplusesasl;digest-md5 attribute in the replication configuration set:
dn: cn=configset0,cn=osdrepld,cn=subconfigsubentry changetype: modify add: orclreplusesasl;digest-md5 orclreplusesasl;digest-md5: 1
See Section 43.3.12, "Managing the Number of Entries the Human Intervention Queue Tools Can Process" for information about changing orclsizelimit.
The attribute orcldebuglevel can be set to any combination of the values shown in Table 43-11. The values are additive. No restart is required.
If a conflict has been written into the log, then it means that the system is not able to resolve it by following its resolution procedure. To avoid further replication change conflicts arising from earlier unapplied changes, it is important to monitor the logs regularly.
To monitor replication change conflicts, examine the contents of the replication log. You can distinguish between messages by their respective timestamps.
Conflict resolution messages are logged in the file ORACLE_INSTANCE/diagnostics/logs/OID/componentName/oidrepld00-XXXX.log where XXXX is a number from 0000 to orclmaxlogfiles configured.
Each message includes the conflict reason, change number, supplier node, change type, target DN, and result. Here are some examples:
This is a conflict resolution message where the conflict was automatically resolved by replication server:
[2008-10-09T09:57:31-07:00] [OID] [NOTIFICATION:16] [] [OIDREPLD] [host: stacu14] [pid: 4280] [tid: 3] Worker(Transport)::[[************ Conflict Resolution Message ************ Conflict reason: Attempted to add an existing entry. Change number: 3696. Supplier: stacu14_lm5. Change type: Add. Target DN: dc=org. Result: Dropped a newer change entry. ]]
This is an unresolved conflict which was moved to Human intervention queue:
[2008-10-09T10:03:28-07:00] [OID] [NOTIFICATION:16] [] [OIDREPLD] [host: stacu14] [pid: 4653] [tid: 13] Worker(Transport)::[[************ Conflict Resolution Message ************ Conflict reason: Attempted to delete a non-existent entry. Change number: 3698. Supplier: stacu14_lm5. Change type: Delete. Target DN: dc=imc,dc=org. Result: Change moved to low priority queue after failing on 10th retry. ]]
Conflict reasons, change types, and results include:
Table 43-12 Conflict Resolution Messages
| Conflict Reason | Change Type | Result |
|---|---|---|
|
Attempted to add an existing entry |
Add |
Dropped a newer change entry. Change moved to low priority queue after failing on Nth retry Deleted duplicated target entry which was created later than the change entry. Apply the change entry again Dropped a newer change entry Dropped change entry since its guid is greater than target entry guid Dropped change entry since its guid is same as target entry i.e change and target entry are identical Deleted duplicated target entry which has greater guid than the change entry |
|
Parent entry does not exist |
Add |
Change moved to low priority queue after failing on Nth retry |
|
Internal Error occurred |
Add Delete Modify moddn |
Change moved to low priority queue after failing on Nth retry |
|
Attempted to modify a non-existent entry |
Modify |
Change moved to low priority queue after failing on Nth retry |
|
Attempted to delete a non-existent entry |
Delete |
Change moved to low priority queue after failing on Nth retry |
|
Attempted to delete a non leaf entry |
Delete |
Change moved to low priority queue after failing on Nth retry |
|
Attempted to move a non-existent entry |
moddn |
Change moved to low priority queue after failing on Nth retry |
|
Attempted to move to an existent entry |
moddn |
Change moved to low priority queue after failing on Nth retry |
|
Synchronization of moddn for another non-existent entry is going on |
moddn |
Deleted existent entry which was created later than the entry trying to move. Move of entry is tried again |
|
Attempted to move to an existent entry which is newer than the source entry |
moddn |
Move of entry is tried again |
|
Attempted to move to an existent entry which is older than the entry trying to move |
moddn |
Deleted Source entry and dropped the change |
|
Attempted to move to an existing entry which was created at the same time and had the same guid |
moddn |
Deleted Source entry and dropped the change |
|
Attempted to move to an existing entry which has greater guid than the entry trying to move |
moddn |
Deleted duplicated target entry and re-applied the change |
|
Attempted to move to an existing entry which has lower guid then entry trying to move |
moddn |
Deleted Source entry and dropped the change |
When a replication conflict arises, the Oracle Internet Directory replication server places the change in the retry queue and tries to apply it from there for a specified number of times. If it fails after the specified number of retries, the replication server puts the change in the human intervention queue. From there, the replication server repeats the change application process at less frequent intervals while awaiting your action.
The human intervention queue tools, ManageHiq.retry and ManageHiq.purge, enable you to move changes from the human intervention queue to the retry queue or the purge queue, respectively. After you move the change to the purge queue, there are no further attempts to re-apply the changelog entry. To address changes in the human intervention queue, follow these general steps:
Examine the change in the human intervention queue.
Reconcile the conflicting changes using the Compare and Reconcile Tool (see Section 43.4, "Comparing and Reconciling Inconsistent Data by Using oidcmprec."
Either place the change back into the retry queue using ManageHiq.retry or into the purge queue using ManageHiq.purge.
See Also:
The Replication Tools chapter in Oracle Fusion Middleware Reference for Oracle Identity Management for instructions on how to use the Human Intervention Queue tools
The Replication Environment Management Tool, remtool, enables you to monitor replication progress in a directory replication group. When you invoke remtool with the -pthput option, the tool binds to the specified node and collects information about all the nodes in the directory replication group. It displays this information at intervals of specified duration.
The syntax is:
remtool -pthput [-bind hostname:port] -interval time_in_seconds [-file filename]
The bind argument is optional. If you do not provide it, remtool prompt you for hostname, port. You are prompted for the replication dn password.
The interval parameter is an optional parameter. Provide its value in seconds. Its default value is 60 seconds. After each interval the tool displays the following information for every supplier and consumer node in the directory replication group:
The changes that were queued in the last interval, q_chgs
Last applied change number, LA_Chg#
Changes applied in the last interval, Appl_chgs
Average throughput for the latest three intervals, Avg_thput
If you specify a file parameter, the output shown on the command line is logged to that file. Otherwise, the output is logged to a file name based on the timestamp.
------------------------------------------------------------------------------
Directory Replication Group (DRG) details :
--- ------------------ ----------------------- ----------------------- -----
Sl Replicaid Directory Information Supplier Information Repl. No. Type
--- ------------------ ----------------------- ----------------------- -----
001 adc2101322_nldap32 adc2101322.us.example.com:3070 adc2101322_nldap3 RW
002 adc2101322_nldap3 adc2101322.us.example.com:3061 adc2101322_nldap32 RW
--- ------------------ ----------------------- ----------------------- -----
Queue Statistics :
------------ ------------- ----- ------- ------ ------ ------ --------- --------- --------------------------------
Supplier Consumer Queued Last Applied Applied Average
Changes Change Number Changes Throughput
Of 3 intervals
------------- ------------- ----- ------- ------ ------ ------ --------- --------- -----------------------------
adc2101322_nldap3 adc2101322_nldap32 0 134369 0 0
adc2101322_nldap32 adc2101322_nldap3 0 47342 0 0
------------- ------------- ----- ------- ------ ------ ------ --------- --------- --------------------------
adc2101322_nldap3 adc2101322_nldap32 2286 136214 1845 615
adc2101322_nldap32 adc2101322_nldap3 0 47342 0 0
------------- ------------- ----- ------- ------ ------ ------ --------- --------- -----------------------
adc2101322_nldap3 adc2101322_nldap32 1608 137886 1672 1172
adc2101322_nldap32 adc2101322_nldap3 0 47342 0 0
------------- ------------- ----- ------- ------ ------ ------ --------- --------- ------------------------
adc2101322_nldap3 adc2101322_nldap32 189 140302 2416 1977
adc2101322_nldap32 adc2101322_nldap3 0 47342 0 0
------------- ------------- ----- ------- ------ ------ ------ --------- --------- -----------------------
The Replication Environment Management Tool, remtool, enables you to monitor the health of the replication process. You can run remtool periodically to ensure that your replication processes are performing properly. The remtool command has options that display queue statistics and verify replication.
The remtool options for monitoring an LDAP-based replication agreement are -pdipqstat and -pverify. Their syntax is as follows:
remtool -pdispqstat [-v] [-bind hostname:port_number]
remtool -pverify [-v] [-bind hostname:port_number] [-hiqmax hiqmax] [-tbtmax tbtmax]
For an Oracle Database Advanced Replication-based replication agreement, the remtool options are -dipqstat and -asrverify.
Their syntax is as follows:
remtool -dispqstat [-connect repl_admin_name@net_service_name] [-v]
remtool -asrverify [-connect repl_admin_name@net_service_name] [-v]
All of these commands prompt for the replication_dn_password.
First run remtool with the -pdispqstat or -dispqstat option, depending on the replication type. It shows the queue statistics of the DRG. Check to see if the number of Human Intervention Queue (HIQ) entries and change logs to be transported (Logs TBP) are higher than usual. If so, that means replication is running more slowly than it should. Run remtool with the -pverify or -asrverify option, depending on the replication type, to verify your replication configurations.
If remtool with the -pverify or -asrverify option reports test failure, check the report that it generates and follow the suggestion in the report to fix the specific failures.
See Also:
The remtool command reference in Oracle Fusion Middleware Reference for Oracle Identity Management
To increase the number of changelogs processed at a time, you must set orclsizelimit in the replication configuration set and orclsizelimit in the server instance where replication is running to the same value, a value greater than 1000. You use ldapmodify to change both of them. In each case, you would type:
ldapmodify -D cn=orcladmin -q -p portNum -h hostname -f ldifFile
To set orclsizelimit in the replication configuration set to 5000, you would use an LDIF file such as:
dn: cn=configset0,cn=osdrepld,cn=subconfigsubentry changetype: modify replace: orclsizelimit orclsizelimit: 5000
To set orclsizelimit in the server instance to 5000, you would use an LDIF file such as:
dn: cn=componentname,cn=osdldapd,cn=subconfigsubentry
changetype: modify
replace: orclsizelimit
orclsizelimit: 5000
Setting the Oracle Internet Directory server instance parameter orclsizelimit very high impacts server performance, because orclsizelimit also controls the maximum number of entries to be returned by a search.
You can change the password for the replication administrator database account on all nodes of a DRG using Oracle Database Advanced Replication-based replication by using the -chgpwd argument to the Replication Environment Management Tool, remtool. To use this argument, enter:
remtool -chgpwd
The remtool utility then prompts you for the MDS Global Name—that is, the name of the Master Definition Site—the current password, and the new password. It then asks you to confirm the new password. If you enter an incorrect current password, then you must run the Replication Environment Management Tool again.
You can also use the -pchgpwd argument to remtool to change the password of the replication DN of a replica.
To change the password only in the replication wallet, $ORACLE_INSTANCE/OID/admin/oidpwdrORACLE_SID, use the -pchgwalpwd argument to remtool. To use this argument, enter:
remtool -pchgwalpwd
See Also:
The remtool command-line tool reference in Oracle Fusion Middleware Reference for Oracle Identity Management for more information about using this tool
When the directory replication server encounters inconsistent data, you can use the Oracle Internet Directory Comparison and Reconciliation Tool to synchronize the entries on the consumer with those on the supplier. When you do this, perform the following general steps:
Set the supplier and the consumer to read-only mode. Use one of the procedures in"Changing Server Mode".
Ensure that the supplier and the consumer are in a tranquil state—that is, that neither is supplying or applying changes. If they are not in a tranquil state, then wait until they have finished updating.
Identify the inconsistent entries or subtree on the consumer.
Use the Oracle Internet Directory Comparison and Reconciliation Tool to fix the inconsistent entries or subtree on the consumer.
Set the participating supplier and consumer back to read/write mode.
See Also:
The oidcmprec command-line tool reference in Oracle Fusion Middleware Reference for Oracle Identity Management for syntax and an explanation of how Oracle Internet Directory Comparison and Reconciliation Tool works.
The compare and reconcile tool oidcmprec enables you to compare two directories. It detects and resolves conflicts. Of the two directories, one directory is considered to be the source directory or "source of truth." The other directory is the destination directory that must be synchronized with the source directory. The directories to be compared can be directories that are not part of any replication group, part of the same replication group, or part of different replication groups.
This section provides an introduction to the oidcmprec tool and some examples of oidcmprec usage. It includes the following topics:
Section 43.4.5, "Setting the Source and Destination Directories"
Section 43.4.7, "Selecting the Attributes for the Operation"
Section 43.4.11, "Overriding Predefined Conflict Resolution Rules"
Section 43.4.12, "Using the User-Defined Compare and Reconcile Operation"
Section 43.4.13, "Known Limitations of the oidcmprec Tool"
See Also:
The "oidcmprec" command reference inOracle Fusion Middleware Reference for Oracle Identity Management for the complete syntax for oidcmprec, including operations, conflict scenarios, and conflict resolution rules.
The oidcmprec tool can detect and resolve the following conflict scenarios:
Entry only in source directory (entos)
Entry only in destination directory (entod)
Attribute only in source directory (atros)
Attribute only in destination directory (atrod)
Single-valued attribute differs (svatrdif)
Multi-valued attribute differs (mvatrdif)
Entry DN differs (dndif)
The dndif scenario can occur in a replication environment when a modrdn or moddn operation performed in one node is not replicated to another node. As a result, the entry has the same orclguid but different DNs on the two nodes. The tool uses the orclguid attribute to detect this conflict.
The oidcmprec tool can also detect and resolve the following schema conflict scenarios:
Object class definition exists only in source directory (odefos)
Object class definition exists only in destination directory (odefod)
Object class definition different in source and destination directory (odefdif)
Attribute definition exists only in source directory (adefos)
Attribute definition exists only in destination directory (adefod)
Attribute definition different in source and destination directory (adefdif)
The tool supports five operation. Each operation compares entries, detects conflicts, and optionally resolves them. The operations differ regarding how they resolve conflicts. The operations are as follows:
Compare operation: compares two directories and stores the changes as LDIF records in a file. The LDIF file can be applied to the destination directory to make it identical to the source directory. Only the data in the source directory is considered valid.
Reconcile operation: compares two directories and applies necessary changes at the destination directory to make it identical to the source directory. All the changes made to the directory are stored as LDIF records in a file. Only the data in the source directory is considered valid.
Merge or two-way reconcile operation: compares two directories and applies necessary changes at the source or destination directory to make them identical. The data in both directories is considered valid. For example, when the tool detects that an entry exists only in the destination directory, the tool adds it to the source. This operation also records all the changes applied to the directory as LDIF records in a file.
Merge dry run operation: compares two directories, similar to the merge operation, but does not apply the changes in the directory. Instead, it stores the changes as LDIF records in a file. The changes to be applied to the source directory and to destination directory are stored in two different files.
User defined compare and reconcile operation: uses conflict resolution rules that you choose for each conflict scenario. See Oracle Fusion Middleware Reference for Oracle Identity Management for a list of conflict resolution rules you can use for each conflict scenario.
The oidcmprec tool normally generates several output files. You can use options to oidcmprec to suppress generation of any of the files. The files and their corresponding options are:
filename.rpt: contains the DNs of all entries compared and the compare result. Use logrpt=false to suppress generation of this file.
filename.s2d.ldif: contains all changes applied to the destination directory or stored for later application to the destination directory. The name is an abbreviation for source directory to destination directory. Use logs2d=false to suppress generation of this file.
filename.d2s.ldif: contains all changes applied to the source directory or stored for later application to the source directory. The name is an abbreviation for destination directory to source directory. Use logd2s=false to suppress generation of this file.
filename.eos.rpt: lists DNs of entries that exist only in the source directory. It also lists name of attributes and object classes that are defined only in the source directory, if the schema is included for the operation.The name is an abbreviation for entries available only in source directory. Use logeos=false to suppress generation of this file.
filename.eod.rpt: lists DNs of entries that exist only in the destination directory. It also lists name of attributes and object classes that are defined only in the destination directory, if the schema is included for the operation. The name is an abbreviation for entries available only in destination directory. Use logeod=false to suppress generation of this file.
filename.dif.rpt: lists DNs of all entire that differ along with names of attribute that differ. It also lists name of attributes and object classes whose definitions differ, if the schema is included for the operation. This file is known as the dif file. Use logdif=false to suppress generation of this file.
filename.err: contains all error messages. This file is known as the err file. Use logerr=false to suppress generation of this file.
The tool can dump the total number of entries loaded by the tool in memory and the number of entries in each of oidcmprec's various queues. The entry counts are logged in the file oidcmprec.log. Use the qlogfreq=frequency argument to specify how frequently oidcmprec logs this information. Possible frequency values are from 1 to 5000. The lower the value, the shorter the interval. For frequent entry counts, use a value between 5 and 10.
Using the replication DN and replication DN password as credentials, the tool performs three tasks. First it loads schema information into memory. Next, it collects the entries to be compared and it compares them, attribute by attribute. The tool uses schema information to determine the compare rule to be used for each attribute. Then, based on the compare result, the tool takes the necessary actions. These operations are performed by different threads:
The DN thread is responsible for collecting entries to be compared. While collecting entries, it does not fetch the entire tree at once. It first fetches the base entry and processes it. Then it fetches the immediate children of the base entry and processes them, and then their immediate children, and so on. The collected entries are passed on to worker threads. You can control the number of DN threads using the dnthreads argument.
The worker thread is responsible for comparing entries attribute by attribute and applying conflict resolution rules. The worker thread then passes on the entry to the log writer thread. You can control the number of worker threads by using the threads argument. The total number of worker threads and DN threads cannot exceed a maximum value equal to 6 * (Number of CPUs) - 2. If you specify more than that, the tool adjusts the number of worker and DN threads so as not to exceed the maximum.
The log writer thread is responsible for writing the contents to all seven output files listed in Section 43.4.3, "Output from oidcmprec." There is only one log writer thread. You cannot increase the number.
These threads are spawned, monitored and terminated by the main thread. The main thread processes command line arguments and parameter files and spawns the other threads. As soon as the main thread detects that all operations are complete, it terminates all threads and cleans up all connections.
Each thread establishes an LDAP connection to the source directory and to the destination directory. These connections remain open until all operations are completed by the thread. If a connection is closed for any reason, the tool tries to reestablish connection if the continueOnError argument is set to TRUE. If the tool can reestablish the connection, it continues operation.
Note:
Use the continueOnError argument to specify whether the tool should continue processing on error. This argument can be set to TRUE or FALSE. By default it is set to TRUE.
You use the source and destination options to set the source and destination directories.
oidcmprec source=staqj13:3060 destination=staqj:3070 base="''" \
scope=subtree file=temp operation=compare
The tool prompts for passwords if they are not provided on the command line:
Enter replication DN password of the source directory : Enter replication DN password of the destination directory :
Use the base, dns2Exclude, and scope options to choose the area to be compared and reconciled.
This example compares the entire directory except c=us,dc=mycom,dc=com and c=uk,dc=mycom,dc=com:
oidcmprec base="''" \
dns2exclude="'c=us,dc=mycom,dc=com' 'c=uk,dc=mycom,dc=com'" \
operation=compare scope=subtree \
source=myhost1.mycom.com:3060 \
destination=myhost2.mycom.com:3060 \
threads=5 dnthreads=2 file=cmpres
This example compares the naming contexts dc=com and dc=org except for the trees c=us,dc=mycom,dc=com and c=uk,dc=myorg,dc=org.
oidcmprec base="'dc=com' 'dc=org'" \
dns2exclude="'c=us,dc=mycom,dc=com' 'c=uk,dc=myorg,dc=org'" \
operation=compare scope=subtree \
source=myhost1.mycom.com:3060 \
destination=myhost2.mycom.com:3060 \
threads=5 dnthreads=2 file=cmpres
By default, oidcmprec compares all attributes except for the operational attributes creatorsname, createtimestamp, modifiersname, modifytimestamp, orclentrydn, and orclnormdn. You can control the attributes to be included or excluded for the chosen operation using excludedAttributes or incudedAttributes, respectively. The excludedAttributes and incudedAttributes arguments allow limited pattern matching. You can use attributename* to match all attributes starting with attributename. You can also use attributename;* to match all subtypes of attributename.
This example excludes the authpassword attribute with and without subtype, plus the attributes userpassword and category, in addition to the standard excluded attributes.
oidcmprec operation=compare scope=subtree base="'dc=com' 'dc=org'" \
source=myhost1.mycom.com:3060\
destination=myhost2.mycom.com:3060 \
exclattr="authpassword authpassword;* userpassword category" \
threads=5 dnthreads=2 file=compare
This example includes only the attributes uid, cn, sn, givenname, and mail in the compare operation.
oidcmprec operation=compare scope=subtree base="'dc=com'" \
source=myhost1.mycom.com:3060 \
destination=myhost2.mycom.com:3060 \
inclattr="uid cn sn givenname mail" \
file=compare
This example includes all attributes for the compare operation except orclguid, creatorsname, and modifiersname. This example also asks the tool to stop when it encounters any error by setting continueOnError=false.
oidcmprec operation=compare scope=subtree base="'dc=com'" \
source=myhost1.mycom.com:3060 \
destination=myhost2.mycom.com:3060 \
inclattr="*" exclattr="orclguid creatorsname modifiersname" \
file=compare contonerr=false
Change log generation for the changes made by oidcmprec depends on the value of the orcldiprepository attribute of the root DSE. Change log generation behavior, however, can be controlled by using the generateChangeLog argument. The generateChangeLog argument can have the following values:
default: The directory server settings determine whether a change log is generated or not. Change logs are generated if the root entry's orcldiprepository attribute is set to true. They are not generated if orcldiprepository is set to false. The same rule applies for both the source and destination directories. default is the default value for gechglog.
true: Change logs are always generated, irrespective of the settings on the source and destination directories.
false: Change logs are never generated, irrespective of the settings on the source and destination directories.
In the following example, generateChangeLog false turns off change log generation:
oidcmprec operation=merge scope=subtree base="'dc=com'" \
source=myhost1.mycom.com:3060 \
destination=myhost2.mycom.com:3060 \
inclattr="*" exclattr="orclguid creatorsname modifiersname" \
file=merge genchglog=false
All the arguments that can be given on the oidcmprec command line can also be stored in a parameter file. You specify a text parameter file using the parameterFile option. You specify an xml parameter file using the xmlparameterFile option. If you specify an argument both on the command line and in the parameter file, the argument specified on the command line takes precedence over the one specified in the parameter file. For example:
oidcmprec paramfile=comp_param threads=4
This example uses the following sample text parameter file:
#############################################
#Parameter file for compare and reconcile tool
#Creator : John
#Date : 21-Mar-2006
#File Name : comp_param
#############################################
operation=compare
source=staqj13:3060/ods
destination=staqj13:3070/ods
base='("cn=oraclecontext" "c=uk,dc=mycom,dc=com" "c=us,dc=mycom,dc=com")'
verbose=false
force=true
threads=6
dnthreads=2
excludedAttributes=orclguid userpassword authpassword authpassword;*
filename=cmp2006Feb01
In this example, the tool spawns four worker threads. It gives precedence to command line arguments.
Here is an XML parameter file equivalent to the sample text parameter file:
<?xml version="1.0" standalone="yes" ?> - <input> <operation>compare</operation> - <source> <host>staqj13</host> <port>3070</port> </source> - <destination> <host>staqj13</host> <port>3070</port> </destination> <base> <dn>cn=oraclecontext</dn> <dn>c=uk,dc=mycom,dc=com</dn> <dn>c=us,dc=mycom,dc=com</dn> </base> <threads>6</threads> <dnthreads>2</dnthreads> <exclattr> <attribute>orclguid</attribute> <attribute>userpassword</attribute> <attribute>authpassword</attribute> <exclattr/> <force>true</force> <verbose>false</verbose> <filename>cmp2006Feb01</filename> </input>
You can include the schema in an oidcmprec operation by including cn=subschemasubentry in the base argument. For example:
oidcmprec operation=merge scope=subtree \
base="'dc=com' 'cn=subschemasubentry'" \
source=myhost1.mycom.com:3060 \
destination=myhost2.mycom.com:3060 \
inclattr="*" exclattr="orclguid creatorsname modifiersname" \
file=merge genchglog=false
If you include other DNs in addition to the schema, oidcmprec performs the operation on the schema first.
Conflict scenarios and conflict resolution rules for each operation are described in the "oidcmprec" command reference in Oracle Fusion Middleware Reference for Oracle Identity Management.
You can override the predefined conflict resolution rules by specifying the conflict name and the rule to use in the command line or parameter file. The following example changes the conflict resolution rule used for the conflicts dndif and mvatrdif to ignore for the compare operation:
oidcmprec operation=compare source=host1:3060 destination=host2:3070 \
base="''" scope=subtree file=temp operation=compare \
dndif=ignore mvatrdif=ignore
In addition to the predefined operations compare, reconcile, merge, and merge dry run, oidcmprec has a user-defined compare and reconcile operation, userdefinedcr, that enables you to specifying conflict resolution rule arguments. Any conflict resolution rule you do not specify with -userdefinedcr defaults to ignore. The following command line uses the userdefinedcr operation:
oidcmprec operation=userdefinedcr scope=subtree \
base="'dc=com' 'dc=org'" \
source=myhost1.mycom.com:3060 \
destination=myhost2.mycom.com:3060 \
entos=add entod=ignore atros=add atrod=ignore \
svatrdif=usesrc mvatrdif=usesrc dndif=ignore \
threads=5 dnthreads=2 file=myreconcile
Conflict scenarios and conflict resolution rules are described in the "oidcmprec" command reference in Oracle Fusion Middleware Reference for Oracle Identity Management.
The oidcmprec tool has the following limitations:
When the tool logs changes to LDIF records in the filename.s2d.ldif or filename.d2s.ldif file for deletion of a tree, it logs the parent record first, followed by its children. If you attempt to apply this change using the ldapmodify command-line tool, it fails, as the directory server does not allow deletion of non-leaf entry. To prevent ldapmodify from failing, edit the file to reorder the records before running ldapmodify.
When the tool performs a delete operation on a entry, it deletes that entry and its children. The tool records that the entry was deleted, but does not log that its children were also deleted.
The tool has limitations with respect to compound RDNs. These are RDNs that contain two or more attribute=attrvalue pairs, separated by a +, for example:
uid=jpaul + cn=john paul + mail=john.paul@example.com,dc=oracle,dc=com
If one of the directories you are comparing contains a compound RDN, when the tool suggests modrdn/moddn changes in the filename.s2d.ldif or filename.d2s.ldif file, the deleteoldrdn value might be incorrect.
If you have provided a filter to oidcmprec, and you plan to use the output as input to ldapmodify, first edit the output to ensure that entries are in the correct order. In particular, if you are migrating a whole tree, ensure that the root of the tree is the first entry.