Using ldapsearch
ldapsearch
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:
(objectClass=person)
# Filter that looks for entries that don't have the last name (sn) "Smith":
(!(sn=Smith))
# Search for entries in the "Accounting" organizational unit with the last name "Smith":
(&(ou=Accounting)(sn=Smith))
# Search for entries in the "Accounting" organizational unit without the last name "Smith":
(&(ou=Accounting)(!(sn=Smith))
# Search for entries with UIDNumber greater or equal to 50:
(UIDNumber>=50)
# Search for entries with UIDNumber greater than 50 (add negation and reverse GT/LT operator):
(!(UID<=50))
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 |