Symas OpenLDAP Knowledge Base

Using ldapsearch


ldapsearch Man Page

Syntax: ldapsearch <opts> [search filter] [return attributes]

The ldapsearch command allows a user to query an LDAP directory. Entries matching the search are returned in LDIF format. In addition to the common options, ldapsearch requires (in bold) or uses the following:

Option Description
-b searchbase The searchbase tells where in the DIT to begin the search
-s (base|one|sub) The scope of the search:
- base scope returns only the entry identified in the searchbase
- one scope returns all entries that are one level below the searchbase
- sub (default) searches the entire subtree starting at the searchbase
-L[L[L]] Decreases the amount of information returned with an entry
-L : Removes search result stats
-LL : Removes LDAP version/search header, search result stats and number of responses
-LLL : Removes all extraneous information
-n Performs a dry run of the search. Useful for testing the syntax of the search filter
-f filename Search using a file containing one attribute value per line to search with.
Uses “%s” string substitution in the search filter
-c Continuous mode. Ignores errors and continues on to the next search.
This mode is only useful with the “-f filename” option
-A Only returns attribute names, no values. Useful for checking if an attribute is present in an entry
-S attribute Sorts the output of entries based on attribute
-z sizelimit Limits the number of entries returned by sizelimit
“err=4 (size limit exceeded)” is also returned, This is informational, not an error
-o ldif-wrap=no Disables word-wrapping of long attribute values

Search Scope

A very important part of efficient searches is to set the scope of the search The search scope tells the server how deep to perform a search (-s base|one|sub):

Scope Result
base Limits the search to the base object only; does not search for entries at any other level of the DIT
one (level) Limits the search to entries that are one level below the search base
sub (tree) Searches the entire subtree starting at the search base

The default search scope is sub (tree). While it’s useful when you want a full, unrestricted search, it also increases search times/overhead since it checks for subentries on every entry

  • If you’re searching for one entry only and you know the full DN or at least know the search base and an attribute of the entry, use -s base for your search scope. Anything more is just wasting CPU cycles
  • If you want to limit your scope to one level, for example getting all of the OU entries (but not their children) in the example database, use -s one (-b dc=example,dc=com -s one )
  • If you want all entries below the search base, use -s sub (or exclude -s since sub is the default). Take note of any non-useful entries returned in the search result and adjust future searches to exclude those entries

Search Filters

Search filters are used to refine searches by attribute values so only necessary entries are returned

  • Filters use one or more attribute/value pairs contained within parentheses “( )” to match items in the directory
  • Search filters also use parentheses for grouping criteria together in conjunction with search operators
  • Search filters work more efficiently when attributes that are commonly searched are indexed in the database. Indexes will be covered in a later part of the class

Filter Operators

Operator Description
& (and) The and operator requires all criteria within a group to match
| (or) The or operator requires any criteria within a group to match
! (not) The not operator required the criteria to match none of the criteria
= (equals) Tests if the attribute value is equal
~= (approximate match) Makes an approximate match of the attribute value (english only)
>= (greater or equal) Attribute value is greater than or equal to criteria
<= (lesser or equal) Attribute value is less than or equal to criteria
=* (presence) A value is present in the attribute
=*string*string* Substring match

Note 1: Greater/lesser than without equality operators (>, <) are not used in LDAP. Negation of the “greater/less or equal” operator is necessary to implement this operation. See examples below.

Note 2: Search results and performance depend on how the attributes are indexed. Unindexed attributes will cause excessive search time and improperly indexed attributes or improperly used operators may cause incomplete search results.

Example Search Filters

# Simple filter looking for entries that use the "person" objectClass:

# Filter that looks for entries that don't have the last name (sn) "Smith":

# Search for entries in the "Accounting" organizational unit with the last name "Smith":

# Search for entries in the "Accounting" organizational unit without the last name "Smith":

# Search for entries with UIDNumber greater or equal to 50:

# Search for entries with UIDNumber greater than 50 (add negation and reverse GT/LT operator):

Search Tips

  • If you know the exact DN of an entry, you can use the DN as the searchbase in the “-b searchbase” and allows you to forego the search filter
  • Search filters are evaluated by the server from left to right. Efficient search filters work from general to specific
  • Use the search filter builder in Apache Directory Studio for building complicated search filters

Return Attributes

At the end of the ldapsearch command, you may provide a list of attributes you want returned with the entry. Here are your options:

Attributes Returns
<none> or “*” Returns the DN and all user attributes of the entry
attr1 attr2 attr3 Returns only the DN and the three requested attributes
opAttr1 opAttr2 opAttr3 Returns the DN and the three requested operational attributes
“+” Returns the DN and all operational attributes
“*” “+” Returns the DN and all user and operational attributes
1.1 Returns only the DN and no attributes