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

   1 .TH LDAPSEARCH 1 "RELEASEDATE" "OpenLDAP LDVERSION"
   2 .\" $OpenLDAP$
   3 .\" Copyright 1998-2005 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 ]
  17 [\c
  18 .BR \-A ]
  19 [\c
  20 .BR \-L[L[L]] ]
  21 [\c
  22 .BR \-M[M] ]
  23 [\c
  24 .BI \-d \ debuglevel\fR]
  25 [\c
  26 .BI \-f \ file\fR]
  27 [\c
  28 .BI \-D \ binddn\fR]
  29 [\c
  30 .BR \-W ]
  31 [\c
  32 .BI \-w \ passwd\fR]
  33 [\c
  34 .BI \-y \ passwdfile\fR]
  35 [\c
  36 .BI \-H \ ldapuri\fR]
  37 [\c
  38 .BI \-h \ ldaphost\fR]
  39 [\c
  40 .BI \-p \ ldapport\fR]
  41 [\c
  42 .BI \-P \ 2\fR\||\|\fI3\fR]
  43 [\c
  44 .BI \-b \ searchbase\fR]
  45 [\c
  46 .BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub\fR\||\|\fIchildren\fR]
  47 [\c
  48 .BI \-a \ never\fR\||\|\fIalways\fR\||\|\fIsearch\fR\||\|\fIfind\fR]
  49 [\c
  50 .BI \-l \ timelimit\fR]
  51 [\c
  52 .BI \-z \ sizelimit\fR]
  53 [\c
  54 .BR \-O \ security-properties ]
  55 [\c
  56 .BR \-I ]
  57 [\c
  58 .BR \-Q ]
  59 [\c
  60 .BI \-U \ authcid\fR]
  61 [\c
  62 .BI \-R \ realm\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 specified parameters.   The \fIfilter\fP should conform to
  83 the string representation for search filters as defined in RFC 2254.
  84 If not provided, the default filter, (objectClass=*), is used.
  85 .LP
  86 If
  87 .B ldapsearch finds one or more entries, the attributes specified by
  88 \fIattrs\fP are returned.  If * is listed, all user attributes are
  89 returned.  If + is listed, all operational attributes are returned.
  90 If no \fIattrs\fP are listed, all user attributes are returned.  If only
  91 1.1 is listed, no attributes will be returned.
  92 .SH OPTIONS
  93 .TP
  94 .B \-n
  95 Show what would be done, but don't actually perform the search.  Useful for
  96 debugging in conjunction with -v.
  97 .TP
  98 .B \-u
  99 Include the User Friendly Name form of the Distinguished Name (DN)
 100 in the output.
 101 .TP
 102 .B \-v
 103 Run in verbose mode, with many diagnostics written to standard output.
 104 .TP
 105 .B \-t
 106 Write retrieved non-printable values to a set of temporary files.  This
 107 is useful for dealing with values containing non-character data such as
 108 jpegPhoto or audio.
 109 .TP
 110 .B \-A
 111 Retrieve attributes only (no values).  This is useful when you just want to
 112 see if an attribute is present in an entry and are not interested in the
 113 specific values.
 114 .TP
 115 .B \-L
 116 Search results are display in LDAP Data Interchange Format detailed in
 117 .BR ldif (5).
 118 A single -L restricts the output to LDIFv1.
 119 A second -L disables comments.
 120 A third -L disables printing of the LDIF version.
 121 The default is to use an extended version of LDIF.
 122 .TP
 123 .B \-M[M]
 124 Enable manage DSA IT control.
 125 .B \-MM
 126 makes control critical.
 127 .TP
 128 .BI \-S \ attribute
 129 Sort the entries returned based on \fIattribute\fP. The default is not
 130 to sort entries returned.  If \fIattribute\fP is a zero-length string (""),
 131 the entries are sorted by the components of their Distinguished Name.  See
 132 .BR ldap_sort (3)
 133 for more details. Note that
 134 .B ldapsearch
 135 normally prints out entries as it receives them. The use of the
 136 .B \-S
 137 option defeats this behavior, causing all entries to be retrieved,
 138 then sorted, then printed.
 139 .TP
 140 .BI \-d \ debuglevel
 141 Set the LDAP debugging level to \fIdebuglevel\fP.
 142 .B ldapsearch
 143 must be compiled with LDAP_DEBUG defined for this option to have any effect.
 144 .TP
 145 .BI \-f \ file
 146 Read a series of lines from \fIfile\fP, performing one LDAP search for
 147 each line.  In this case, the \fIfilter\fP given on the command line
 148 is treated as a pattern where the first occurrence of \fB%s\fP is
 149 replaced with a line from \fIfile\fP.  If \fIfile\fP is a single \fI-\fP
 150 character, then the lines are read from standard input.
 151 .TP
 152 .B \-x
 153 Use simple authentication instead of SASL.
 154 .TP
 155 .BI \-D \ binddn
 156 Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory.
 157 .TP
 158 .B \-W
 159 Prompt for simple authentication.
 160 This is used instead of specifying the password on the command line.
 161 .TP
 162 .BI \-w \ passwd
 163 Use \fIpasswd\fP as the password for simple authentication.
 164 .TP
 165 .BI \-y \ passwdfile
 166 Use complete contents of \fIpasswdfile\fP as the password for
 167 simple authentication.
 168 .TP
 169 .BI \-H \ ldapuri
 170 Specify URI(s) referring to the ldap server(s); only the protocol/host/port
 171 fields are allowed; a list of URI, separated by whitespace or commas
 172 is expected.
 173 .TP
 174 .BI \-h \ ldaphost
 175 Specify an alternate host on which the ldap server is running.
 176 Deprecated in favor of -H.
 177 .TP
 178 .BI \-p \ ldapport
 179 Specify an alternate TCP port where the ldap server is listening.
 180 Deprecated in favor of -H.
 181 .TP
 182 .BI \-b \ searchbase
 183 Use \fIsearchbase\fP as the starting point for the search instead of
 184 the default.
 185 .TP
 186 .BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub\fR\||\|\fIchildren
 187 Specify the scope of the search to be one of
 188 .IR base ,
 189 .IR one ,
 190 .IR sub ,
 191 or
 192 .I children
 193 to specify a base object, one-level, subtree, or children search.
 194 The default is
 195 .IR sub .
 196 .TP
 197 .BI \-a \ never\fR\||\|\fIalways\fR\||\|\fIsearch\fR\||\|\fIfind
 198 Specify how aliases dereferencing is done.  Should be one of
 199 .IR never ,
 200 .IR always ,
 201 .IR search ,
 202 or
 203 .I find
 204 to specify that aliases are never dereferenced, always dereferenced,
 205 dereferenced when searching, or dereferenced only when locating the
 206 base object for the search.  The default is to never dereference aliases.
 207 .TP
 208 .BI \-P \ 2\fR\||\|\fI3
 209 Specify the LDAP protocol version to use.
 210 .TP
 211 .BI \-l \ timelimit
 212 wait at most \fItimelimit\fP seconds for a search to complete.
 213 A timelimit of
 214 .I 0
 215 (zero) or
 216 .I none
 217 means no limit.
 218 A timelimit of
 219 .I max
 220 means the maximum integer allowable by the protocol.
 221 A server may impose a maximal timelimit which only
 222 the root user may override.
 223 .TP
 224 .BI \-z \ sizelimit
 225 retrieve at most \fIsizelimit\fP entries for a search.
 226 A sizelimit of
 227 .I 0
 228 (zero) or
 229 .I none
 230 means no limit.
 231 A sizelimit of
 232 .I max
 233 means the maximum integer allowable by the protocol.
 234 A server may impose a maximal sizelimit which only
 235 the root user may override.
 236 .TP
 237 .BI \-O \ security-properties
 238 Specify SASL security properties.
 239 .TP
 240 .B \-I
 241 Enable SASL Interactive mode.  Always prompt.  Default is to prompt
 242 only as needed.
 243 .TP
 244 .B \-Q
 245 Enable SASL Quiet mode.  Never prompt.
 246 .TP
 247 .BI \-U \ authcid
 248 Specify the authentication ID for SASL bind. The form of the ID
 249 depends on the actual SASL mechanism used.
 250 .TP
 251 .BI \-R \ realm
 252 Specify the realm of authentication ID for SASL bind. The form of the realm
 253 depends on the actual SASL mechanism used.
 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 and
 302 other parameters defined 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     ...
 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.