ldapsearch(1ldap)

ldapsearch -- LDAP search tool

Synopsis

ldapsearch [-u] [-v] [-t] [-A] [-B] [-L] [-R] [-d debuglevel] [-F sep] [-S attribute] [-f file] [-D binddn] [-w bindpasswd] [-W] [-h ldaphost] [-p ldapport] [-b searchbase] [-s scope] [-a deref] [-l timelimit] [-z sizelimit] filter [attrs...]

Description

ldapsearch is a shell-accessible interface to the ldap_search(3ldap) library function.

ldapsearch opens a connection to an LDAP server, binds, and performs a search using the filter filter. The filter should conform to the string representation for LDAP filters as defined in RFC 1558.

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.

A common problem when using ldapsearch is a failure to specify a search base with the -b option. Without this, the result of the search will be the message ldapsearch: partial results and referral received. The search base must match one of the suffix entries on the LDAP server.

Options

-u

Include the User Friendly form of the Distinguished Name (DN) in the output.

-v

Run in verbose mode, with some diagnostics written to standard output.

-t

Write retrieved values to a set of temporary files. This is useful for dealing with non-ASCII values such as jpegPhoto or audio.

-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

Do not suppress display of non-ASCII values. This is useful when dealing with values that appear in alternate characters sets such as ISO-8859.1. This option is implied by -L (see below).

-L

Display search results in ldif(4ldap) format. This option also turns on the -B option, and causes the -F option to be ignored.

-R

Do not automatically follow referrals returned while searching.

-d debuglevel

Set the LDAP debugging level to debuglevel. See the loglevel option in slapd.conf(4ldap).

-F sep

Use sep as the field separator between attribute names and values. The default separator is the equals sign (=), unless the -L option has been specified, in which case this option is ignored.

-S attribute

Sort the entries returned based on attribute. The default is not to sort entries returned. If attribute is a zero-length string (""), the entries are sorted by the components of their Distinguished Name. See ldap_sort_entries(3ldap) for more details. Note that ldapsearch normally prints out entries as it receives them. The use of the -S option defeats this behavior, causing all entries to be retrieved, then sorted, then printed.

-f 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 hyphen (-), then the lines are read from standard input.

-D binddn

Specify the Distinguished Name to be used in binding to the directory.

binddn should be a string-represented DN, as defined in RFC 1779 or its successor.

If a -D binddn option is not supplied, the command will take the binddn value from the LDAP_BINDDN_SEARCH environmental variable, if set. If LDAP_BINDDN_SEARCH specifies a null string, it is assumed that an anonymous bind is required.

If a -D option is not supplied, and LDAP_BINDDN_SEARCH is not used to specify the bind DN, the configuration file /etc/ldap_defaults will be examined for a default value to be used. If no default is supplied, a value of "" will be assumed.

-w bindpasswd

Use bindpasswd as the password for simple authentication.

-W

Read the password from the terminal. This is an alternative to supplying a password via the -w passwd option.

The password is prompted for in a non-echoing input mode. If ldapsearch has no controlling terminal, then the password will be read from standard input.

-h ldaphost

Specify the LDAP servers to connect to.

More than one server can be specified, in which case the servers are tried in the order specified, stopping with the first one to which a successful connection is made.

The servers can be specified either as hostnames or as dotted strings giving IP addresses.

A server port may be specified along with the server names or addresses by using the notation servername:portnumber or serverIPaddr:portnumber. If a port number is not explicitly specified for the particular server, a default port (as described for the -p option) is used.

If a null string is supplied, the local host is assumed. See the -p option for how the local port is selected.

If no -h option is supplied, the command will take the ldaphost value from the LDAP_HOST environmental variable, if this is present.

If no -h option is supplied, and LDAP_HOST is not set, then the configuration file /etc/ldap_defaults will be examined for a default value to be used.

If no default is supplied, a value of "", implying the local host, will be assumed.

-p ldapport

Specify the TCP port number to connect to (using the notation server:portnumber), if not specified via the -h option.

If no port number is explicitly supplied, the default LDAP port is assumed.

-b searchbase

Use searchbase as the starting point for the search instead of the default.

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

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

-l timelimit

Wait at most timelimit seconds for a search to complete.

-z sizelimit

Retrieve at most sizelimit seconds for a search to complete.

Output format

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

   Distinguished Name (DN) 
   User Friendly Name (this line present only if the -u option is used) 
   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 equals sign (=). 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.

Exit codes

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.

Examples

The following command will perform a subtree search (using the default search base) for entries with a commonName of ``mark smith'':

ldapsearch "cn=mark smith" cn telephoneNumber

The commonName and telephoneNumber values will be retrieved and printed to standard output. The output might look something like this if two entries are found:

   cn=Mark D Smith, ou="College of Literature, Science, and the Arts", ou=Students, ou=People, o=University of Michigan, c=US 
   cn=Mark Smith 
   cn=Mark David Smith 
   cn=Mark D Smith 1 
   cn=Mark D Smith 
   telephoneNumber=+1 313 930-9489 
    
   cn=Mark C Smith, ou=Information Technology Division, ou=Faculty and Staff, ou=People, o=University of Michigan, c=US 
   cn=Mark Smith 
   cn=Mark C Smith 1 
   cn=Mark C Smith 
   telephoneNumber=+1 313 764-2277

The following command will perform a subtree search using the default search base for entries with user ID of ``mcs'':

ldapsearch -u -t "uid=mcs" jpegPhoto audio

The user friendly form of the entry's DN will be output after the line that contains the DN itself, and the jpegPhoto and audio values will be 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=Mark C Smith, ou=Information Technology Division, ou=Faculty and Staff, ou=People, o=University of Michigan, c=US 
   Mark C Smith, Information Technology Division, Faculty and Staff, People, University of Michigan, US 
   audio=/tmp/ldapsearch-audio-a19924 
   jpegPhoto=/tmp/ldapsearch-jpegPhoto-a19924

The following command will perform a one-level search at the ``c=US'' level for all organizations whose organizationName begins with ``university'':

ldapsearch -L -s one -b "c=US" "o=university" o description

Search results will be displayed in the LDIF 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 yesterday 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: Warper of young minds

...

References

Intro(3ldap), ldapadd(1ldap), ldapdelete(1ldap), ldapmodify(1ldap), ldapmodrdn(1ldap), ldap_search(3ldap)

Kille, S., A String Representation of Distinguished Names, RFC 1779, ISODE Consortium, March 1995.

Howes, T., A String Representation of LDAP Search Filters, RFC 1558, University of Michigan, December 1993.