Sun Java System Directory Server Enterprise Edition 6.1 Reference

Searching the Directory

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

The access control that has been set in your directory determines 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.

Searching the Directory With ldapsearch

You can use the ldapsearch command-line utility to locate and retrieve directory entries. Note that the ldapsearch utility described in this section is not the utility provided with the Solaris platform, but is part of the Directory Server Resource Kit.

This utility opens a connection to the server with a specified a user identity (usually a distinguished name) and password, and locates entries based on a 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.

ldapsearch Command-Line Format

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

ldapsearch [optional_options] [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.


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=Charlene Daniels,ou=People,dc=example,dc=com"

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

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=example,dc=com".

-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=Charlene Daniels, ou=People, dc=example,dc=com"
-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 Directory Server, and it must also have the authority to search for the entries. For example:

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

-h

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

-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 (except in the case of a persistent search.)Sun Java System Directory Server Enterprise Edition 6.1 Reference.

For example, -l 300. The default value for the nsslapd-timelimit attribute is 3,600 seconds (1 hour.)

-p

Specifies the TCP port number that Directory Server uses. For example, -p 5201. The default is 389, and 636 when the SSL options are used.

-s

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

  • 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, although server-side sorting uses server resources.

-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 2,000 entries.

For detailed information on all ldapsearch utility options, refer to ldapmodify(1).

ldapsearch Examples

In the next set of examples, the following assumptions are made:

Returning All Entries

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

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config
 -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 myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -b "dc=example,dc=com" "(cn=Charlene Daniels)"

Searching the Root DSE Entry

The root DSE is a special entry that contains information related to the current server instance, such as a list of supported suffixes, available authentication mechanisms, and so forth. 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 myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -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 myServer -p 5201 -D cn=admin,cn=Administrators,cn=config
 -b "cn=schema" -s base "(objectclass=*)"

Note –

For strict compliance, the location of the schema subentry for a given entry is specified by the subschemaSubentry operational attribute. In this version of Directory Server, the value of this attribute is always cn=schema.


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, if you have set LDAP_BASEDN to dc=example,dc=com, you can search for (cn=Charlene Daniels) in your directory using the following command-line call:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(cn=Charlene Daniels)"

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. For more information on operational attributes, refer to the TODO: No more AdminServerAdminGuide.

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:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" sn cn

This example assumes you set your search base with LDAP_BASEDN.

Searching Multi-Valued Attributes

During a search, Directory Server does not necessarily return multi-valued attributes in sorted order. For example, suppose you want to search for configuration attributes on cn=config requiring that the server be restarted before changes take effect.

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -b cn=config "(objectclass=*)" nsslapd-requiresrestart

The following result is returned:

dn: cn=config
nsslapd-requiresrestart: cn=config:nsslapd-port
nsslapd-requiresrestart: cn=config:nsslapd-secureport
nsslapd-requiresrestart: cn=config:nsslapd-plugin
nsslapd-requiresrestart: cn=config:nsslapd-changelogdir
nsslapd-requiresrestart: cn=config:nsslapd-changelogsuffix
nsslapd-requiresrestart: cn=config:nsslapd-changelogmaxentries
nsslapd-requiresrestart: cn=config:nsslapd-changelogmaxage
nsslapd-requiresrestart: cn=config:nsslapd-db-locks
nsslapd-requiresrestart: cn=config:nsslapd-return-exact-case
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-allidsthreshold
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-dbcachesize
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-dbncache
nsslapd-requiresrestart: cn=config,cn=ldbm database,cn=plugins,
  cn=config:nsslapd-directory
nsslapd-requiresrestart: cn=encryption,cn=config:nssslsessiontimeout
nsslapd-requiresrestart: cn=encryption,cn=config:nssslclientauth
nsslapd-requiresrestart: cn=encryption,cn=config:nssslserverauth
nsslapd-requiresrestart: cn=encryption,cn=config:nsssl2
nsslapd-requiresrestart: cn=encryption,cn=config:nsssl3
...

As shown here, the nsslapd-requiresrestart attribute takes multiple values. These values are not, however, in sorted order. If you develop an application that requires multi-valued attributes in sorted order, make sure that your application performs the sort.

Using Client Authentication When Searching

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

ldapsearch -h myServer -p 636 -b "dc=example,dc=com"
  -N  "cdanielsscertname" -Z -W certdbpassword
  -P /home/cdaniels/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 Lucie Du Bois:

(cn=Lucie Du Bois)

This search filter returns all entries that contain the common name Lucie Du Bois. 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: Lucie Du Bois
cn;lang-fr: Lucie Du Bois

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.

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:

Using Operators in Search Filters

The operators that you can use in search filters are listed in Table 13–5:

Table 13–5 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=*Johnsoncn=*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

The Approximate operator is experimental and works only with English language strings. It does not work with non-ASCII based strings, such as Ja or Zn. 

Extended operators exist that extend searches to dn attributes (cn:dn:=John, for example) and provide support for internationalized searches.

Using OIDs in Search Filters

LDAPv3 enables you to build match operators and rules for a particular attribute. Matching rules define how to compare attribute values with a particular syntax. In other words, a matching rule defines how potentially matching attributes are compared. For example, a matching rule can define whether or not to take text case into account when comparing attributes.

When the rules are created, they can be referred to in a search filter.

For example, the following search filter compares entries containing the surname “Jensen” by using the matching rule designated by OID 2.5.13.5:

(sn:2.5.13.5:=Jensen)

The following example illustrates the use of the ":dn" notation to indicate that OID 2.5.13.5 should be used when making comparisons, and that the attributes of an entry\qs distinguished name should be considered part of the entry when evaluating the match:

(sn:dn:2.5.13.5:=Jensen)

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 13–6.

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 13–6 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))

The use of the NOT operator results in an unindexed search. 

Boolean expressions are evaluated in the following order:

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=Daniels)
(givenname=Charlene)

then ldapsearch first finds all the entries with the surname Daniels, and then all the entries with the given name Charlene. If an entry is found that matches both search criteria, 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. The following returns all the entries that match either search filter:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -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 myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 -f searchdb sn givenname

Specifying Non 7-Bit ASCII Characters in Search Filters

Non 7-bit ASCII characters in search filters must be replaced with a representation of the character, where each byte of the UTF-8 encoding is preceded by a backslash. In UTF-8, characters are represented by a hexadecimal code for each byte.

For example, the character é has UTF-8 representation c3a9. Thus, in a search filter, you represent é as \\c3\\a9. So, to search for cn=Véronique Martin:

ldapsearch -h myServer -b "dc=example,dc=com" "(cn=V\\c3\\a9ronique Martin)"

The special characters listed in Table 13–7 must also be represented in this fashion when used in search filters.

Table 13–7 Special Characters in Search Filters

Special character  

Value With Special Character  

Example Filter  

Five*Star

(cn=Five\\2aStar)

\\ 

c:\\File

(cn=\\5cFile)

() 

John (2nd)

(cn=John \\282nd\\29)

null 

0004

(bin=\\00\\00\\00\\04)

Escaped Characters in Distinguished Names within Search Filters

When using a DN in any part of Directory Server, you must escape commas and certain other special characters with a backslash (\\). If you are using a DN in a search filter, the backslash used for escaping special characters in DNs must be represented by \\5c. For example:

DN: cn=Julie Fulmer,ou=Marketing\\,Bolivia,dc=example,dc=com

DN in a search filter: ldapsearch -h myServer -b "dc=example,dc=com" "(manager=cn=Julie Fulmer,ou=Marketing\\5c,Bolivia,dc=example,dc=com)"

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

Note that the previous filter will have a negative performance impact and should be used as part of a complex search. The following filter returns all entries that do not represent a person and whose common name is similar to printer3b:

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

Searching for Operational Attributes

If you want operational attributes returned as a result of a search operation, you must explicitly specify them in the search command.

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" aci

To retrieve regular attributes in addition to explicitly specified operational attributes, specify “*” in addition to the operational attributes. For example:

ldapsearch -h myServer -p 5201 -D cn=admin,cn=Administrators,cn=config -w -
 "(objectclass=*)" aci *