10.3. Using ldapsearch
ldapsearchcommand-line utility can locate and retrieve directory entries. This utility opens a connection to the specified server using the specified identity and credentials and locates entries based on a specified search filter. The search scope can include a single entry (
-s base), an entry's immediate subentries (
-s one), or an entire tree or subtree (
uid=bjensen,ou=People,dc=example,dc=com, then a search for
dc=exampledoes not match that entry unless
dc:examplehas explicitly been added as an attribute in that entry.
10.3.1. ldapsearch Command-Line Format
ldapsearchcommand must use the following format:
ldapsearch [-x | -Y mechanism] [optional_options] [optional_search_filter] [optional_list_of_attributes]
-x(to disable SASL) or
-Y(to set the SASL mechanism) must be used to configure the type of connection.
- 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 10.4, “LDAP Search Filters”. Do not specify a separate search filter if search filters are specified in a file using the
- 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 10.5.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).
NoteFor 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
ldapsearchcommand. 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
10.3.2. Commonly Used ldapsearch Options
ldapsearchcommand-line options. If a specified value contains a space ( ), the value should be surrounded by single or double quotation marks, such as
-b "cn=My Special Group,ou=groups,dc=example,dc=com".
ldapsearchutility from OpenLDAP uses SASL connections by default. To perform a simple bind or to use TLS/SSL, use the
-xargument to disable SASL and allow other connection methods.
|-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 |
-b "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"To search the root DSE entry, specify an empty string here, such as
|-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, |
Specifies an LDAP URL to use to connect to the server. For a traditional LDAP URL, this has the following format:
ldap[s]://hostname[:port]The port is optional; it will use the default LDAP port of 389 or LDAPS port of 636 if the port is not given.
This can also use an LDAPI URL, with each element separated by the HTML hex code
ldapi://%2Ffull%2Fpath%2Fto%2Fslapd-example.socketFor LDAPI, specify the full path and filename of the LDAPI socket the server is listening to. Since this value is interpreted as an LDAP URL, the forward slash characters (/) in the path and filename must be escaped encoded as the URL escape value
|-h|| Specifies the host name or IP address of the machine on which the Directory Server is installed. For example, |
Directory Server supports both IPv4 and IPv6 addresses.
|-l|| Specifies the maximum number of seconds to wait for a search request to complete. For example, |
|-p|| Specifies the TCP port number that the Directory Server uses. For example, |
|-s scope|| Specifies the scope of the search. The scope can be one of the following:
Gives the password associated with the distinguished name that is specified in the
If there are metacharacters in the password that may be interpreted by the shell (such as exclamation points, !) then use single quotes to enclose the password. For example,
Alternatively, use the
|-x||Disables the default SASL connection to allow simple binds.|
|-Y SASL_mechanism|| Defines the SASL mechanism to use for connections. For example, |
|-z|| Sets the maximum number of entries to return in response to a search request. For example, |
10.3.3. Using Special Characters
ldapsearchcommand-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"