ldapsearch

The LDAP search tool and sample program

Synopsis

ldapsearch [-a deref] [-A] [-b searchbase] [-B] [-C charset] [-d debuglevel]
[-D binddn] [-e] [-f file] [-F sep] [-G realm] [-h ldaphost] [-i file] [-K keyfile]
[-l timelimit] [-L] [-m mechanism] [-M] [-n] [-N certificatename]
[-o attr_type] [-O maxhops] [-p ldapport] [-P keyfilepw] [-q pagesize]
[-R] [-s scope ] [-t] [-T seconds] [-U username] [-v] [-V version]
[-w passwd | ?] [-z sizelimit] [-y proxydn] [-Y] [-Z]
filter [-9 p] [-9 s] [attrs...]

Description

ldapsearch is a command-line interface to the ldap_search application programming interface (API).

ldapsearch opens a connection to an LDAP server, binds, and performs a search using the filter. The filter should conform to the string representation for LDAP filters (see ldap_search in the Directory Server APIs for more information about filters).

If ldapsearch finds one or more entries, the attributes specified by attrs are retrieved and the entries and values are printed to standard output. If no attrs are listed, all attributes are returned.

To display syntax help for ldapsearch, type ldapsearch -?.

Options

-a deref
Specify how aliases dereferencing is done. deref should be one of never, always, search, or find to specify that aliases are never dereferenced, always dereferenced, dereferenced when searching, or dereferenced only when locating the base object for the search. The default is to never dereference aliases.
-A
Retrieve attributes only (no values). This is useful when you just want to see if an attribute is present in an entry and are not interested in the specific values.
-b searchbase
Use searchbase as the starting point for the search instead of the default. If -b is not specified, this utility will examine the LDAP_BASEDN environment variable for a searchbase definition. If neither is set, the default base is set to "".
-B
Do not suppress display of non-ASCII values. This is useful when dealing with values that appear in alternate character sets such as ISO-8859.1. This option is implied by the -L option.
-C charset
Specifies that strings supplied as input to the ldapsearch utility are represented in a local character set (as specified by charset). String input includes the filter, the bind DN and the base DN. Similarly, when displaying data, ldapsearch converts data received from the LDAP server to the specified character set. Use the -C charset option if the input string codepage is different from the job codepage value. Refer to the ldap_set_iconv_local_charset() API to see supported charset values. Also, if the -C option and the -L option are both specified, input is assumed to be in the specified character set, but output from ldapsearch is always preserved in its UTF-8 representation, or a base-64 encoded representation of the data when non-printable characters are detected. This is the case because standard LDIF files only contain UTF-8 (or base-64 encoded UTF-8) representations of string data. Note that the supported values for charset are the same values supported for the charset tag that is optionally defined in Version 1 LDIF files.
-d debuglevel
Set the LDAP debugging level to debuglevel.
-D binddn
Use binddn to bind to the LDAP directory. binddn should be a string-represented DN (see LDAP Distinguished Names). When used with -m DIGEST-MD5, it is used to specify the authorization ID. It can either be a DN, or an authzId string starting with "u:" or "dn:".
-e
Display the LDAP library version information and exit.
-F sep
Use sep as the field separator between attribute names and values. The default separator is `=', unless the -L flag has been specified, in which case this option is ignored.
-G realm
Specify the realm. This parameter is optional. When used with -m DIGEST-MD5, the value is passed to the server during the bind.
-h ldaphost
Specify an alternate host on which the ldap server is running.
-i file
Read a series of lines from file, performing one LDAP search for each line. In this case, the filter given on the command line is treated as a pattern where the first occurrence of %s is replaced with a line from file. If file is a single "-" character, then the lines are read from standard input.
-K keyfile
Specify the name of the SSL key database file. If the key database file is not in the current directory, specify the fully-qualified key database filename.

If the utility cannot locate a key database, it will use a hard-coded set of default trusted certificate authority roots. The key database file typically contains one or more certificates of certification authorities (CAs) that are trusted by the client. These types of X.509 certificates are also known as trusted roots.

This parameter effectively enables the -Z switch. For Directory Server on i5/OS if you use -Z and do not use -K or -N, the certificate associated with the Directory Services Client application ID will be used.

-l timelimit
Wait at most timelimit seconds for a search to complete.
-L
Display search results in LDIF format. This option also turns on the -B option, and causes the -F option to be ignored.
-m mechanism
Use mechanism to specify the SASL mechanism to be used to bind to the server. The ldap_sasl_bind_s() API is used. The -m parameter is ignored if -V 2 is set. If -m is not specified, simple authentication is used. Valid mechanisms are:
-M
Manage referral objects as regular entries.
-n
Show what would be done, but don't actually change entries. Useful for debugging in conjunction with -v.
-N certificatename
Specify the label associated with the client certificate in the key database file.
Note:
If the LDAP server is configured to perform server authentication only, a client certificate is not required. If the LDAP server is configured to perform client and server authentication, a client certificate might be required. certificatename is not required if a default certificate/private key pair has been designated as the default. Similarly, certificatename is not required if there is a single certificate/private key pair in the designated key database file. This parameter is ignored if neither -Z nor -K is specified.
For Directory Server on i5/OS if you use -Z and do not use -K or -N, the certificate associated with the Directory Services Client application ID will be used.
-o attr_type
To specify an attribute to use for sort criteria of search results, you can use the -o (order) parameter. You can use multiple -o parameters to further define the sort order. In the following example, the search results are sorted first by surname (sn), then by given name, with the given name (givenname) being sorted in reverse (descending) order as specified by the prefixed minus sign ( - ): 
-o sn -o -givenname
Thus, the syntax of the sort parameter is as follows: 
 	[-]<attribute name>[:<matching rule OID>]
where The default ldapsearch operation is not to sort the returned results.
-O maxhops
Specify maxhops to set the maximum number of hops that the client library takes when chasing referrals. The default hopcount is 10.
-p ldapport
Specify an alternate TCP port where the ldap server is listening. The default LDAP port is 389. If not specified and -Z is specified, the default LDAP SSL port 636 is used.
-P keyfilepw
Specify the key database password. This password is required to access the encrypted information in the key database file (which can include one or more private keys). If a password stash file is associated with the key database file, the password is obtained from the password stash file, and the -P parameter is not required. This parameter is ignored if neither -Z nor -K is specified.
-q pagesize
To specify paging of search results, two parameters can be used: -q (query page size), and -T (time between searches in seconds). In the following example, the search results return a page (25 entries) at a time, every 15 seconds, until all the results for that search are returned. The ldapsearch client handles all connection continuation for each paged results request for the life of the search operation.

These parameters can be useful when the client has limited resources or when it is connected through a low-bandwidth connection. In general, it allows you to control the rate at which data is returned from a search request. Instead of receiving all of the results at once, you can get them a few entries (a page) at a time. In addition, you can control the duration of the delay taken between each page request, giving the client time to process the results.

 -q 25  -T 15
If the -v (verbose) parameter is specified, ldapsearch lists how many entries have been returned so far, after each page of entries returned from the server, for example, 30 total entries have been returned.

Multiple -q parameters are enabled such that you can specify different page sizes throughout the life of a single search operation. In the following example, the first page is 15 entries, the second page is 20 entries, and the third parameter ends the paged result/search operation:

-q 15 -q 20 -q 0

In the following example, the first page is 15 entries, and all the rest of the pages are 20 entries, continuing with the last specified -q value until the search operation completes: 

-q 15 -q 20

The default ldapsearch operation is to return all entries in a single request. No paging is done for the default ldapsearch operation.

-R
Specifies that referrals are not to be automatically followed.
-s scope
Specify the scope of the search. scope should be one of base, one, or sub to specify a base object, one-level, or subtree search. The default is sub.
-t
Write retrieved values to a set of temporary files. This is useful for dealing with non-ASCII values such as jpegPhoto or audio.
-T seconds
Time between searches (in seconds). The -T option is only supported when the -q option is specified.
-U username
Specify the username. Required with -m DIGEST-MD5 and ignored with any other mechanism.
-v
Use verbose mode, with many diagnostics written to standard output.
-V
Specifies the LDAP version to be used by ldapmodify when it binds to the LDAP server. By default, an LDAP V3 connection is established. To explicitly select LDAP V3, specify "-V 3". Specify "-V 2" to run as an LDAP V2 application. An application, like ldapmodify, selects LDAP V3 as the preferred protocol by using ldap_init instead of ldap_open.
-w passwd | ?
Use passwd as the password for authentication. Use the ? to generate a password prompt. .
-y proxydn
Set proxied ID for proxied authorization operation.
-Y
Use a secure LDAP connection (TLS).
-z sizelimit
Limit the results of the search to at most sizelimit entries. This makes it possible to place an upper bound on the number of entries that are returned for a search operation.
-Z
Use a secure SSL connection to communicate with the LDAP server. For Directory Server on i5/OS if you use -Z and do not use -K or -N, the certificate associated with the Directory Services Client application ID will be used.
filter
Specifies a string representation of the filter to apply in the search. Simple filters can be specified as attributetype=attributevalue. More complex filters are specified using a prefix notation according to the following Backus Naur Form (BNF): 
<filter> ::='('<filtercomp>')'
<filtercomp> ::= <and>|<or>|<not>|<simple>
<and> ::= '&' <filterlist>
<or> ::= '|' <filterlist>
<not> ::= '!' <filter>
<filterlist> ::= <filter>|<filter><filterlist>
<simple> ::= <attributetype><filtertype>
<attributevalue>
<filtertype> ::= '='|'~='|'<='|'>='
The '~=' construct is used to specify approximate matching. The representation for <attributetype> and <attributevalue> are as described in "RFC 2252, LDAP V3 Attribute Syntax Definitions" Link outside the Information Center. In addition, if the filtertype is '=' then <attributevalue> can be a single * to achieve an attribute existence test, or can contain text and asterisks ( * ) interspersed to achieve substring matching.

For example, the filter "mail=*" finds any entries that have a mail attribute. The filter "mail=*@student.of.life.edu" finds any entries that have a mail attribute ending in the specified string. To put parentheses in a filter, escape them with a backslash (\) character.

Note:
A filter like "cn=Bob *", where there is a space between Bob and the asterisk ( * ), matches "Bob Carter" but not "Bobby Carter" in IBM Directory. The space between "Bob" and the wildcard character ( * ) affects the outcome of a search using filters.

See "RFC 2254, A String Representation of LDAP Search Filters" Link outside the Information Center for a more complete description of allowable filters.

Output format

If one or more entries are found, each entry is written to standard output in the form: 

      Distinguished Name (DN)

      attributename=value

      attributename=value

      attributename=value

     ...

Multiple entries are separated with a single blank line. If the -F option is used to specify a separator character, it will be used instead of the `=' character. If the -t option is used, the name of a temporary file is used in place of the actual value. If the -A option is given, only the "attributename" part is written.

Examples

The following command: 

 ldapsearch "cn=john doe" cn telephoneNumber
performs a subtree search (using the default search base) for entries with a commonName of "john doe". The commonName and telephoneNumber values are retrieved and printed to standard output. The output might look something like this if two entries are found: 
  cn=John E Doe, ou="College of Literature, Science, and the Arts",
ou=Students, ou=People, o=University of Higher Learning, c=US

  cn=John Doe

  cn=John Edward Doe

  cn=John E Doe 1

  cn=John E Doe

  telephoneNumber=+1 313 555-5432



  cn=John B Doe, ou=Information Technology Division,
ou=Faculty and Staff, ou=People, o=University of Higher Learning, c=US

  cn=John Doe

  cn=John B Doe 1

  cn=John B Doe

  telephoneNumber=+1 313 555-1111

The command: 

ldapsearch -t "uid=jed" jpegPhoto audio
performs a subtree search using the default search base for entries with user id of "jed". The jpegPhoto and audio values are retrieved and written to temporary files. The output might look like this if one entry with one value for each of the requested attributes is found: 
cn=John E Doe, ou=Information Technology Division,

  ou=Faculty and Staff,

  ou=People, o=University of Higher Learning, c=US

  audio=/tmp/ldapsearch-audio-a19924

  jpegPhoto=/tmp/ldapsearch-jpegPhoto-a19924

The command: 

ldapsearch -L -s one -b "c=US" "o=university*" o description
performs a one-level search at the c=US level for all organizations whose organizationName begins with university. Search results will be displayed in the LDIF format (see LDAP Data Interchange Format). The organizationName and description attribute values will be retrieved and printed to standard output, resulting in output similar to this: 
dn: o=University of Alaska Fairbanks, c=US

  o: University of Alaska Fairbanks

  description: Preparing Alaska for a brave new tomorrow

  description: leaf node only



  dn: o=University of Colorado at Boulder, c=US

  o: University of Colorado at Boulder

  description: No personnel information

  description: Institution of education and research



  dn: o=University of Colorado at Denver, c=US

  o: University of Colorado at Denver

  o: UCD

  o: CU/Denver

  o: CU-Denver

  description: Institute for Higher Learning and Research



  dn: o=University of Florida, c=US

  o: University of Florida

  o: UFl

  description: Shaper of young minds



 ...

The command: 

ldapsearch -b "c=US" -o ibm-slapdDN "objectclass=person" ibm-slapdDN
performs a subtree level search at the c=US level for all persons. This special attribute (ibm-slapdDN), when used for sorted searches, sorts the search results by the string representation of the Distinguished Name (DN). The output might look something like this: 
cn=Al Edwards,ou=Widget Division,ou=Austin,o=IBM,c=US

cn=Al Garcia,ou=Home Entertainment,ou=Austin,o=IBM,c=US

cn=Amy Nguyen,ou=In Flight Systems,ou=Austin,o=IBM,c=US

cn=Arthur Edwards,ou=Widget Division,ou=Austin,o=IBM,c=US

cn=Becky Garcia,ou=In Flight Systems,ou=Austin,o=IBM,c=US

cn=Ben Catu,ou=In Flight Systems,ou=Austin,o=IBM,c=US

cn=Ben Garcia Jr,ou=Home Entertainment,ou=Austin,o=IBM,c=US

cn=Bill Keller Jr.,ou=In Flight Systems,ou=Austin,o=IBM,c=US

cn=Bob Campbell,ou=In Flight Systems,ou=Austin,o=IBM,c=US

The command:

ldapsearch –h hostname –o sn –b "o=ibm,c=us" "title=engineer"
returns all entries in an IBM employee directory whose title is "engineer", with the results sorted by surname.

The command:

ldapsearch –h hostname –o -sn –o cn –b "o=ibm,c=us" "title=engineer"
returns all entries in an IBM employee directory whose title is "engineer", with the results sorted by surname (in descending order) and then by common name (in ascending order).

The command:

ldapsearch –h hostname –q 5 –T 3 –b o=ibm,c=us "title=engineer"
returns five entries per page, with a delay of 3 seconds between pages for all entries in an IBM employee directory whose title is "engineer".

This example demonstrates searches where a referral object is involved. As discussed in LDAP directory referrals, Directory Server LDAP directories can contain referral objects, provided that they contain only the following:

Assume that 'System_A' holds the referral entry: 

dn: cn=Barb Jensen, ou=Rochester, o=Big Company, c=US
ref: ldap://System_B:389/cn=Barb Jensen,
  ou=Rochester, o=Big Company, c=US
objectclass: referral

All attributes associated with the entry should reside on 'System_B'.

System_B contains an entry:

dn: cn=Barb Jensen, ou=Rochester, o=Big Company, c=US
cn: Barb Jensen
objectclass: organizationalPerson
sn: Jensen
telephonenumber: (800) 555 1212

When a client issues a request to 'System_A', the LDAP server on System_A responds to the client with the URL: 

ldap://System_B:389/cn=Barb Jensen,
 ou=Rochester, o=Big Company, c=US

The client uses this information to issue a request to System_B. If the entry on System_A contains attributes in addition to dn, objectclass, and ref, the server ignores those attributes (unless you specify the -R flag to indicate not to chase referrals).

When the client receives a referral response from a server, it issues the request again, this time to the server to which the returned URL refers. The new request has the same scope as the original request. The results of this search vary depending on the value you specify for the scope of the search (-b).

If you specify -s base, as shown here: 

ldapsearch -h System_A -b 'ou=Rochester, o=Big Company, c=US'
     -s base 'sn=Jensen'

the search returns all attributes for all entries with 'sn=Jensen' that reside in 'ou=Rochester, o=Big Company, c=US' on both System_A and System_B.

Start of changeIf you specify -s sub, as shown here: 

ldapsearch -s sub "cn=John"

the server would search all suffixes and return all entries with "cn=John". This is known as a subtree search on a null base. The entire directory is searched with one search operation instead of doing multiple searches each with a different suffix as the search base. This type of search operation takes longer and consumes more system resources because it is searching the entire directory (all suffixes).

Note:
A subtree search on a null base does not return schema information, change log information, nor anything from the system-projected backend.
End of change

If you specify -s sub, as shown here: 

ldapsearch -h System_A -b 'ou=Rochester, o=Big Company, c=US'
     -s sub 'sn=Jensen'

the search returns all attributes for all entries with 'sn=Jensen' that reside in or below 'ou=Rochester, o=Big Company, c=US' on both System_A and System_B.

If you specify -s one, as shown here: 

ldapsearch -h System_A -b 'ou=Rochester, o=Big Company, c=US'
     -s one 'sn=Jensen'

the search returns no entries on either system. Instead, the server returns the referral URL to the client:

ldap://System_B:389/cn=Barb Jensen,
  ou=Rochester, o=Big Company, c=US

The client in turn submits a request:

 ldapsearch -h System_B -b 'ou=Rochester, o=Big Company, c=US'
     -s one 'sn=Jensen'

This does not give any results either, because the entry

dn: cn=Barb Jensen, ou=Rochester, o=Big Company, c=US

resides at 

ou=Rochester, o=Big Company, c=US

A search with -s one attempts to find entries in the level immediately below

ou=Rochester, o=Big Company, c=US

Diagnostics

Exit status is 0 if no errors occur. Errors result in a non-zero exit status and a diagnostic message being written to standard error.