Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun ONE Directory Server Resource Kit 5.2 Tools Reference 

Chapter 6
The ldapcompare Tool

The ldapcompare tool compares an attribute value against the contents of a given directory entry. It compares either a textual value or a binary value, providing a simple interface to check data against directory contents. This chapter provides instructions on how to use the ldapcompare tool. It contains the following sections:


The ldapcompare tool compares one attribute value with the same attribute’s value in one or more entries of a directory. Standard, textual values can be entered directly on the command-line; binary attribute values may be entered on the command-line with base-64 encoding or stored in a file referenced using the URL syntax.


To compare the contents of two directories, use ldapcmp described in Chapter 7.

ldapcompare is also provided with Sun™ ONE Directory Server in the DirectoryServer_base/shared/bin directory. However, the DSRK and its updates should include the latest version of the tool in the DSRK_base/bin/dsrk52 directory.


If you use the Solaris™ operating environment, there may be an older version of ldapcompare in /usr/bin. Be sure your path is set to use the latest version in DSRK_base/bin/dsrk52.

Command Usage

ldapcompare supports the common options of the other LDAP commands, such as managing referrals, handling locales, and providing SSL-based security. By default, it will print out the success of the comparisons, stopping after the first failed comparison. The command-line options can be used to control this behavior and other aspects of the input and output.


The syntax of the ldapcompare tool on the command-line can take any of these forms:

ldapcompare [ options ] ’attribute:value’ [ "targetDN" ... | -f DNfile ]

ldapcompare [ options ] ’attribute::base64value’ [ "targetDN" ... | -f DNfile ]

ldapcompare [ options ] ’attribute:<fileURL’ [ "targetDN" ... | -f DNfile ]



The ldapcompare tool has three types of options:

The following sections detail these options. The ldapcompare -H command and option when run on the command-line will display brief descriptions of the command syntax, options, and parameters.

Common Options

The common options listed in Table 6-1 control the binding and general behavior of the ldapcompare command.

Table 6-1  Common Options for ldapcompare 






Specify the hostname of the directory server. When this option is omitted, the default is localhost.



Specify the port number for accessing the directory server host. The default is 389 normally and 636 when the SSL options are used.



Specify a bind DN for accessing your directory with simple authentication, usually in double quotes ("") for the shell. If the bind DN and its password are omitted, the tool will use anonymous binding. The bind DN determines what entries may be accessed, according to the DN’s access permissions.



Specify the password for the bind DN. CAUTION: Specifying the password on the command-line is a possible security risk.



Type the password for the bind DN when prompted. This is the most secure way of specifying the password.



Specify a file containing the password for the bind DN. Use this option in scripts and place the password in a secure file to protect the password. This option is mutually exclusive with the -w option.



Give the name of a file containing the DNs of entries to be compared. The DNs should be listed one per line in this file, each line being taken as the entire literal DN. Do not use quotes.



Specify the LDAP protocol version number to be used for the comparison, either 2 or 3. LDAP v3 is the default; only specify LDAP v2 when connecting to servers that do not support v3.



Specify the proxy DN to use for the comparison, usually in double quotes ("") for the shell. For more information about proxy authorization, see Chapter 6, “Managing Access Control,” in the Sun ONE Directory Server Administration Guide.



Manage smart referrals: when they are the target of the comparison, compare values in the actual entry containing the referral instead of the entry obtained by following the referral. For more information, see “Creating Smart Referrals” in Chapter 2 of the Sun ONE Directory Server Administration Guide.



(Capital letter O) Specify the maximum number of referral hops to follow while finding an entry to compare. By default, there is no limit.



Specify that referrals should not be followed. By default, referrals are followed automatically.



Verbose output mode: the tool will display additional information about the operations it performs.



No-op mode: use with the -v option to show what the tool would do with the given input but do not perform the comparison.



Allow runtime library version mismatches. When this option is omitted, the default behavior is to assert that the revision number of the LDAP API is greater than or equal to that used to compile the tool. Also, if the API library and the tool have the same vendor name, the tool will also assert that the vendor version number of the API is greater than or equal to that used to compile the tool. This information is based on the contents of the LDAPAPIInfo structure. (See the Sun ONE LDAP SDK for C Programming Guide.)



Display the usage help text that briefly describes all options.

Input And Output Options

The input and output options listed in Table 6-2 control how ldapcompare processes input files and handles errors.

Table 6-2  Input and Output Options for ldapcompare 






Specify the character set to use for command-line input. The default is the character set specified in the LANG environment variable. This option can be used to convert from the specified character set to UTF8, thus overriding the LANG setting. You can also input a specific character set for the bind DN, base DN, and the search filter pattern. The ldapcompare tool converts the input from these arguments before it processes the request. For example, -i no indicates that the bind DN and target DNs are provided in Norwegian. This argument only affects the command-line input. A DN file (specified with the -f option) will not be converted by ldapcompare.



Specify the path to a directory containing conversion routines. These routines are used if you wish to specify a locale that is not supported by default by your directory server. For more information, see Appendix C, “Directory Internationalization” in the Sun ONE Directory Server Reference Manual.



Continuous mode: errors are reported but the ldapcompare tool will continue processing input and performing operations. When this option is omitted, the default behavior is to quit after reporting an error.



Quiet mode: information and results of comparisons are not displayed in the output, however LDAP errors still are.

SSL (Secure Socket Layer) Options

The options in Table 6-3 allow you to use LDAPS (LDAP over SSL) to establish a secure connection for the compare operation. These options are valid only when LDAPS has been turned on and configured in your SSL-enabled directory server. For information on certificate-based authentication and creating a certificate database for use with LDAP clients, see Chapter 11, “Implementing Security,” in the Sun ONE Directory Server Administration Guide.


Only the -P option is required for server authentication. For the more secure client authentication, the -P, -N, -K and -W options are required.

Table 6-3  SSL Options for ldapcompare 






Specify the path and filename of the client’s certificate database. This file may be the same as the certificate database for an SSL-enabled version of Netscape™ Communicator, if available; for example:
-P /home/uid/.netscape/cert7.db.

When using the command on the same host as the directory server, you may use the server’s own certificate database, for example:
-P installDir/slapd-serverID/alias/cert7.db.

Use the -P option alone to specify server authentication only.



Specify that SSL be used to provide certificate-based client authentication. This option requires the -N and -W options and any other of the SSL options needed to identify the certificate and the key database.



Specify the certificate name to use for certificate-based client authentication, for example: -N "Directory-Cert".



Specify the path to the security module database. For example, /usr/iplanet/servers/slapd-serverID/secmodule.db. You need to specify this option only if the security module database is in a different directory from the certificate database itself.



Specify the file and path name of the client’s private key database. This option may be omitted if the key database is in the location already given by the -P option.



Specify the password for the client’s key database given in the -K or -P options. This option is required for certificate-based client authentication.

Return Values

The ldapcompare tool is based on the Sun ONE LDAP SDK for C and its return values are those of the functions it uses, such as ldap_simple_bind_s(), ldap_compare_ext(), and ldap_result(). These functions return both client-side and server-side errors and codes. Table 6-4 shows the possible return values when the directory is hosted on a Sun ONE Directory Server. Other LDAP servers may send these values under different circumstances or may send different values. They may also send other result codes entirely; for example, custom result codes from a custom plug-in. Under most conditions though, the ldapcompare tool returns one of the following integer values:

For further information about result codes, see the Sun ONE LDAP SDK for C Programming Guide.

Table 6-4  Return Values of ldapcompare 

Return Value

Result Code
and Explanation

  1 (0x01)

LDAP_OPERATIONS_ERROR: sent by Directory Server for general errors encountered by the server when processing the request.

  2 (0x02)

LDAP_PROTOCOL_ERROR: Directory Server may send this error code in the results for a variety of reasons, such as encountering an error when decoding the BER-encoded request.

  3 (0x03)

LDAP_TIMELIMIT_EXCEEDED: sent by Directory Server if a comparison search exceeded the default time limit for an operation on the server.

  4 (0x04)

LDAP_SIZELIMIT_EXCEEDED: sent by Directory Server if a comparison search found more results than the default maximum allowed by the server.

  5 (0x05)

LDAP_COMPARE_FALSE: returned by the tool when the operation is successful but the comparison fails.

  6 (0x06)

LDAP_COMPARE_TRUE: returned by the tool when the operation is successful and the comparison holds.

10 (0x0a)

LDAP_REFERRAL: sent by Directory Server if the given base DN is an entry not handled by either server and if the referral URL identifies a different server to handle the entry.

11 (0x0b)

LDAP_ADMINLIMIT_EXCEEDED: sent by Directory Server if a comparison search found more results than the limit specified by the lookthroughlimit directive in the slapd.conf configuration file. If not specified in the configuration file, the default limit is 5000.

32 (0x20)

LDAP_NO_SUCH_OBJECT: the given base DN cannot be found in the directory server and no referral URL is available.

50 (0x32)

LDAP_INSUFFICIENT_ACCESS: sent by the directory server if the DN used for authentication does not have permission to read from the directory.

81 (0x51)

LDAP_SERVER_DOWN: the directory server did not respond to the comparison operations or the connection was lost.

82 (0x52)

LDAP_LOCAL_ERROR: an error occurred when receiving the results from the server.

83 (0x53)

LDAP_ENCODING_ERROR: the request could not be BER-encoded.

84 (0x54)

LDAP_DECODING_ERROR: an error occurred when decoding the BER-encoded results from the server.

89 (0x59)

LDAP_PARAM_ERROR: one of the options or parameters is invalid.

90 (0x5a)

LDAP_NO_MEMORY: memory cannot be allocated as needed.

91 (0x5b)

LDAP_CONNECT_ERROR: a specified hostname or port is invalid.

92 (0x5c)

LDAP_NOT_SUPPORTED: the -V 2 option is needed to access a server that only supports LDAP v2.

Command-Line Examples

The following examples demonstrate the three types of values on which the tool will perform comparisons. All examples assume the following context:

Comparing a Text Value

In this example, ldapcompare takes a textual value from the command-line and compares it to an attribute in the given DN.

% ldapcompare -h ’givenname:Barbara’ "uid=bjensen,ou=People,dc=example,dc=com"

comparing type: "givenname" value: "Barbara" in entry "uid=bjensen,ou=People,dc=example,dc=com" compare TRUE

Comparing a Binary Value

The following two examples use base-64 binary encoding. First, the comparative value is given directly in base-64 binary encoding, allowing you to compare binary values from some other output, for example, a script. This example also shows the output for multiple entry comparisons (including one which fails for authentication reasons) and uses the -c option to ensure all entries are compared.

% ldapcompare -h -c ’cn:: d29vZiAK’ "uid=tmorgan,ou=People,dc=example,dc=com" "dc=example,dc=com"

comparing type: "cn" value: "woof" in entry "uid=tmorgan,ou=People,dc=example,dc=com" compare FALSE

comparing type: "cn" value: "woof" in entry "dc=example,dc=com" ldap_compare: Insufficient access

Finally, the binary value to compare is a file referenced by a URL.

% ldapcompare -h ’usercertificate;binary:<file:/tmp/mycert’ "uid=bjensen,ou=People,dc=example,dc=com"

comparing type: "usercertificate;binary" value: "NOT ASCII (777 bytes)" in entry "uid=bjensen,ou=People,dc=siroe,dc=com" compare TRUE

Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.