Chapter 3. Searching the directory

Table of Contents

The ldapsearch tool
What is ldapsearch?


This chapter discusses how to perform searches on the LDAP database, using the following methods:

  • The ldapsearch command-line tool.

  • Applying filters in searches.

The ldapsearch tool

What is ldapsearch?

The ldapsearch utility is used to locate and retrieve directory entries. It opens a connection to the specified server using the specified distinguished name and password, and locates entries based on a specific search filter. The search can be performed on an individual entry, on an entry's immediate subentries or on an entire tree or subtree.

The command is located in the /<ldaphome>/shared/bin/ directory. Search results are returned in LDIF format.



The most general syntax of the ldapsearch is as follows:

ldapsearch -h host -b basedn [options] filter [attributes]


Optional parameters are a series of command line arguments. If any, they must be specified before the filter. Special characters in values are escaped using double quotes and backslashes. This is a list of the most commonly used options:

  • -b: Specifies the starting point (a distinguished name) of the search. Can be omitted if the variable LDAP_BASEDN has been set to a base DN. Value should be provided enclosed in double quotes.

  • -D: Specifies the distinguished name with which to authenticate to the server. Optional if anonymous access is supported. Must be a DN having authority to perform queries.

  • -h: hostname or IP address of the directory server. Defaults to the local host.

  • -l: Time limit to wait for completion of the request. Cannot exceed the time limit configured on the server side; defaults to 3600 seconds.

  • -p: TCP port number, defaults to 389.

  • -s: scope of the search, can be one of the following:

    • base: search only the entry specified with the -b option or the one defined by the LDAP_BASEDN environment variable.

    • one: search only the immediate children of the entry specified with the -b option. The actual entry itself is not searched.

    • sub: search the entry specified with the -b option and all of its descendants. This is the default scope for a search.

  • -w: password for authenticating the distinguished name specified with the -D option.

  • -x: simple authentication is used instead of sasl.

  • -z: maximum number of search results.

Optional search filters

Optional search filters take the form


An example would be mailhost=server1.

Optional attribute list

The scope of the search can be reduced by specifying space separated attributes. This list must appear after the search filter. If not specified, all attributes for which the distinguished name specified with the -D has access rights will be returned.


Return all entries

The "objectclass=*" attribute applies to all entries in the directory:

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

Return only specified entries

This command returns the common name and user ID attributes on all entries in the people branch:

ldapsearch -h server1 -b "ou=people,dc=example,dc=com" [-x] "objectclass=*"

The output should be like this:

version: 2
# filter: objectclass=*
# requesting: cn uid
# People, example, com
dn: ou=People,dc=example,dc=com

# mmichiel, People, example, com
dn: uid=mmichiel,ou=People,dc=example,dc=com
uid: mmichiel
cn: Mieke Michiels

# jjansen, People, example, com
dn: uid=jjansen,ou=People,dc=example,dc=com
uid: jjansen
cn: Jan Jansen
<--output omitted-->

# search result
search: 2
result: 0 Success
# numResponses: 45
# numEntries: 44

Using a search filter

This is how you can look up all attributes for a particular person:

ldapsearch -h server1 -b "dc=example,dc=com" [-x] "cn=Mieke Michiels"

The following is a typical result for such a query:

version: 2
# filter: cn=Mieke Michiels
# requesting: ALL
# mmichiel, People, example, com
dn: uid=mmichiel,ou=People,dc=example,dc=com
objectClass: person
objectClass: organizationalPerson
objectClass: inetOrgPerson
objectClass: account
objectClass: top
objectClass: posixAccount
objectClass: shadowAccount
host: *
uid: mmichiel
givenName: Mieke
sn: Michiels
cn: Mieke Michiels
loginShell: /bin/bash
gecos: Mieke Michiels
shadowMax: 30
shadowWarning: 7
shadowInactive: 2
physicalDeliveryOfficeName: hq
telephoneNumber: +32-16-666666
facsimileTelephoneNumber: +32-16-666666
l: Leuven
homeDirectory: /nethome/mmichiel
gidNumber: 533
uidNumber: 533
userPassword:: e2NyeXB0xSQxJ4lDRzF2Z0rMJHVKT6tBOThwYmN7RGQzbzJNQ3lXLzE=
shadowLastChange: 12233

# search result
search: 2
result: 0 Success
# numResponses: 2
# numEntries: 1
[Note]Solaris alternative for ldapsearch

Sun provides the ldaplist tool, which eases searches. It uses less options and arguments. The searches are based on the containers as listed in /etc/nsswitch.conf and on the information generated by ldapclient when the Solaris client is initialized. An example:

ldaplist passwd tille

will return the distinguished name (dn) for user tille.