Finding Directory Entries


ou can find entries in your directory using any LDAP client. Most clients provide some form of a search interface that allows you to easily search the directory and retrieve entry information. Note, however, that you cannot search the directory unless the appropriate access control has been set in your directory. For information on setting access control in your directory, see Chapter 5, "Managing Access Control."

The Netscape Directory Server comes with the following LDAP clients that allow you to search your directory:

Regardless of the type of LDAP client you are using to search your directory, you can use search filters to help locate entries.

The following topics are covered in this section:

For information on how to use the Users and Groups area of the administration server, see the online help that is available through your administration server. For information on how to use the directory server gateway, see the online help that is available through the gateway.

 

LDAP Search Filters

Search filters select the entries to be returned for search operation. They are most commonly used with the ldapsearch command-line utility. When you are using ldapsearch, you can place multiple search filters in a file, with each filter on a separate line in the file, or you can specify a search filter directly on the command-line call to ldapsearch.

For example, the following filter specifies a search for a common name equal to Babs Jensen:


	cn=babs jensen
This search filter returns all entries that contain a common name equal to Babs Jensen. Note that any language tags associated with the common name attribute are also returned. Thus, the following two attributes both match this filter:


	cn: babs jensen


	cn;lang-fr: babs jensen
For a list of all the supported language tags, see Table D.1.

 

Search Filter Syntax

The basic syntax of a search filter is:


	<attribute><operator><value>
For example:


	employeenumber>=100
In this example, employeenumber is the attribute, >= is the operator, and 100 is the value. You can also define filters that use different attributes combined together using boolean operators.

The following sections describe search filters in detail.

 

Using Attributes in Search Filters

When searching for an entry, you can specify attributes associated with that type of entry. For example, when you search for entries about people, you can use the cn attribute to search for people with a specific common name.

Examples of attributes for entries about people might include:

For a listing of the attributes associated with types of entries, see Appendix A, "Object Classes".

 

Using Operators in Search Filters

A search filter operator can be one of the following:
Search type

 Symbol

 Description

Equality

 =

 Returns entries containing attributes set to 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

Greater than or equal to

 >=

 Returns entries containing attributes that are greater than or equal to the specified value. For example,

employeenumber >= 100

Less than or equal to

 <=

 Returns entries containing attributes that are less than or equal to the specified value. For example,

employeenumber <= 100

Presence

 =*

 Returns entries containing the specified attribute. For example,

cn=*

telephonenumber=*

manager=*

Approximate

 ~=

 Returns entries containing the specified attribute that is approximately equal to the specified value. For example,

cn~=surette

l~=san fransico

could return

cn=sarette

l=sfo

 

Using Multiple Search Filters

 Multiple search operations can be combined using Boolean operators expressed in prefix notation as follows:


(<operator>(<search operation>)(<search operation>)(<search operation>)...))
where <operator> is any one of the Boolean operators. In addition, multiple search operation Boolean operators can be nested together to form complex expressions, such as:


(<operator>(<search operation>)((<operator>(<search operation>)(<search operation>)))
 

Boolean Operators

 The Boolean operators available for use with search filters are:
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. Note that only one filter is affected by the NOT operator. For example,

(!(filter))

Boolean expressions are evaluated in the following order:

 

Search Filter Examples

 The following filter searches for entries containing the manager attribute. This is also known as a presence search:


	manager=*
The following filter searches for entries containing the common name of Ray Kultgen. This is also known as an equality search:


	cn=Ray Kultgen
The following filter returns any entries that do not contain the common name of Ray Kultgen:


	(!(cn=Ray Kultgen))
The following filter returns any entries that contain a description attribute with a substring of X.500:


	description=*X.500*
The following filter returns any entries whose organizational unit is Marketing and whose description field does not contain the substring X.500:


	(&(ou=Marketing)(!(description=*X.500*)))
The following filter returns any entries whose organizational unit is Marketing and that have Julie Fulmer or Cindy Zwaska as a manager:


	(&(ou=Marketing)(|(manager=cn=Julie Fulmer,ou=Marketing,o=airius.com)(manager=cn=Cindy Zwaska,ou=Marketing,o=arius.com)))
The following filter returns any entries that do not represent a person:


	(!(objectClass=person))
The following filter returns any entries that do not represent a person and whose common name is similar to printer3b:

(&(!(objectClass=person))(cn~=printer3b))

 

Using ldapsearch

You use the ldapsearch command-line utility to locate and retrieve directory entries. This utility opens a connection to the specified server using the specified distinguished name and password, and locates entries based on a specified search filter. Search scopes can include a single entry, an entry's immediate subentries, or an entire tree or subtree.

Search results are returned in LDIF format.

For information on where you can find the command line utilities in your directory server installation, see "Finding the Command-Line Utilities".

 

Using Special Characters

When using the ldapsearch command-line utility, you may need to specify values that contain characters that have special meaning to the command-line interpreter (such as space [ ], asterisk [*], backslash [\], and so forth). When this situation occurs, enclose the value in quotation marks (""). For example:


-D "cn=Barbara Jensen, ou=Product Development, o=airius.com"



-D "cn=Patricia Fuentes, ou=people, o=Airius Bolivia\, S.A."
 

ldapsearch Command Line Format

 When you call ldapsearch, you must enter the command using the following format:


ldapsearch [<optional parameters>] [<optional search filter>] [<optional list of attributes>]
where:

 

Commonly Used ldapsearch Parameters

 The following lists the most commonly used ldapsearch command-line parameters:

 

SSL Parameters

 You can use the following command-line parameters to specify that ldapsearch is to use LDAPS when communicating with your directory server. These parameters are valid only when LDAPS has been turned on and configured for your directory server. For more information on LDAPS, see "Managing SSL".

Make sure that you specify your directory server's encrypted port when you use these parameters:

 

Additional ldapsearch Parameters

 To further customize a search, use the following optional parameters:

 

ldapsearch Examples

 Suppose:

 

Specifying Search Filters on the Command Line

 You can also specify a search filter directly on the call to the command line. If you do this, be sure to enclose your filter in quotation marks ("filter"). Also, do not specify the -f parameter. For example:


ldapsearch -h cyclops -b "o=airius.com" "cn=babs jensen"
 

Searching the DSE Entry

 The Directory Server Entry (DSE) contains a list of all the suffixes supported by the local directory server. You can search this entry by supplying a null search base, or "". You must also specify a search scope of base. For example:


ldapsearch -h cyclops -b "" -s base "objectclass=*"
 

Searching the Schema Entry

 The LDAP v3 protocol requires that all directory server schema be contained in a special directory tree who's suffix is cn=schema. This tree contains a single entry (cn=schema), and this entry contains information on every objectclass and attribute defined for your directory server.

You can examine the contents of this entry as follows:


ldapsearch -h cyclops -b "cn=schema" -s base "objectclass=*"
 

Using LDAP_BASEDN

 To make searching easier, you can set your search base using the LDAP_BASEDN environment variable. Doing this allows you to skip specifying the search base with the
-b parameter (for information on how to set environment variables, see the documentation for your operating system).

Typically, you set LDAP_BASEDN to your directory's suffix value. Since your directory suffix is equal to the root, or topmost, entry in your directory, this causes all searches to begin from your directory's root entry.

For example, suppose you have set LDAP_BASEDN to o=airius.com. Then to search for cn=babs jensen in your directory use the following command-line call:


ldapsearch -h cyclops "cn=babs jensen"
 

Displaying Subsets of Attributes

 ldapsearch returns all search results in LDIF format. By default, ldapsearch returns the entry's distinguished name and all of the attributes that you are allowed to read (you can set up the directory access control such that you are allowed to read only a subset of the attributes on any given directory entry).

Suppose you do not want to see all of the attributes returned on the search results. In this case, you can limit the returned attributes to just a few specific attributes by specifying those attributes on the command line immediately after the search filter. For example, to show the common name and surname attributes for every entry in the directory, use the following command-line call:


ldapsearch -h cyclops "objectclass=*" sn cn
Note that this example assumes you set your search base with LDAP_BASEDN.

 

Specifying Search Filters Using a File

You can enter search filters into a file instead of entering them on the command line. When you do this, specify each search filter on a separate line in the file. ldapsearch will run each search in order until the last search filter is found in the file. That is, if you enter


	sn=Francis
	givenname=Richard
into the file, then ldapsearch will first find all the entries who's surname is Francis, and then all the entries whose givenname is Richard. Note that if an entry is found that matches both search criteria, then that entry is returned twice.

For example, suppose you specified the previous search filters in a file named searchdb, and you set your search base using LDAP_BASEDN. Then the following returns all the entries that match both search filters:


ldapsearch -h cyclops -f searchdb
You can limit the set of attributes returned here by appending the attribute names that you want to see at the end of the search line. For example, the following performs both searches, but only returns the entry's DN and each entry's givenname and surname attributes:


ldapsearch -h cyclops -f searchdb sn givenname
 

Specifying DNs that Contain Commas

 When a DN within a search filter contains a comma as part of its value, you must escape the comma with a backslash (\). For example, to find everyone in the Airius Bolivia, S.A. subtree, you would use the following command:


ldapsearch -h cyclops -s base -b "o=Airius Bolivia\, S.A." "objectclass=*"
 

Searching an Internationalized Directory

 You can perform search operations on the directory server using any language for which the server has a supporting collation order. For a listing of the collation orders supported by the directory server, see "Identifying Supported Locales".

This section focuses on the matching rule filter portion of the ldapsearch syntax. For more information on general ldapsearch syntax, see "LDAP Search Filters".

 

Supported Search Types

The directory server supports the following types of international searches:

Note that approximate, or phonetic, and presence searches are only supported in English.

As with a regular ldapsearch search operation, an international search uses operators to define the type of search. However, when invoking an international search, you can either use the standard operators (=, >=, >, <, <=) in the value portion of the search string, or you can use a special type of operator, called a suffix (not to be confused with the directory suffix), in the matching rule portion of the filter to define the search type. The following table summarizes each type of search, the operator, and the equivalent suffix.

Table 8.1 Search types, operators, and suffixes

Search Type

 Operator

 Suffix

Less than

 <

 .1

Less than or equal to

 <=

 .2

Equality

 =

 .3

Greater than or equal to

 >=

 .4

Greater than

 >

 .5

Substring

 *

 .6

 

Matching Rule Filter Syntax

A matching rule provides special guidelines for how strings are to be compared in a search operation. In an international search, the matching rule tells the system what collation order and operator to use when performing the search operation. For example, a matching rule in an international search might tell the server to search for attribute values that come at or after llama in the Spanish collation order. The syntax of the matching rule filter is as follows:

<attr>:<matchingRule>:=<value>

where

 

matchingRule Formats

 There are several ways that you can represent the matchingRule portion of a search filter, the one you use is a matter of personal preference. The matching rule can be:

The syntax for each of these options is discussed in the following sections.

 

Using an OID for the matchingRule
Each locale supported by the directory server has an associated collation order OID. For a list of locales supported by the directory server and their associated OIDs, see Table D.1. You can use the collation order OID in the matchingRule portion of the matching rule filter as follows:

<attr>:<OID>:=(<relational operator><space><value>)

Notice that in this case, the relational operator is included in the value portion of the string, separated from the value by a single space. For example, to search for all departmentNumber attributes that are at or after N4709 in the Swedish collation order, use the following filter:


departmentNumber:2.16.840.1.113730.3.3.2.46.1:=>= N4709
 
Using a Language Tag for the matchingRule
 Each locale supported by the directory server has an associated language tag. For a list of locales supported by the directory server and their associated language tags, see Table D.1. You can use the language tag in the matchingRule portion of the matching rule filter as follows:

<attr>:<language-tag>:=(<relational operator><space><value>)

Notice that in this case, the relational operator is included in the value portion of the string, separated from the value by a single space. For example, to search the directory for all description attributes with a value of estudiante using the Spanish collation order, use the following filter:


cn:es:== estudiante
 
Using an OID and Suffix for the matchingRule
 As an alternative to using a relational operator + value pair, you can append a suffix that represents a specific operator to the OID in the matchingRule portion of the filter. For a list of locales supported by the directory server and their associated OIDs, see Table D.1. For a list of relational operators and their equivalent suffixes, see Table 8.1. You combine the OID and suffix as follows:

<attr>:<OID>+<suffix>:=<value>

For example, to search for businessCategory attributes with the value softwareproduckte in the German collation order, use the following filter:

businessCategory:2.16.840.1.113730.3.3.2.7.1.3:=softwareproduckte

 

Using a Language Tag and Suffix for the matchingRule
As an alternative to using a relational operator + value pair, you can append a suffix that represents a specific operator to the language tag in the matchingRule portion of the filter. For a list of locales supported by the directory server and their associated language tags, see Table D.1. For a list of relational operators and their equivalent suffixes, see Table 8.1. You combine the language tag and suffix as follows:

<attr>:<language-tag>+<suffix>:=<value>

For example, to search for all surnames that come at or after La Salle in the French collation order, use the following filter:

sn:fr.4:=La Salle

 

Using Wildcards in Matching Rule Filters

When performing a substring search using a matching rule filter, you can use the asterisk (*) character as a wildcard to represent zero or more characters. For example, to search for an attribute that starts with the letter "l" and ends with the letter "n," you would enter a "l*n" in the value portion of the search filter. Similarly, to search for all attribute values beginning with the letter "u," you would enter a value of "u*" in the value portion of the search filter.

To search for a value that contains the asterisk (*) character, you must escape the * with the designated escape sequence, \5c2a. For example, to search for all employees with businessCategory attribute values of Airius*Net product line, enter the following value in the search filter:

Airius\5c2a*Net product line

 

International Search Examples

The following sections show examples of how to perform international searches on directory server data. Each example shows all the possible matching rule filter formats so that you can become familiar with the formats and select the one that works the best for you.

 

Less Than Example

When you perform locale-specific search using the less than operator (<) or suffix (.1), you are searching for all attribute values that come before the given attribute in a specific collation order. For example, to search for all surnames that come before the surname Marquez in the Spanish collation order, you could use any of the following matching rule filters:


sn:2.16.840.1.113730.3.3.2.15.1:=< Marquez
sn:es:=< Marquez
sn:2.16.840.1.113730.3.3.2.15.1.1:=Marquez
sn:es.1:=Marquez
 

Less Than or Equal to Example

 When you perform locale-specific search using the less than or equal to operator (<=) or suffix (.2), you are searching for all attribute values that come at or before the given attribute in a specific collation order. For example, to search for all room numbers that come at or before room number CZ422 in the Hungarian collation order, you could use any of the following matching rule filters:


roomNumber:2.16.840.1.113730.3.3.2.23.1:=<= CZ422
roomNumber:hu:=<= CZ422
roomNumber:2.16.840.1.113730.3.3.2.23.1.2:=CZ422
roomNumber:hu.2:=CZ422
 

Equality Example

 When you perform locale-specific search using the equal to operator (=) or suffix (.3), you are searching for all attribute values that match the given attribute in a specific collation order. For example, to search for all businessCategory attributes with the value softwareproduckte in the German collation order, you could use any of the following matching rule filters:


businessCategory:2.16.840.1.113730.3.3.2.7.1:== softwareproduckte
businessCategory:de:== softwareproduckte
businessCategory:2.16.840.1.113730.3.3.2.7.1.3:=softwareproduckte
businessCategory:de.3:=softwareproduckte
 

Greater Than or Equal to Example

 When you perform locale-specific search using the greater than or equal to operator (>=) or suffix (.4), you are searching for all attribute values that come at or after the given attribute in a specific collation order. For example, to search for all localities that come at or Québec in the French collation order, you could use any of the following matching rule filters:


locality:2.16.840.1.113730.3.3.2.18.1:=>= Québec
locality:fr:=>= Québec
locality:2.16.840.1.113730.3.3.2.18.1.4:=Québec
locality:fr.4:=Québec
 

Greater Than Example

 When you perform locale-specific search using the greater than operator (>) or suffix (.5), you are searching for all attribute values that come at or before the given attribute in a specific collation order. For example, to search for all mail hosts that come after host schranka4 in the Czechoslovakian collation order, you could use any of the following matching rule filters:


mailHost:2.16.840.1.113730.3.3.2.5.1:=> schranka4
mailHost:en-GB:=> schranka4
mailHost:2.16.840.1.113730.3.3.2.5.1.5:=schranka4
mailHost:en-GB.5:=schranka4
 

Substring Example

 When you perform an international substring search, you are searching for all values that match the given pattern in the specified collation order. For example, to search for all user IDs that end in ming in the Chinese collation order, you could use any of the following matching rule filters:


uid:2.16.840.1.113730.3.3.2.49.1:=* *ming
uid:zh:=* *ming
uid:2.16.840.1.113730.3.3.2.49.1.6:=* *ming
uid:zh.6:=* *ming