Chapter 7   ldapcmp


The ldapcmp tool compares the contents of a single entry or of an entire subtree that is present in two directories. It detects entries that do not appear in both directories and any difference between attributes in those that do. This tool supports the common options of the LDAP commands, such as managing referrals, handling locales, and providing SSL-based security.

This chapter contains the following sections:

• Command Usage

• Return Values

• Command-Line Examples

Command Usage

---

A comparison involves performing a search operation on both directories and analyzing the differences in the results. Each search returns all attributes for all entries in the given scope of the given base DN. The ldapcmp tool then compares these search results and reports the following differences in its output:

• 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

Syntax

The ldapcmp command has the following syntax:

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

Where:

• host1, port1, host2, port2 are the hostnames and port numbers for accessing the two directories you wish to compare. The first host and port correspond to directory 1 in the output, the second to directory 2. If the second host and port are omitted, port 389 on the localhost will be used by default for directory 2.

• baseDN is the base of the comparison, usually enclosed in double quotes ("") for the shell. The -b baseDN parameter may be omitted if the LDAP_BASEDN environment variable is set.

• options are the command-line options and their parameters described in the next section. Except for the host and port options, all other options must apply to both directories being compared. For example, both directory servers must accept the same certificate when using the security options.

The ldapcmp -H command will display a usage help text that briefly describes all options.

Options

The ldapcmp command has three types of options:

• Common options.

• Input and output options.

• SSL (Secure Socket Layer) options.

The common options listed in the following table control the binding and general behavior of the ldapcmp command.

Table 7-1    Common Options of the ldapcmp Command 

Option	Parameter	Purpose
-h	hostname	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.
-p	port	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.
-D	bindDN	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.
-w	password	Specify the password for the bind DN. CAUTION: Specifying the password on the command line is a possible security risk.
-w	-	Type the password for the bind DN when prompted in the terminal window. This is the most secure way of specifying the password.
-j	filename	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.
-b	baseDN	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.
-s	scope	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.
-V	version	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.
-Y	proxyDN	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 iPlanet Directory Server Administrator's Guide.
-M		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 "Smart Referrals" in Chapter 5 of the iPlanet Directory Server Deployment Guide.
-O	hopLimit	(Capital letter O) Specify the maximum number of referral hops to follow when performing comparison searches.
-R		Specify that referrals should not be followed. By default, referrals are followed automatically during comparison searches.
-v		Verbose output mode: the tool will display additional information about binding to the directory servers, searching the two directories, and comparing the search results.
-n		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.
-0 (zero)		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 iPlanet LDAP SDK for C Programming Guide).
-H		Display the usage help text that briefly describes all options.

The input and output options given in the following table control how the ldapcmp results are sorted and presented.

Table 7-2    Input and Output Options of the ldapcmp Command 

Option	Parameter	Purpose
-i	locale	Specify the character set to use for command-line 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. Using this argument, you can input the bind DN in the specified character set. The ldapcmp tool converts the input from these arguments before it processes the search request. For example, -i no indicates that the bind DN and attribute names are provided in Norwegian.
-k	path	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 "Searching an Internationalized Directory" in Appendix B of the iPlanet Directory Server Administrator's Guide.

The SSL (Secure Socket Layer) options listed in the following table allow you to use LDAPS (LDAP over SSL) to establish secure connections for the comparison. 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, "Managing SSL" in the iPlanet Directory Server Administrator's Guide.

Table 7-3    SSL Options of the ldapcmp Command 

Option	Parameter	Purpose
-P	path	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.
-Z		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.
-N	certificate	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.
-m	path	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.
-K	keyFile	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.
-W	password	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 iPlanet 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.

The following table shows the possible return values when the directories are hosted on iPlanet Directory Servers. Other LDAP servers may send these values under different circumstances or may send different values. The directory servers responding to the ldapcmp tool may also send other result codes in addition to those described here, for example, custom result codes from a custom plug-in.

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

Table 7-4    Return Values of the ldapcmp Command 

Return Value	Result Code and Explanation
0 (0x00)	LDAP_SUCCESS: the operation was successful.
1 (0x01)	LDAP_OPERATIONS_ERROR: sent by the Directory Server for general errors encountered by the server when processing the request.
2 (0x02)	LDAP_PROTOCOL_ERROR: the 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 the Directory Server if a comparison search exceeded the default time limit for an operation on the server.
4 (0x04)	LDAP_SIZELIMIT_EXCEEDED: sent by the Directory Server if a comparison search found more results than the default maximum allowed by the server.
10 (0x0a)	LDAP_REFERRAL: sent by the 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 the 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 the 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 to compare two directories. All examples assume the following context:

• All entries in the directories are stored under dc=siroe,dc=com.

• The directory server has been configured to support anonymous access for search and read. Therefore, you do not have to specify any bind information in order to perform the search.

• The servers are located on the machines named host1 and host2 .

• The servers both use port number 389. Because this is the default port, you do not have to specify the port number on the search request.

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 directory contents:

$ ldapcmp -h host1 -h host2 -b "dc=siroe,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. The output will be very large and not very helpful if all entries are completely different. In this case, narrow the comparison by specifying the base DN of a similar subtree in both directories.

Comparing 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. If you know the DN of the entry to compare, use it as the base DN on the command line, for example:

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

Using LDAP_BASEDN

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

For example, suppose you have set LDAP_BASEDN to dc=siroe,dc=com. Then to compare your directories on two different hosts, use the following command:

$ 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

The Directory Server configuration information is stored as entries in the directory, and you may use the ldapcmp tool to compare how your Directory Servers are configured. The following command line will compare the root DSE of two Directory Servers, such as the extensions and controls they support:

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