8.2. Using ldapsearch

The ldapsearch command-line utility can locate and retrieve directory entries. This utility opens a connection to the specified server using the specified distinguished name and password and locates entries based on a specified search filter. The search scope can include a single entry, an entry's immediate subentries, or an entire tree or subtree.
Search results are returned in LDIF format.
Red Hat Directory Server uses Mozilla LDAP tools, including ldapsearch. The MozLDAP tools are installed with Directory Server and are located in the /usr/lib64/mozldap directory for Red Hat Enterprise Linux 5 (64-bit), and in the /usr/lib/mozldap directory on Red Hat Enterprise Linux 5 (32-bit). When running any LDAP command, make sure to use the MozLDAP utilities, otherwise the command will return errors.

NOTE

For most Linux systems, OpenLDAP tools are already installed in the /usr/bin/ directory. These OpenLDAP tools will not work for Directory Server operations.
This section contains information about the following topics:

8.2.1. ldapsearch Command-Line Format

The ldapsearch command must use the following format:
/usr/lib64/mozldap/ldapsearch [optional_options] [optional_search_filter] [optional_list_of_attributes]
  • optional_options is a series of command-line options. These must be specified before the search filter, if any are used.
  • optional_search_filter is an LDAP search filter as described in Section 8.3, “LDAP Search Filters”. Do not specify a separate search filter if search filters are specified in a file using the -f option.
  • optional_list_of_attributes is a list of attributes separated by a space. Specifying a list of attributes reduces the number of attributes returned in the search results. This list of attributes must appear after the search filter. For an example, see Section 8.4.6, “Displaying Subsets of Attributes”. If a list of attributes is not specified, the search returns values for all attributes permitted by the access control set in the directory (with the exception of operational attributes).

    NOTE

    For operational attributes to be returned as a result of a search operation, they must be explicitly specified in the search command. To retrieve regular attributes in addition to explicitly specified operational attributes, use an asterisk (*) in the list of attributes in the ldapsearch command. To retrieve no attributes, just a list of the matching DNs, use the special attribute 1.1. This is useful, for example, to get a list of DNs to pass to the ldapdelete command.

8.2.2. Commonly Used ldapsearch Options

The following table lists the most commonly used ldapsearch command-line options. If a specified value contains a space ( ), the value should be surrounded by single or double quotation marks, such as -b "ou=groups,dc=example,dc=com".
Option Description
-b Specifies the starting point for the search. The value specified here must be a distinguished name that currently exists in the database. This is optional if the LDAP_BASEDN environment variable has been set to a base DN. The value specified in this option should be provided in single or double quotation marks. For example:
-b "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"
To search the root DSE entry, specify an empty string here, such as -b "" .
-D Specifies the distinguished name with which to authenticate to the server. This is optional if anonymous access is supported by the server. If specified, this value must be a DN recognized by the Directory Server, and it must also have the authority to search for the entries. For example, -D "uid=bjensen,dc=example,dc=com".
-h Specifies the hostname or IP address of the machine on which the Directory Server is installed. For example, -h server.example.com. If a host is not specified, ldapsearch uses the localhost.

NOTE

Directory Server supports both IPv4 and IPv6 IP addresses.
-l Specifies the maximum number of seconds to wait for a search request to complete. For example, -l 300. The default value for the nsslapd-timelimit attribute is 3600 seconds. Regardless of the value specified, ldapsearch will never wait longer than is allowed by the server's nsslapd-timelimit attribute.
-p Specifies the TCP port number that the Directory Server uses. For example, -p 1049. The default is 389. If -Z is used, the default is 636.
-s Specifies the scope of the search. The scope can be one of the following:
base searches only the entry specified in the -b option or defined by the LDAP_BASEDN environment variable.
one searches only the immediate children of the entry specified in the -b option. Only the children are searched; the actual entry specified in the -b option is not searched.
sub searches the entry specified in the -b option and all of its descendants; that is, perform a subtree search starting at the point identified in the -b option. This is the default.
-w Gives the password associated with the distinguished name that is specified in the -D option. If this option is not specified, anonymous access is used. For example, -w diner892.
-x Specifies that the search results are sorted on the server rather than on the client. This is useful for sorting according to a matching rule, as with an international search. In general, it is faster to sort on the server rather than on the client.
-z Sets the maximum number of entries to return in response to a search request. For example, -z 1000. Normally, regardless of the value specified here, ldapsearch never returns more entries than the number allowed by the server's nsslapd-sizelimit attribute. However, this limitation can be overridden by binding as the root DN when using this command-line argument. When binding as the root DN, this option defaults to zero (0). The default value for the nsslapd-sizelimit attribute is 2000 entries.
For detailed information on all ldapsearch utility options, refer to the Directory Server Configuration and Command-Line Tool Reference.

8.2.3. Using Special Characters

When using the ldapsearch command-line utility, it may be necessary to specify values that contain characters that have special meaning to the command-line interpreter, such as space ( ), asterisk (*), or backslash (\). Enclose the value which has the special character in quotation marks (""). For example:
-D "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"
Depending on the command-line interpreter, use either single or double quotation marks. In general, use single quotation marks (') to enclose values. Use double quotation marks (") to allow variable interpolation if there are shell variables. Refer to the operating system documentation for more information.