B.2. Using ldapsearch

B.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/lib/mozldap directory for Red Hat Enterprise Linux i386, in the /usr/lib64/mozldap directory on 64-bit versions of Red Hat Enterprise Linux and Solaris, and in the /opt/dirsrv/bin/mozldap/ directory on HP-UX. 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:

B.2.1. 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.

B.2.2. ldapsearch Command-Line Format

The ldapsearch command must use the following format:

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 B.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 B.2.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.

B.2.3. 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 mozilla. If a host is not specified, ldapsearch uses the localhost.
-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, Command, and File Reference.

B.2.4. ldapsearch Examples

The next set of examples assumes the following:

  • The search is for all entries in the directory.

  • The directory is configured to support anonymous access for search and read. This means that no bind information has to be supplied in order to perform the search. For more information on anonymous access, see Section 6.4.2, “Defining User Access - userdn Keyword”.

  • The server is located on a host named mozilla.

  • The server uses port number 389. Since this is the default port, the port number does not have to be sent in the search request.

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

  • The suffix under which all data is stored is dc=example,dc=com.

B.2.4.1. Returning All Entries

Given the previous information, the following call will return all entries in the directory (subject to the configured size and time resource limits):

ldapsearch -h mozilla -b "dc=example,dc=com" -s sub "objectclass=*"

"objectclass=*" is a search filter that matches any entry in the directory. Since every entry must have an object class, and the objectclass attribute is always indexed, this is a useful search filter to return every entry.

B.2.4.2. Specifying Search Filters on the Command Line

A search filter can be specified directly on the command line as long as the filter is enclosed in quotation marks ("filter"). If the filter is supplied with the command, do not specify the -f option. For example:

ldapsearch -h mozilla -b "dc=example,dc=com" "cn=babs jensen"

B.2.4.3. 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. This entry can be searched by supplying a search base of "", a search scope of base, and a filter of "objectclass=*". For example:

ldapsearch -h mozilla -b "" -s base "objectclass=*"

B.2.4.4. Searching the Schema Entry

Directory Server stores all directory server schema in the special cn=schema entry. This entry contains information on every object class and attribute defined for the Directory Server. The following command searches the contents of the cn=schema entry:

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

B.2.4.5. Using LDAP_BASEDN

To make searching easier, it is possible to set the search base using the LDAP_BASEDN environment variable. Doing this means that the search base does not have to be set with the -b option. For information on how to set environment variables, see the documentation for the operating system.

Typically, set LDAP_BASEDN to the directory's suffix value. Since the directory suffix is equal to the root, or topmost, entry in the directory, this causes all searches to begin from the directory's root entry.

For example, suppose LDAP_BASEDN is set to dc=example,dc=com. Then to search for cn=babs jensen in the directory, use the following command-line call:

ldapsearch -h mozilla "cn=babs jensen"

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

B.2.4.6. Displaying Subsets of Attributes

The ldapsearch command returns all search results in LDIF format. By default, ldapsearch returns the entry's distinguished name and all of the attributes that a user is allowed to read. The directory access control can be set such that users are allowed to read only a subset of the attributes on any given directory entry. Only operational attributes are not returned. For operational attributes to be returned as a result of a search operation, explicitly specify them in the search command.

It may not be necessary to have all of the attributes for an entry returned in the search results. The returned attributes can be limited to just a few specific attributes by specifying the desired ones on the command line immediately after the search filter. For example, to show the cn and sn attributes for every entry in the directory, use the following command-line call:

ldapsearch -h mozilla "objectclass=*" sn cn

This example assumes the search base is set with LDAP_BASEDN.

B.2.4.7. Specifying Search Filters Using a File

Search filters can be entered into a file instead of entering them on the command-line. In this case, specify each search filter on a separate line in the file. The ldapsearch command runs each search in the order in which it appears in the file.

For example:

sn=Francis
givenname=Richard

ldapsearch first finds all the entries with the surname Francis, then all the entries with the givenname Richard. If an entry is found that matches both search criteria, then the entry is returned twice.

For example, suppose the previous search filters were specified in a file named searchdb, and the search base is set using LDAP_BASEDN. Then the following returns all the entries that match either search filter:

ldapsearch -h mozilla -f searchdb

The set of attributes returned here can be limited by specifying the attribute names at the end of the search line. For example, the following ldapsearch command performs both searches but returns only the DN and the givenname and sn attributes of each entry:

ldapsearch -h mozilla -f searchdb sn givenname

B.2.4.8. Specifying DNs That Contain Commas in Search Filters

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

ldapsearch -h mozilla -s base -b "l=Bolivia\,S.A.,dc=example,dc=com" "objectclass=*"

B.2.4.9. Using Client Authentication When Searching

This example shows user bjensen searching the directory using client authentication:

ldapsearch -h mozilla -p 636 -b "dc=example,dc=com" -N "bjensenscertname" 
     -Z -W certdbpassword -P /home/bjensen/certdb/cert8.db "givenname=Richard"

Note: This documentation is provided {and copyrighted} by Red Hat®, Inc. and is released via the Open Publication License. The copyright holder has added the further requirement that Distribution of substantively modified versions of this document is prohibited without the explicit permission of the copyright holder. The CentOS project redistributes these original works (in their unmodified form) as a reference for CentOS-5 because CentOS-5 is built from publicly available, open source SRPMS. The documentation is unmodified to be compliant with upstream distribution policy. Neither CentOS-5 nor the CentOS Project are in any way affiliated with or sponsored by Red Hat®, Inc.