The ldap-diff Command-Line Tool

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.

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.

Usage

ldap-diff {arguments} {attributes}

Source Connection and Authentication Arguments

• --sourceHostname {host} — 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.
  
  
• --sourcePort {port} — The port to use to connect to the directory server. If this is not provided, then a default value of 389 will be used.
  The specified value must not be less than 1 or greater than 65,535.
  
  
• --sourceBindDN {dn} — The DN to use to bind to the directory server when performing simple authentication.
  A provided value must be able to be parsed as an LDAP distinguished name as described in RFC 4514.
  
  
• --sourceBindPassword {password} — The password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
  
  
• --sourceBindPasswordFile {path} — 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.
  The specified path must refer to a file that exists.
  
  
• --sourceUseSSL — Use SSL when communicating with the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --sourceUseStartTLS — Use StartTLS when communicating with the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --sourceDefaultTrust — Use the JVM's default trust store, 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.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --sourceTrustAll — Trust any certificate presented by the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --sourceKeyStorePath {path} — The path to the file to use as the key store for obtaining client certificates when communicating securely with the directory server.
  
  
• --sourceKeyStorePassword {password} — The password to use to access the key store contents.
  
  
• --sourceKeyStorePasswordFile {path} — The path to the file containing the password to use to access the key store contents.
  The specified path must refer to a file that exists.
  
  
• --sourceKeyStoreFormat {format} — The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the key store file.
  
  
• --sourceTrustStorePath {path} — The path to the file to use as trust store when determining whether to trust a certificate presented by the directory server.
  
  
• --sourceTrustStorePassword {password} — The password to use to access the trust store contents.
  
  
• --sourceTrustStorePasswordFile {path} — The path to the file containing the password to use to access the trust store contents.
  The specified path must refer to a file that exists.
  
  
• --sourceTrustStoreFormat {format} — The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the trust store file.
  
  
• --sourceCertNickname {nickname} — The nickname (alias) of the client certificate in the key store to present to the directory server for SSL client authentication.
  
  
• --sourceSASLOption {name=value} — A name-value pair providing information to use when performing SASL authentication.
  
  

Target Connection and Authentication Arguments

• --targetHostname {host} — 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.
  
  
• --targetPort {port} — The port to use to connect to the directory server. If this is not provided, then a default value of 389 will be used.
  The specified value must not be less than 1 or greater than 65,535.
  
  
• --targetBindDN {dn} — The DN to use to bind to the directory server when performing simple authentication.
  A provided value must be able to be parsed as an LDAP distinguished name as described in RFC 4514.
  
  
• --targetBindPassword {password} — The password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
  
  
• --targetBindPasswordFile {path} — 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.
  The specified path must refer to a file that exists.
  
  
• --targetUseSSL — Use SSL when communicating with the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --targetUseStartTLS — Use StartTLS when communicating with the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --targetDefaultTrust — Use the JVM's default trust store, 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.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --targetTrustAll — Trust any certificate presented by the directory server.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --targetKeyStorePath {path} — The path to the file to use as the key store for obtaining client certificates when communicating securely with the directory server.
  
  
• --targetKeyStorePassword {password} — The password to use to access the key store contents.
  
  
• --targetKeyStorePasswordFile {path} — The path to the file containing the password to use to access the key store contents.
  The specified path must refer to a file that exists.
  
  
• --targetKeyStoreFormat {format} — The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the key store file.
  
  
• --targetTrustStorePath {path} — The path to the file to use as trust store when determining whether to trust a certificate presented by the directory server.
  
  
• --targetTrustStorePassword {password} — The password to use to access the trust store contents.
  
  
• --targetTrustStorePasswordFile {path} — The path to the file containing the password to use to access the trust store contents.
  The specified path must refer to a file that exists.
  
  
• --targetTrustStoreFormat {format} — The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the trust store file.
  
  
• --targetCertNickname {nickname} — The nickname (alias) of the client certificate in the key store to present to the directory server for SSL client authentication.
  
  
• --targetSASLOption {name=value} — A name-value pair providing information to use when performing SASL authentication.
  
  

Processing Arguments

• -b {baseDN} / --baseDN {baseDN} — 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.
  A provided value must be able to be parsed as an LDAP distinguished name as described in RFC 4514.
  
  
• --sourceDNsFile {path} — 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.
  The specified path must refer to a file that exists.
  
  
• --targetDNsFile {path} — 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.
  The specified path must refer to a file that exists.
  
  
• -B {dn} / --excludeBranch {dn} — The base DN of a subtree to exclude when examining entries. This argument may be provided multiple times if multiple subtrees should be excluded.
  A provided value must be able to be parsed as an LDAP distinguished name as described in RFC 4514.
  
  
• -f {filter} / --searchFilter {filter} — The filter to use when identifying entries to compare. If this is not specified, then a default filter of '(objectClass=*)' will be used.
  A provided value must be able to be parsed as an LDAP search filter as described in RFC 4515.
  
  
• -s {base|one|sub|subordinates} / --searchScope {base|one|sub|subordinates} — 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.
  The provided value should be one of 'base', 'one', 'sub', or 'subordinate'.
  
  
• -o {path} / --outputLDIF {path} — The path to the file to which LDIF records will be written for any differences identified between the source and target servers.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --wrapColumn {value} — 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.
  The specified value must not be less than 0 or greater than 2,147,483,647.
  
  
• -Q / --quiet — Do not write any progress information to standard output.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --numThreads {value} — 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.
  The specified value must not be less than 1 or greater than 2,147,483,647.
  
  
• --numPasses {value} — 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.
  The specified value must not be less than 1 or greater than 2,147,483,647.
  
  
• --secondsBetweenPasses {value} — 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.
  The specified value must not be less than 0 or greater than 2,147,483,647.
  
  
• --byteForByte — 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.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --missingOnly — 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.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --useLegacyExitCode — 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).
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Additional Arguments

• -h {value} —
  
  
• -p {value} —
  The specified value must not be less than 1 or greater than 65,535.
  
  
• -D {dn} —
  A provided value must be able to be parsed as an LDAP distinguished name as described in RFC 4514.
  
  
• -w {value} —
  
  
• -O {value} —
  
  
• -F {path} —
  The specified path must refer to a file that exists.
  
  
• -X / --trustAll —
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• -K {path} / --keyStorePath {path} —
  The specified path must refer to a file that exists.
  
  
• -W {value} / --keyStorePassword {value} —
  
  
• -u {path} / --keyStorePasswordFile {path} —
  The specified path must refer to a file that exists.
  
  
• --keyStoreFormat {value} —
  
  
• -N {value} / --certNickname {value} —
  
  
• -P {path} / --trustStorePath {path} —
  The specified path must refer to a file that exists.
  
  
• --trustStorePassword {value} —
  
  
• -U {path} / --trustStorePasswordFile {path} —
  The specified path must refer to a file that exists.
  
  
• --trustStoreFormat {value} —
  
  
• -H / --help — Display usage information for this program.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --help-debug — Display usage information for debug logging.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --enable-debug-logging — Enables debug logging for the tool.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --debug-log-level {level} — The debug log level to use for the tool. Allowed values include 'off', 'severe', 'warning', 'info', 'fine', 'finer', and 'finest'. If this is not specified, a default level of 'severe' will be used.
  
  
• --debug-log-category {category} — The message categories to include in the debug log output. Allowed values include 'asn1', 'connect', 'exception', 'ldap', 'connectionpool', 'ldif', 'monitor', 'codingerror', and 'other'. This argument may be provided multiple times to indicate that multiple categories should be included. If this is not specified, then all categories will be included.
  
  
• --include-debug-stack-traces — Indicates that debug log messages should include a stack trace with the code location from which each debug message originated.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --use-multi-line-debug-messages — Indicates that debug log messages (which will be JSON objects) should be written as multi-line strings rather than single-line strings.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --debug-log-file {path} — The path to the debug log file to be written. If this is not specified, a default path of 'ldap-diff.debug' will be used.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• -V / --version — Display version information for this program.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --propertiesFilePath {path} — The path to a properties file used to specify default values for arguments not supplied on the command line.
  The specified path must refer to a file that exists.
  
  
• --generatePropertiesFile {path} — Write an empty properties file that may be used to specify default values for arguments.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --noPropertiesFile — Do not obtain any argument values from a properties file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  
• --suppressPropertiesFileComment — Suppress output listing the arguments obtained from a properties file.
  This argument is not allowed to have a value. If this argument is included in a set of arguments, then it will be assumed to have a value of 'true'. If it is absent from a set of arguments, then it will be assumed to have a value of 'false'.
  
  

Dependent Argument Sets

• If the --sourceBindDN argument is provided, then at least one of the following arguments must also be provided: --sourceBindPassword, --sourceBindPasswordFile
• If the --targetBindDN argument is provided, then at least one of the following arguments must also be provided: --targetBindPassword, --targetBindPasswordFile

Exclusive Argument Sets

• The following arguments cannot be used together: --sourceUseSSL, --sourceUseStartTLS
• The following arguments cannot be used together: --sourceBindPassword, --sourceBindPasswordFile
• The following arguments cannot be used together: --sourceKeyStorePassword, --sourceKeyStorePasswordFile
• The following arguments cannot be used together: --sourceTrustStorePassword, --sourceTrustStorePasswordFile
• The following arguments cannot be used together: --sourceTrustAll, --sourceTrustStorePath
• The following arguments cannot be used together: --sourceTrustAll, --sourceDefaultTrust
• The following arguments cannot be used together: --targetUseSSL, --targetUseStartTLS
• The following arguments cannot be used together: --targetBindPassword, --targetBindPasswordFile
• The following arguments cannot be used together: --targetKeyStorePassword, --targetKeyStorePasswordFile
• The following arguments cannot be used together: --targetTrustStorePassword, --targetTrustStorePasswordFile
• The following arguments cannot be used together: --targetTrustAll, --targetTrustStorePath
• The following arguments cannot be used together: --targetTrustAll, --targetDefaultTrust
• The following arguments cannot be used together: --sourceHostname, -h
• The following arguments cannot be used together: --sourcePort, -p
• The following arguments cannot be used together: --sourceBindDN, -D
• The following arguments cannot be used together: --sourceBindPassword, -w
• The following arguments cannot be used together: --targetHostname, -O
• The following arguments cannot be used together: --targetBindPasswordFile, -F
• The following arguments cannot be used together: --sourceTrustAll, --trustAll
• The following arguments cannot be used together: --targetTrustAll, --trustAll
• The following arguments cannot be used together: --sourceKeyStorePath, --keyStorePath
• The following arguments cannot be used together: --targetKeyStorePath, --keyStorePath
• The following arguments cannot be used together: --sourceKeyStorePassword, --keyStorePassword
• The following arguments cannot be used together: --targetKeyStorePassword, --keyStorePassword
• The following arguments cannot be used together: --sourceKeyStorePasswordFile, --keyStorePasswordFile
• The following arguments cannot be used together: --targetKeyStorePasswordFile, --keyStorePasswordFile
• The following arguments cannot be used together: --sourceKeyStoreFormat, --keyStoreFormat
• The following arguments cannot be used together: --targetKeyStoreFormat, --keyStoreFormat
• The following arguments cannot be used together: --sourceCertNickname, --certNickname
• The following arguments cannot be used together: --targetCertNickname, --certNickname
• The following arguments cannot be used together: --sourceTrustStorePath, --trustStorePath
• The following arguments cannot be used together: --targetTrustStorePath, --trustStorePath
• The following arguments cannot be used together: --sourceTrustStorePassword, --trustStorePassword
• The following arguments cannot be used together: --targetTrustStorePassword, --trustStorePassword
• The following arguments cannot be used together: --sourceTrustStorePasswordFile, --trustStorePasswordFile
• The following arguments cannot be used together: --targetTrustStorePasswordFile, --trustStorePasswordFile
• The following arguments cannot be used together: --sourceTrustStoreFormat, --trustStoreFormat
• The following arguments cannot be used together: --targetTrustStoreFormat, --trustStoreFormat
• The following arguments cannot be used together: --propertiesFilePath, --noPropertiesFile

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