5.3 Advanced Searching Options

Chapter 4 presented LDAP searches as a means of verifying the correctness of your directory. That's obviously a very limited use of the search capability: a directory isn't much use if you can't search it. Given our limited goals in the previous chapter, we didn't do justice to the topic of search filters. It's now time to take a more thorough look at the topic of filters.^[1]

^[1] For the full details of representing LDAP searches using strings, read RFC 2254.

In its commonly used form, an LDAP search filter has the following syntax:

( attribute filterOperator value )

The attribute is the actual name of the attribute type. The filterOperator is one of:

=

For equality matches

~=

For approximate matches

<=

For less than comparisons

>=

For greater than comparisons

If you deal only with string comparisons, you may only need the equality operator.

The value portion can be either an absolute value, such as carter or 555-1234, or a pattern using the asterisk (*) character as a wildcard. Here are some wildcard searches:

(cn=*carter)

Finds all entries whose cn attribute ends in "carter" (not just those with a last name of Carter)

(telephoneNumber=555*)

Finds all telephone numbers beginning with 555

You can combine single filters like these using the following Boolean operators:

&

Logical AND

|

Logical OR

!

Logical NOT

LDAP search filters use prefix notation for joining search conditions. Therefore, to search for users with a surname (sn) of "smith" or "jones," you can build the following filter:

(|(sn=smith)(sn=jones))

The sn attribute uses a case-insensitive matching rule, so it doesn't matter whether you use "Smith," "smith," or "SMITH" in the filter (or in the directory itself). To look for people with a last name of "smith" or "jones" and a first name beginning with "John," the search would be modified to look like:

(&(|(sn=smith)(cn=jones))(cn=john*))

Note that the (cn=john*) search filter matches any cn that begins with "john": it matches cn=john doe as well as cn=johnathon doe.

5.3.1 Following Referrals with ldapsearch

By default, the ldapsearch tool shipped with OpenLDAP 2 prints information about referral objects but does not automatically follow them. For example, let's use ldapsearch to list all entries in your directory that possess an ou attribute:

$ ldapsearch -H ldap://localhost/ -LL -x \
> -b "dc=plainjoe,dc=org"  "(ou=*)" ou
      
# plainjoe.org
dn: dc=plainjoe,dc=org
ou: PlainJoe Dot Org
      
# people, plainjoe.org
dn: ou=people,dc=plainjoe,dc=org
ou: people
      
# Search reference
# refldap://ldap2.plainjoe.org/ou=hosts,dc=plainjoe,dc=org??sub

Note that ldapsearch returned the referral value, but not the entries below the ou=hosts,dc=plainjoe,dc=org naming context. This information is obviously useful when you're trying to debug a directory tree that is distributed between several servers, but it's not what you want if you only intend to look up information. To follow the search referral, give the -C (chase referrals) option when you invoke ldapsearch:

$ ldapsearch -H ldap://localhost/ -LL -x \
> -b "dc=plainjoe,dc=org"  "(ou=*)" ou
      
# plainjoe.org
dn: dc=plainjoe,dc=org
ou: PlainJoe Dot Org
      
# people, plainjoe.org
dn: ou=people,dc=plainjoe,dc=org
ou: people
      
# hosts, plainjoe.org
dn: ou=hosts,dc=plainjoe,dc=org
ou: hosts

5.3.2 Limiting Your Searches

A production directory can easily grow to thousands or millions of entries�and with such large directories, searches with filters such as (objectclass=*) can put quite a strain on the directory server and generate more output than you want to deal with. Therefore, ldapsearch lets you define limits for both the client and the server that control the amount of time a search is allowed to take and the number of entries it is allowed to return. Table 5-2 lists the ldapsearch parameters that limit the resources required by any search.

Table 5-2. Command-line parameters for defining search limits in ldapsearch

Parameter	Description
-l integer	Specifies the number of seconds in real time to wait for a response to a search request. A value of 0 removes the timelimit default in ldap.conf.
-z integer	Defines the maximum number of entries to be retrieved as a result of a successful search request. A value of 0 removes the limits set by the sizelimit option in ldap.conf.

You can also specify limits on the server, in the slapd.conf file. Table 5-3 lists the global parameters that limit searches.

Table 5-3. OpenLDAP 2 slapd.conf global search limit parameters

Parameter	Description
sizelimit integer	Defines the maximum number of entries that the server will return to a client when responding to a search request. The default value is 500 entries.
timelimit integer	Specifies the maximum number of seconds in real time to be spent when responding to a search request. The default limit is 1 hour (3,600 seconds).