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