Chapter 3   ldapsearch


The ldapsearch tool issues search requests to a directory and displays the result as LDIF text (see Appendix A, "LDAP Data Interchange Format," in the iPlanet Directory Server Administrator's Guide). Its many options allow you to perform different types of search operations, from simple entry retrieval to advanced searches that involve security and that manage LDAP referrals.

The ldapsearch tool is also provided with iPlanet Directory Server in the /usr/iplanet/servers/shared/bin directory. However, iPlanet DSRK and its updates include the latest version of the tool. If you use the Solaris operating environment, you may have an older version of ldapsearch in /usr/bin. Be sure your path is set to use the latest version in /opt/iPlanet/bin/idsrk51.

This chapter contains the following sections:

• Command Usage

• Return Values

• Command-Line Examples

Command Usage

---

A search involves binding and possibly authenticating to the directory server and initiating a search operation with a certain scope from a given base DN. The request includes a filter of the attribute values that must match in the entries returned. The command-line options allow you to sort the results, limit how much information is returned, control how referrals are followed, enable a secure connection, and set a time limit for the operation.

Results are displayed as LDIF text to the standard output. By default, the results contain the DN and all attributes for each entry found by the search. The results may also be reformatted through command-line options.

Syntax

The syntax of the ldapsearch command line has two forms:

ldapsearch -b "baseDN " [ options ]  "filter "  [ attributeName ... ]

ldapsearch -b "baseDN " [ options ]  -f filterFile   [ attributeName ... ]

Where:

• baseDN is the base of the search, 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.

• filter is an RFC 2254-compliant LDAP search filter, usually in double quotes ("") for the shell (see "LDAP Search Filters" in Appendix B of the iPlanet Directory Server Administrator's Guide).

• The filterFile contains one LDAP search filter per line, each one being used for a separate search. You cannot specify a filter on the command line when using the -f option.

• One or more attributeNames specifies the list of attributes and their values to be returned for each entry matching the filter. When the list of attributes is omitted, ldapsearch will return all attributes permitted by the access rights of the bind DN, with the exception of operational attributes.

  If you want to retrieve operational attributes, you must explicitly specify their attributeName . To retrieve all regular attributes in addition to operational attributes, append an asterisk (*) to the attribute list.

The ldapsearch -H command will display a usage text that briefly describes the command-line options.

Options

The ldapsearch command has four types of options:

• Common options.

• Input and output options.

• Options for LDAP controls.

• SSL (Secure Socket Layer) options.

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

Table 3-1    Common Options of the ldapsearch 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, 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 search results, 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.
-b	baseDN	Specify the base DN for the search operation, 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 a search. The scope parameter may have one of the following values: base - For searching only the base entry. one  - For searching only the children of the base entry. sub  - For searching the base entry and all its descendants.       This is the default if the -s option is omitted.
-f	filterFile	Specify the name of a file containing filter strings. A filter file contains one or more filters, each on a separate line: ldapsearch will perform a separate search with each filter, in the order found in the file.
-l	seconds	Specify the maximum number of seconds to wait for a search request to complete. Regardless of the value specified here, ldapsearch will never wait longer than is allowed by the server's nsslapd-timelimit attribute, whose default is 3,600 seconds. For more information, see "nsslapd-timelimit (Time Limit)" in the iPlanet Directory Server Command, Configuration and File Reference.
-V	version	Specify the LDAP protocol version number to be used for the search operation, 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 search operation, 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.
-a	aliasMode	Specify how aliases are dereferenced when encountered in a search. The aliasMode parameter may have one of the following values: never  - Aliases are never dereferenced; this is the default. find   - Aliases are dereferenced only while finding the base DN. search - Aliases are dereferenced when searching entries below the         base DN (but not when finding the base DN). always - Aliases are dereferenced both when finding the base DN         and searching beneath it.
-M		Manage smart referrals: when referrals are part of the search results, 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 while searching.
-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 search, such as the filter string and the number of results for each search.
-n		No-op mode: use with the -v option to show what the tool would do with the given input but do not actually perform the search.
-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 ldapsearch results are sorted and presented.

Table 3-2    Input and Output Options of the ldapsearch 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, base DN, and the search filter pattern in the specified character set. The ldapsearch tool converts the input from these arguments before it processes the search request. For example, -i no indicates that the bind DN, base DN, and search filter are provided in Norwegian. This argument only affects the command-line input. If you specify a file containing a search filter (with the -f option), ldapsearch will not convert the data in the file.
-k	path	Specify the path to a directory containing conversion routines. Use these routines 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.
-S	[-]attribute	Specify an attribute for sorting the entries returned by the search. The sort criteria is alphabetical on the attribute's value or reverse alphabetical with the form -attribute . You may give multiple -S options to refine the sorting, for example: -S sn -S givenname. By default, the entries are not sorted. Use the -x option described in Table 3-3 to perform server-side sorting.
-z	max	Specify the maximum number of entries to return in response to a search request. Regardless of the value specified here, ldapsearch will never return more entries than the number allowed by the directory server's nsslapd-sizelimit attribute whose default is 2,000 entries. See "nsslapd-sizelimit (Size Limit)" in the iPlanet Directory Server Command, Configuration and File Reference. This limitation does not apply if you bind as the root DN (with -D "cn=directory manager"), in which case this option defaults to 0 (zero) and the size limit attribute is overridden.
-A		Specify that the search retrieve only attribute names, not the attribute values. This option is useful if you just want to determine if an attribute is present for an entry.
-1		Omit the leading "version: 1" line in the LDIF output.
-u		User-friendly DNs: specify that this alternate form of the DN also be included in the output of a search result entry, in addition to the complete form that is always displayed.
-t		Temporary file output: each attribute of each entry in the search results will be written to a separate file in the system's temporary directory (usually /tmp). The standard output of the tool will include the name of the file instead of the attribute's value. When using this option, no base-64 encoding is performed on the values, regardless of the content.
-U		URL format (valid only with the -t option): when using temporary file output, the standard output of the tool will include the URL of the file instead of the attribute's value, for example: jpegPhoto:< file:/tmp/ldapsearch-jpegPhoto-YzaOMh
-T		Format the output of search results so that no line breaks are used within individual attribute values.
-o		Format the output of search results so that no line breaks are used within individual attribute values and that equal signs (=) are used to separate attribute names from values. This argument produces output whose format is not compliant with LDIF.
-F	separator	Format the output of search results so that the given separator is used between attribute names and their values. This option may be used only in conjunction with the -o option.
-B		Format the output of search results to print binary values as they are stored in the directory. When used in conjunction with -o, the binary data in the output will not use base-64 encoding.

The options in the following table provide advanced search controls for server-side sorting, virtual lists, and persistent searches. This functionality is available only if the server supports the corresponding LDAP controls. These options will also display any additional information that the server sends in response to the control.

Table 3-3    Options for LDAP Controls Using the ldapsearch Command 

Option	Parameter	Purpose
-x		Use with the -S option to specify that search results be sorted on the server rather than by the ldapsearch command running on the client. This is useful if you want to sort according to a matching rule, as with an international search. It is usually faster to sort on the server, if that is supported, rather than on the client.
-C	pattern	Persistent search: perform a search that keeps the connection open and displays results whenever entries matching the scope and filter of the search are added, modified, or removed. With this option, the ldapsearch tool will run indefinitely, and you must type Control-C to stop it. The pattern has the following format:     ps:changeType [:changesOnly [:entryChangeControls ]] The changeType determines which modifications to an entry are detected and displayed in the output. Its possible values are add, delete, modify, moddn, or any. The changesOnly parameter is an optional boolean value: specify 0, f, or false to display the results of the search before waiting for changes. The default is 1: only changes will be displayed when they occur. By default, the tool will instruct the server to return entry change controls with the persistent search results. These controls indicate the type of operation that caused the entry to be detected by the search. The entryChangeControls parameter is also an optional boolean value: specify 0, f, or false if you do not want the server to return entry change controls. In this case, you must also specify a value for the changesOnly parameter.
-G	pattern	Virtual list view: retrieve only a portion of all results, as determined by the index or value of the search target and the number of entries to be returned before and after the target. This option always requires the -S and -x options to specify the sorting order on the server. The pattern has two possible formats: entriesBefore :entriesAfter :value - Specify the search target as the first entry in the sorted results for which the sort attribute is "greater than" or equal to the given value . For example, -S sn -x -G 5:10:johnson will return 16 entries in alphabetical order of the surname attribute: 5 less than johnson, the entry equal to or following johnson, and the 10 subsequent entries. entriesBefore :entriesAfter :index :count - Specify the search target as the index position relative to the estimated count . If the count is 0 (zero), the index is taken as the absolute index of the target entry within the actual number of entries found. An index of 1 will always select the first entry in the sorted list of results. Otherwise, the target index is the first entry in slice of the list represented by the fraction index /count . For example, -G 5:10:2:4 specifies the index closest to the beginning of the second quarter of the entire list. If the search yielded 100 entries, the target index would be 26, and this pattern would return entries 21 through 36. Give an index greater than the count to specify the last search result in the list. The number of entriesBefore and entriesAfter that are displayed may be limited by the beginning and end of the virtual list. After the results, ldapsearch will display the control response that gives the total count of entries in the virtual list and the actual index of the target entry. Use these values to refine the search with more accurate index and count parameters.

The SSL (Secure Socket Layer) options allow you to use LDAPS (LDAP over SSL) to establish a secure connection for the search. 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.

The SSL options are listed in the following table. See "Using Authentication" for examples using the SSL options.

Table 3-4    SSL Options of the ldapsearch 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 ldapsearch 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 directory is hosted on iPlanet Directory Server. Other LDAP servers may send these values under different circumstances or may send different values. The directory server responding to the ldapsearch 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 3-5    Return Values of the ldapsearch 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 search request did not comply with the LDAP protocol. The Directory Server may send this error code if it could not sort the search results or could not send sorted results.
3 (0x03)	LDAP_TIMELIMIT_EXCEEDED: sent by the Directory Server if the search exceeded the maximum time specified by the -l option.
4 (0x04)	LDAP_SIZELIMIT_EXCEEDED: sent by the Directory Server if the search found more results than the maximum number of results specified by the -z option.
10 (0x0a)	LDAP_REFERRAL: sent by the Directory Server if the given base DN is an entry not handled by the current 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 the 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.
21 (0x15)	LDAP_INVALID_SYNTAX: sent by the Directory Server if your substring filter contains no value for comparison.
32 (0x20)	LDAP_NO_SUCH_OBJECT: sent by the Directory Server if the given base DN does not exist 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.
53 (0x35)	LDAP_UNWILLING_TO_PERFORM: sent by the Directory Server if the database is read-only.
81 (0x51)	LDAP_SERVER_DOWN: the LDAP server did not receive the request or the connection to the server 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.
85 (0x55)	LDAP_TIMEOUT: the search exceeded the time specified by the -l option.
87 (0x57)	LDAP_FILTER_ERROR: an error occurred when parsing and BER-encoding a search filter specified on the command line or in a filter file.
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: the 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 ldapsearch tool to access a directory. All examples assume the following context:

• You want to perform a search of all entries in the directory.

• All entries in directory 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 server is located on a machine with the given hostname .

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

• SSL is enabled for the server on port 636 (the default SSL port number).

Returning All Entries

Given the context, the following command will return all entries in the directory:

$ ldapsearch -h hostname -b "dc=siroe,dc=com" -s sub \
             "objectclass=*"

The "objectclass=*" parameter is a search filter that matches any entry in the directory. The scope is set to the full subtree of the base DN (-s sub), and no attribute list is given, so all attributes for all entries will be returned.

Narrowing a Search

To narrow a search, specify a search filter enclosed in quotation marks directly on the command line. Then, you can ask to receive only those attributes that you need. For example:

$ ldapsearch -h hostname -b "dc=siroe,dc=com" \
             "cn=babs jensen" mail telephonenumber

In this example, the search will return only the mail and telephonenumber attributes of all entries with a common name (cn) that matches "babs jensen" exactly.

Searching the Root DSE Entry

The root DSE is a special entry that contains a list of all the suffixes supported by the local directory server. You can view this entry by performing a search with an empty search base (-b ""). You must also specify a search scope of base and a filter of "objectclass=*", as follows:

$ ldapsearch -h hostname -b "" -s base "objectclass=*"

Searching the Schema Entry

iPlanet Directory Server stores all directory server schema in the special entry with the DN "cn=schema". This entry contains information on every object class and attribute defined for your directory server.

You can examine the contents of this entry as follows:

$ ldapsearch -h hostname -b "cn=schema" -s base "objectclass=*"

Using LDAP_BASEDN

To make searching easier, you can set your search base 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 ldapsearch tool. For information on how to set environment variables, see the documentation for your operating environment.

Typically, you set LDAP_BASEDN to your directory's root suffix value. Because the root suffix is the topmost entry in your directory, all searches will be able to scan the entire directory tree. For example, suppose you have set LDAP_BASEDN to dc=siroe,dc=com. Then, to search for cn=babs jensen in your directory, use the following command line:

$ ldapsearch -h hostname "cn=babs jensen"

In this example, the default scope is sub because the -s option was not used to specify the scope explicitly.

Using a Filter File

You can store search filters in a file instead of entering them on the command line. When creating a filter file, specify each search filter on a separate line. The ldapsearch command runs a separate search with each filter in the order in which the filters appear in the file. This example uses a file named myFilters that contains the following lines:

sn=Francis
givenname=Richard

Suppose search base is defined by the LDAP_BASEDN environment variable, then the following command returns all the entries that match either search filter:

$ ldapsearch -h hostname -f myFilters

In the output, ldapsearch first displays all the entries with the surname Francis, and then all the entries with the given name Richard. The two searches are independent, so an entry that matches both search criteria will be returned twice.

You can limit the set of attributes returned by specifying the attribute names that you want at the end of the search line. For example, the following ldapsearch command performs both searches, but returns only the surname and the given name attributes of each entry:

$ ldapsearch -h hostname -f myFilters sn givenname

Specifying Commas in Filters

When a DN within a search filter contains a comma as part of its value, you must escape the comma with a backslash (\). For example, to find everyone in the "Siroe Bolivia, S.A." subtree of the directory, use the following command:

$ ldapsearch -h hostname \
             -b "o=Siroe Bolivia\, S.A.,dc=siroe,dc=com" \
             "objectclass=*"

Using Authentication

There are two levels of authentication that the directory server may enforce with clients such as the ldapsearch tool: server authentication and client authentication. In server authentication, the server accepts connections only from clients that have a trusted certificate. In the stronger client authentication the client must sign the certificate with a password-protected private key.

To perform a search with server authentication, give only the -P SSL option on the command line, in addition to other common options. For example:

$ ldapsearch -h hostname -p 636 -b "dc=siroe,dc=com" \
             -D "uid=bjensen,dc=siroe,dc=com" -w bindPassword \
             -P /home/bjensen/certs/cert.db \
             "givenname=Richard"

To perform a search with client authentication, you must give all SSL options on the command line, in addition to other common options. However, do not use the -D and -w options with client authentication, otherwise the bind operation will use the authentication credentials specified with -D and -w instead of the certificate credentials. For example:

$ ldapsearch -h hostname -p 636 -b "dc=siroe,dc=com" \
             -Z -P /home/bjensen/security/cert.db -N "bjscert" \
             -K /home/bjensen/security/key.db -W KeyPassword \
             "givenname=Richard"

In either case, use the -p option to specify your directory server's SSL port. All non-SSL options retain their original meaning and may be used as necessary.