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

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