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. See Chapter 2, "LDAP Data Interchange Format," for information on LDIF.
For information on where you can find the command line utilities in your directory server installation, see "Finding the Command-Line Utilities".
Using Special Characters
When using the ldapsearch command-line utility, you may need to specify values that contain characters that have special meaning to the command-line interpreter (such as space [ ], asterisk [*], backslash [\], and so forth). When this situation occurs, enclose the value in quotation marks (""). For example:
-D "cn=Barbara Jensen, ou=Product Development, o=airius.com"
Depending on which command-line interpreter you use, 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 in values, 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 use ldapsearch, you must enter the command using the following format:
ldapsearch [<optional parameters>] [<optional search filter>]
[<optional list of attributes>]
where
Commonly Used ldapsearch Parameters
The following lists the most commonly used ldapsearch command-line parameters. If you specify a value that contains a space [ ], the value should be surrounded by double quotation marks, for example, -b "ou=groups, o=airius.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 parameter is
optional if the LDAP_BASEDN environment variable has been set to a base DN.
The value specified in this parameter should be provided in double quotation
marks. For example: -b "cn=Barbara Jensen, ou=Product
Development, o=airius.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
parameter 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, o=airius.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 "Time Limit" parameter. For example,
-l 300. The default value for the Time Limit parameter is 3,600 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:
-w. Specifies the password associated with the distinguished name that is specified
in the -D option. If you do not specify this parameter, anonymous access is
used. For example, -w diner89&2.
-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 "Size Limit" parameter. However, you can override this limitation by
binding as the root DN when using this command-line argument. This is
because, when you bind as the root DN, this parameter defaults to zero (0).
The default value for the Size Limit parameter is 2,000 entries.
SSL Parameters
You can use the following command-line parameters to specify that ldapsearch use LDAPS when communicating with your SSL-enabled directory server. You also use these parameters if you want to use certificate-based authentication. These parameters are valid only when LDAPS has been turned on and configured for your Directory Server. For more information on certificate-based authentication, see "Using Certificate-Based Authentication". For information on creating a certificate database for use with LDAP clients, see "Creating Certificate Databases for LDAP Clients".
Make sure that you specify your directory server's encrypted port, using the -p argument, when you use these parameters.
-I. FORTEZZA Only. Specifies the personal identification number (PIN) associated
with the FORTEZZA crypto card and certificate you specified in the -Q
parameter. For example, 1234.
-K. Specifies the name of the certificate key used for certificate-based client
authentication. For example, -K Server-Key.
-m. Specifies the path to the security module database. For example,
<NSHOME>/netscape/secmodule.db. You only need to specify this option
if the security module database is in a different directory from the certificate
database itself.
-N. Specifies the certificate name to use for certificate-based client authentication.
For example, -N "Server-Cert". If this option is specified, then the -Z, -P,
and -W parameters are required. Also, if this option is specified, then the -D
and -w parameters must not be specified, or certificate-based authentication
will not occur and the bind operation will use the authentication credentials
specified on -D and -w.
-P. Specifies the path and filename of the certificate database of the client. This
parameter is used only with the -Z parameter. When used on a machine where
an SSL-enabled version of Netscape Communicator is configured, the path
specified on this option can be that of the certificate database for
Communicator. For example, -P c:\security\cert.db. The client security
files can also be stored on the directory server in the <NSHOME>/alias
directory. In this case, the -P parameter would call out a path and filename
similar to the following:
-P c:\Netscape\Server4\alias\client-cert.db.
-Q. FORTEZZA Only. Specifies the number of the slot into which you plugged
your FORTEZZA crypto card and, optionally, the name of the FORTEZZA
certificate you want to use. The slot number and certificate name are separated
by a colon. For example, if you plugged your crypto card into slot 2 and want
to use the certificate named doe, you would specify the following: -Q 2:doe.
-W. Specifies the password for the certificate database identified in the -P
parameter. For example, -W serverpassword.
-X. FORTEZZA Only. Specifies the path and filename of the compromised key list
(CKL).
-Z. Specifies that SSL is to be used for the search request.
Additional ldapsearch Parameters
To further customize a search, use the following optional parameters:
-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."
-B. Print binary values. Specifies that binary values stored in the directory should
be printed in the search output. If you use -B and -o together, then the binary
data will not use base 64 encoding.
-F. Specify a different separator. This option can only be used with -o. This
parameter allows you to specify a separator other than a colon ":" to separate
an attribute name from the corresponding value. For example, -F +
-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". Omit this parameter if you want to supply a search filter directly to the
command line.
-G. Virtual list search. Allows you to specify the number of entries before or after
the search target, and the index or value of the first entry returned. For
example, if you are sorting by surname, -G 20:30:johnson returns the first
entry with a surname equal to or less than johnson, in addition to 20 entries
that come before it and 30 entries that come after it. If there are fewer matching
entries in the directory than the "before" or "after" number requested by the
search, all available entries before/after the search target that match the search
criteria are returned.
-i. Character set. Specifies the character set to use for command line input. The
default is the character set specified in the LANG environment variable. You
might want to use this parameter to perform the conversion from the specified
character set to UTF8, thus overriding the environment variable setting.
Using this argument, you can input the bind DN, base DN, and the search filter
pattern in the specified character set. ldapsearch converts the input from
these arguments before it processes the search request. For example, -i no
indicates that the bind DN, base DN, and search filter are provided in
Norwegian.
This argument only affects the command-line input, that is, if you specify a file
containing a search filter (with the -f parameter) ldapsearch will not
convert the data in the file.
-k. Conversion routines directory. If you want to specify a sort language that is not
supported by default in this release of the directory server, for example, one
obtained from a later release of the LDAP SDK, you need to supply the
directory in which you store the conversion routines. You can view the list of
supported languages in Table B.1.
When performing the search, the server looks in the current working directory.
However, if the conversion routines are not in the current working directory
you need to specify this option when using ldapsearch. The conversion
routines directory is located by default in <NSHOME>/<ServerID>/lib/nls.
-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".
-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.
-O. Specifies the maximum number of referral hops ldapsearch should
automatically follow. For example, -O 2.
-o. Specifies that the output for individual values be formatted without line breaks
and that equal signs "=" be used to separate attribute names from values. This
argument produces output in a non-LDIF format.
-R. Specifies that referrals are not to be followed automatically. By default, referrals
are followed automatically.
-S. Specifies the attribute to use as the sort criteria. For example, -S sn. You can
use multiple -S arguments if you want to further define the sort order. In the
following example, the search results will be sorted first by surname and then
by given name:
-S sn -S givenname
The default is not to sort the returned entries.
-T. Specifies that no line breaks should be used within individual values in the
search results.
-t. Specifies that the results be written to a set of temporary files. When you use
this option, each attribute value is placed in a separate file within the system
temporary directory. No base64 encoding is performed on the values,
regardless of the content.
-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. Specifies the LDAP version number to be used on the search. For example, -V
2. LDAP v3 is the default. You cannot perform an LDAP v3 search against a
directory server that only supports LDAP v2. Only use LDAP v2 when
connecting to LDAP v2 servers, such as Netscape Directory Server 1.x.
-y. Specifies the proxy DN to use for the search. This argument is provided for
testing purposes. For more information about proxied authorization, see
"Overview of Proxied Authorization".
ldapsearch Examples
For the following 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 "o=airius.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 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 mozilla -b "o=airius.com" "cn=babs jensen"
Searching the root DSE Entry
Among other things, the root Directory Server Entry (root DSE) 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
The Netscape Directory Server stores all directory server schema 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 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 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 mozilla "cn=babs jensen"
In this example, the default scope of "sub" is used.
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), with the exception of operational attributes. 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 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 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. 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 first finds all the entries who's surname is Francis, and then all the entries whose givenname is Richard. 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 either search filter:
ldapsearch -h mozilla -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 sn attributes:
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 Airius Bolivia, S.A. subtree, you would use the following command:
ldapsearch -h mozilla -s base -b "o=Airius Bolivia\, S.A."
"objectclass=*"
Using Client Authentication When Searching
This example shows user bjensen searching the directory using client authentication.
ldapsearch -h mozilla -p 636 -b "o=airius.com" -N "bjensenscertname" -Z
-W certdbpassword -P /home/bjensen/certdb/cert.db "givenname=Richard"
Previous
