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:

the Users and Groups area of your administration server

the directory server gateway

the ldapsearch command-line utility

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:

LDAP Search Filters

Using ldapsearch

Searching an Internationalized Directory

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 on page 500.

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:

cn (the person's common name)

sn (the person's surname, or last name, or family name)

telephonenumber (the person's telephone number)

employeenumber (the person's employeenumber)

l (the location where you can find the person)

For a listing of the attributes associated with types of entries, see Appendix B, "Attributes" of the online Administrator's Guide.

Using Operators in Search Filters

A search filter operator can be one of the following:

Table 8.1


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`

Note

In addition to these search filters, you can specify special filters to work with a preferred language collation order. For information on how to search a directory with international character sets, see

"Searching an Internationalized Directory" on page 185

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:

Table 8.2


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:

innermost to outermost parenthetical expressions first

all expressions from left to right

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" on page 29.

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"

Note

Depending on which command-line interpreter you are using, you should use either single or double quotation marks for this purpose. Refer to your operating system documentation for more information.

In addition, if you are using DNs that contain commas, you must escape the commas with a backslash (\). For example:


-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:

<optional parameters> are a series of command line parameters. These must be specified before the search filter, if any.

<optional search filter> is an LDAP search filter as described in "LDAP Search Filters" on page 172. Do not specify a search filter if you are supplying search filters in a file using the -f parameter.

<optional list of attributes> are space separated attributes that reduce the scope of the attributes returned in the search results. This list of attributes must appear after the search filter. For a usage example, see "Displaying Subsets of Attributes" on page 183.

Commonly Used ldapsearch Parameters

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

-D

-D uid=bjensen, o=airius.com

-w

-w diner89&2

-h

-h 
cyclops

-p

-p 
1049

-b

LDAP_BASEDN

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

-b ""

-s

Specifies the scope of the search. The scope can be one of the following:

base--Search only the entry specified in the -b option.

one--Search only the most immediate children of the entry specified in the -b parameter. Note that only the children are searched; the actual entry specified in the -b parameter is not searched.

sub--Search the entry specified in the -b parameter and all of its descendants. That is, perform a subtree search starting at the point identified in the -b parameter. This is the default.

-l

ldapsearch

-l 
300

-x

Specifies that the search results are to be sorted on the server rather than on the client. This is useful if you want to sort according to a matching rule, as with an international search. This is also useful if your client cannot sort or you do not want to waste client CPU cycles.
-z

Specifies the maximum number of entries to return in response to a search request. Regardless of the value specified here, ldapsearch never returns more entries than is allowed by the server's

Size Limit in Entries

-z 1000

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" on page 234.

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

-Z

Specifies that SSL is to be used for the search request.
-P

-P 
c:\security\cert.db

<NSHOME>/alias

-P 
c:\Netscape\Suitespot\alias\client-cert.db

-N

-K

-W

-Q

-I

Specifies the personal identification number (PIN) associated with the FORTEZZA crypto card and certificate you specified in the -Q parameter.
-X

Specifies the path and filename of the compromised key list (CKL).

Additional ldapsearch Parameters

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

-f

Specifies the file containing the search filter(s) to be used in the search. For example, -f search_filters. Search filters are described in

"LDAP Search Filters" on page 172

-A

Specifies that the search retrieve the attributes only, not the attribute values. This parameter is useful if you just want to determine if an attribute is present for an entry and you are not interested in the value.
-a

Specifies how alias dereferencing is completed. Value can be "never," "always," "search," or "find." Default value is "never."
-m

Manage smart referrals. Causes the server to not return the smart referral contained on the entry, but to instead return the actual entry containing the referral. Use this parameter if you are attempting to search for entries that contain smart referrals. For more information about smart referrals, see

"Creating and Changing Smart Referrals" on page 275

-n

Specifies that the search is not to be actually performed, but that ldapsearch is to show what it would do with the specified input.
-R

Specifies that referrals are not to be followed automatically.
-O

ldapsearch

-O 2

-S

-S sn

-t

Specifies that the results be written to a set of temporary files.
-u

Specifies that the user-friendly form of the distinguished name be used in the output.
-v

Specifies that the utility is to run in verbose mode.
-V

-V 
2

-B

Legacy option. Not currently supported.
-F

Legacy option. Not currently supported.
-L

Legacy option. Not currently supported.
-o

Legacy option. Not currently supported.

ldapsearch Examples

Suppose:

You want to perform a search for all entries in the directory.

You have configured your directory to support anonymous access for search and read. In this case, you do not have to specify any bind information in order to perform the search. For more information on anonymous access, see "Anonymous Access" on page 88.

The server is located on hostname cyclops.

The server uses port number 389. Since this is the default port, you do not have to identify the port number on the search request.

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" on page 499.

Note

ldapsearch

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

Supported Search Types

The directory server supports the following types of international searches:

equality (=)

substring (*)

greater than (>)

greater than or equal to (>=)

less than (<)

less than or equal to (<=)

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.3 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

<attr> is the attribute of entries you're searching for, such as cn or mail

<matchingRule> is a string that identifies either the collation order or the collation order and a relational operator, depending on the format you prefer. For a discussion of matching rule formats, see "matchingRule Formats" on page 187.

<value> is either the attribute value you want to search for or a relational operator plus the attribute value you want to search for; the syntax of the value portion of the filter depends on the matchingRule format you use.

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 OID for the collation order you want to base your search on

the language tag associated with the collation order you want to base your search on

the OID for the collation order you want to base your search on plus a suffix that represents a relational operator

the language tag associated with the collation order you want to base your search on plus a suffix that represents a relational operator

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 on page 500. 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 on page 500. 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


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

Museum

Finding Directory Entries

LDAP Search Filters

Search Filter Syntax

Using Attributes in Search Filters

Using Operators in Search Filters

Using Multiple Search Filters

Boolean Operators

Search Filter Examples

Using ldapsearch

Using Special Characters

ldapsearch Command Line Format

Commonly Used ldapsearch Parameters

SSL Parameters

Additional ldapsearch Parameters

ldapsearch Examples

Specifying Search Filters on the Command Line

Searching the DSE Entry

Searching the Schema Entry

Using LDAP_BASEDN

Displaying Subsets of Attributes

Specifying Search Filters Using a File

Specifying DNs that Contain Commas

Searching an Internationalized Directory

Supported Search Types

Matching Rule Filter Syntax

matchingRule Formats

Using an OID for the matchingRule

Using a Language Tag for the matchingRule

Using an OID and Suffix for the matchingRule

Using a Language Tag and Suffix for the matchingRule

Using Wildcards in Matching Rule Filters

International Search Examples

Less Than Example

Less Than or Equal to Example

Equality Example

Greater Than or Equal to Example

Greater Than Example

Substring Example