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

   1 .TH LDAPSEARCH 1 "20 April 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 \-B ]
  25 [\c
  26 .BR \-L ]
  27 [\c
  28 .BR \-M[M] ]
  29 [\c
  30 .BR \-R ]
  31 [\c
  32 .BI \-d \ debuglevel\fR]
  33 [\c
  34 .BI \-F \ sep\fR]
  35 [\c
  36 .BI \-f \ file\fR]
  37 [\c
  38 .BI \-D \ binddn\fR]
  39 [\c
  40 .BR \-W ]
  41 [\c
  42 .BI \-w \ bindpasswd\fR]
  43 [\c
  44 .BI \-h \ ldaphost\fR]
  45 [\c
  46 .BI \-p \ ldapport\fR]
  47 [\c
  48 .BI \-P \ 2\fR\||\|\fI3\fR]
  49 [\c
  50 .BI \-b \ searchbase\fR]
  51 [\c
  52 .BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub\fR]
  53 [\c
  54 .BI \-a \ never\fR\||\|\fIalways\fR\||\|\fIsearch\fR\||\|\fIfind\fR]
  55 [\c
  56 .BI \-l \ timelimit\fR]
  57 [\c
  58 .BI \-z \ sizelimit\fR]
  59 [\c
  60 .BR \-E[E] ]
  61 [\c
  62 .BR \-I[I] ]
  63 [\c
  64 .BI \-U \ username\fR]
  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 \-B
 126 Do not suppress display of non-ascii values.  This is useful when
 127 dealing with values that appear in alternate characters sets such as
 128 ISO-8859.1.  This option is implied by -L (see below).
 129 .TP
 130 .B \-L
 131 Display search results in
 132 .BR ldif (5)
 133 format.  This option also turns on the -B option, and causes the -F option
 134 to be ignored.
 135 .TP
 136 .B \-M[M]
 137 Enable manage DSA IT control.
 138 .B \-MM
 139 makes control critical.
 140 .TP
 141 .B \-R
 142 Do not automatically follow referrals returned while searching.
 143 .B ldapsearch
 144 must be compiled with LDAP_REFERRALS defined for referrals to be
 145 automatically followed by default, and for this option to have any effect.
 146 .TP
 147 .BI \-F \ sep
 148 Use \fIsep\fP as the field separator between attribute names and values.
 149 The default separator is `=', unless the -L flag has been specified, in
 150 which case this option is ignored.
 151 .TP
 152 .BI \-S \ attribute
 153 Sort the entries returned based on \fIattribute\fP. The default is not
 154 to sort entries returned.  If \fIattribute\fP is a zero-length string (""),
 155 the entries are sorted by the components of their Distingished Name.  See
 156 .BR ldap_sort (3)
 157 for more details. Note that
 158 .B ldapsearch
 159 normally prints out entries as it receives them. The use of the
 160 .B \-S
 161 option defeats this behavior, causing all entries to be retrieved,
 162 then sorted, then printed.
 163 .TP
 164 .BI \-d \ debuglevel
 165 Set the LDAP debugging level to \fIdebuglevel\fP.
 166 .B ldapsearch
 167 must be compiled with LDAP_DEBUG defined for this option to have any effect.
 168 .TP
 169 .BI \-f \ file
 170 Read a series of lines from \fIfile\fP, performing one LDAP search for
 171 each line.  In this case, the \fIfilter\fP given on the command line
 172 is treated as a pattern where the first occurrence of \fB%s\fP is
 173 replaced with a line from \fIfile\fP.  If \fIfile\fP is a single \fI-\fP
 174 character, then the lines are read from standard input.
 175 .TP
 176 .BI \-D \ binddn
 177 Use \fIbinddn\fP to bind to the LDAP directory. \fIbinddn\fP should be
 178 a string-represented DN as defined in RFC 1779.
 179 .TP
 180 .B \-W
 181 Prompt for simple authentication.
 182 This is used instead of specifying the password on the command line.
 183 .TP
 184 .BI \-w \ bindpasswd
 185 Use \fIbindpasswd\fP as the password for simple authentication.
 186 .TP
 187 .BI \-h \ ldaphost
 188 Specify an alternate host on which the ldap server is running.
 189 .TP
 190 .BI \-p \ ldapport
 191 Specify an alternate TCP port where the ldap server is listening.
 192 .TP
 193 .BI \-b \ searchbase
 194 Use \fIsearchbase\fP as the starting point for the search instead of
 195 the default.
 196 .TP
 197 .BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub
 198 Specify the scope of the search to be one of
 199 .IR base ,
 200 .IR one ,
 201 or
 202 .I sub
 203 to specify a base object, one-level, or subtree search.  The default
 204 is
 205 .IR sub .
 206 .TP
 207 .BI \-a \ never\fR\||\|\fIalways\fR\||\|\fIsearch\fR\||\|\fIfind
 208 Specify how aliases dereferencing is done.  Should be one of
 209 .IR never ,
 210 .IR always ,
 211 .IR search ,
 212 or
 213 .I find
 214 to specify that aliases are never dereferenced, always dereferenced,
 215 dereferenced when searching, or dereferenced only when locating the
 216 base object for the search.  The default is to never dereference aliases.
 217 .TP
 218 .BI \-P \ 2\fR\||\|\fI3
 219 Specify the LDAP protocol version to use.
 220 .TP
 221 .BI \-l \ timelimit
 222 wait at most \fItimelimit\fP seconds for a search to complete.  A
 223 timelimit of
 224 .I 0
 225 (zero) removes the
 226 .B ldap.conf
 227 limit.
 228 A server may impose a maximal timelimit which only
 229 the root user may override.
 230 .TP
 231 .BI \-z \ sizelimit
 232 retrieve at most \fIsizelimit\fP entries for a search.  A sizelimit
 233 of
 234 .I 0
 235 (zero) removes the
 236 .B ldap.conf
 237 limit.
 238 A server may impose a maximal sizelimit which only
 239 the root user may override.
 240 .TP
 241 .B \-E[E]
 242 Requset the use of SASL privacy (encryption). If the server allows it, data
 243 sent between the client and the server will be encrypted. If the server
 244 requires the use of encryption and this flag is not specified, the command
 245 will fail. If you use
 246 .B \-EE\c
 247 , the command will fail if the server does not support encryption.
 248 .B \-E[E]
 249 implies
 250 .B \-I[I]
 251 .TP
 252 .B \-I[I]
 253 Request the use of SASL integrity checking. It protects data sent between the
 254 client and the server from being modified along the way, but it does not
 255 prevent sniffing. If the server requires the use of integrity checking and
 256 this flag is not specified, the command will fail.If you use
 257 .B \-II\c
 258 , the command will fail if the server does not support this function.
 259 .TP
 260 .BI \-U \ username
 261 Specify the username for SASL bind. The syntax of the username depends on the
 262 actual SASL mechanism used.
 263 .TP
 264 .BI \-X \ authzid
 265 Specify the requested authorization ID for SASL bind.
 266 .I authzid
 267 must be one of the following formats:
 268 .B dn:\c
 269 .I <distinguished name>
 270 or
 271 .B u:\c
 272 .I <username>
 273 .TP
 274 .BI \-Y \ mech
 275 Specify the SASL mechanism to be used for authentication. If it's not
 276 specified, the program will choose the best mechanism the server knows.
 277 .TP
 278 .B \-Z[Z]
 279 Request the use of TLS (Transport Layer Security). If you use
 280 .B \-ZZ\c
 281 , the command will fail if TLS negotiation does not succeed for some reason.
 282 .SH OUTPUT FORMAT
 283 If one or more entries are found, each entry is written to standard output
 284 in the form:
 285 .LP
 286 .nf
 287     Distinguished Name (DN)
 288     User Friendly Name (this line present only if the -u option is used)
 289     attributename=value
 290     attributename=value
 291     attributename=value
 292     ...
 293 .fi
 294 .LP
 295 Multiple entries are separated with a single blank line.  If the -F option
 296 is used to specify a separator character, it will be used instead of the
 297 `=' character.  If the -t option is used, the name of a temporary file
 298 is used in place of the actual value.  If the -A option
 299 is given, only the "attributename" part is written.
 300 .SH EXAMPLE
 301 The following command:
 302 .LP
 303 .nf
 304     ldapsearch "(sn=smith)" cn sn telephoneNumber
 305 .fi
 306 .LP
 307 will perform a subtree search (using the default search base) for
 308 entries with a surname (sn) of smith.  The common name (cn), surname
 309 (sn) and telephoneNumber values will be retrieved and printed to
 310 standard output.
 311 The output might look something like this if two entries are found:
 312 .LP
 313 .nf
 314 uid=jts, ou=Volunteers, ou=People, dc=OpenLDAP, dc=org
 315 cn=John Smith
 316 cn=John T. Smith
 317 sn=Smith
 318 telephoneNumber=+1 555 123-4567
 319
 320 uid=sss, ou=Staff, ou=People, dc=OpenLDAP, dc=org
 321 cn=Steve Smith
 322 cn=Steve S. Smith
 323 sn=Smith
 324 telephoneNumber=+1 555 765-4321
 325 .fi
 326 .LP
 327 The command:
 328 .LP
 329 .nf
 330     ldapsearch -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 uid=xyz, ou=Staff, ou=People, dc=OpenLDAP, dc=org
 342 xyz, Staff, People, OpenLDAP, org
 343 audio=/tmp/ldapsearch-audio-a19924
 344 jpegPhoto=/tmp/ldapsearch-jpegPhoto-a19924
 345 .fi
 346 .LP
 347 This command:
 348 .LP
 349 .nf
 350     ldapsearch -L -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 organizationName (o) begins begins with \fBUniversity\fP.
 355 Search results will be displayed in the LDIF format.
 356 The organizationName and description attribute values will be retrieved
 357 and printed to standard output, resulting in output similar to this:
 358 .LP
 359 .nf
 360 dn: o=University of Alaska Fairbanks, c=US
 361 o: University of Alaska Fairbanks
 362 description: Preparing Alaska for a brave new yesterday
 363 description: leaf node only
 364
 365 dn: o=University of Colorado at Boulder, c=US
 366 o: University of Colorado at Boulder
 367 description: No personnel information
 368 description: Institution of education and research
 369
 370 dn: o=University of Colorado at Denver, c=US
 371 o: University of Colorado at Denver
 372 o: UCD
 373 o: CU/Denver
 374 o: CU-Denver
 375 description: Institute for Higher Learning and Research
 376
 377 dn: o=University of Florida, c=US
 378 o: University of Florida
 379 o: UFl
 380 description: Warper of young minds
 381
 382 etc....
 383 .fi
 384 .SH DIAGNOSTICS
 385 Exit status is 0 if no errors occur.  Errors result in a non-zero exit
 386 status and 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 ldap (3),
 394 .BR ldap_search (3)
 395 .LP
 396 Kille, S.,
 397 .IR "A String Representation of Distinguished Names",
 398 .SM RFC
 399 1779,
 400 ISODE Consortium, March 1995.
 401 .LP
 402 Howes, T.,
 403 .IR "A String Representation of LDAP Search Filters",
 404 .SM RFC
 405 1558,
 406 University of Michigan, December 1993.
 407 .SH ACKNOWLEDGEMENTS
 408 .B      OpenLDAP
 409 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 410 .B      OpenLDAP
 411 is derived from University of Michigan LDAP 3.3 Release.