Previous Contents Index DocHome Next |
iPlanet Directory Server 5.1 Administrator's Guide |
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 easily search the directory and retrieve entry information.
Note The access control that you or your administrator have set in your directory determine the results of your searches. Common users typically do not "see" much of the directory, and directory administrators have full access to all data, including configuration.
For information on setting access control in your directory, see "Managing Access Control," on page 187.
This chapter covers the following topics:
Finding Entries Using the Server Console
Finding Entries Using the Server Console
Use the Directory tab of the iPlanet Directory Server Console to browse the contents of the directory tree and search for specific entries in the directory.
Make sure the Directory Server is running.
Start iPlanet Directory Server Console.
See "Starting iPlanet Directory Server Console," on page 26 for specific instructions.
On iPlanet 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.
The Search dialog provides a simple interface for finding names in the directory. This dialog performs a search from the node in the directory that was selected when the dialog was invoked. Search from the highest level of the directory for a wider search, or from a lower subtree for a quicker search.
The Advanced Search allows you to refine your search to certain attributes and their values. The Filtered Search is then also available if you want to search with your own LDAP filter string.
See the online help for further information on using this feature.
Note Searches performed with the Search dialog do not follow referrals.
If you want to view or edit the entries returned by your search, click OK to close the Search dialog. The search results will be listed in another window where double-clicking any name will display its full entry. Entries are displayed in the Edit dialog and may be modified if allowed by the access control.
Otherwise, click Cancel to close the Search dialog without further displaying the search results.
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.
This section contains information about the following topics:
Using Special Characters
ldapsearch Command-Line Format
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=siroe,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]
optional_options represents a series of command-line options. These must be specified before the search filter, if any.
optional_search_filter represents an LDAP search filter as described in "LDAP Search Filters". Do not specify a search filter if you are supplying search filters in a file using the -f option.
optional_list_of_attributes represents a list of attributes separated by a space. Specifying a list of attributes reduces the number of attributes returned in the search results. This list of attributes must appear after the search filter. For an example, see "Displaying Subsets of Attributes". If you do not specify a list of attributes, the search returns values for all attributes permitted by the access control set in the directory (with the exception of operational attributes).
Commonly Used ldapsearch options
The following 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=siroe,dc=com".
ldapsearch Examples
In the next set of examples, suppose the following are true:
You want to perform a search of all entries in the directory.
You have configured your directory to support anonymous access for search and read. You do not have to specify any bind information in order to perform the search. For more information on anonymous access, see "Defining User Access - userdn Keyword," on page 205.
The server is located on hostname mozilla.
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.
The suffix under which all data is stored is dc=siroe,dc=com.
Returning All Entries
Given the previous information, the following call will return all entries in the directory:
ldapsearch -h mozilla -b "dc=siroe,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=siroe,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
iPlanet 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=*"
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 -b "dc=siroe,dc=com" "objectclass=*" sn cn
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 siroe.com Bolivia, S.A. subtree, use the following command:
ldapsearch -h mozilla -s base -b "o=siroe.com Bolivia\, S.A.,dc=siroe,dc=com" "objectclass=*"
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:
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:
For a list of all the supported language tags, see Table D-1 on page 523.
Search Filter Syntax
The basic syntax of a search filter is:
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
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:
cn (the person's common name)
sn (the person's surname, or last name, or family name)
telephoneNumber (the person's telephone number)
buildingName (the name of the building in which the person resides) For a listing of the attributes associated with types of entries, see the iPlanet Directory Server Schema Reference.
Using Operators in Search Filters
The operators that you can use in search filters are listed in Table B-1:
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".
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:
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:
The following filter searches for entries containing the common name Ray Kultgen. This is also known as an equality search:
The following filter returns all entries that do not contain the common name Ray Kultgen:
The following filter returns all entries that contain a description attribute that contains the substring 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=siroe,dc=com)(manager=cn=Cindy Zwaska,ou=Marketing,dc=siroe,dc=com)))
The following filter returns all entries that do not represent a 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 523.
This section focuses on the matching rule filter portion of the ldapsearch syntax. For more information on general ldapsearch syntax, see "LDAP Search Filters". For information on searching internationalized directories using the Users and Groups portion of the iPlanet Console, refer to the online help or Managing Servers with iPlanet Console.
This section covers the following topics:
Matching Rule Filter Syntax
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 is an attribute belonging to 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 "Matching Rule Formats".
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 matching rule format you use.
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:
As the OID of the collation order for the locale on which you want to base your search.
As the language tag associated with the collation order on which you want to base your search.
As the OID of the collation order and a suffix that represents a relational operator.
As the language tag associated with the collation order and 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 Matching Rule
Using a Language Tag for the Matching Rule
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 523.
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 523.
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:
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:
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 523. For a list of relational operators and their equivalent suffixes, see Table B-3.
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:
For a list of locales supported by the directory server and their associated language tags, see Table D-1 on page 523. For a list of relational operators and their equivalent suffixes, see Table B-3.
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 character, \. For example, to search for all employees with businessCategory attribute values of Siroe*Net product line, enter the following value in the search filter:
Supported Search Types
The directory server supports the following types of international searches:
equality (=) 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
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
Previous Contents Index DocHome Next
Copyright © 2002 Sun Microsystems, Inc. Some preexisting portions Copyright © 2001 Netscape Communications Corp. All rights reserved.
Last Updated February 26, 2002