unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (SunOS-5.10)
Page:
Section:
Apropos / Subsearch:
optional field

ldapsearch(1)                    User Commands                   ldapsearch(1)



NAME
       ldapsearch - ldap search tool

SYNOPSIS
       ldapsearch  [-n] [-u] [-v] [-t] [-A] [-B] [-L] [-R] [-H] [-?] [-t] [-T]
       [-B] [-E] [-J]  [-e]  [-l]  [-Z]  [-r]  [-M]  [-d debuglevel]  [-F sep]
       [-f file]    [-D bindDN]    [-j filename]   [-V version]   [-Y proxyDN]
       [-O hopLimit] [-i locale] [-k path]  [-S   [-] attribute]  [-C pattern]
       [-c authzid]   [-P path]   [-N certificate]  [-w passwd]  [-h ldaphost]
       [-p ldapport]   [-o attributename=value]   [-b searchbase]   [-s scope]
       [-a deref] [-l timelimit] [-z sizelimit] filter [attrs...]

DESCRIPTION
       The ldapsearch utility opens a connection to an LDAP server, binds, and
       performs a search using the filter filter.

       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.

   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 (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 different separator character, this charac-
       ter  will  be  used  instead  of the `=' character. If the -t option is
       used, the name of a temporary file is returned in place of  the  actual
       value.  If the -A option is given, only the "attributename" is returned
       and not the attribute value.

OPTIONS
       The foloowing options are supported:

       -A

           Retrieve attributes only (no values). This is useful when you  just
           want to see whether an attribute is present in an entry and are not
           interested in the specific value.



       -a deref

           Specify how aliases dereferencing is done. The possible values  for
           deref  are  never,  always, search, or find to specify respectively
           that aliases are never dereferenced, always dereferenced,  derefer-
           enced  when  searching,  or dereferenced only when finding the base
           object for the search. The default is to never dereference aliases.



       -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 automatically set by the -L option.



       -b searchbase

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



       -C pattern

           Persistent  search. Perform a search that keeps the connection open
           and displays results whenever entries matching the scope and filter
           of  the  search  are added, modified, or removed. With this option,
           the ldapsearch tool runs indefinitely; you must type  Control-c  to
           stop it. The pattern has the following format:


           ps:changeType[:changesOnly[:entryChangeControls]]



       -c authzid

           Specifies the getEffectiveRights control authzid. For example:


           dn:uid=bjensen,dc=example,dc=com



       -D bindDN

           Use the distinguished name bindDN to bind to the directory.



       -d debuglevel

           Set  the  LDAP  debugging  level.  Useful  levels  of debugging for
           ldapsearch are:


           1        Trace




           2        Packets



           4        Arguments



           32       Filters



           128      Access control


           To request more than one category of debugging information, add the
           masks.  For example, to request trace and filter information, spec-
           ify a debuglevel of 33.


       -E

           Ask server to expose (report) bind identity by means of authentica-
           tion response control.



       -e

           Minimize base-64 encoding of values.



       -F sep

           Use  sep as the field separator between attribute names and values.
           The default separator is `='. If -L option has been specified, this
           option is ignored.



       -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 -  character,  then  the
           lines are read from standard input.



       -G pattern

           Virtual  list  view.  Retrieve  only  a  portion of all results, as
           determined by the index or value of the search target and the  num-
           ber  of  entries  to  be returned before and after the target. This
           option always requires the -S and -x options to specify the sorting
           order on the server.



       -?

           Display the usage help text that briefly describes all options.



       -H

           Display the usage help text that briefly describes all options.



       -h ldaphost

           Specify  an  alternate host on which the secure LDAP server is run-
           ning.



       -i locale

           Specify 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 option to perform the  conver-
           sion  from the specified character set to UTF8, thus overriding the
           LANG setting. Using this argument, you can input the bind DN,  base
           DN,  and  the search filter pattern in the specified character set.
           The ldapsearch tool 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. If you specify a
           file containing a search filter (with the  -f  option),  ldapsearch
           will not convert the data in the file.



       -j filename

           Specify a file containing the password for the bind DN or the pass-
           word for the SSL client's key database. To  protect  the  password,
           use this option in scripts and place the password in a secure file.
           This option is mutually exclusive of the -w and -W options.



       -J [:criticality[:value|::b64value|b64value|:fileurl]]

           Criticality is a boolean value (default is false).



       -k path

           Specify the path to a  directory  containing  conversion  routines.
           These routines are used if you want to specify a locale that is not
           supported by default by your directory server. This is for NLS sup-
           port.



       -L

           Display search results in a modified format. This option also turns
           on the -B option, and causes the -F  option  to  be  ignored.  This
           behavior is the default.



       -l timelimit

           Wait at most timelimit seconds for a search to complete.



       -M

           Manage  smart referrals. When they are the target of the operation,
           search the entry containing  the  referral  instead  of  the  entry
           obtained by following the referral.



       -N certificate

           Specify  the  certificate  name to use for certificate-based client
           authentication. For example: -N "Directory-Cert".



       -n

           Show what would be done, but do not actually  perform  the  search.
           Useful in conjunction with -v and -d for debugging.



       -O hopLimit

           Specify the maximum number of referral hops to follow while finding
           an entry to modify. By default, there is no limit.



       -o attributename=value

           For SASL mechanisms and other options such as security  properties,
           mode  of  operation,  authorization  ID,  authentication ID, and so
           forth.

           The different attribute names and their values are as follows:


           secProp="number"

               For defining SASL security properties.




           realm="value"

               Specifies SASL realm (default is realm=none).



           authzid="value"

               Specify the authorization ID name for SASL bind.



           authid="value"

               Specify the authentication ID for SASL bind.



           mech="value"

               Specifies the various SASL mechanisms.



       -P path

           Specify the path and filename of the client's certificate database.
           For example:


           -P /home/uid/.netscape/cert7.db

           When  using  the  command on the same host as the directory server,
           you can use the server's own certificate database. For example:


           -P installDir/lapd-serverID/alias/cert7.db

           Use the -P option alone to specify server authentication only.



       -p ldapport

           Specify an alternate TCP port where the secure LAPD server is  lis-
           tening.



       -R

           Do not automatically follow referrals returned while searching.



       -r

           Display the output of the ldapsearch command in the old format.



       -S [-]attribute

           Specify  an  attribute  for  sorting  the  entries  returned by the
           search. The sort criteria is alphabetical on the attribute's  value
           or reverse alphabetical with the form -attribute. You can give mul-
           tiple -S options to refine the sorting, For example:


           -S sn -S givenname

           By default, the entries are not sorted. Use the -x option  to  per-
           form server-side sorting.



       -s scope

           Specify  the  scope of the search. The possible values of scope are
           base, one, or sub to specify respectively a base object, one-level,
           or subtree search. The default is sub.



       -T

           Format the output of search results so that no line breaks are used
           within individual attribute values.



       -t

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



       -U

           URL  format  (valid  only with the -t option). When using temporary
           file output, the standard output of the tool will include  the  URL
           of the file instead of the attributes value. For example:


           jpegPhoto:< file:/tmp/ldapsearch-jpegPhoto-YzaOMh



       -u

           Include  the  user-friendly  form of the Distinguished Name (DN) in
           the output.



       -V version

           Specify the LDAP protocol version number to be used for the  delete
           operation,  either  2 or 3. LDAP v3 is the default. Specify LDAP v2
           when connecting to servers that do not support v3.



       -v

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



       -W password

           Specify the password for the client's key database given in the  -P
           option.  This  option  is  required  for  certificate-based  client
           authentication. Specifying password on the command line  has  secu-
           rity  issues because the password can be seen by others on the sys-
           tem by means of the ps command. Use the -j instead to  specify  the
           password from the file. This option is mutually exclusive of -j.



       -w passwd

           Use  passwd  as  the  password for authentication to the directory.
           When you use -w passwd to specify  the  password  to  be  used  for
           authentication,  the password is visible to other users of the sys-
           tem by means of the ps command, in script files or  in  shell  his-
           tory.  If  you  use the ldapsearch command without this option, the
           command will prompt for the password and read it from standard  in.
           When  used  without the -w option, the password will not be visible
           to other users.



       -x

           Use with the -S option to specify that search results be sorted  on
           the  server  rather  than  by the ldapsearch command running on the
           client. This is useful if you want to sort according to a  matching
           rule, as with an international search. It is usually faster to sort
           on the server, if that is supported, rather than on the client.



       -Y proxyDN

           Specify the proxy DN (proxied authorization id) to use for the mod-
           ify operation, usually in double quotes (" ") for the shell.



       -Z

           Specify  that  SSL  be  used  to  provide  certificate-based client
           authentication. This option requires the -N and  SSL  password  and
           any other of the SSL options needed to identify the certificate and
           the key database.



       -z sizelimit

           Retrieve at most sizelimit entries for a search to complete.



EXAMPLES
       Example 1: Performing a Subtree Search

       The following command performs a  subtree  search  (using  the  default
       search base) for entries with a commonName of "mark smith". The common-
       Name and telephoneNumber values will be retrieved and printed to  stan-
       dard  output.  Use the -r option to display this output in the old for-
       mat.

       example% ldapsearch "cn=mark smith" cn telephoneNumber

       The output looks something like this:

       cn=Mark D Smith, ou=Sales, ou=Atlanta, ou=People, o=XYZ, c=US
       cn=Mark Smith
       cn=Mark David Smith
       cn=Mark D Smith 1
       cn=Mark D Smith
       telephoneNumber=+1 123 456-7890
       cn=Mark C Smith, ou=Distribution, ou=Atlanta, ou=People, o=XYZ, c=US
       cn=Mark Smith
       cn=Mark C Smith 1
       cn=Mark C Smith
       telephoneNumber=+1 123 456-9999

       Example 2: Performing a Subtree Search Using the Default Search Base

       The following command performs  a  subtree  search  using  the  default
       search  base  for entries with user id of "mcs". 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 writ-
       ten to temporary files.

       example% ldapsearch -u -t "uid=mcs" -r jpegPhoto audio

       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=Distribution, ou=Atlanta, ou=People, o=XYZ, c=US
       Mark C Smith, Distribution, Atlanta, People, XYZ, US
       audio=/tmp/ldapsearch-audio-a19924
       jpegPhoto=/tmp/ldapsearch-jpegPhoto-a19924

       Example 3: Performing a One-Level Search

       The following command performs a one-level search at the c=US level for
       all organizations whose organizationName begins with XY.

       example% ldapsearch -s one -b "c=US" "o=XY*" o description

       Search results are displayed in the LDIF format, which is the  default.
       The organizationName and description attribute values will be retrieved
       and printed to standard output, resulting in output similar to this:

       dn: o=XYZ, c=US
       o: XYZ
       description: XYZ Corporation
       dn: o="XY Trading Company", c=US
       o: XY Trading Company
       description: Import and export specialists

       dn: o=XYInternational, c=US
       o: XYInternational
       o: XYI
       o: XY International

       Example 4: Performing a Subtree Search on an IPv6 Server

       The following command performs  a  subtree  search  using  the  default
       search  base for entries with a user id of mcs on an IPv6 (that is, -h)
       server:

       example% ldapsearch -u -h '['fec0::111:a00:20ff:fea3:edcf']' \
       -t "uid=mcs" jpegPhoto audio

EXIT STATUS
       The following exit values are returned:

       0               Successful completion.



       >&gt;0              An error occurred. A diagnostic message is  written  to
                       standard error.



ATTRIBUTES
       See attributes(5) for a description of the following attributes:


       tab()     allbox;     cw(2.750000i)|    cw(2.750000i)    lw(2.750000i)|
       lw(2.750000i).  ATTRIBUTE TYPEATTRIBUTE VALUE AvailabilitySUNWcsu  Sta-
       bility LevelEvolving


SEE ALSO
       ldapadd(1), ldapdelete(1), ldapmodify(1), ldapmodrdn(1), attributes(5)



SunOS 5.10                        5 Mar 2004                     ldapsearch(1)