Sun Java logo     Previous      Contents      Index      Next     

Sun logo
Sun ONE Directory Server Resource Kit 5.2 Tools Reference 

Chapter 7
The ldapcmp Tool

The ldapcmp tool compares the contents of a single Lightweight Directory Access Protocol (LDAP) entry (or an entire LDAP subtree) that is present in two directories. It detects entries that do not appear in both directories and the attribute differences in those that do. This chapter provides instructions on how to use the ldapcmp tool. It contains the following sections:


The ldapcmp tool compares parallel entries or subtrees stored in two different directories. It detects entries that do not appear in both directories and attribute differences in entries that do appear in both directories.

ldapcmp 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.


To compare one attribute value with the same attribute’s value in one or more entries of a directory, use the ldapcompare tool described in Chapter 6, "The ldapcompare Tool."

Command Usage

Each ldapcmp search returns all attributes for all entries in the given scope of the given base distinguished name (DN). The ldapcmp tool then compares these search results and reports the differences as in Table 7-1.

Table 7-1  How ldapcmp Reports Comparision Results 

Comparison Result

How It Appears

Entries that only appear in the first directory

1only: DN

Entries that only appear in the second directory

2only: DN

Entries whose DN appears in both directories but whose attributes or attribute values are different

matchingDN different: missingAttributeName 1 or 2: attributeValueWherePresent different: differingAttributeName 1: valueInDirectory1 2: valueInDirectory2

ldapcmp supports the common options of the Lightweight Directory Access Protocol (LDAP) commands, such as managing referrals, handling locales, and providing SSL-based security.


The syntax of the ldapcmp tool on the command-line takes the following form:

ldapcmp -h host1 -p port1 [ -h host2 -p port2 ] -b "baseDN" [ options ]



The ldapcmp tool has three types of options:

The following sections detail these options. The ldapmodify -H command and option when run on the command-line will display text that briefly describes all of the command-line options.


The common options listed in Table 7-2 control the binding and general behavior of the ldapcmp command.

Table 7-2  Common Options for ldapcmp 






Specify the hostname of a directory server. This option may be given twice to specify the two target directories for the comparison. If it is only given once, the default for the second host is localhost. If it is not specified at all, the default is localhost for both.



Specify the port number for accessing a directory server host. This option may be given twice to specify the port for each directory server. When either occurrence is omitted, the default is 389 normally and 636 when the SSL options are used. Note that the first occurrence of this option specifies the port for the first host, even if it appears after the second hostname on the command-line.



Specify a bind DN for accessing both directories, 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 and attributes will appear in the comparison results, according to the DN’s search 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 in the terminal window. 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.



Specify the base DN for the comparison, usually in double quotes ("") for the shell. You may omit this option if you specify the base DN in the LDAP_BASEDN environment variable.



Specify the scope of the comparison. Use this option to restrict the number of entries being compared. The scope parameter may have one of the following values:

  • base - For comparing only the base entry.
  • one  - For comparing only the children of the base entry.
  • sub  - For comparing the base entry and all its descendants. This is the default if the -s option is omitted.



Specify the LDAP protocol version number to be used for search operations, 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 search operations, 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 part of the comparison searches, return 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 when performing comparison searches.



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



Verbose output mode: the tool will display additional information about binding to the directory servers, searching the two directories, and comparing the search results.



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



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 given in Table 7-3 control how the ldapcmp results are sorted and presented.

Table 7-3  Input and Output Options for ldapcmp 






Specify the character set to use for the -f LDIFfile or standard input. The default is the character set specified in the LANG environment variable. You might want to use this option to perform the conversion from the specified character set to UTF8, thus overriding the LANG setting.



Specify the path to a directory containing conversion routines. These routines are used if you wish to specify a sorting language 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.

SSL (Secure Socket Layer) Options

The options in Table 7-4 allow you to use LDAPS (LDAP over SSL) to establish a secure connection for the update operation. These options are valid only when LDAPS has been enabled 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.

Table 7-4  SSL Options for ldapcmp 






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 certification 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". Both of the directory servers must recognize this certificate to perform the comparison.



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 ldapcmp 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_search_ext(), and ldap_result(). These functions return both client-side and server-side errors and codes. Table 7-5 shows the possible return values when the directory is 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. For further information about result codes, see the Sun ONE LDAP SDK for C Programming Guide.

Table 7-5  Return Values of ldapcmp 

Return Value

Result Code
and Explanation

  0 (0x00)

LDAP_SUCCESS: the operation was successful.

  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.

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 both Directory Servers and if no referral URLs are available.

50 (0x32)

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

81 (0x51)

LDAP_SERVER_DOWN: either of the LDAP servers did not respond to the comparison search or a connection was lost.

82 (0x52)

LDAP_LOCAL_ERROR: an error occurred when receiving the results from either 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 either 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 examples in this section demonstrate common uses of the ldapcmp tool. All examples assume the following context:

Comparing Two Directories

By specifying the root DN as the base DN, ldapcmp will search all entries of both directories. The output of the following command will show you all differences between the directories’ contents:

$ ldapcmp -h host1 -h host2 -b "dc=company,dc=com"

You should have some idea of the size and differences between your directories before comparing them. Comparing two directories is useful for finding small difference between directories. This output though will be very large and not very helpful if all entries are completely different. The comparison can be narrowed here by specifying the base DN of a similar subtree in both directories.

Comparing Two Entries

The ldapcmp tool can also be used to compare single entries. This operation is much quicker than comparing a subtree because the searches are faster and only a single comparison needs to be performed. The following command uses the DN of the comparative entry as the base DN on the command-line:

$ ldapcmp -h host1 -h host2 -s base \
             -b "cn=Pete Minsky,ou=People,dc=company,dc=com"


To simplify the command-line, you can set the base DN using the LDAP_BASEDN environment variable. Doing this allows you to avoid specifying the search base with the -b option every time you use the ldapcmp tool.


For information on how to set environment variables, see the documentation for your operating environment.

Assuming LDAP_BASEDN is set to dc=company,dc=com., the following command will compare your directories on two different hosts:

$ ldapcmp -v -h host1 -h host2

Specifying the -v option for verbose output is helpful because the base DN being used will be displayed in the output for verification.

Comparing Directory Configurations

Directory Server configuration information is stored as entries in the directory itself. You may use the ldapcmp tool to compare how each of your servers is configured. The following command-line will compare the root DSE of two Directory Servers:

$ ldapcmp -h host1 -h host2 -b ""

Because some configuration information is host- and directory-specific, the previous command will always display some differences.

Another source of configuration information is the schema used by your directories. The following command will compare two directory schemas:

$ ldapcmp -h host1 -h host2 -b "cn=schema"

Schemas can be very large, and comparisons between them are useful only if they are known to have small differences. For example, you can see if a master schema has been customized in different ways for separate directories.

Previous      Contents      Index      Next     

Copyright 2004 Sun Microsystems, Inc. All rights reserved.