PingAuthorize Server Documentation Index
Command-Line Tool Reference Home

ldap-diff

Description
Examples
Arguments

Description

Compare the contents of two LDAP servers.

This tool identifies the differences between data stored in two LDAPv3 servers and records the output in an LDIF file with the changes that may be applied (using a tool like ldapmodify or parallel-update) to the source server to bring its contents in sync with the target server. By default, all entries beneath the specified base DN will be compared, but you can use the --searchFilter argument to restrict the comparison to a specified set of entries. Also by default, all user attributes in each entry will be compared, and operational attributes will be ignored, but you can use trailing arguments to specify the set of attributes to request when retrieving entries.

This tool can be used on servers that are actively being updated by clients. It will attempt to avoid reporting false positives that result from replication delays by checking differing entries multiple times (as configured by the --numPasses and --secondsBetweenPasses arguments). The output is formatted so that deletes are included first, followed by modifies, and finally adds. Deletes will be listed in reverse order so that children will be removed before parents, and processing modifies before adds should help avoid problems resulting from uniqueness conflicts.

This tool tries to make efficient use of memory, but it must store compact representations of all entries in memory. For directories with a very large number of entries, this might require a substantial amount of memory. If processing progress slows dramatically, or if the tool reports an out of memory error, then you may need to increase the amount of memory available to the JVM when running the tool. That can be done by editing the ldap-diff.java-args line in the config/java.properties file to specify alternative values for the '-Xmx' (for the maximum amount of memory to give the tool) and '-Xms' (for the initial amount of memory to give the tool) and running the dsjavaproperties tool with no arguments.

The accounts used for performing the searches must be sufficiently privileged to retrieve all the appropriate entries from each server, and all appropriate attributes from those entries. In the Ping Identity Directory Server, we recommend using an account with at least the bypass-acl (or bypass-read-acl) and unindexed-search privileges, as well as values of zero for the ds-rlim-size-limit, ds-rlim-time-limit, ds-rlim-idle-time-limit, and ds-rlim-lookthrough-limit operational attributes.

Examples

Compares all entries beneath 'dc=example,dc=com' between the source and port servers and writes an LDIF representation of any differences identified to 'diff.ldif'.
ldap-diff --sourceHostname source.example.com --sourcePort 636 --sourceUseSSL \
     --sourceBindDN "cn=Directory Manager" \
     --sourceBindPasswordFile /path/to/password.txt \
     --targetHostname target.example.com --targetPort 636 --targetUseSSL \
     --targetBindDN "cn=Directory Manager" \
     --targetBindPasswordFile /path/to/password.txt --baseDN dc=example,dc=com \
     --outputLDIF diff.ldif

For examples and help with LDAP options see LDAP Option Help. For help with SASL authentication, see SASL Option Help

Arguments

-V
--version

Description Display PingAuthorize Server version information

-H
--help

Description Display general usage information

--help-ldap

Description Display help for using LDAP options

--help-sasl

Description Display help for using SASL options

--help-debug

Description Display help for using debug options
Advanced Yes

--sourceHostname {host}

Description The IP address or resolvable name to use to connect to the directory server. If this is not provided, then a default value of 'localhost' will be used.
Default Value localhost
Required Yes
Multi-Valued No

--sourcePort {port}

Description The port to use to connect to the directory server. If this is not provided, then a default value of 389 will be used.
Default Value 389
Required Yes
Multi-Valued No

--sourceBindDN {dn}

Description The DN to use to bind to the directory server when performing simple authentication.
Required No
Multi-Valued No

--sourceBindPassword {password}

Description The password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
Required No
Multi-Valued No

--sourceBindPasswordFile {path}

Description The path to the file containing the password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
Required No
Multi-Valued No

--sourceUseSSL

Description Use SSL when communicating with the directory server.

--sourceUseStartTLS

Description Use StartTLS when communicating with the directory server.

--sourceDefaultTrust

Description Use the JVM's default trust store, the server's default trust store, the server's topology registry, and optionally an additional trust store specified using the --trustStorePath argument to non-interactively determine whether to trust any certificate chain presented during TLS negotiation. If the chain cannot be trusted based on any of those sources, then negotiation will fail without prompting about whether to trust it.

--sourceTrustAll

Description Trust any certificate presented by the directory server.

--sourceKeyStorePath {path}

Description The path to the file to use as the key store for obtaining client certificates when communicating securely with the directory server.
Required No
Multi-Valued No

--sourceKeyStorePassword {password}

Description The password to use to access the key store contents.
Required No
Multi-Valued No

--sourceKeyStorePasswordFile {path}

Description The path to the file containing the password to use to access the key store contents.
Required No
Multi-Valued No

--sourceKeyStoreFormat {format}

Description The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the key store file.
Required No
Multi-Valued No

--sourceTrustStorePath {path}

Description The path to the file to use as trust store when determining whether to trust a certificate presented by the directory server.
Required No
Multi-Valued No

--sourceTrustStorePassword {password}

Description The password to use to access the trust store contents.
Required No
Multi-Valued No

--sourceTrustStorePasswordFile {path}

Description The path to the file containing the password to use to access the trust store contents.
Required No
Multi-Valued No

--sourceTrustStoreFormat {format}

Description The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the trust store file.
Required No
Multi-Valued No

--sourceCertNickname {nickname}

Description The nickname (alias) of the client certificate in the key store to present to the directory server for SSL client authentication.
Required No
Multi-Valued No

--sourceSASLOption {name=value}

Description A name-value pair providing information to use when performing SASL authentication.
Required No
Multi-Valued Yes

--targetHostname {host}

Description The IP address or resolvable name to use to connect to the directory server. If this is not provided, then a default value of 'localhost' will be used.
Default Value localhost
Required Yes
Multi-Valued No

--targetPort {port}

Description The port to use to connect to the directory server. If this is not provided, then a default value of 389 will be used.
Default Value 389
Required Yes
Multi-Valued No

--targetBindDN {dn}

Description The DN to use to bind to the directory server when performing simple authentication.
Required No
Multi-Valued No

--targetBindPassword {password}

Description The password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
Required No
Multi-Valued No

--targetBindPasswordFile {path}

Description The path to the file containing the password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
Required No
Multi-Valued No

--targetUseSSL

Description Use SSL when communicating with the directory server.

--targetUseStartTLS

Description Use StartTLS when communicating with the directory server.

--targetDefaultTrust

Description Use the JVM's default trust store, the server's default trust store, the server's topology registry, and optionally an additional trust store specified using the --trustStorePath argument to non-interactively determine whether to trust any certificate chain presented during TLS negotiation. If the chain cannot be trusted based on any of those sources, then negotiation will fail without prompting about whether to trust it.

--targetTrustAll

Description Trust any certificate presented by the directory server.

--targetKeyStorePath {path}

Description The path to the file to use as the key store for obtaining client certificates when communicating securely with the directory server.
Required No
Multi-Valued No

--targetKeyStorePassword {password}

Description The password to use to access the key store contents.
Required No
Multi-Valued No

--targetKeyStorePasswordFile {path}

Description The path to the file containing the password to use to access the key store contents.
Required No
Multi-Valued No

--targetKeyStoreFormat {format}

Description The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the key store file.
Required No
Multi-Valued No

--targetTrustStorePath {path}

Description The path to the file to use as trust store when determining whether to trust a certificate presented by the directory server.
Required No
Multi-Valued No

--targetTrustStorePassword {password}

Description The password to use to access the trust store contents.
Required No
Multi-Valued No

--targetTrustStorePasswordFile {path}

Description The path to the file containing the password to use to access the trust store contents.
Required No
Multi-Valued No

--targetTrustStoreFormat {format}

Description The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the trust store file.
Required No
Multi-Valued No

--targetCertNickname {nickname}

Description The nickname (alias) of the client certificate in the key store to present to the directory server for SSL client authentication.
Required No
Multi-Valued No

--targetSASLOption {name=value}

Description A name-value pair providing information to use when performing SASL authentication.
Required No
Multi-Valued Yes

-b {baseDN}
--baseDN {baseDN}

Description The base DN to use when searching for entries to compare. Only entries that exist below this base DN will be examined. The empty base DN is not permitted.
Required Yes
Multi-Valued No

--sourceDNsFile {path}

Description The path to a file containing the DNs of the entries to compare from the source server. If this is provided, then the DNs contained in this file will be used instead of retrieving them from the source server.
Required No
Multi-Valued No

--targetDNsFile {path}

Description The path to a file containing the DNs of the entries to compare from the target server. If this is provided, then the DNs contained in this file will be used instead of retrieving them from the target server.
Required No
Multi-Valued No

-B {dn}
--excludeBranch {dn}

Description The base DN of a subtree to exclude when examining entries. This argument may be provided multiple times if multiple subtrees should be excluded.
Required No
Multi-Valued Yes

-f {filter}
--searchFilter {filter}

Description The filter to use when identifying entries to compare. If this is not specified, then a default filter of '(objectClass=*)' will be used.
Default Value (objectClass=*)
Required No
Multi-Valued No

-s {base|one|sub|subordinates}
--searchScope {base|one|sub|subordinates}

Description The scope to use when searching for entries to compare in the source and target servers. If this is not specified, a default scope of 'sub' will be used.
Allowed Values sub
subord
base
one
Default Value SUB
Required No
Multi-Valued No

-o {path}
--outputLDIF {path}

Description The path to the file to which LDIF records will be written for any differences identified between the source and target servers.
Required Yes
Multi-Valued No

--wrapColumn {value}

Description The column at which to wrap long lines in the generated LDIF output. If this is not specified, then a default value of zero (which indicates no wrapping) will be used.
Upper Bound 2147483647
Default Value 0
Required No
Multi-Valued No

-Q
--quiet

Description Do not write any progress information to standard output.

--numThreads {value}

Description The number of concurrent threads to use when comparing entries between the source and target servers. A separate connection will be established for each thread, so this argument also controls the number of connections to establish to each server. If this is not specified, then a default value of 20 will be used. A smaller value may have a lesser impact on server performance, but it may take longer for processing to complete.
Upper Bound 2147483647
Default Value 20
Required No
Multi-Valued No

--numPasses {value}

Description The maximum number of times that each entry may be compared between the source and target servers to determine whether they are in sync. Using multiple passes can help eliminate false positives that may result from replication delay or from comparing an entry that is altered at the time it is being compared. If this is not specified, then up to three passes will be used by default.
Upper Bound 2147483647
Default Value 3
Required No
Multi-Valued No

--secondsBetweenPasses {value}

Description The number of seconds that the tool should wait between each pass to re-examine any entries that were found to be out of sync in the previous pass. If this is not specified, then a default delay of two seconds will be used.
Upper Bound 2147483647
Default Value 2
Required No
Multi-Valued No

--byteForByte

Description Use a byte-for-byte comparison when identifying differences between entries. By default, the tool will attempt to use schema-aware matching based on the equality matching rule for each attribute type to determine whether attribute values are logically equivalent.

--missingOnly

Description Only report on entries that are present in one of the servers but not in the other. If this option is used, then entries that exist in both servers will not be compared for differences. This can significantly reduce the length of time required to run the tool.

--useLegacyExitCode

Description Use the same exit codes as a legacy version of this tool. If all processing completes successfully and no differences are identified, then a legacy exit code of 0 will be used (which is the same in legacy and non-legacy modes). If all processing completes successfully but one or more differences are identified, then a legacy exit code of 3 will be used (rather than the default of 5, which corresponds to the compareFalse LDAP result code). If an error occurs while processing the command-line arguments, then a legacy exit code of 2 will be used (rather than the default of 89, which corresponds to the paramError LDAP result code). If any other error occurs, then a legacy exit code of 1 will be used (rather than the default behavior of using the integer value that corresponds to the LDAP result code that most closely reflects the error that occurred).

--propertiesFilePath {path}

Description The path to a properties file used to specify default values for arguments not supplied on the command line.
Required No
Multi-Valued No

--generatePropertiesFile {path}

Description Write an empty properties file that may be used to specify default values for arguments.
Required No
Multi-Valued No

--noPropertiesFile

Description Do not obtain any argument values from a properties file.

--suppressPropertiesFileComment

Description Suppress output listing the arguments obtained from a properties file.