The ldapcompare Command-Line Tool

Perform compare operations in an LDAP directory server. Compare operations may be used to efficiently determine whether a specified entry has a given value.

The exit code for this tool will indicate whether processing was successful or unsuccessful, and to provide a basic indication of the reason for unsuccessful attempts. By default, it will use an exit code of zero (which corresponds to the LDAP 'success' result) if all compare operations completed with a result code of either 'compare false' or 'compare true' (integer values 5 and 6, respectively), but if the --useCompareResultCodeAsExitCode argument is provided, only one compare assertion is performed, and it yields an exit code of 'compare false' or 'compare true', then the numeric value for that result code will be used as the exit code. If any error occurs during processing, then the exit code will be a nonzero value that reflects the first error result that was encountered.

The attribute type and assertion value to use for the compare operations will typically be provided as the first unnamed trailing argument provided on the command line. It should be formatted with the name or OID of the target attribute type followed by a single colon and the string representation of the assertion value. Alternatively, the attribute name or OID may be followed by two colons and the base64-encoded representation of the assertion value, or it may be followed by a colon and a less-than symbol to indicate that the assertion value should be read from a file (in which case the exact bytes of the file, including line breaks, will be used as the assertion value).

The DNs of the entries to compare may either be provided on the command line as additional unnamed trailing arguments after the provided attribute-value assertion, or they may be read from a file whose path is provided using the --dnFile argument.

If the attribute-value assertion is provided on the command line as an unnamed trailing argument, then the same assertion will be performed for all operations. If multiple types of assertions should be performed, then you may use the --assertionFile argument to specify the path to a file containing both attribute-value assertions and entry DNs.

Usage

ldapcompare {arguments} [attribute:value|attribute::base64Value|attribute:<valueFilePath [dn1 [dn2 [ dn3 [ .. ]]]]]

LDAP Connection and Authentication Arguments

• -h {host} / --hostname {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.
  
  
• -p {port} / --port {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.
  
  
• -D {dn} / --bindDN {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.
  
  
• -w {password} / --bindPassword {password} — The password to use to bind to the directory server when performing simple authentication or a password-based SASL mechanism.
  
  
• -j {path} / --bindPasswordFile {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.
  
  
• --promptForBindPassword — Indicates that the tool should interactively prompt the user for the bind password.
  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'.
  
  
• -Z / --useSSL — 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'.
  
  
• -q / --useStartTLS — 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'.
  
  
• --defaultTrust — 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'.
  
  
• -X / --trustAll — 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'.
  
  
• -K {path} / --keyStorePath {path} — The path to the file to use as the key store for obtaining client certificates when communicating securely with the directory server.
  
  
• -W {password} / --keyStorePassword {password} — The password to use to access the key store contents.
  
  
• -u {path} / --keyStorePasswordFile {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 may or may not exist.
  
  
• --promptForKeyStorePassword — Indicates that the tool should interactively prompt the user for the password to use to access the key store contents.
  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'.
  
  
• --keyStoreFormat {format} — The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the key store file.
  
  
• -P {path} / --trustStorePath {path} — The path to the file to use as trust store when determining whether to trust a certificate presented by the directory server.
  
  
• -T {password} / --trustStorePassword {password} — The password to use to access the trust store contents.
  
  
• -U {path} / --trustStorePasswordFile {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 may or may not exist.
  
  
• --promptForTrustStorePassword — Indicates that the tool should interactively prompt the user for the password to use to access the trust store contents.
  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'.
  
  
• --trustStoreFormat {format} — The format (e.g., JKS, PKCS12, PKCS11, BCFKS, etc.) for the trust store file.
  
  
• --verifyCertificateHostnames — Indicates that the tool should verify that the hostname or IP addressed used to establish connections ot the LDAP server matches an address for which the server's TLS certificate was issued.
  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'.
  
  
• -N {nickname} / --certNickname {nickname} — The nickname (alias) of the client certificate in the key store to present to the directory server for SSL client authentication.
  
  
• --enableSSLDebugging — Enable Java's low-level support for debugging SSL/TLS communication. This is equivalent to setting the 'javax.net.debug' property to 'all'.
  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'.
  
  
• -o {name=value} / --saslOption {name=value} — A name-value pair providing information to use when performing SASL authentication.
  
  
• --useSASLExternal — Use the SASL EXTERNAL mechanism to authenticate.
  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'.
  
  
• --helpSASL — Provide information about the supported SASL mechanisms, including the properties available for use with each.
  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'.
  
  

Processing Arguments

• -f {path} / --dnFile {path} — The path to a file containing the DNs of the entries in which to perform the compare assertions. If this argument is provided, then each DN must be provided on its own line with no other content on that line, and there must be exactly one unnamed trailing argument to specify the attribute-value assertion to evaluate against all entries referenced in the DN file. If this argument is not provided, then there must be at least two unnamed trailing arguments, with the first specifying the attribute-value assertion and all remaining trailing arguments providing the DNs of the entries to evaluate.
  The specified path must refer to a file that exists.
  
  
• --assertionFile {path} — The path to a file with information about the compare assertions to be evaluated. If this is provided, then each line of the file must contain the DN of the target entry followed by one or more horizontal tab characters and the attribute-value assertion to process against that entry (specified as the attribute name followed by a single colon and the string representation of the assertion value, the attribute name followed by two colons and a base64-encoded representation of the assertion value, or the attribute name followed by a colon, a less-than sign, and the path to a file from which the raw assertion value should be read).
  The specified path must refer to a file that exists.
  
  
• --followReferrals — Attempt to follow any referrals encountered during compare processing.
  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'.
  
  
• --useAdministrativeSession — Use an administrative session to process all operations using a dedicated pool of worker threads. This may be useful when trying to diagnose problems in a server that is unresponsive because all normal worker threads are busy processing other requests.
  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'.
  
  
• -c / --continueOnError — Continue processing even if there are errors.
  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'.
  
  
• -n / --dryRun — Indicate which compare assertions would be processed, but do not actually send them to the 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'.
  
  

Bind Control Arguments

• --bindControl {oid}[:{criticality}[:{stringValue}|::{base64Value}]] — Include the indicated control in all bind requests used to authenticate to the server.
  A provided value must be a string representation of a valid LDAP control in the form {oid}[:{criticality}[:{stringValue}|::{base64Value}]].
  
  
• -E / --authorizationIdentity — Include the authorization identity request control (as described in RFC 3829) in all bind requests. If this control is included, a successful bind result should include the authorization identity assigned to the connection.
  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'.
  
  
• --usePasswordPolicyControl — Include the password policy request control (as described in draft-behera-ldap-password-policy) in all bind requests. If this control is included, the bind result may include additional information about the target user's password policy state.
  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'.
  
  
• --getAuthorizationEntryAttribute {attribute} — Include the UnboundID-proprietary get authorization entry request control in all bind requests to indicate that the bind result should include the specified attributes from the entries for the authentication and authorization identities. This argument may be provided multiple times to specify multiple attributes to request.
  
  
• --getUserResourceLimits — Include the UnboundID-proprietary get user resource limits request control in all bind requests to indicate that a successful bind result should include information about resource limits (e.g., size limit, time limit, idle time limit, etc.) that the server may impose for the user.
  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'.
  
  

Compare Control Arguments

• -J {oid}[:{criticality}[:{stringValue}|::{base64Value}]] / --compareControl {oid}[:{criticality}[:{stringValue}|::{base64Value}]] — Include the indicated control in all compare requests sent to the directory server.
  A provided value must be a string representation of a valid LDAP control in the form {oid}[:{criticality}[:{stringValue}|::{base64Value}]].
  
  
• -Y {authzID} / --proxyAs {authzID} — Include the proxied authorization control (also known as the proxied authorization v2 request control, as described in RFC 4370) in compare requests to indicate that the server should process the operation under the authority of the specified user. The authorization identity should generally be specified in the form 'dn:' followed by the DN of the target user, or 'u:' followed by a username for the target user.
  
  
• --proxyV1As {dn} — Include the proxied authorization v1 request control (as described in draft-weltman-ldapv3-proxy-04) in compare requests to indicate that the server should process the operation under the authority of the user with the specified DN.
  A provided value must be able to be parsed as an LDAP distinguished name as described in RFC 4514.
  
  
• --manageDsaIT — Include the manageDsaIT request control in all compare requests to indicate that any referral entries should be treated as regular entries rather than causing the server to generate a referral result.
  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'.
  
  
• --assertionFilter {filter} — Include the LDAP assertion request control (as described in RFC 4528) in all compare requests to indicate that the compare operation should only be evaluated if the target entry matches the provided filter.
  A provided value must be able to be parsed as an LDAP search filter as described in RFC 4515.
  
  
• --operationPurpose {purpose} — Include the UnboundID-proprietary operation purpose request control in all compare requests to provide information about the purpose for the operation.
  
  

Output Arguments

• --outputFile {path} — The path to a file to which standard output should be written. Messages written to standard error will not be written to this file.
  The specified path must refer to a file which may or may not exist, but whose parent directory must exist.
  
  
• --teeOutput — Write standard output messages to both the specified output file and the default standard output stream.
  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'.
  
  
• --outputFormat {tab-delimited|csv|json} — Specifies the format in which the output should be written. Allowed values include 'tab-delimited' 'csv', or 'json'. For each output format, the output will include the DN of the target entry, the name of the attribute type, the assertion value, the numeric value for the result code, and the name for the result code. The JSON format may also include additional fields.
  A provided value should be one of the following: 'json', 'tab-delimited', 'csv'.
  
  
• --scriptFriendly — Indicates that the output should be generated in a script-friendly format. This argument is not used, as the output will always be in a script-friendly format, and the --outputFormat argument may be used to customize the format in which the output is written.
  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'.
  
  
• -v / --verbose — Indicates that the tool should generate verbose output. If this is provided, then complete details about the result of each compare operation will be written to standard error. If this is not provided, then that detail will only be written for operations that include an error result or that include one or more response controls.
  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'.
  
  
• --terse — Indicates that the tool should generate terse output. If this is provided, then additional compare output will be suppressed, even for error results and results with response controls.
  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'.
  
  
• --useCompareResultCodeAsExitCode — Use the integer value of the compare operation result code as the tool exit code. This primarily applies to cases in which only a single compare assertion is processed and the response to that compare operation has a result code of either 'compare false' (integer value 5) or 'compare true' (integer value 6). By default, the tool will use an exit code of zero in such cases to indicate that processing completed successfully, but the exit code may be useful in scripts to more easily obtain the result of the compare operation. Note that if multiple compare operations are all processed successfully, then the tool will always return an exit code of zero, and if an error is encountered during processing, then the exit code will reflect the LDAP result code for that associated error. This option only affects the tool exit code and does not alter the visible output in any way.
  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

• --interactive — Launch the tool in interactive mode.
  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'.
  
  
• -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 'ldapcompare.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 --keyStorePassword argument is provided, then the --keyStorePath argument must also be provided.
• If the --keyStorePasswordFile argument is provided, then the --keyStorePath argument must also be provided.
• If the --promptForKeyStorePassword argument is provided, then the --keyStorePath argument must also be provided.
• If the --trustStorePassword argument is provided, then the --trustStorePath argument must also be provided.
• If the --trustStorePasswordFile argument is provided, then the --trustStorePath argument must also be provided.
• If the --promptForTrustStorePassword argument is provided, then the --trustStorePath argument must also be provided.
• If the --keyStorePath argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --trustStorePath argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --defaultTrust argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --trustAll argument is provided, then at least one of the following arguments must also be provided: --useSSL, --useStartTLS
• If the --bindPassword argument is provided, then at least one of the following arguments must also be provided: --bindDN, --saslOption
• If the --bindPasswordFile argument is provided, then at least one of the following arguments must also be provided: --bindDN, --saslOption
• If the --promptForBindPassword argument is provided, then at least one of the following arguments must also be provided: --bindDN, --saslOption
• If the --teeOutput argument is provided, then the --outputFile argument must also be provided.

Exclusive Argument Sets

• The following arguments cannot be used together: --useSSL, --useStartTLS
• The following arguments cannot be used together: --keyStorePassword, --keyStorePasswordFile, --promptForKeyStorePassword
• The following arguments cannot be used together: --trustStorePassword, --trustStorePasswordFile, --promptForTrustStorePassword
• The following arguments cannot be used together: --defaultTrust, --trustAll
• The following arguments cannot be used together: --trustAll, --trustStorePath
• The following arguments cannot be used together: --bindDN, --saslOption, --useSASLExternal
• The following arguments cannot be used together: --bindPassword, --bindPasswordFile, --promptForBindPassword
• The following arguments cannot be used together: --dnFile, --assertionFile
• The following arguments cannot be used together: --proxyAs, --proxyV1As
• The following arguments cannot be used together: --verbose, --terse
• The following arguments cannot be used together: --propertiesFilePath, --noPropertiesFile

Examples

• Use an LDAP compare operation to determine whether entry 'uid=jdoe,ou=People,dc=example,dc=com' has a value of 'Austin' for the 'l' attribute. The result of the compare operation will be displayed in the default tab-delimited text format.

    ldapcompare --hostname ds.example.com --port 636 --useSSL \
         --bindDN uid=admin,dc=example,dc=com l:Austin \
         uid=jdoe,ou=People,dc=example,dc=com

• Use a series of LDAP compare operations to determine which of the entries with DNs are read from the file 'entry-dns.txt' have a 'title' value of 'manager'. The result of each compare operation will be displayed in the comma-separated values (CSV) format, with all unnecessary output suppressed.

    ldapcompare --hostname ds.example.com --port 636 --useSSL \
         --bindDN uid=admin,dc=example,dc=com --dnFile entry-dns.txt \
         --outputFormat csv --terse title:manager

• Use a series of LDAP compare operations using both entry DNs and attribute-value assertions read from the file 'compare-assertions.txt'. The results of the compare operations will be written in JSON format to the file 'compare-assertion-results.json', and verbose output about the processing will be written to standard error.

    ldapcompare --hostname ds.example.com --port 636 --useSSL \
         --bindDN uid=admin,dc=example,dc=com \
         --assertionFile compare-assertions.txt --outputFormat json \
         --outputFile compare-assertion-results.json --verbose