PingAuthorize Server Documentation Index
Command-Line Tool Reference Home

ldap-diff

Description
Examples
Arguments

Description

Compare the contents of two LDAP servers.

The 'ldap-diff' tool outputs the difference between data stored in two LDAP servers into an LDIF file. This file could be used with the 'ldapmodify' command to bring the source directory server in sync with the target directory server. The specific entries to compare can be controlled with the --searchFilter option. In addition, only a subset of attributes can be compared by listing those attributes as trailing arguments of the command. Specific attributes can also be excluded by prepending a ^ character to the attribute. On Windows operating systems, excluded attributes must be quoted, for example, "^attrToExclude". When retrieving entries from a Ping Identity Directory Server, the @objectClassName notation can be used to compare only attributes that are defined for a given objectclass.

This command can be used on servers actively being modified, without reporting false positives due to replication delays, by checking differing entries multiple times. By default, it will re-check each differing entry twice, pausing two seconds between checks. These settings can be configured with the --numPasses and --secondsBetweenPass options. The output is formatted so that delete operations come first, modify operations come next, and add operations come last. This gives the best chance that the resulting output file can be used to bring the source server into sync with the target server without causing any conflicts. This takes into account attribute uniqueness constraints as well as that child entries must be deleted before parents and parents must be added before children.

The directory 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 Ping Identity Directory 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

For servers from other vendors, consult their documentation for configuring the proper privileges.

The 'ldap-diff' tool tries to make efficient use of memory, but it must store the DNs of all entries in memory. For directories that contain tens 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. The memory used by ldap-diff can be customized by editing the ldap-diff.java-args setting in the config/java.properties file and running the dsjavaproperties command.

Examples

Compare all entries in the servers running on the default port (389) on server1.example.com and server2.example.com within dc=example,dc=com accessible by the uid=admin,dc=example,dc=com user. Store the difference in difference.ldif:
ldap-diff --outputLDIF difference.ldif --baseDN dc=example,dc=com \
     --sourceHost server1.example.com --targetHost server2.example.com \
     --sourceBindDN uid=admin,dc=example,dc=com --sourceBindPassword password

Arguments

-V
--version

Description Display PingAuthorize Server version information

-H
--help

Description Display general usage information

--help-debug

Description Display help for using debug options
Advanced Yes

-h {host}
--sourceHost {host}

Description PingAuthorize Server host name or IP address of the source server whose contents will be used as the source of the computed diff. The output LDIF file could be applied to this server to synchronize it with the target server
Default Value localhost
Required No
Multi-Valued No

-p {port}
--sourcePort {port}

Description PingAuthorize Server port number of the source server whose contents will be used as the source of the computed diff
Default Value 389
Required No
Multi-Valued No

--sourceUseSSL

Description Use SSL for secure communication with the source server

--sourceUseStartTLS

Description Use StartTLS to secure communication with the source server

-D {bindDN}
--sourceBindDN {bindDN}

Description DN used to bind to the source PingAuthorize Server
Default Value cn=Directory Manager
Required No
Multi-Valued No

-w {bindPassword}
--sourceBindPassword {bindPassword}

Description Password used to bind to the source PingAuthorize Server
Required No
Multi-Valued No

--sourceBindPasswordFile {bindPasswordFile}

Description File containing the password used to bind to the source server
Required No
Multi-Valued No

--sourceSASLOption {name=value}

Description A SASL option (in the form 'name=value') to use when attempting to authenticate to the source server
Required No
Multi-Valued Yes

--sourceDNsFile {file-with-dns}

Description Build the list of source DNs to compare by reading DNs from this file instead of by doing a search from the source server. This can speed up the ldap-diff process in topologies where retrieving the list of DNs is expensive, such as a disk-bound environment. DNs should be listed in this file according to standard LDIF syntax
Required No
Multi-Valued No

-O {host}
--targetHost {host}

Description PingAuthorize Server host name or IP address of the target server whose contents will be used as the target of the computed diff. The output LDIF file could be applied to the source server synchronize it with the this server
Default Value localhost
Required No
Multi-Valued No

--targetPort {port}

Description PingAuthorize Server port number of the target server whose contents will be used as the target of the computed diff
Default Value 389
Required No
Multi-Valued No

--targetUseSSL

Description Use SSL for secure communication with the target server

--targetUseStartTLS

Description Use SSL for secure communication with the target server

--targetBindDN {bindDN}

Description DN used to bind to the target PingAuthorize Server. Defaults to the source bind DN if not specified
Required No
Multi-Valued No

--targetBindPassword {bindPassword}

Description Password used to bind to the target PingAuthorize Server. Defaults to password of source server
Required No
Multi-Valued No

-F {bindPasswordFile}
--targetBindPasswordFile {bindPasswordFile}

Description File containing the password to use to bind to the target server. Defaults to password of source server
Required No
Multi-Valued No

--targetSASLOption {name=value}

Description A SASL option (in the form 'name=value') to use when attempting to authenticate to the target server
Required No
Multi-Valued Yes

--targetDNsFile {file-with-dns}

Description Build the list of target DNs to compare by reading DNs from this file instead of by doing a search from the target server. This can speed up the ldap-diff process in topologies where retrieving the list of DNs is expensive, such as a disk-bound environment. DNs should be listed in this file according to standard LDIF syntax
Required No
Multi-Valued No

-X
--trustAll

Description Trust all server SSL certificates

-K {keystorePath}
--keyStorePath {keystorePath}

Description Certificate keystore path
Required No
Multi-Valued No

-W {keystorePassword}
--keyStorePassword {keystorePassword}

Description Certificate keystore PIN
Required No
Multi-Valued No

-u {keystorePasswordFile}
--keyStorePasswordFile {keystorePasswordFile}

Description Certificate keystore PIN file
Required No
Multi-Valued No

--keyStoreFormat {keyStoreFormat}

Description Certificate keystore format
Required No
Multi-Valued No

-N {nickname}
--certNickname {nickname}

Description Nickname of the certificate for SSL client authentication
Required No
Multi-Valued No

-P {truststorePath}
--trustStorePath {truststorePath}

Description Certificate truststore path
Required No
Multi-Valued No

--trustStorePassword {truststorePassword}

Description Certificate truststore PIN
Required No
Multi-Valued No

-U {path}
--trustStorePasswordFile {path}

Description Certificate truststore PIN file
Required No
Multi-Valued No

--trustStoreFormat {trustStoreFormat}

Description Certificate truststore format
Required No
Multi-Valued No

-b {baseDN}
--baseDN {baseDN}

Description Only entries beneath this base DN will be compared
Required Yes
Multi-Valued No

-f {filter}
--searchFilter {filter}

Description The LDAP search filter to use at the source and destination server when retrieving entries
Default Value (objectclass=*)
Required Yes
Multi-Valued No

-s (base|one|sub|subordinate)
--searchScope (base|one|sub|subordinate)

Description The LDAP search scope to use at the source and destination server when retrieving entries
Allowed Values base
one
sub
subordinate
Default Value sub
Required No
Multi-Valued No

-B {branchDN}
--excludeBranch {branchDN}

Description Base DN of a branch to exclude from the LDAP diff
Required No
Multi-Valued Yes

-o {file}
--outputLDIF {file}

Description File to which the LDIF output should be written
Required Yes
Multi-Valued No

--wrapColumn {column}

Description The column at which long lines in the output LDIF should be wrapped. A value of zero (which is the default) indicates that long line should not be wrapped
Lower Bound 0
Upper Bound 2147483647
Default Value 0
Required No
Multi-Valued No

-Q
--quiet

Description No progress information is written to the standard output

--numConnections {num-connections}

Description The number of concurrent connections to open to each PingAuthorize Server instance when comparing entries. A smaller value will have a smaller impact on overall server performance, but a larger value might execute faster
Lower Bound 1
Upper Bound 100
Default Value 20
Required No
Multi-Valued No

--numPasses {num-passes}

Description The total number of times to compare an entry that is out-of-sync to account for replication delays. If both servers are quiescent, then a value of 1 can be provided. If either server is actively being modified, a larger value for this attribute might prevent false positives. For example, an entry reported as out-of-sync when in fact a modification to it has not yet replicated
Lower Bound 1
Upper Bound 100
Default Value 3
Required No
Multi-Valued No

--secondsBetweenPass {seconds}

Description The number of seconds to wait between each pass of rechecking entries that were out-of-sync in the hope that they are only temporarily out-of-sync due to replication delays
Lower Bound 0
Upper Bound 1000
Default Value 2
Required No
Multi-Valued No

--missingOnly

Description Only report on entries that are missing on one of the servers. This can significantly reduce the running time of the tool