git.sur5r.net Git - openldap/blob - doc/man/man1/ldapsearch.1

   1 .TH LDAPSEARCH 1 "20 August 2000" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved.
   4 .\" Copying restrictions apply.  See COPYRIGHT/LICENSE.
   5 .SH NAME
   6 ldapsearch \- LDAP search tool
   7 .SH SYNOPSIS
   8 .B ldapsearch
   9 [\c
  10 .BR \-n ]
  11 [\c
  12 .BR \-u ]
  13 [\c
  14 .BR \-v ]
  15 [\c
  16 .BR \-k ]
  17 [\c
  18 .BR \-K ]
  19 [\c
  20 .BR \-t ]
  21 [\c
  22 .BR \-A ]
  23 [\c
  24 .BR \-C ]
  25 [\c
  26 .BR \-L[L[L]] ]
  27 [\c
  28 .BR \-M[M] ]
  29 [\c
  30 .BI \-d \ debuglevel\fR]
  31 [\c
  32 .BI \-f \ file\fR]
  33 [\c
  34 .BI \-D \ binddn\fR]
  35 [\c
  36 .BR \-W ]
  37 [\c
  38 .BI \-w \ bindpasswd\fR]
  39 [\c
  40 .BI \-H \ ldapuri\fR]
  41 [\c
  42 .BI \-h \ ldaphost\fR]
  43 [\c
  44 .BI \-p \ ldapport\fR]
  45 [\c
  46 .BI \-P \ 2\fR\||\|\fI3\fR]
  47 [\c
  48 .BI \-b \ searchbase\fR]
  49 [\c
  50 .BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub\fR]
  51 [\c
  52 .BI \-a \ never\fR\||\|\fIalways\fR\||\|\fIsearch\fR\||\|\fIfind\fR]
  53 [\c
  54 .BI \-l \ timelimit\fR]
  55 [\c
  56 .BI \-z \ sizelimit\fR]
  57 [\c
  58 .BR \-O \ security-properties ]
  59 [\c
  60 .BR \-I ]
  61 [\c
  62 .BR \-Q ]
  63 [\c
  64 .BI \-U \ username\fR]
  65 [\c
  66 .BR \-x ]
  67 [\c
  68 .BI \-X \ authzid\fR]
  69 [\c
  70 .BI \-Y \ mech\fR]
  71 [\c
  72 .BR \-Z[Z] ]
  73 .I filter
  74 [\c
  75 .IR attrs... ]
  76 .SH DESCRIPTION
  77 .I ldapsearch
  78 is a shell-accessible interface to the
  79 .BR ldap_search (3)
  80 library call.
  81 .LP
  82 .B ldapsearch
  83 opens a connection to an LDAP server, binds, and performs a search
  84 using the filter \fIfilter\fP.  The \fIfilter\fP should conform to
  85 the string representation for search filters as defined in RFC 2254.
  86 .LP
  87 If
  88 .B ldapsearch
  89 finds one or more entries, the attributes specified by
  90 \fIattrs\fP are retrieved and the entries and values are printed to
  91 standard output.  If no \fIattrs\fP are listed, all attributes are
  92 returned.  If * is listed, all user attributes are returned.
  93 If + is listed, all operational attributes are returned.
  94 If only 1.1 is listed, no attributes are listed.
  95 .SH OPTIONS
  96 .TP
  97 .B \-n
  98 Show what would be done, but don't actually perform the search.  Useful for
  99 debugging in conjunction with -v.
 100 .TP
 101 .B \-u
 102 Include the User Friendly Name form of the Distinguished Name (DN)
 103 in the output.
 104 .TP
 105 .B \-v
 106 Run in verbose mode, with many diagnostics written to standard output.
 107 .TP
 108 .B \-k
 109 Use Kerberos authentication instead of simple authentication.  It is
 110 assumed that you already have a valid ticket granting ticket.
 111 .B ldapsearch
 112 must be compiled with Kerberos support for this option to have any effect.
 113 .TP
 114 .B \-K
 115 Same as \-k, but only does step 1 of the Kerberos bind.  This is useful
 116 when connecting to a slapd and there is no x500dsa.hostname principal
 117 registered with your Kerberos servers.
 118 .TP
 119 .B \-t
 120 Write retrieved values to a set of temporary files.  This is useful for
 121 dealing with non-ASCII values such as jpegPhoto or audio.
 122 .TP
 123 .B \-A
 124 Retrieve attributes only (no values).  This is useful when you just want to
 125 see if an attribute is present in an entry and are not interested in the
 126 specific values.
 127 .TP
 128 .B \-L
 129 Search results are display in LDAP Data Interchange Format detailed in
 130 .BR ldif (5).
 131 A single -L restricts the output to LDIFv1.
 132 A second -L disables comments.
 133 A third -L disables printing of the LDIF version.
 134 The default is to use an extended version of LDIF.
 135 .TP
 136 .B \-M[M]
 137 Enable manage DSA IT control.
 138 .B \-MM
 139 makes control critical.
 140 .TP
 141 .B \-C
 142 Automatically chase referrals.
 143 .TP
 144 .BI \-S \ attribute
 145 Sort the entries returned based on \fIattribute\fP. The default is not
 146 to sort entries returned.  If \fIattribute\fP is a zero-length string (""),
 147 the entries are sorted by the components of their Distingished Name.  See
 148 .BR ldap_sort (3)
 149 for more details. Note that
 150 .B ldapsearch
 151 normally prints out entries as it receives them. The use of the
 152 .B \-S
 153 option defeats this behavior, causing all entries to be retrieved,
 154 then sorted, then printed.
 155 .TP
 156 .BI \-d \ debuglevel
 157 Set the LDAP debugging level to \fIdebuglevel\fP.
 158 .B ldapsearch
 159 must be compiled with LDAP_DEBUG defined for this option to have any effect.
 160 .TP
 161 .BI \-f \ file
 162 Read a series of lines from \fIfile\fP, performing one LDAP search for
 163 each line.  In this case, the \fIfilter\fP given on the command line
 164 is treated as a pattern where the first occurrence of \fB%s\fP is
 165 replaced with a line from \fIfile\fP.  If \fIfile\fP is a single \fI-\fP
 166 character, then the lines are read from standard input.
 167 .TP
 168 .B \-x
 169 Use simple authentication instead of SASL.
 170 .TP
 171 .BI \-D \ binddn
 172 Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory.
 173 .TP
 174 .B \-W
 175 Prompt for simple authentication.
 176 This is used instead of specifying the password on the command line.
 177 .TP
 178 .BI \-w \ bindpasswd
 179 Use \fIbindpasswd\fP as the password for simple authentication.
 180 .TP
 181 .BI \-H \ ldapuri
 182 Specify URI(s) referring to the ldap server(s).
 183 .TP
 184 .BI \-h \ ldaphost
 185 Specify an alternate host on which the ldap server is running.
 186 Deprecated in favor of -H.
 187 .TP
 188 .BI \-p \ ldapport
 189 Specify an alternate TCP port where the ldap server is listening.
 190 Deprecated in favor of -H.
 191 .TP
 192 .BI \-b \ searchbase
 193 Use \fIsearchbase\fP as the starting point for the search instead of
 194 the default.
 195 .TP
 196 .BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub
 197 Specify the scope of the search to be one of
 198 .IR base ,
 199 .IR one ,
 200 or
 201 .I sub
 202 to specify a base object, one-level, or subtree search.  The default
 203 is
 204 .IR sub .
 205 .TP
 206 .BI \-a \ never\fR\||\|\fIalways\fR\||\|\fIsearch\fR\||\|\fIfind
 207 Specify how aliases dereferencing is done.  Should be one of
 208 .IR never ,
 209 .IR always ,
 210 .IR search ,
 211 or
 212 .I find
 213 to specify that aliases are never dereferenced, always dereferenced,
 214 dereferenced when searching, or dereferenced only when locating the
 215 base object for the search.  The default is to never dereference aliases.
 216 .TP
 217 .BI \-P \ 2\fR\||\|\fI3
 218 Specify the LDAP protocol version to use.
 219 .TP
 220 .BI \-l \ timelimit
 221 wait at most \fItimelimit\fP seconds for a search to complete.  A
 222 timelimit of
 223 .I 0
 224 (zero) removes the
 225 .B ldap.conf
 226 limit.
 227 A server may impose a maximal timelimit which only
 228 the root user may override.
 229 .TP
 230 .BI \-z \ sizelimit
 231 retrieve at most \fIsizelimit\fP entries for a search.  A sizelimit
 232 of
 233 .I 0
 234 (zero) removes the
 235 .B ldap.conf
 236 limit.
 237 A server may impose a maximal sizelimit which only
 238 the root user may override.
 239 .TP
 240 .BI \-O \ security-properties
 241 Specify SASL security properties.
 242 .TP
 243 .B \-I
 244 Enable SASL Interactive mode.  Always prompt.  Default is to prompt
 245 only as needed.
 246 .TP
 247 .B \-Q
 248 Enable SASL Quiet mode.  Never prompt.
 249 .TP
 250 .BI \-U \ username
 251 Specify the username for SASL bind. The syntax of the username depends on the
 252 actual SASL mechanism used.
 253 .TP
 254 .TP
 255 .BI \-X \ authzid
 256 Specify the requested authorization ID for SASL bind.
 257 .I authzid
 258 must be one of the following formats:
 259 .B dn:\c
 260 .I <distinguished name>
 261 or
 262 .B u:\c
 263 .I <username>
 264 .TP
 265 .BI \-Y \ mech
 266 Specify the SASL mechanism to be used for authentication. If it's not
 267 specified, the program will choose the best mechanism the server knows.
 268 .TP
 269 .B \-Z[Z]
 270 Issue StartTLS (Transport Layer Security) extended operation. If you use
 271 .B \-ZZ\c
 272 , the command will require the operation to be successful.
 273 .SH OUTPUT FORMAT
 274 If one or more entries are found, each entry is written to standard
 275 output in LDAP Data Interchange Format or
 276 .BR ldif (5):
 277 .LP
 278 .nf
 279         version: 1
 280
 281         # bjensen, example, net
 282         dn: uid=bjensen, dc=example, dc=net
 283         objectClass: person
 284         objectClass: dcObject
 285         uid: bjensen
 286         cn: Barbara Jensen
 287         sn: Jensen
 288     ...
 289 .fi
 290 .LP
 291 If the -t option is used, the URI of a temporary file
 292 is used in place of the actual value.  If the -A option
 293 is given, only the "attributename" part is written.
 294 .SH EXAMPLE
 295 The following command:
 296 .LP
 297 .nf
 298     ldapsearch -LLL "(sn=smith)" cn sn telephoneNumber
 299 .fi
 300 .LP
 301 will perform a subtree search (using the default search base defined
 302 in
 303 .BR ldap.conf (5))
 304 for entries with a surname (sn) of smith.  The common name (cn), surname
 305 (sn) and telephoneNumber values will be retrieved and printed to
 306 standard output.
 307 The output might look something like this if two entries are found:
 308 .LP
 309 .nf
 310     dn: uid=jts, dc=example, dc=com
 311         cn: John Smith
 312         cn: John T. Smith
 313         sn: Smith
 314         sn;lang-en: Smith
 315         sn;lang-de: Schmidt
 316         telephoneNumber: 1 555 123-4567
 317
 318         dn: uid=sss, dc=example, dc=com
 319         cn: Steve Smith
 320         cn: Steve S. Smith
 321         sn: Smith
 322         sn;lang-en: Smith
 323         sn;lang-de: Schmidt
 324         telephoneNumber: 1 555 765-4321
 325 .fi
 326 .LP
 327 The command:
 328 .LP
 329 .nf
 330     ldapsearch -LLL -u -t "(uid=xyz)" jpegPhoto audio
 331 .fi
 332 .LP
 333 will perform a subtree search using the default search base for entries
 334 with user id of "xyz".  The user friendly form of the entry's DN will be
 335 output after the line that contains the DN itself, and the jpegPhoto
 336 and audio values will be retrieved and written to temporary files.  The
 337 output might look like this if one entry with one value for each of the
 338 requested attributes is found:
 339 .LP
 340 .nf
 341     dn: uid=xyz, dc=example, dc=com
 342     ufn: xyz, example, com
 343     audio:< file::/tmp/ldapsearch-audio-a19924
 344     jpegPhoto:< file::=/tmp/ldapsearch-jpegPhoto-a19924
 345 .fi
 346 .LP
 347 This command:
 348 .LP
 349 .nf
 350     ldapsearch -LLL -s one -b "c=US" "(o=University*)" o description
 351 .fi
 352 .LP
 353 will perform a one-level search at the c=US level for all entries
 354 whose organization name (o) begins begins with \fBUniversity\fP.
 355 The organization name and description attribute values will be retrieved
 356 and printed to standard output, resulting in output similar to this:
 357 .LP
 358 .nf
 359     dn: o=University of Alaska Fairbanks, c=US
 360     o: University of Alaska Fairbanks
 361     description: Preparing Alaska for a brave new yesterday
 362     description: leaf node only
 363
 364     dn: o=University of Colorado at Boulder, c=US
 365     o: University of Colorado at Boulder
 366     description: No personnel information
 367     description: Institution of education and research
 368
 369     dn: o=University of Colorado at Denver, c=US
 370     o: University of Colorado at Denver
 371     o: UCD
 372     o: CU/Denver
 373     o: CU-Denver
 374     description: Institute for Higher Learning and Research
 375
 376     dn: o=University of Florida, c=US
 377     o: University of Florida
 378     o: UFl
 379     description: Warper of young minds
 380
 381     etc....
 382 .fi
 383 .SH DIAGNOSTICS
 384 Exit status is zero if no errors occur.
 385 Errors result in a non-zero exit status and
 386 a diagnostic message being written to standard error.
 387 .SH "SEE ALSO"
 388 .BR ldapadd (1),
 389 .BR ldapdelete (1),
 390 .BR ldapmodify (1),
 391 .BR ldapmodrdn (1),
 392 .BR ldap.conf (5),
 393 .BR ldif (5),
 394 .BR ldap (3),
 395 .BR ldap_search (3)
 396 .SH AUTHOR
 397 The OpenLDAP Project <http://www.openldap.org/>
 398 .SH ACKNOWLEDGEMENTS
 399 .B      OpenLDAP
 400 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 401 .B      OpenLDAP
 402 is derived from University of Michigan LDAP 3.3 Release.