|
| |
| Sun ONE Directory Server Resource Kit 5.2 Tools Reference | |
Chapter 6
The ldapcompare ToolThe 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:
OverviewThe 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.
Tip
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.
Caution
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 Usageldapcompare 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.
Syntax
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 ]
Where:
- options are the command-line options described in Options.
- attribute is the type name of the attribute, followed by one of the three ways to specify its comparative value. The attribute type name and value string should be enclosed in single quotes (‘’) for the shell.
- targetDN is the distinguished name (DN) or list of DNs in which to search for the given attribute and compare its value.
- DNfile is a file with a list of DNs, one per line, to search for the given attribute and compare its value.
Options
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
Option
Parameter
Purpose
-h
hostname
Specify the hostname of the directory server. When this option is omitted, the default is localhost.
-p
port
Specify the port number for accessing the directory server host. The default is 389 normally and 636 when the SSL options are used.
-D
bindDN
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.
-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. 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.
-f
DNfile
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.
-V
version
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.
-Y
proxyDN
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.
-M
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.
-O
hopLimit
(Capital letter O) Specify the maximum number of referral hops to follow while finding an entry to compare. By default, there is no limit.
-R
Specify that referrals should not be followed. By default, referrals are followed automatically.
-v
Verbose output mode: the tool will display additional information about the operations it performs.
-n
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.
-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 listed in Table 6-2 control how ldapcompare processes input files and handles errors.
Table 6-2 Input and Output Options for ldapcompare
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. 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.
-k
path
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.
-c
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.
-q
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.
Note
Only the -P option is required for server authentication. For the more secure client authentication, the -P, -N, -K and -W options are required.
Return ValuesThe 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.
Command-Line ExamplesThe 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 phonebook.example.com ’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 phonebook.example.com -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 phonebook.example.com ’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