Chapter 14. Finding Directory Entries
Entries in the directory can be searched for and found using the command line or the web console.
14.1. Finding Directory Entries Using the Command Line
You can use the
ldapsearch command-line utility to search for directory entries. This utility opens a connection to a 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 immediate subentries (
-s one) - an entire tree or subtree (
-s sub)
Note
A common mistake is to assume that the directory is searched based on the attributes used in the distinguished name. The distinguished name is only a unique identifier for the directory entry and cannot be used as a search key. Instead, search for entries based on the attribute-data pairs stored on the entry itself. Thus, if the distinguished name of an entry is
uid=bjensen,ou=People,dc=example,dc=com, then a search for dc=example does not match that entry unless dc:example has explicitly been added as an attribute in that entry.
Search results are returned in LDIF format. LDIF is defined in RFC 2849 and is described in detail in Appendix B, LDAP Data Interchange Format.
This section contains information about the following topics:
14.1.1. ldapsearch Command-Line Format
The
ldapsearch command must use the following format:
# ldapsearch [-x | -Y mechanism] [options] [search_filter] [list_of_attributes]
- Either
-x(to use simple binds) or-Y(to set the SASL mechanism) must be used to configure the type of connection. - options is a series of command-line options. These must be specified before the search filter, if any are used.
- search_filter is an LDAP search filter as described in Section 14.3, “LDAP Search Filters”. Do not specify a separate search filter if search filters are specified in a file using the
-foption. - 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 14.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.For operational attributes to be returned as a result of a search operation, they must be explicitly specified in the search command. To return all operational attributes of an object specify
+. To retrieve regular attributes in addition to explicitly specified operational attributes, use an asterisk (*) in the list of attributes in theldapsearchcommand.To retrieve only a list of matching DNs, use the special attribute1.1. For example:# ldapsearch -D "cn=Directory Manager" -W -p 389 -h server.example.com \ -b "dc=example,dc=com" -x "(objectclass=inetorgperson)" 1.1
14.1.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 "cn=My Special Group,ou=groups,dc=example,dc=com".
Important
The
ldapsearch utility from OpenLDAP uses SASL connections by default. To perform a simple bind or to use TLS, use the -x argument to disable SASL and allow other connection methods.
| 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=user,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=user_name,dc=example,dc=com". | |||
| -H |
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
%2F, rather than a forward slash (/):
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 %2F.
The
-H option is used instead of -h and -p.
| |||
| -h | Specifies the host name 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 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
-h is specified, -p must also be specified, even if it gives the default value.
| |||
| -s scope | Specifies the scope of the search. The scope can be one of the following:
| |||
| -W |
Prompt for the password. If this option is not set, anonymous access is used.
Alternatively, use the
-w option to pass the password to the utility. Note that the password can be visible in the process list for other users and is saved in the shell's history.
| |||
| -x | Disables the default SASL connection to allow simple binds. | |||
| -Y SASL_mechanism |
Sets the SASL mechanism to use for authentication. If no mechanism is set,
ldapsearch selects the best mechanism supported by the server.
If If
-x is not used, then the -Y option must be used.
| |||
| -z number | Sets the maximum number of entries to return in a response to a search request. This value overwrites the server-side nsslapd-sizelimit parameter when binding using the root DN. |
14.1.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=user_name,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.
