43 Managing and Monitoring Replication

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:

Note:

Some changes do not take effect until the replication server is restarted.

43.1 Introduction to Managing and Monitoring Replication

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

This introduction includes the following topics:

43.1.1 Modifying What Is to Be Replicated in LDAP-Based Partial Replication

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

43.1.2 Managing Worker Threads

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

Maximum Number of Workers

orclreplmaxworkers

Autotune Replication

orclreplautotune

Number of Apply Threads Per Supplier

orclthreadspersupplier;apply

Number of Transport Threads per Supplier

orclthreadspersupplier;transport


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.

43.1.3 Change Logs in Directory Replication

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.

43.1.4 The Human Intervention Queue

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.

43.1.4.1 Managing the Queues

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

43.1.4.2 Queue Statistics

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

43.1.4.3 The Number of Entries the Human Intervention Queue Tools Can Process

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 replication configuration set

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

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.

43.1.5 Pilot Mode

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.

43.1.6 Conflict Resolution in Oracle Replication

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

43.1.6.1 Levels at Which Replication Conflicts Occur

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:

  • Adding an entry that already exists

  • Deleting an entry that does not exist

  • Modifying an entry that does not exist

  • Applying a modifyrdn operation when the DN does not exist

These conflicts can be difficult to resolve. For instance, it may be impossible to resolve a conflict because:

  • The entry has been moved to a different location

  • The entry has not yet arrived from a supplier

  • The entry has been deleted

  • The entry never existed on the consumer

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 orclReplAttrConfl in the replication configuration set entry determines which is honored first. If orclReplAttrConfl is 0 (the default) timestamp is honored first. If it is 1, attribute version is honored first.


43.1.6.2 Automatic Conflict Resolution

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.

43.1.6.3 How Automated Conflict Resolution Works

The directory replication server attempts to resolve all conflicts that it encounters by following this process:

  1. The conflict is detected when a change is applied.

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

  3. 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:

43.2 Managing and Monitoring Replication by Using ODSM and Fusion Middleware Control

You can manage and monitor replication by using Oracle Enterprise Manager Fusion Middleware Control. This section contains the following topics:

43.2.1 Enabling or Disabling Change Log Generation by Using Fusion Middleware Control

You can enable and disable change log generation by using Oracle Enterprise Manager Fusion Middleware Control, as follows:

  1. Choose Administration, then Server Properties from the Oracle Internet Directory menu.

  2. Choose the Performance tab.

  3. Select or deselect Enable Change Log Generation.

  4. After changing the configuration, choose Apply.

43.2.2 Viewing the Local Change Logs by Using Oracle Directory Services Manager

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:

  1. From the task selection bar, select Advanced.

  2. Expand Change Log if it is not already expanded. The left panel lists the last 500 changes, beginning with the most recent.

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

changenumber

Operation

changetype

TargetDN

targetdn

Changes

changes

Global Unique Identifier (GUID)

orclguid

Parent GUID

orclparentguid

Change Retry Count

orclchangeretrycount

Modifier's Name

modifiersname

Operation Time

operationtime

Server Name

servername


43.2.3 Viewing and Modifying Replica Naming Context Objects

To add, delete, view, and modify parameters for replica naming context objects, use the Replication Wizard in Oracle Enterprise Manager Fusion Middleware Control:

  1. From the Oracle Internet Directory menu on the home page, select Administration, then Replication Management.

  2. You are prompted to log into the replication DN account. Provide the host, port, replication DN, and replication DN password.

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

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

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

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

  7. To apply your changes, click Apply.

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

43.2.4 Viewing or Modifying a Replication Setup by Using the Replication Wizard

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.

  1. From the Oracle Internet Directory menu on the home page, select Administration, then Replication Management.

  2. You are prompted to log into the replication DN account. Provide the host, port, replication DN, and replication DN password.

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

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

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

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

    2. Enter the Replication Frequency.

    3. Enter the Human Intervention Queue Schedule. This is the interval, in seconds, at which the directory replication server repeats the change application process.

    4. Click Apply to apply your changes, or click Cancel to discard your changes.

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

  7. To view the type, host, port, and user name for each node, click the Replicas tab of the Edit Replication Definition page.

  8. To view or edit Replica Primary URI, Replica Secondary URI, or Replica State for a node:

    1. Select the Replicas tab and click the "+" next to the supplier or consumer.

    2. Make desired changes to the Replica Primary URI or Replica Secondary URI fields.

    3. Select a Replica State from the list.

    4. Click Apply to apply your changes, or click Cancel to discard your changes.

  9. To make a node the primary node in a multimaster replication group:

    1. Click the Replicas tab, select the node, and

    2. Click the Make Primary Node icon.

    3. Click Apply to add the node to the existing directory replication group or click Cancel to discard your changes.

  10. To add a node to a multimaster replication group:

    1. Select the Replicas tab.

    2. Click the Create icon.

    3. In the popup window, provide the host, port and replication DN password details for the new node. Click Add.

    4. Click Apply to add the node to the existing directory replication group or click Cancel to discard your changes.

  11. To delete a node from a multimaster replication group containing three or more nodes:

    1. Select the Replicas tab.

    2. Click the replica you want to delete from the multimaster replication deployment. The Delete icon becomes enabled.

    3. Click Delete.

    4. Click Apply to delete the node from the directory replication group (DRG)

43.2.5 Deleting an LDAP-Based Replication Agreement by Using the Replication Wizard

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

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

  2. You are prompted to log into the replication DN account. Provide the host, port, replication DN, and replication DN password.

  3. To delete a replication agreement, select the agreement and click the Delete icon. When the Delete Popup appears, click Delete.

43.2.6 Configure Replication Attributes by Using Fusion Middleware Control

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

Change Retry Count

orclchangeretrycount

Maximum Number of Workers

orclreplmaxworkers

Autotune Replication

orclreplautotune

Number of Apply Threads Per Supplier

orclthreadspersupplier;apply

Number of Transport Threads per Supplier

orclthreadspersupplier;transport

Entries to Process per Replication Cycle

orclsizelimit

Automatically Resolve Replication Conflicts

orclconflresolution

Generate Stack Dump

orclsdumpflag

SASL for Replication Bind

orclreplusesasl;digest-md5

Maximum Log File Size (MB)

orclmaxlogfilesize

Maximum number of log files to keep in rotation

orclmaxlogfiles

DebugLevel

orcldebuglevel


Restart the server after changing Autotune Replication or Generate Stack Dump.

43.2.7 Activating or Inactivating a Replication Server by Using Fusion Middleware Control

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:

  1. Select Administration, then Shared Properties from the Oracle Internet Directory menu, then select Replication.

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

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

Table 43-5 Replication Server Status Attributes on Shared Properties, Replication Tab

Field or Heading Configuration Attribute

Replication Status

orclreplicationstate

Activate Replication on

orclactivatereplication


43.2.8 Configuring the Replication Debug Level by Using Fusion Middleware Control

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:

  1. Select Administration, then Shared Properties from the Oracle Internet Directory menu, then select Replication.

  2. Select any combination of Replication Process, Trace Function Calls, Replication Performance Log, and Heavy Trace Debugging.

  3. Choose Apply.

43.2.9 Configuring Replica Details by Using Fusion Middleware Control

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

Replica ID

orclreplicaid

Replica Primary URI

orclreplicauri

Replica Secondary URI

orclreplicasecondaryuri

Replica State

orclreplicastate

Replica Type

orclreplicatype


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.

43.2.10 Viewing Queue Statistics by Using Fusion Middleware Control

You view statistics for an LDAP replica by using the Oracle Enterprise Manager Fusion Middleware Control replication wizard, as follows.

  1. From the Oracle Internet Directory menu on the home page, select Administration, then Replication Management.

  2. You are prompted to log into the replication DN account. Provide the host, port, replication DN, and replication DN password.

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

  4. The bottom of the page lists the following statistics:

    • New Changes

    • Retry Changes

    • Purge Changes

    • HIQ Changes

    • Last Applied Change

    • Last Transported Change

43.2.11 Managing Changelog Processing by Using Fusion Middleware Control

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:

  1. Select Administration, then Shared Properties from the Oracle Internet Directory menu

  2. Select Replication.

  3. Change the parameter Maximum Number of Entries to Process per Replication Cycle.

  4. Choose Apply.

To change orclsizelimit in a server instance by using Oracle Enterprise Manager Fusion Middleware Control:

  1. Select Administration, then Server Properties from the Oracle Internet Directory menu.

  2. Select General.

  3. Change the value of Maximum number of entries to be returned by a search.

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

43.2.12 Monitoring Conflict Resolution Messages by Using Fusion Middleware Control

You can view conflict resolution messages in the Replication Log by using Oracle Enterprise Manager Fusion Middleware Control, as follows:

  1. From the Oracle Internet Directory menu, select Monitoring, then Logs. The Log Messages page appears.

  2. Click Log Files. The Log Files page appears.

  3. Select Replication Log.

See Also:

43.3 Managing and Monitoring Replication by Using the Command Line

This section contains the following topics

43.3.1 Enabling and Disabling Change Log Generation by Using the Command Line

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

43.3.2 Viewing Change Logs by Using ldapsearch

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

changenumber

Change Number

changetype

Operation

targetdn

Target DN

changes

Changes

orclguid

Global Unique Identifier (GUID)

orclparentguid

Parent GUID

orclchangeretrycount

Change Retry Count

modifiersname

Modifier's Name

operationtime

Operation Time

servername

Server Name

changeloginfo

Additional change log information, such as the value of the client IP address

For example: changeloginfo=clientip=::ffff:10.229.116.104


43.3.3 Configuring Attributes of the Replica Subentry by Using ldapmodify

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 43-8 Replica Subentry Attributes

Description Configuration Attribute

Replica ID

orclreplicaid

Replica Primary URI

orclreplicauri

Replica Secondary URI

orclreplicasecondaryuri

Replica State

orclreplicastate

Replica Type

orclreplicatype


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

43.3.4 Specifying Pilot Mode for a Replica by Using remtool

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:

  • orclreplicatype is set to 2 (pilot)

  • orclpilotmode is set to 1

  • pilotstarttime is set to current time.

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.

43.3.5 Configuring Replication Agreement Attributes by Using ldapmodify

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

Description Configuration Attribute Default Value

Replication frequency

orclupdateschedule

60 (seconds)

HIQ Schedule

orclhiqschedule

600 (seconds)

Whether the connections from the directory replication server to the directory server are kept active or established every time changelog processing is done

orclldapconnkeepalive

1


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

43.3.6 Modifying Replica Naming Context Object Parameters by Using ldapmodify

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

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:

  1. 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
    
  2. 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.

  1. 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
    
  2. Use ldapmodify to update the replication agreement orclupdateschedule attribute.

    ldapmodify -D "cn=orcladmin" -q -h supplier_host -p port -f mod.ldif
    
  3. 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.

  1. 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
    
  2. Use ldapmodify to update the replication agreement orclupdateschedule attribute.

    ldapmodify -D "cn=orcladmin" -q -h supplier_host -p port -f mod.ldif
    
  3. 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.

  1. 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
    
  2. Use ldapmodify to update the replication agreement orclupdateschedule attribute.

    ldapmodify -D "cn=orcladmin" -q -h my_host -p port -f mod.ldif
    
  3. Restart the directory replication server.

43.3.7 Configuring Attributes of the Replication Configuration Set by Using ldapmodify

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

Change Retry Count

orclchangeretrycount

10

Maximum Number of Workers

orclreplmaxworkers

20

Autotune Replication

(Restart server after changing.)

orclreplautotune

1

Number of Apply Threads Per Supplier

orclthreadspersupplier;applly

5

Number of Transport Threads per Supplier

orclthreadspersupplier;transport

1

Maximum Number of Entries to Process per Replication Cycle

orclsizelimit

1000

Automatically Resolve Replication Conflicts

orclconflresolution

1

Generate Stack Dump

(Restart server after changing.)

orclsdumpflag

 

SASL for Replication Bind

orclreplusesasl;digest-md5

none

Maximum Log File Size (MB)

orclmaxlogfilesize

1

Maximum number of log files to keep in rotation

orclmaxlogfiles

100

DebugLevel

orcldebuglevel

0

Replication Status

orclreplicationstate

 

Activate/Inactivate

orclactivatereplication

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.

Table 43-11 Replication Debug Levels

Debug Level Value of orcldebuglevel

Replication Process Trace

4194304

Replication Performance Log

2097152

Trace Function Calls

8388608

Heavy Trace Debugging

16777216


43.3.8 Monitoring Conflict Resolution Messages by Using the Command Line

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


43.3.9 Managing the Human Intervention Queue

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:

  1. Examine the change in the human intervention queue.

  2. Reconcile the conflicting changes using the Compare and Reconcile Tool (see Section 43.4, "Comparing and Reconciling Inconsistent Data by Using oidcmprec."

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

43.3.10 Monitoring Replication Progress in a Directory Replication Group by Using remtool -pthput

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.

Example Output

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

43.3.11 Viewing Queue Statistics and Verifying Replication by Using remtool

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

43.3.12 Managing the Number of Entries the Human Intervention Queue Tools Can Process

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.

43.3.13 Changing the Replication Administrator's Password for Advanced Replication

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

43.4 Comparing and Reconciling Inconsistent Data by Using oidcmprec

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:

  1. Set the supplier and the consumer to read-only mode. Use one of the procedures in"Changing Server Mode".

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

  3. Identify the inconsistent entries or subtree on the consumer.

  4. Use the Oracle Internet Directory Comparison and Reconciliation Tool to fix the inconsistent entries or subtree on the consumer.

  5. 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:

43.4.1 Conflict Scenarios

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)

43.4.2 Operations Supported by oidcmprec

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.

43.4.3 Output from oidcmprec

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.

43.4.4 How oidcmprec Works

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.

43.4.5 Setting the Source and Destination Directories

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 :

43.4.6 Selecting the DIT for the Operation

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

43.4.7 Selecting the Attributes for the Operation

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

43.4.8 Controlling Change Log Generation

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

43.4.9 Using a Text or XML Parameter File

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>

43.4.10 Including Directory Schema

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.

43.4.11 Overriding Predefined Conflict Resolution Rules

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

43.4.12 Using the User-Defined Compare and Reconcile Operation

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.

43.4.13 Known Limitations of the oidcmprec Tool

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.