10.4. LDAP Search Filters

Search filters select the entries to be returned for a search operation. They are most commonly used with the ldapsearch command-line utility. When using ldapsearch, there can be multiple search filters in a file, with each filter on a separate line in the file, or a search filter can be specified directly on the command line.
The basic syntax of a search filter is: 
attribute operator value 
For example: 
buildingname>=alpha
In this example, buildingname is the attribute, >= is the operator, and alpha is the value. Filters can also be defined that use different attributes combined together with Boolean operators.

Note

When performing a substring search using a matching rule filter, use the asterisk (*) character as a wildcard to represent zero or more characters.
For example, to search for an attribute value that starts with the letter l and ends with the letter n, enter a l*n in the value portion of the search filter. Similarly, to search for all attribute values beginning with the letter u, enter a value of u* in the value portion of the search filter.
To search for a value that contains the asterisk (*) character, the asterisk must be escaped with the designated escape sequence, \5c2a. For example, to search for all employees with businessCategory attribute values of Example*Net product line, enter the following value in the search filter: 
Example\5c2a*Net product line

Note

A common mistake is to assume that the directory is searched based on the attributes used in the distinguished name. The distinguished name is only a unique identifier for the directory entry and cannot be used as a search key. Instead, search for entries based on the attribute-data pairs stored on the entry itself. Thus, if the distinguished name of an entry is uid=bjensen,ou=People,dc=example,dc=com, then a search for dc=example does not match that entry unless dc:example has explicitly been added as an attribute in that entry.

10.4.1. Using Attributes in Search Filters

The most basic sort of search looks for the presence of attributes or specific values in entries. There are many variations on how to look for attributes in entries. It is possible to check that the attribute merely exists, to match an exact value, or to list matches against a partial value.
A presence search uses a wild card (an asterisk) to return every entry which has that attribute set, regardless of value. For example, this returns every entry which has a manager attribute: 
"(manager=*)"
It is also possible to search for an attribute with a specific value; this is called an equality search. For example: 
"(cn=babs jensen)"
This search filter returns all entries that contain the common name Babs Jensen. Most of the time, equality searches are not case sensitive.
When an attribute has values associated with a language tag, all of the values are returned. Thus, the following two attribute values both match the "(cn=babs jensen)" filter: 
cn: babs jensen
cn;lang-fr: babs jensen
It is also possible to search for a partial match on an attribute value, a substring index. For example: 
"(description=*X.500*)"
"(sn=*nderson)"
"(givenname=car*)"
The length of the substring searches is configured in the substring index itself, as described in Section 9.6, “Changing the Width for Indexed Substring Searches”.

10.4.2. Using Operators in Search Filters

Operators in search filters set the relationship between the attribute and the given search value. For people searches, operators can be used to set a range, to return a last names within a subset of letters in the alphabet or employee numbers that come after a certain number. 
"(employeeNumber>=500)"
"(sn~=suret)"
"(salary<=150000)"
Operators also enable phonetic and approximate searches, which allow more effective searches with imperfect information and are particularly useful in internationalized directories.
The operators that can be used in search filters are listed in Table 10.2, “Search Filter Operators”. In addition to these search filters, special filters can be specified to work with a preferred language collation order. For information on how to search a directory with international charactersets, see Section D.4, “Searching an Internationalized Directory”.

Table 10.2. Search Filter Operators

Search Type Operator Description
Equality = Returns entries containing attribute values that exactly match the specified value. For example, cn=Bob Johnson
Substring =string* string Returns entries containing attributes containing the specified substring. For example, cn=Bob* cn=*Johnson cn=*John* cn=B*John. The asterisk (*) indicates zero (0) or more characters.
Greater than or equal to >= Returns entries containing attributes that are greater than or equal to the specified value. For example, buildingname >= alpha.
Less than or equal to <= Returns entries containing attributes that are less than or equal to the specified value. For example, buildingname <= alpha.
Presence =* Returns entries containing one or more values for the specified attribute. For example, cn=* telephoneNumber=* manager=*.
Approximate ~= Returns entries containing the specified attribute with a value that is approximately equal to the value specified in the search filter. For example, cn~=suret l~=san fransico could return cn=sarette l=san francisco.

10.4.3. Using Compound Search Filters

Multiple search filter components can be combined using Boolean operators expressed in prefix notation as follows: 
(Boolean-operator(filter)(filter)(filter)...)
Boolean-operator is any one of the Boolean operators listed in Table 10.3, “Search Filter Boolean Operators”.
FOr example, this filter returns all entries that do not contain the specified value: 
(!(cn=Ray Kultgen))
(!(objectClass=person))
Obviously, compound search filters are most useful when they are nested together into completed expressions: 
(Boolean-operator(filter)((Boolean-operator(filter)(filter)))
These compound filters can be combined with other types of searches (approximate, substring, other operators) to get very detailed results. For example, this filter returns all entries whose organizational unit is Marketing and whose description field does not contain the substring X.500: 
(&(ou=Marketing)(!(description=*X.500*)))
That filter can be expanded to return entries whose organizational unit is Marketing, that do not have the substring X.500, and that have Julie Fulmer or Cindy Zwaska as a manager: 
(&(ou=Marketing)(!(description=*X.500*))(|(manager=cn=Julie Fulmer,ou=Marketing,dc=example,dc=com)(manager=cn=Cindy Zwaska,ou=Marketing,dc=example,dc=com)))
This filter returns all entries that do not represent a person and whose common name is similar to printer3b: 
(&(!(objectClass=person))(cn~=printer3b))

Table 10.3. Search Filter Boolean Operators

Operator Symbol Description
AND & All specified filters must be true for the statement to be true. For example, (&(filter)(filter)(filter)...).
OR | At least one specified filter must be true for the statement to be true. For example, (|(filter)(filter)(filter)...)
NOT ! The specified statement must not be true for the statement to be true. Only one filter is affected by the NOT operator. For example, (!(filter)).
Boolean expressions are evaluated in the following order:
  • Innermost to outermost parenthetical expressions first.
  • All expressions from left to right.

10.4.4. Using Matching Rules

A matching rule tells the Directory Server how to compare two values (the value stored in the attribute and the value in the search filter). A matching rule also defines how to generate index keys. Matching rules are somewhat related to attribute syntaxes. Syntaxes define the format of an attribute value; matching rules define how that format is compared and indexed.
There are three different types of matching rules:
  • EQUALITY specifies how to compare two values for an equal match. For example, how to handle strings like “Fred” and “FRED”. Search filters that test for equality (e.g. attribute=value) use the EQUALITY rule. Equality (eq) indexes use the EQUALITY rule to generate the index keys. Update operations use the EQUALITY rule to compare values to be updated with values already in an entry.
  • ORDERING specifies how to compare two values to see if one value is greater or less than another value. Search filters that set a range (e.g. attribute<=value or attribute>=value) use the ORDERING rule. An index for an attribute with an ORDERING rule orders the equality values.
  • SUBSTR specifies how to do substring matching. Substring search filters (e.g. attribute=*partial_string* or attribute=*end_string) use the SUBSTR rule. Substring (sub) indexes use the SUBSTR rule to generate the index keys.

Important

A matching rule is required in order to support searching or indexing for the corresponding search filter or index type. For example, an attribute must have an EQUALITY matching rule in order to support equality search filters and eq indexes for that attribute. An attribute must have both an ORDERING matching rule and an EQUALITY matching rule in order to support range search filters and indexed range searches.
A search operation will be rejected with PROTOCOL_ERROR or UNWILLING_TO_PERFORM if an attempt is made to use a search filter for an attribute that has no corresponding matching rule.

Example 10.1. Matching Rules and Custom Attributes

Example Corp. administrators create a custom attribute type called MyFirstName with IA5 String (7-bit ASCII) syntax and an EQUALITY matching rule of caseExactIA5Match. An entry with a MyFirstName value of Fred is returned in a search with a filter of (MyFirstName=Fred), but it is not returned for filters like (MyFirstName=FRED) and (MyFirstName=fred) Fred, FRED, and fred are all valid IA5 String values, but they do not match using the caseExactIA5Match rule.
For all three variants of Fred to be returned in a search, then the MyFirstName should be defined to use the caseIgnoreIA5Match matching rule.
An extensible matching rule search filter can be used to search for an attribute value with a different matching rule than the one defined for the attribute. The matching rule must be compatible with the syntax of the attribute being searched. For example, to run a case insensitive search for an attribute that has a case-sensitive matching rule defined for it, specify a case insensitive matching rule in the search filter. 
(MyFirstName:caseIgnoreIA5Match:=fred)

Note

Matching rules are used for searches in internationalized directories, to specify the language types to use for the results. This is covered in Section D.4, “Searching an Internationalized Directory”.

Note

An index for an attributes uses whatever matching rules are defined for that attribute in its schema definition. Additional matching rules to use for an index can be configured using the nsMatchingRule attribute, as in Section 9.2.2, “Creating Indexes from the Command Line”.
The syntax of the matching rule filter inserts a matching rule name or OID into the search filter: 
attr:matchingRule:=value
  • attr is an attribute belonging to entries being searched, such as cn or mail.
  • matchingRule is a string that contains the name or OID of the rule to use to match attribute values according to the required syntax.
  • value is either the attribute value to search for or a relational operator plus the attribute value to search for. The syntax of the value of the filter depends on the matching rule format used.
A matching rule is actually a schema element, and, as with other schema elements is uniquely identified by an object identifier (OID).
Many of the matching rules defined for Red Hat Directory Server relate to language codes and set internationalized collation orders supported by the Directory Server. For example, the OID 2.16.840.1.113730.3.3.2.17.1 identifies the Finnish collation order.

Note

Unlike other schema elements, additional matching rules cannot be added to the Directory Server configuration.
Most of the matching rules list in Table 10.4, “General Syntax Matching Rules” are used for equality indexes. Matching rules with ordering in their name are used for ordering indexes, and those with substring in their name are used for substring (SUBSTR) indexes. (The matching rules used for international matching and collation orders use a different naming scheme.)

Table 10.4. General Syntax Matching Rules

Matching Rule Object Identifiers (OIDs) Definitions Compatible Syntaxes
Bitwise AND Match 1.2.840.113556.1.4.803 Performs bitwise AND matches. Typically used with:[a]
Integer
Numeric String
Bitwise OR Match 1.2.840.113556.1.4.804 Performs bitwise OR matches. Typically used with:[a]
Integer
Numeric String
booleanMatch 2.5.13.13 Evaluates whether the values to match are TRUE or FALSE. Boolean
caseExactIA5Match 1.3.6.1.4.1.1466.109.114.1 Makes a case-sensitive comparison of values.
IA5 Syntax
URI
caseExactMatch 2.5.13.5 Makes a case-sensitive comparison of values.
Directory String
Printable String
OID
caseExactOrderingMatch 2.5.13.6 Allows case-sensitive ranged searches (less than and greater than).
Directory String
Printable String
OID
caseExactSubstringsMatch 2.5.13.7 Performs case-sensitive substring and index searches.
Directory String
Printable String
OID
caseIgnoreIA5Match 1.3.6.1.4.1.1466.109.114.2 Performs case-insensitive comparisons of values.
IA5 Syntax
URI
caseIgnoreIA5SubstringsMatch 1.3.6.1.4.1.1466.109.114.3 Performs case-insensitive searches on substrings and indexes.
IA5 Syntax
URI
caseIgnoreListMatch 2.5.13.11 Performs case-insensitive comparisons of values. Postal Address
caseIgnoreListSubstringsMatch 2.5.13.12 Performs case-insensitive searches on substrings and indexes. Postal Address
caseIgnoreMatch 2.5.13.2 Performs case-insensitive comparisons of values.
Directory String
Printable String
OID
caseIgnoreOrderingMatch 2.5.13.3 Allows case-insensitive ranged searches (less than and greater than).
Directory String
Printable String
OID
caseIgnoreSubstringsMatch 2.5.13.4 Performs case-insensitive searches on substrings and indexes.
Directory String
Printable String
OID
distinguishedNameMatch 2.5.13.1 Compares distinguished name values. Distinguished name (DN)
generalizedTimeMatch 2.5.13.27 Compares values that are in a Generalized Time format. Generalized Time
generalizedTimeOrderingMatch 2.5.13.28 Allows ranged searches (less than and greater than) on values that are in a Generalized Time format. Generalized Time
integerMatch 2.5.13.14 Evaluates integer values. Integer
integerOrderingMatch 2.5.13.15 Allows ranged searches (less than and greater than) on integer values. Integer
keywordMatch 2.5.13.33 Compares the given search value to a string in an attribute value. Directory String
numericStringMatch 2.5.13.8 Compares more general numeric values. Numeric String
numericStringOrderingMatch 2.5.13.9 Allows ranged searches (less than and greater than) on more general numeric values. Numeric String
numericStringSubstringMatch 2.5.13.10 Compares more general numeric values. Numeric String
objectIdentifierMatch 2.5.13.0 Compares object identifier (OID) values. OID
octetStringMatch 2.5.13.17 Evaluates octet string values. Octet String
octetStringOrderingMatch 2.5.13.18 Supports ranged searches (less than and greater than) on a series of octet string values. Octet String
telephoneNumberMatch 2.5.13.20 Evaluates telephone number values. Telephone Number
telephoneNumberSubstringsMatch 2.5.13.21 Performs substring and index searches on telephone number values. Telephone Number
uniqueMemberMatch 2.5.13.23 Compares both name and UID values. Name and Optional UID
wordMatch 2.5.13.32 Compares the given search value to a string in an attribute value. This matching rule is case-insensitive. Directory String
[a] This has a special format; the value is converted to integer before being used by Directory Server.

Table 10.5. Language Ordering Matching Rules

Matching Rule Object Identifiers (OIDs)
English (Case Exact Ordering Match) 2.16.840.1.113730.3.3.2.11.3
Albanian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.44.1
Arabic (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.1.1
Belorussian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.2.1
Bulgarian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.3.1
Catalan (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.4.1
Chinese - Simplified (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.49.1
Chinese - Traditional (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.50.1
Croatian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.22.1
Czechoslovakian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.5.1
Danish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.6.1
Dutch (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.33.1
Dutch - Belgian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.34.1
English - US (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.11.1
English - Canadian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.12.1
English - Irish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.14.1
Estonian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.16.1
Finnish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.17.1
French (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.18.1
French - Belgian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.19.1
French - Canadian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.20.1
French - Swiss (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.21.1
German (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.7.1
German - Austrian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.8.1
German - Swiss (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.9.1
Greek (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.10.1
Hebrew (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.27.1
Hungarian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.23.1
Icelandic (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.24.1
Italian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.25.1
Italian - Swiss (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.26.1
Japanese (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.28.1
Korean (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.29.1
Latvian, Lettish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.31.1
Lithuanian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.30.1
Macedonian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.32.1
Norwegian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.35.1
Norwegian - Bokmul (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.36.1
Norwegian - Nynorsk (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.37.1
Polish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.38.1
Romanian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.39.1
Russian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.40.1
Serbian - Cyrillic (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.45.1
Serbian - Latin (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.41.1
Slovakian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.42.1
Slovenian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.43.1
Spanish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.15.1
Swedish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.46.1
Turkish (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.47.1
Ukrainian (Case Insensitive Ordering Match) 2.16.840.1.113730.3.3.2.48.1

Table 10.6. Language Substring Matching Rules

Matching Rule Object Identifiers (OIDs)
English (Case Exact Substring Match) 2.16.840.1.113730.3.3.2.11.3.6
Albanian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.44.1.6
Arabic (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.1.1.6
Belorussian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.2.1.6
Bulgarian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.3.1.6
Catalan (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.4.1.6
Chinese - Simplified (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.49.1.6
Chinese - Traditional (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.50.1.6
Croatian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.22.1.6
Czechoslovakian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.5.1.6
Danish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.6.1.6
Dutch (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.33.1.6
Dutch - Belgian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.34.1.6
English - US (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.11.1.6
English - Canadian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.12.1.6
English - Irish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.14.1.6
Estonian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.16.1.6
Finnish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.17.1.6
French (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.18.1.6
French - Belgian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.19.1.6
French - Canadian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.20.1.6
French - Swiss (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.21.1.6
German (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.7.1.6
German - Austrian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.8.1.6
German - Swiss (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.9.1.6
Greek (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.10.1.6
Hebrew (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.27.1.6
Hungarian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.23.1.6
Icelandic (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.24.1.6
Italian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.25.1.6
Italian - Swiss (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.26.1.6
Japanese (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.28.1.6
Korean (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.29.1.6
Latvian, Lettish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.31.1.6
Lithuanian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.30.1.6
Macedonian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.32.1.6
Norwegian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.35.1.6
Norwegian - Bokmul (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.36.1.6
Norwegian - Nynorsk (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.37.1.6
Polish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.38.1.6
Romanian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.39.1.6
Russian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.40.1.6
Serbian - Cyrillic (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.45.1.6
Serbian - Latin (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.41.1.6
Slovakian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.42.1.6
Slovenian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.43.1.6
Spanish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.15.1.6
Swedish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.46.1.6
Turkish (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.47.1.6
Ukrainian (Case Insensitive Substring Match) 2.16.840.1.113730.3.3.2.48.1.6