Administrator’s Guide
Red Hat Directory Server                                                            
Previous
 Contents
 Index
 Next

Appendix B

Finding Directory Entries

You can find entries in your directory using any LDAP client. Most clients provide some form of a search interface that allows you to search the directory easily and retrieve entry information.

Note

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 6, "Managing Access Control."


This chapter covers the following topics:

Finding Entries Using the Server Console

Use the Directory tab of the Directory Server Console to browse the contents of the directory tree and search for specific entries in the directory.

  1. Make sure the Directory Server is running.
  2. Start Directory Server Console.
See "Starting Directory Server Console," on page 34, for specific instructions.
  1. On Directory Server Console, select the Directory tab.
Depending on the DN you used to authenticate to the directory, this tab displays the contents of the directory that you have access permissions to view. You can browse through the contents of the tree, or right-click an entry, and select Search from the pop-up menu. See the online help for information on using this feature.
Caution

Do not modify the contents of the o=NetscapeRoot suffix using the Directory tab unless instructed to do so by Red Hat Technical Support.


Using ldapsearch

You can 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.

This section contains information about the following topics:

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 you specify special characters, enclose the value in quotation marks (""). For example: 

-D "cn=Barbara Jensen,ou=Product Development,dc=example,dc=com"

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

ldapsearch Command-Line Format

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

ldapsearch [optional_options] [optional_search_filter] [optional_list_of_attributes]

where

Note

If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command. To retrieve regular attributes in addition to explicitly specified operational attributes, use an asterisk (*) in the list of attributes in the ldapsearch command.


Commonly Used ldapsearch Options

The following table lists the most commonly used ldapsearch command-line options. If you specify a value that contains a space [ ], the value should be surrounded by double quotation marks; for example, -b "ou=groups, dc=example,dc=com".

Option
Description
 
-b

Specifies the starting point for the search. The value specified here must be a distinguished name that currently exists in the database. This option is optional if the LDAP_BASEDN environment variable has been set to a base DN.

The value specified in this option should be provided in double quotation marks. For example: 

-b "cn=Barbara Jensen, ou=Product Development, 
dc=example,dc=com"

If you want to search the root DSE entry, specify an empty string here. For example:
-b "" 

-D

Specifies the distinguished name with which to authenticate to the server. This option is optional if anonymous access is supported by your server. If specified, this value must be a DN recognized by the Directory Server, and it must also have the authority to search for the entries. For example:

-D "uid=bjensen, dc=example,dc=com" 

-h

Specifies the hostname or IP address of the machine on which the Directory Server is installed. If you do not specify a host, ldapsearch uses the localhost. For example, -h mozilla. 

-l

Specifies the maximum number of seconds to wait for a search request to complete. Regardless of the value specified here, ldapsearch will never wait longer than is allowed by the server's nsslapd-timelimit attribute. For example, -l 300. The default value for the nsslapd-timelimit attribute is 3600 seconds. 

-p

Specifies the TCP port number that the Directory Server uses. For example, -p 1049. The default is 389. If -Z is used, the default is 636. 

-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 or defined by the LDAP_BASEDN environment variable.
  • one - Search only the immediate children of the entry specified in the -b option. Only the children are searched; the actual entry specified in the -b option is not searched.
  • sub - Search the entry specified in the -b option and all of its descendants; that is, perform a subtree search starting at the point identified in the -b option. This is the default. 
-w

Specifies the password associated with the distinguished name that is specified in the -D option. If you do not specify this option, anonymous access is used. For example, -w diner892. 

-x

Specifies that the search results are 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. In general, it is faster to sort on the server rather than on the client. 

-z

Specifies the maximum number of entries to return in response to a search request. For example, -z 1000.

Normally, regardless of the value specified here, ldapsearch never returns more entries than the number allowed by the server's nsslapd-sizelimit attribute. However, you can override this limitation by binding as the root DN when using this command-line argument. When you bind as the root DN, this option defaults to zero (0). The default value for the nsslapd-sizelimit attribute is 2000 entries.


For detailed information on all ldapsearch utility options, refer to the Red Hat Directory Server Configuration, Command, and File Reference.

ldapsearch Examples

In the next set of examples, suppose the following are true:

Returning All Entries

Given the previous information, the following call will return all entries in the directory: 

ldapsearch -h mozilla -b "dc=example,dc=com" -s sub 
"objectclass=*"

"objectclass=*" is a search filter that matches any entry in the directory.

Specifying Search Filters on the Command-Line

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

ldapsearch -h mozilla -b "dc=example,dc=com" "cn=babs jensen"

Searching the Root DSE Entry

The root DSE is a special entry that contains a list of all the suffixes supported by the local Directory Server. You can search this entry by supplying a search base of "". You must also specify a search scope of base and a filter of "objectclass=*". For example: 

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

Searching the Schema Entry

Directory Server stores all directory server schema in the special cn=schema entry. This entry contains information on every object class and attribute defined for your Directory Server.

You can examine the contents of this entry as follows: 

ldapsearch -h mozilla -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 option. 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 dc=example,dc=com. Then to search for cn=babs jensen in your directory, use the following command-line call: 

ldapsearch -h mozilla "cn=babs jensen"

In this example, the default scope of sub is used because the -s option was not used to specify the scope.

Displaying Subsets of Attributes

The ldapsearch command 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. Only operational attributes are not returned. If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command.

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

ldapsearch -h mozilla "objectclass=*" sn cn

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. The ldapsearch command runs each search in the order in which it appears in the file.

For example, if the file contains: 

sn=Francis

givenname=Richard

then ldapsearch first finds all the entries with the surname Francis and, then, all the entries with the givenname Richard. If an entry is found that matches both search criteria, then the 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 either search filter: 

ldapsearch -h mozilla -f searchdb

You can limit the set of attributes returned here by specifying the attribute names that you want at the end of the search line. For example, the following ldapsearch command performs both searches but returns only the DN and the givenname and sn attributes of each entry: 

ldapsearch -h mozilla -f searchdb sn givenname

Specifying DNs That Contain Commas in Search Filters

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 example.com Bolivia, S.A. subtree, use the following command: 

ldapsearch -h mozilla -s base -b "o=example.com Bolivia\, 
S.A.,dc=example,dc=com" "objectclass=*"

Using Client Authentication When Searching

This example shows user bjensen searching the directory using client authentication: 

ldapsearch -h mozilla -p 636 -b "dc=example,dc=com" -N 
"bjensenscertname" -Z -W certdbpassword -P 
/home/bjensen/certdb/cert.db "givenname=Richard"

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 you use 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.

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

cn=babs jensen

This search filter returns all entries that contain the common name Babs Jensen. Searches for common name values are not case sensitive.

When the common name attribute has values associated with a language tag, all of the values are returned. Thus, the following two attribute values 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 617,.

Search Filter Syntax

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. You can also define filters that use different attributes combined together with Boolean operators.

Search filters are described in detail in the following sections:

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 people entries, you can use the cn attribute to search for people with a specific common name.

Examples of attributes that people entries might include:

For a listing of the attributes associated with types of entries, see the Red Hat Directory Server Schema Reference.

Using Operators in Search Filters

The operators that you can use in search filters are listed in Table B-1. 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 charactersets, see "Searching an Internationalized Directory," on page 601.

Table B-1 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

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

where Boolean-operator is any one of the Boolean operators listed in Table B-2.

Boolean operators can be combined and nested together to form complex expressions, such as: 

(Boolean-operator(filter)((Boolean-operator(filter)(filter)))

The Boolean operators available for use with search filters include the following:

Table B-2 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:

Search Filter Examples

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

manager=*

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

cn=Ray Kultgen

The following filter returns all entries that do not contain the common name Ray Kultgen: 

(!(cn=Ray Kultgen))

The following filter returns all entries that contain a description attribute that contains the substring X.500: 

description=*X.500*

The following 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*)))

The following filter returns all 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,dc=example,dc=com)(manager=cn=Cindy 
Zwaska,ou=Marketing,dc=example,dc=com)))

The following filter returns all entries that do not represent a person: 

(!(objectClass=person))

The following filter returns all entries that do not represent a person and whose common name is similar to printer3b: 

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

Searching an Internationalized Directory

When you perform search operations, you can request that the directory sort the results based on any language for which the server has a supporting collation order. For a listing of the collation orders supported by the directory, see "Identifying Supported Locales," on page 617.

Note

When performing internationalized searches, you must perform an LDAP v3 search; therefore, do not specify the -V2 option on the call to 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 597. For information on searching internationalized directories using the Users and Groups portion of the Red Hat Console, refer to the online help or Managing Servers with Red Hat Console.

This section covers the following topics:

Matching Rule Filter Syntax

A matching rule provides special guidelines for how the directory compares strings during 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:

Matching Rule Formats

The matching rule portion of a search filter can be represented in several ways. The one you use is a matter of personal preference. The matching rule can be represented in the following ways:

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

Using an OID for the Matching Rule

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 617,.

You can use the collation order OID in the matching rule portion of the matching rule filter as follows: 

attr:OID:=(relational_operator value)

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 Matching Rule

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 617,.

You can use the language tag in the matching rule portion of the matching rule filter as follows: 

attr:language-tag:=(relational_operator value)

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 Matching Rule

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 matching rule portion of the filter. 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:=softwareprodukte

The .3 in the previous example is the equality suffix.

For a list of locales supported by the directory server and their associated OIDs, see Table D-1, on page 617,. For a list of relational operators and their equivalent suffixes, see Table B-3, on page 605,.

Using a Language Tag and Suffix for the Matching Rule

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 matching rule portion of the filter. 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

For a list of locales supported by the directory server and their associated language tags, see Table D-1, on page 617,. For a list of relational operators and their equivalent suffixes, see Table B-3, on page 605,.

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 value 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 Example*Net product line, enter the following value in the search filter: 

Example\2a*Net product line

Supported Search Types

The directory server supports the following types of international searches:

Approximate, or phonetic, and presence searches are supported only 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. Table B-3 summarizes each type of search, the operator, and the equivalent suffix.

Table B-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

International Search Examples

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

Less-Than Example

When you perform a locale-specific search using the less-than operator (<), or suffix (.1), you search 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 a locale-specific search using the less-than or equal-to operator (<=), or suffix (.2), you search 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 a locale-specific search using the equal to operator (=), or suffix (.3), you search 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 softwareprodukte 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:== 
softwareprodukte

businessCategory:de:== softwareprodukte

businessCategory:2.16.840.1.113730.3.3.2.7.1.3:=softwareprodukte

businessCategory:de.3:=softwareprodukte

Greater-Than or Equal-to Example

When you perform a locale-specific search using the greater-than or equal-to operator (>=), or suffix (.4), you search 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 after 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 a locale-specific search using the greater-than operator (>), or suffix (.5), you search 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:cs:=> schranka4

mailHost:2.16.840.1.113730.3.3.2.5.1.5:=schranka4

mailHost:cs.5:=schranka4

Substring Example

When you perform an international substring search, you search 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

Substring search filters that use DN-valued attributes, such as modifiersName or memberOf, do not always match entries correctly if the filter contains one or more space characters.

To work around this problem, use the entire DN in the filter instead of a substring, or ensure that the DN substring in the filter begins at an RDN boundary; that is, make sure it starts with a "type=" part of the DN. For example, this filter should not be used: 

(memberof=*Domain Administrators*)

But either one of these will work correctly: 

(memberof=cn=Domain Administrators*)

(memberof=cn=Domain Administrators,ou=Groups,dc=example,dc=com)



Previous
 Contents
 Index
 Next
© 2001 Sun Microsystems, Inc. Used by permission. © 2005 Red Hat, Inc. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

 last updated May 20, 2005