Searching the directory resembles searching for a phone number in a paper phone book. You can look up a phone number because you know the last name of a subscriber's entry. In other words, you use the value of one attribute of the entry to find entries that have another attribute you want.
Yet whereas a paper phone book has only one index (alphabetical order by name), the directory has many indexes. For a search you therefore always specify which index to use, by specifying which attribute(s) you are using to lookup entries.
Your paper phone book might be divided into white pages for residential subscribers, and yellow pages for businesses. If you are looking up an individual's phone number, you limit your search to the white pages. Directory services divide entries in various ways, often to separate organizations, and to separate groups from user entries from printers for example, but potentially in other ways. When searching you therefore also specify where in the directory to search.
The ldapsearch command thus takes at minimum a
search base DN option and an LDAP filter. The search base DN identifies
where in the directory to search for entries that match the filter.
For example, if you are looking for printers, you might specify the base
DN as ou=Printers,dc=example,dc=com. Perhaps you are
visiting the GNB00 office and are looking for a
printer.
$ ldapsearch --baseDN ou=Printers,dc=example,dc=com "(printerLocation=GNB00)"
In the example, the LDAP filter indicates to the directory that you
want to lookup printer entries where the printerLocation
attribute is equal to GNB00.
You also specify the host and port to access directory services, what protocol to use (for example, LDAP/SSL, or StartTLS to protect communication). If the directory service does not allow anonymous access to the data you want to search, you also identify who is performing the search and provide their credentials, such as a password or certificate. Finally, you can specify a list of attributes to return. If you do not specify attributes, then the search returns all user attributes for the entry.
Review the following examples in this section to get a sense of how searches work.
Example 6.1. Search: Simple Filter
The following example searches for entries with user IDs
(uid) containing jensen, returning
only DNs and user ID values.
$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(uid=*jensen*)" uid dn: uid=ajensen,ou=People,dc=example,dc=com uid: ajensen dn: uid=bjensen,ou=People,dc=example,dc=com uid: bjensen dn: uid=gjensen,ou=People,dc=example,dc=com uid: gjensen dn: uid=jjensen,ou=People,dc=example,dc=com uid: jjensen dn: uid=kjensen,ou=People,dc=example,dc=com uid: kjensen dn: uid=rjensen,ou=People,dc=example,dc=com uid: rjensen dn: uid=tjensen,ou=People,dc=example,dc=com uid: tjensen Result Code: 0 (Success)
Example 6.2. Search: Complex Filter
The following example returns entries with uid
containing jensen for users located in Santa Clara. The
command returns the attributes associated with the person
object class.
$ ldapsearch --port 1389 --baseDN ou=people,dc=example,dc=com "(&(uid=*jensen*)(l=Santa Clara))" @person dn: uid=ajensen,ou=People,dc=example,dc=com objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson objectClass: posixAccount objectClass: top cn: Allison Jensen telephoneNumber: +1 408 555 7892 sn: Jensen dn: uid=gjensen,ou=People,dc=example,dc=com objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson objectClass: posixAccount objectClass: top cn: Gern Jensen telephoneNumber: +1 408 555 3299 sn: Jensen dn: uid=kjensen,ou=People,dc=example,dc=com objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson objectClass: posixAccount objectClass: top cn: Kurt Jensen telephoneNumber: +1 408 555 6127 sn: Jensen dn: uid=tjensen,ou=People,dc=example,dc=com objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson objectClass: posixAccount objectClass: top cn: Ted Jensen telephoneNumber: +1 408 555 8622 sn: Jensen
Complex filters can use both "and" syntax,
(&(,
and "or" syntax,
filtercomp)(filtercomp))(|(.
filtercomp)(filtercomp))
Example 6.3. Search: Return Operational Attributes
Use + in the attribute list after the filter
to return all operational attributes. Alternatively, specify operational
attributes by name.
$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen + dn: uid=bjensen,ou=People,dc=example,dc=com numSubordinates: 0 structuralObjectClass: inetOrgPerson pwdPolicySubentry: cn=Default Password Policy,cn=Password Policies,cn=config subschemaSubentry: cn=schema hasSubordinates: false entryDN: uid=bjensen,ou=people,dc=example,dc=com entryUUID: fc252fd9-b982-3ed6-b42a-c76d2546312c
Example 6.4. Search: Return Attributes for an Object Class
Use @ in the
attribute list after the filter to return the attributes associated with
a particular object class.
objectClass
$ ldapsearch --port 1389 --baseDN dc=example,dc=com uid=bjensen @person dn: uid=bjensen,ou=People,dc=example,dc=com objectClass: person objectClass: organizationalPerson objectClass: inetOrgPerson objectClass: posixAccount objectClass: top cn: Barbara Jensen cn: Babs Jensen telephoneNumber: +1 408 555 1862 sn: Jensen
Example 6.5. Search: Escaping Search Filter Characters
RFC 4515: Lightweight Directory Access Protocol (LDAP): String Representation of Search Filters mentions a number of characters that you must handle with care when using them in search filters.
For a filter like (attr=, the following list indicates characters
that you must replace with a backslash ( value)\ ) followed
by two hexadecimal digits when using them as part of the
value string.
-
Replace
*with\2a. -
Replace
(with\28. -
Replace
)with\29. -
Replace
\with\5c. -
Replace NUL (0x00) with
\00.
The following example shows a filter with escaped characters matching an actual value.
$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(description=\28*\5c*\2a\29)" description dn: uid=bjensen,ou=People,dc=example,dc=com description: (A \great\ description*)
Example 6.6. Search: List Active Accounts
OpenDJ supports extensible matching rules, meaning you can pass in filters specifying a matching rule OID that extends your search beyond what you can do with standard LDAP. One specific matching rule of this type that OpenDJ supports is the generalized time based "later than" and "earlier than" matching rules. See the example, Configure an Extensible Match Index, showing how to build an index for these matching rules.
You can use these matching rules to list, for example, all users who have authenticated recently.
First set up an attribute to store a last login timestamp. You can do this by adding a schema file for the attribute.
$ ldapmodify --port 1389 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password dn: cn=schema changetype: modify add: attributeTypes attributeTypes: ( lastLoginTime-oid NAME 'lastLoginTime' DESC 'Last time the user logged in' EQUALITY generalizedTimeMatch ORDERING generalizedTimeOrderingMatch SYNTAX 1.3.6.1.4.1.1466.115.121.1.24 SINGLE-VALUE NO-USER-MODIFICATION USAGE directoryOperation X-ORIGIN 'OpenDJ example documentation' ) Processing MODIFY request for cn=schema MODIFY operation successful for DN cn=schema
Configure the applicable password policy to write the last login
timestamp when a user authenticates. The following command configures the
default password policy to write the timestamp in generalized time format
to the lastLoginTime operational attribute on the user's
entry.
$ dsconfig set-password-policy-prop --port 4444 --hostname opendj.example.com --bindDN "cn=Directory Manager" --bindPassword password --policy-name "Default Password Policy" --set last-login-time-attribute:lastLoginTime --set last-login-time-format:"yyyyMMddHH'Z'" --trustAll --no-prompt
Wait a while for users to authenticate again (or test it yourself) so that OpenDJ writes the timestamps. The following search then returns users who have authenticated in the last three months (13 weeks) after you configured OpenDJ to keep the last login timestamps.
$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(lastLoginTime:1.3.6.1.4.1.26027.1.4.6:=13w)" mail dn: uid=bjensen,ou=People,dc=example,dc=com mail: bjensen@example.com dn: uid=kvaughan,ou=People,dc=example,dc=com mail: kvaughan@example.com
Example 6.7. Search: Language Subtype
OpenDJ directory server supports many language subtypes. See the chapter on Localization for a list.
When you perform a search you can request the language subtype by OID or by language subtype string. For example, the following search gets the French version of a common name. The example uses the base64 command provided with OpenDJ directory server to decode the attribute value.
$ ldapsearch --port 1389 --baseDN dc=example,dc=com "(givenName:fr:=Fréderique)" cn\;lang-fr dn: uid=fdupont,ou=People,dc=example,dc=com cn;lang-fr:: RnJlZMOpcmlxdWUgRHVwb250 $ base64 decode -d RnJlZMOpcmlxdWUgRHVwb250 Fredérique Dupont
At the end of the OID or language subtype, you further specify the matching rule as follows:
-
Add
.1for less than -
Add
.2for less than or equal to -
Add
.3for equal to (default) -
Add
.4for greater than or equal to -
Add
.5for greater than -
Add
.6for substring
The following table describes the operators you can use in LDAP search filters.
Table 6.1. LDAP Filter Operators
| Operator | Definition | Example |
|---|---|---|
= |
Equality comparison, as in This can also be used with substring matches. For example, to match
last names starting with |
|
<= |
Less than or equal to comparison, which works alphanumerically. |
|
>= |
Greater than or equal to comparison, which works alphanumerically. |
|
=* |
Presence comparison. For example, to match all entries having a
|
|
~= |
Approximate comparison, matching attribute values similar to the value you specify. |
|
[:dn][: |
Extensible match comparison. At the end of the OID or language subtype, you further specify the matching rule as follows:
|
You also use extensible match filters with localized values.
Directory servers like OpenDJ support a variety of internationalized
locales, each of which has an OID for collation order, such as
|
! |
NOT operator, to find entries that do not match the specified filter component. Take care to limit your search when using |
|
& |
AND operator, to find entries that match all specified filter components. |
|
| |
OR operator, to find entries that match one of the specified filter components. |
|
