Chapter 23 The LDAP Compare and Modify Tool

The ldiffer.pl tool detects differences between two LDAP directories and performs modifications accordingly. This chapter provides instructions on how to use the ldiffer.pl tool. It contains the following sections:

Overview

The ldiffer.pl tool is a Perl script that detects differences between two LDAP directories and can perform modifications accordingly. Comparisons are based on attribute values so that directories with different DN structures and different schemas may be compared. When the tool detects comparable entries in each directory, it can be configured to add or modify attributes in either entry. The value of new or modified attributes is given as a regular expression involving other attribute values. This flexibility can be used to migrate data to a new schema or to import specific data from one directory into another. The DSRK includes the tool in the DSRK_base/perl directory.

Using the Script


Note	This script requires Perl version 5.005_03 or later. See Third-Party Sources of Information for links to Perl resources.

ldiffer.pl interacts with two directories. One is called sequential and can be considered the source of information. The other is called random and can be considered the target to be modified. However, the tool also allows modifications to be made in the sequential directory. Entries from each directory are matched based on equality between the value of one or more key attributes, allowing you to match entries that do not necessarily have the same DN. Because only attribute values are compared, key attributes may have different names in each directory. (The bind credentials, the base DN, and the filter for each search are specified separately, allowing arbitrarily different sets of entries to be compared.)

Within a pair of matched entries, the tool compares the values of one or more attributes using a regular expression (a string of characters that defines a pattern used to search for a matching string). A discrepancy between any of them will trigger the tool to perform a set of update actions. An update action involves modifying an attribute in one of the entries based on the value of an attribute in its matched entry. For example, an administrator may wish to migrate information from an old directory under the suffix o=example.com,c=us to a new directory under dc=example,dc=com.. The key attribute might be employee login names; this attribute would be invariant. ldiffer.pl could then compare an attribute such as fax in a custom schema to facsimileTelephoneNumber in the standard schema of the new directory. The value of facsimileTelephoneNumber could then be updated with the value of the fax attribute or with a new area code. When matching entries are not found, the tool may also be configured to delete the entry in the source directory, add it to the target directory, or both.

Customizing the Script


Note	The ldiffer.pl script uses ldapsearch to extract a set of entries from both directories and ldapmodify to modify entries. See Chapter 3, "The ldapsearch Tool" and Chapter 4, "The ldapmodify Tool" for more information on these tools.

If you customize the ldiffer.pl script for added functionality, we encourage you to share your work with other LDAP users. Please post a message to the iplanet.server.idsrk public newsgroup with your ideas or your code.

Command Usage

Due to the flexibility it offers, the ldiffer.pl script requires many parameters to describe the modifications of one or both target directories. These parameters are defined in a configuration file that is named on the command-line. The configuration file is discussed in Configuration File.

Where configFile is the name of a file that contains all of the information for binding to the directories, performing comparisons, and making any potential modifications. The file and its format is described in Configuration File.


Note	You will need to specify values for all of the parameters in the configuration file before running ldiffer.pl. Due to the potential complexity of comparisons and updates, we recommend testing your configuration files on mock directories with the debugging parameter turned on.

Output Files

All output from the script is written to log files with names and locations based on information in the configuration file. The following sections detail these log files.

configFile.timestamp.action.log

configFile.timestamp.action.log displays the comparisons, additions, and modifications that were performed in a given run. It also gives a count of the differences and lists the entries that were not successfully matched.

configFile.timestamp.debug.log

configFile.timestamp.debug.log records commands that were executed while comparing and modifying the directories. This file is created only if the debugging parameter is specified.

Configuration File

The ldiffer.pl script requires a configuration file that defines both the sequential and the random directories. The DSRK installation includes an example configuration file named ldiffer-sample.config. The file is located in DSRK_base/perl and reproduced in Code Example 23-1.

Code Example 23-1 ldiffer-sample.config Sample Configuration File


# Global parameters
ldapsearch:/opt/iPlanet/bin/dsrk52/ldapsearch
ldapmodify:/opt/iPlanet/bin/dsrk52/ldapmodify
debug:1

# the delimiter should be a character that will not
# occur in the values of key attributes to match
delimiter:!

# The "sequential" directory can be considered the source
sqn_h:legacy.example.com
sqn_p:389
sqn_D:cn=directory manager
sqn_w:bindPassword
sqn_b:o=example.com,c=us
sqn_filter:login=*
sqn_key_attrs:login
sqn_comp_attrs:dn
sqn_add_attrs:branch;l;
sqn_mod_attrs:
sqn_del_unmatched:0

# The "random" directory can be considered the target
rnd_h:ldap.example.com
rnd_p:389
rnd_D:cn=directory manager
rnd_w:bindPassword
rnd_b:dc=example,dc=com
rnd_filter:uid=*
rnd_key_attrs:uid
rnd_comp_attrs:dn
rnd_add_attrs:
rnd_mod_attrs:mail;email;,cn;fullName;,sn;fullName;s/.*\s//
rnd_add_unmatched:0

Configuration File Syntax

The parameters may be given in any order, but are usually grouped according to the directory they affect. The file contains three sections grouped as global, sequential and random parameters.

Global Parameters

Table 23-1 Global Parameters in the ldiffer.pl Configuration File
Parameter	Purpose
ldapsearch	Specify the path for running the ldapsearch tool. If you installed the Sun™ ONE DSRK in the default location, this parameter should be set to /opt/iPlanet/bin/idsrk/ldapsearch.
ldapmodify	Specify the path for running the ldapmodify tool. If you installed the Sun ONE DSRK in the default location, this parameter should be set to /opt/iPlanet/bin/idsrk/ldapmodify.
debug	Indicate the use of the debugging log. The possible values are 0 for no logging or 1 for creating the log file.
delimiter	Set the character used internally to delimit key attribute values. You should set this parameter to a character that does not occur in the attribute values of your directories, for example !.

Sequential and Random Parameters

Connection Parameters

The connection parameters determine the LDAP directories to operate upon and give the bind credentials for accessing them. They are detailed in Table 23-2.

Table 23-2 Connection Parameters in the ldiffer.pl Configuration File
Parameter	Purpose
sqn_h sqn_p rnd_h rnd_p	Specify the host name or IP address and port number of each LDAP directory.
sqn_D sqn_w rnd_D rnd_w	Give the bind DN and password needed to access each directory. These parameters may be left blank for anonymous binding. The bind credentials must have permissions for both searching the directories and modifying entries, if necessary. Also note that the bind DN may influence the results of searches when determining the set of entries to compare.

Comparison Parameters

The comparison parameters determine the set of entries to compare, how to match entries from each directory, and the attribute values that will trigger actions. They are detailed in Table 23-3.

Table 23-3 Comparison Parameters in the ldiffer.pl Configuration File
Parameter	Purpose
sqn_b sqn_filter rnd_b rnd_filter	These parameters determine the set of entries that will be compared from each directory. Their values are not necessarily identical, as the ldiffer.pl tool allows you to match entries based on any attribute values, not only the DN of an entry. Specify the base DN and filter string used to search each directory. The filter string should be an RFC 2254-compliant LDAP search filter, for example: (uid=). For more information, see “LDAP Search Filters” in Chapter 4 of the Sun ONE Directory Server Getting Started Guide*.
sqn_key_attrs rnd_key_attrs	Specify the names of the key attributes whose values must be equal in order to match an entry from each directory. The parameters may contain multiple attribute names in a comma separated list. The lists may contain different attribute names, but they must contain the same number of names. In order for two entries to match, all attribute values must match in the order that the attribute names are given in their respective list. To match entries based on their DN, specify the dn attribute in both parameters.
sqn_comp_attrs rnd_comp_attrs	Specify the names of the comparison attributes for entries from each directory. These are comma separated lists containing an equal number of attribute names. When two entries match according to the key attributes, the values of the comparison attributes are compared in the order that the attribute names are given in their respective list. If any one of the comparison attribute values differ in the pair, the two entries will be modified according to the action parameters. To perform a DN-based comparison, specify the dn attribute in both lists. If any one of the attributes does not exist in its respective entry, the comparison will fail but no action will be triggered. If you wish to trigger an action for every pair of matching entries, you must specify a single attribute name in each list parameter that you know will have a value and be different on each entry.

Action Parameters

The action parameters in the following table determine what modifications will be made when matching entries fail the comparison or when entries fail to match. These parameters are complex lists of:

The regularExpression must follow the syntax for Perl regular expressions or they may also be omitted, but the punctuation of the list must be respected, as in:

Table 23-4 Action Parameters in the ldiffer.pl Configuration File
Parameter	Purpose
sqn_add_attrs rnd_add_attrs	Specify the attributes to add to each of the matched entries and how to determine their initial value. These parameters are complex lists of the format previously described. Each Statement will create a new attribute with the given AttributeName in the entry of the corresponding directory (either sqn or rnd). The initial value given to the attribute will be the value of the otherAttribute in the matching entry (in the other directory), after applying the regularExpression. To create multivalued attributes, specify multiple add statements with the same AttributeName.
sqn_mod_attrs rnd_mod_attrs	Specify the attribute values to modify and how to determine their new value. These parameters have the same complex list format as described previously. Each Statement will modify the value of the given AttributeName in the entry of the corresponding directory (either sqn or rnd). The new value will be that of the otherAttribute in the matching entry (in the other directory), after applying the regularExpression.

All actions specified by the parameters in Table 23-4 will be triggered when a pair of matching entries fail the comparison. Thus, you may configure ldiffer.pl to add attributes or modify entries in both directories. Leave parameters blank if that specific action is not required. For example, if you do not wish to modify the source sqn directory, do not define the sqn_add_attrs or sqn_mod_attrs parameters.

Unmatched Entry Parameters

The tool currently offers less flexibility for entries that do not match. After pairing up all entries in the chosen set from each directory, ldiffer.pl can only determine those entries from the source sqn directory that do have a match. These entries may optionally be removed from the sqn directory, added to the rnd directory, or both, according to the parameters in Table 23-5.

Table 23-5 Unmatched Entry Parameters in the ldiffer.pl Configuration File
Parameter	Purpose
rnd_add_unmatched	Specify whether unmatched entries from the source sqn directory will be added to the target rnd directory. The value of this flag is either 0 for no additions or 1 for adding all unmatched entries. When entries are added, there is no mechanism to modify their attributes or attribute values. Therefore, when this flag is true (1), the target rnd directory must support the same DN hierarchy and the same schema as the source sqn directory.
sqn_del_unmatched	Specify whether unmatched entries are deleted from the source sqn directory. The value of this flag is either 0 to leave the sqn directory unchanged or 1 to remove all unmatched entries.

Configuration File Use Scenario

The configuration file reproduced in Code Example 23-1 might be used in a hypothetical scenario where example.com has undergone geographic expansion and created a new LDAP directory using the standard schema. Some data has already been added to the new directory, such as employee uid and location (l). The rest of the needed information can be extracted from the legacy directory that has a custom schema. Running the ldiffer.pl tool with this configuration file will match entries based on the uid attribute. Then, data from the legacy directory can be used to set attributes with standard names (mail, cn, and sn) in the new directory. If these attributes do not exist in the new directory, they will be created. The value of the surname (sn) attribute is assumed to be the second word of the legacy fullName attribute, as extracted by the Perl regular expression s/.*\s//. However, the legacy system is still in use by the human resources department, and now that example.com has several offices, it also needs to update the legacy directory. The tool will copy the employees’ new locations into a new attribute called branch.

After the migration, example.com might also wish to keep information in the legacy directory up to date, assuming that the latest modifications occur only in the new directory. The ldiffer.pl tool can be used to automate the transfer of information back into the schema of the legacy directory. Another configuration file would be needed for this scenario, in which the attribute values in the new rnd directory would be used to modify attributes in the legacy sqn directory.

Working With ldifxform

Updating or creating new directories can be highly automated through the use of the ldifxform and ldiffer.pl tools. (For more information on these tools, see Chapter 21, "The LDIF Transformation Tool.") Together, they can modify extracted information for complex operations such as porting existing data to a new schema. However, careful planning is necessary to perform a complicated sequence of transformations. Directory modifications of this scope will require special considerations such as turning off schema checking and disallowing other read and write requests while the data is in an intermediate state.

Previous Contents Index Next
Sun ONE Directory Server Resource Kit 5.2 Tools Reference