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

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