The differences are identified by first issuing a subtree search on both servers under the base distinguished name (DN) using the default search filter (objectclass=*) to retrieve the DNs of all entries in each server. When the tool finds an entry that is on both servers, it retrieves the entry from each server and compares all of its attributes. The tool writes any differences it finds to an LDIF file in a format that could be used to modify the content of the source server so that it matches the content of the target server. Any non-synchronized entries can be compared again for a configurable number of times with an optional pause between each attempt to account for replication delays.

You can control the specific entries to be compared with the --searchFilter option. In addition, only a subset of attributes can be compared by listing those attributes as trailing arguments of the command. You can also exclude specific attributes by prepending a ^ character to the attribute. On Windows operating systems, excluded attributes must be quoted, such as "^attrToExclude". The @objectClassName notation is used to compare only attributes that are defined for a given objectclass.

The ldap-diff tool can be used on servers actively being modified by checking differing entries multiple times without reporting false positives caused by replication delays. By default, it re-checks each entry twice, pausing two seconds between checks. You can configure these settings with the --numPasses and --secondsBetweenPass options. If the utility cannot make a clean comparison on an entry, it lists any exceptions in comments in the output file.

The PingDirectory server user specified for performing the searches must be privileged enough to see all of the entries being compared and to issue a long-running, unindexed search. For the PingDirectory server, the out-of-the-box cn=Directory Manager user has these privileges, but you can assign the necessary privileges by setting the following attributes in the user entry.

ds-cfg-default-root-privilege-name: unindexed-search
ds-cfg-default-root-privilege-name: bypass-acl
ds-rlim-size-limit: 0
ds-rlim-time-limit: 0
ds-rlim-idle-time-limit: 0
ds-rlim-lookthrough-limit: 0

The ldap-diff tool tries to make efficient use of memory, but it must store the DNs of all entries in memory. For PingDirectory servers that contain hundreds of millions of entries, the tool might require a few gigabytes of memory. If the progress of the tool slows dramatically, it might be running low on memory. You can customize the memory used by the ldap-diff tool by editing the ldap-diff.java-args setting in the config/java.properties file and running the dsjavaproperties command.

If you do not want to use a subtree search filter, you can use an input file of DNs for the source, target, or both. The format of the file can accept various syntaxes for each DN.

dn: cn=this is the first dn
dn: cn=this is the second dn and it is wrapped cn=this is the third dn
# The following DN is base-64 encoded dn:: 
Y249ZG9uJ3QgeW91IGhhdmUgYmV0dGVyIHRoaW5ncyB0byBkbyB0aGFuIHNlZSB3aGF0IHRoaXMgc2F5cw==
# There was a blank line above dn: cn=this is the final entry.
CAUTION:

Do not manually update the servers when the tool identifies differences between two servers involved in replication. First contact your authorized support provider for explicit confirmation because manual updates to the servers risk introducing additional replication conflicts.