Chapter 1. Finding entries using the command line (ldapsearch)
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
)
The ldapsearch
utility does not search for directory entries based on attributes in the distinguished name. The distinguished name is only a unique identifier for a directory entry and cannot be used as a search key. Instead, ldapsearch
searches for entries based on the attribute value pairs stored in entries. If the distinguished name of an entry is, for example, uid=bjensen,ou=People,dc=example,dc=com
, then a search for dc=example
does not match that entry unless dc:example
was explicitly added as an attribute value pair to this entry.
The ldapsearch utility returns results in the LDIF format that is defined in the RFC 2849 specification.
1.1. The ldapsearch command format
The ldapsearch
command must use the following format:
# ldapsearch [-x | -Y mechanism] [options] [search_filter] [list_of_attributes]
-x
or-Y
Use
-x
(simple binds) or-Y
(SASL mechanism) to configure the type of the connection.options
The
ldapsearch
command-line options. Specify the options before the search filter, if any are used.search_filter
An LDAP search filter. Do not specify a search filter if you configure search filters in a file using the
-f
option.list_of_attributes
A list of attributes separated by a space character. Specifying the list of attributes reduces the number of attributes returned in the search results. This list of attributes must appear after the search filter. If you do not specify the list of attributes, the search returns values for all attributes permitted by the access control set in the directory with the exception of operational attributes.
If you want the search to return operational attributes, you must explicitly specify it in the
ldapsearch
search command. To return all operational attributes of an object use+
. To retrieve regular attributes in addition to explicitly specified operational attributes, use an asterisk (*
) in the list of attributes.Note that you might need to escape the asterisk character with a backslash (
\*
).To retrieve only a list of matching DNs, use the attribute
1.1
. For example:# ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com \ -b "dc=example,dc=com" -x "(objectclass=inetorgperson)" 1.1
Additional resources
1.2. Commonly used ldapsearch options
The following table lists the most commonly used ldapsearch
utility options. If a specified value contains a space character, the value must be surrounded by single or double quotation marks, for example:
-b "cn=My Special Group,ou=groups,dc=example,dc=com"
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 - base Distinguished Name (DN). Note that distinguished name must exist in the database. If you set the |
-D |
Specifies the DN used to authenticate to the server. Directory Server must recognize the DN value, and the DN must have the authority to search for the entries. For example: |
-H |
Specifies an LDAP URL to connect to the server. An LDAP URL has the following format: ldap[s]://hostname:[port]
Specifying the port value is optional. The
The utility can also use an LDAPI URL with each element separated by the HTML hex code %2F instead of a forward slash ( ldapi://%2Ffull%2Fpath%2Fto%2Fslapd-example.socket
For LDAPI, specify the full path to the file which represents the LDAPI socket the server is listening to. If you did not specify the URL, |
-h |
Specifies the hostname or IP address of the machine with installed Directory Server. For example, Note
The |
-p |
Specifies the TCP port number used by Directory Server. For example, Note
The |
-l |
Specifies the maximum time limit in seconds for a search request to complete. For example, |
-s scope | Specifies the scope of the search. You can choose one of the following scopes:
|
-W |
Prompts for the password. if you did not specify the option, the Note 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 you do not set any mechanism, |
-z number |
Sets the maximum number of entries to return in a response to a search request. This value overwrites the |
-f | Specifies a file with search filters. |
Additional resources
1.3. Using special characters
When using the ldapsearch
utility, you might need to specify values with characters that have special meaning to the command-line interpreter, such as space character, asterisk (*
), or backslash (\
). Depending on the command-line interpreter, enclose the value that has the special character either in single (' '
) or double (" "
) quotation marks. For example:
-D "cn=John Smith,ou=Product Development,dc=example,dc=com"
In general, use single quotation marks (' '
) to enclose values. Use double quotation marks (" "
) to allow variable interpolation if there are shell variables.