Chapter 6
ldapcompare
The ldapcompare tool compares an attribute value given on the command line with the contents of a given directory entry. It compares either a textual value or a binary value, thus providing a simple interface to check data against directory contents. This tool supports the common options of the LDAP commands, such as managing referrals, handling locales, and providing SSL-based security.
To compare the contents of two directories, use ldapcmp described in Chapter 7.
This chapter contains the following sections:
Command Usage
The ldapcompare tool compares one attribute value given on the command line with the same attribute's value in one or more entries of a directory. Standard, textual values are entered directly on the command line. Binary attribute values may either be given on the command line with base-64 encoding or stored in a file referenced by the URL syntax.
The tool will compare this attribute value to that of each DN given on the command line or in a separate file. By default, it will print out the success or failure of the comparison and stop after the first failed comparison. Use the command-line options to control this behavior and other aspects of the input and output.
The return values are the standard return codes of the iPlanet LDAP SDK for C, including LDAP_COMPARE_FALSE (decimal 5), LDAP_COMPARE_TRUE (decimal 6), and any others for various errors that may be encountered.
Syntax
The ldapcompare command has the following syntax:
-
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 the next section.
attribute
is the type name of the attribute, followed by one of the three ways of specifying its value to compare. The attribute type name and value string should be enclosed in single quotes ('') for the shell.
targetDN
is the DN or list of DNs in which to search for the given attribute and compare its value.
DNfile
is a list of DNs, one per line, to search for the given attribute and compare its value.
The ldapcompare -H command will display a usage help text that briefly describes the command syntax, options, and parameters.
Options
The ldapcompare 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 ldapcompare command.
Table 6-1 Common Options of the ldapcompare Command
|
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 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.
|
|
-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 iPlanet Directory Server Administrator's 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 "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 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 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 ldapcompare processes input files and handles errors.
Table 6-2 Input and Output Options of the ldapcompare 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 and the target DNs in the specified character set. The ldapcompare tool converts the input from these arguments before it processes the search request. For example, -i no indicates that the bind DN and target DNs are provided in Norwegian.
This option affects only the command-line input, that is, if you specify a file containing DNs (with the -f option), ldapcompare will not convert the data in the file.
|
|
-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 "Searching an Internationalized Directory" in Appendix B of the iPlanet Directory Server Administrator's Guide.
|
|
-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.
|
The SSL (Secure Socket Layer) options listed in the following table 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, "Managing SSL" in the iPlanet Directory Server Administrator's 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 of the ldapcompare 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 authentication 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".
|
|
-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 ldapcompare 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_compare_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 ldapcompare tool may also send other result codes in addition to those described here, for example, custom result codes from a custom plug-in.
Under most conditions, the ldapcompare tool returns one of the following integer values:
For further information about result codes, see the iPlanet LDAP SDK for C Programming Guide.
Table 6-4 Return Values of the ldapcompare Command
|
Return Value
|
Result Code
and Explanation
|
|
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.
|
|
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 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 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. In these sample command lines, the directory server port is assumed to be 389 which is the default when the -p option is omitted. The bind DN and password for simple authentication are also omitted, so ldapcompare will use anonymous binding to perform operations.
In the first example, ldapcompare takes a textual value on the command line and compares it to the given attribute in the given DN.
-
% ldapcompare -h phonebook.siroe.com 'givenname:Barbara' \
"uid=bjensen,ou=People,dc=siroe,dc=com"
-
comparing type: "givenname" value: "Barbara" in entry
"uid=bjensen,ou=People,dc=siroe,dc=com"
compare TRUE
In the second example, the value to compare is given directly in base-64 binary encoding. This allows you to compare binary values from some other output, for example in a script. This example also shows the output for multiple entry comparisons, including one which fails for authentication reasons, and using the -c option to ensure all entries are compared.
-
% ldapcompare -h phonebook.siroe.com -c 'cn:: d29vZiAK' \
"uid=tmorgan,ou=People,dc=siroe,dc=com" \
"dc=siroe,dc=com"
-
comparing type: "cn" value: "woof" in entry
"uid=tmorgan,ou=People,dc=siroe,dc=com"
compare FALSE
-
comparing type: "cn" value: "woof" in entry "dc=siroe,dc=com"
ldap_compare: Insufficient access
In the last example, the binary value to compare is a file referenced by a URL.
-
% ldapcompare -h phonebook.siroe.com \
'usercertificate;binary:<file:/tmp/mycert'
"uid=bjensen,ou=People,dc=siroe,dc=com"
-
comparing type: "usercertificate;binary" value: "NOT ASCII
(777 bytes)" in entry "uid=bjensen,ou=People,dc=siroe,dc=com"
compare TRUE