This section gives an overview on how to search your directory
Searching with LDAP
From a users point of view, searching is the most important LDAP operation at all. Normally end users perform queries against a directory with the help of custom applications, which fit their specific needs. E-Mail programs like Thunderbird for instance allow the look up of adresses in a convenient way:
The actual LDAP search operation with all it's parameters is hidden here (which is desired in this situation).
So, when do you need the original LDAP syntax and parameters? Here are some use cases:
- command line tools (ldapsearch)
- LDAP clients (browsers, administrative tools)
- custom application development (using an API like JNDI)
- configuration of software products, which integrate LDAP directories
The following description about LDAP searches matches all of the above.
Important parameters in LDAP searches
The search base and the search scope are used to reduce the amount of entries, which should take into account as result entries. To the set of entries defined by base and scope, a filter is applied.
Search base
The search base determines an entry as the starting point within the tree. No entries above this point will be returned within the search result.
Search scope
The search scope defines the set of entries below the base, which is examined by the server.
Scope |
Description |
---|---|
Base |
Only the base entry |
One-Level |
One level below, all direct children of the base entry |
Subtree |
The whole subtree below the base, including the base entry |
Base scope is useful for reading attribute values of a particular entry. One example for using One_Level scope is expanding the tree in graphical LDAP clients. For extensive investigations within your data, Subtree is the most powerful option.
Search Filters
If you look for entries with certain properties (attribute values), you need search filters to delimit the result set in order to contain the entries which meet your search criteria.
Within a filter expression, the following operators are used to combine an attribute name with a value
Name |
Operator |
Example |
Example macthes |
---|---|---|---|
Presence |
=* |
(mail=*) |
all entries which have at least one mail attribute value |
Equality |
= |
(givenName=William) |
all antries where a givenName attribute value equals "William" |
Substring |
= |
(sn=H*) |
all entries where a sn (surname) attribute value starts with "H" |
Order |
<=, >= |
(ou>=N) |
all entries where a ou attribute value is greater than "N" |
Approximatly |
~= |
(sn~=Mayer) |
all entries where an sn attribute value is similar to "Mayer" |
Simple filter expressions like the examples above can be combined with the help of boolean operators. To form expressions with them, the prefix notation is used. Prefix means that the operator does not stand between the operands (like in "(3 + 6)"), but before them (like in "(+ 3 6)"), which allows you to use more than two operands within a single expression (like in "(+ 3 6 2)").
Name |
Operator |
Example |
Example matches |
---|---|---|---|
and |
& |
(&(objectClass=person)(sn=H*)) |
all person entries with surnames starting with "H" |
or |
| |
(&(objectClass=person)(|(sn=H*)(sn=W*))) |
all person entries with surnames starting with "H" or "W" |
not |
! |
(&(objectClass=person)(!(mail=*)) |
all person entries without mail address |
(objectClass=*)
Quite often, for instance as default in UI tools, you will see the search filter (objectClass=*). It is used if a filter expression is required as a parameter, but all entries should be returned regardless of their attribute values. (objectClass=*) does the job, because each entry has at least one objectClass value occurence (normally two or more), the filter therefore matches all entries.
Searching with a command line tool
If you connect to ApacheDS with command line tools, you execute searches against the directory with the ldapsearch command.
An example
The query searches all entries below "ou=people,o=sevenSeas" which match the filter (&(objectClass=person)(givenName=William)), and therefore are persons called William.
The tool return the attribute values for the attributes given in the command line (uid and mail). If no attributes are provided, all attributes the user is allowed to read will be returned.
Command line options used in the example
Option |
Example value |
Meaning |
---|---|---|
-h |
zanzibar |
Hostname of LDAP server to connect to (default is localhost) |
-p |
10389 |
Port on which the server listens (default is 389) |
-D |
"uid=admin,ou=system" |
Distinguished name of bind user |
-w |
secret |
Password of bind user |
-b |
"ou=people,o=sevenSeas" |
search base |
-s |
sub |
search scope, one of "base", "one", or "sub" (default is sub) |
Searching with a Java program
Here is the same search as above, performed against the "Seven seas" example from within a Java program with the help of JNDI.
The output of the program looks like this:
Key for LDAP searches with JNDI are the search methods in the javax.naming.directory.DirContext interface (javadoc). Learn more about JNDI and how to perform searches against an LDAP directory with it in the JNDI tutorial
Searching with a graphical client tool
If you connect to ApacheDS with graphical tools, normally a search dialog is provided which allows you to enter the parameters needed to perform your search.
Here is the search query used throughout this section, performed with Softerra LDAP Browser:
If you prefer to use JXplorer, the search dialog looks like this:
Resources
- RFC 4515 LDAP: String Representation of Search Filters
- manpage of ldapsearch contains the options for the OpenLDAP of this LDAP search tool
- The JNDI tutorial is a good resource to learn about LDAP client programming with Java