|
| |
| Sun ONE Directory Server Resource Kit 5.2 Tools Reference | |
Chapter 7
The ldapcmp ToolThe 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:
OverviewThe 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.
Note
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 UsageEach 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.
ldapcmp supports the common options of the Lightweight Directory Access Protocol (LDAP) commands, such as managing referrals, handling locales, and providing SSL-based security.
Syntax
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 ]
Where:
- host1, port1, host2, port2 are the hostnames and port numbers for 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.
- baseDN is the base for 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 Options.
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.
CommonOptions
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
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:
-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 Sun ONE Directory Server Administration 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 “Creating Smart Referrals” in Chapter 2 of the Sun ONE Directory Server Administration 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 Sun ONE LDAP SDK for C Programming Guide.)
-H
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
Option
Parameter
Purpose
-i
locale
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.
-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 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.
Return ValuesThe 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.
Command-Line ExamplesThe examples in this section demonstrate common uses of the ldapcmp tool. All examples assume the following context:
- All entries in the directories are stored under dc=company,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 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"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.
Note
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.