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

   1 .TH LDAPSEARCH 1 "21 July 1999" "OpenLDAP LDVERSION"
   2 .SH NAME
   3 ldapsearch \- ldap search tool
   4 .SH SYNOPSIS
   5 .B ldapsearch
   6 [\c
   7 .BR \-n ]
   8 [\c
   9 .BR \-u ]
  10 [\c
  11 .BR \-v ]
  12 [\c
  13 .BR \-k ]
  14 [\c
  15 .BR \-K ]
  16 [\c
  17 .BR \-t ]
  18 [\c
  19 .BR \-A ]
  20 [\c
  21 .BR \-B ]
  22 [\c
  23 .BR \-L ]
  24 [\c
  25 .BR \-R ]
  26 [\c
  27 .BI \-d \ debuglevel\fR]
  28 [\c
  29 .BI \-F \ sep\fR]
  30 [\c
  31 .BI \-f \ file\fR]
  32 [\c
  33 .BI \-D \ binddn\fR]
  34 [\c
  35 .BR \-W ]
  36 [\c
  37 .BI \-w \ bindpasswd\fR]
  38 [\c
  39 .BI \-h \ ldaphost\fR]
  40 [\c
  41 .BI \-p \ ldapport\fR]
  42 [\c
  43 .BI \-b \ searchbase\fR]
  44 [\c
  45 .BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub\fR]
  46 [\c
  47 .BI \-a \ never\fR\||\|\fIalways\fR\||\|\fIsearch\fR\||\|\fIfind\fR]
  48 [\c
  49 .BI \-l \ timelimit\fR]
  50 [\c
  51 .BI \-z \ sizelimit\fR]
  52 .I filter
  53 [\c
  54 .IR attrs... ]
  55 .SH DESCRIPTION
  56 .I ldapsearch
  57 is a shell-accessible interface to the
  58 .BR ldap_search (3)
  59 library call.
  60 .LP
  61 .B ldapsearch
  62 opens a connection to an LDAP server, binds, and performs a search
  63 using the filter \fIfilter\fP.  The \fIfilter\fP should conform to
  64 the string representation for LDAP filters as defined in RFC 1558.
  65 .LP
  66 If
  67 .B ldapsearch
  68 finds one or more entries, the attributes specified by
  69 \fIattrs\fP are retrieved and the entries and values are printed to
  70 standard output.  If no \fIattrs\fP are listed, all attributes are
  71 returned.
  72 .SH OPTIONS
  73 .TP
  74 .B \-n
  75 Show what would be done, but don't actually perform the search.  Useful for
  76 debugging in conjunction with -v.
  77 .TP
  78 .B \-u
  79 Include the User Friendly form of the Distinguished Name (DN) in the output
  80 .TP
  81 .B \-v
  82 Run in verbose mode, with many diagnostics written to standard output
  83 .TP
  84 .B \-k
  85 Use Kerberos authentication instead of simple authentication.  It is
  86 assumed that you already have a valid ticket granting ticket.
  87 .B ldapsearch
  88 must be compiled with KERBEROS defined for this option to have any effect.
  89 .TP
  90 .B \-K
  91 Same as \-k, but only does step 1 of the kerberos bind.  This is useful
  92 when connecting to a slapd and there is no x500dsa.hostname principal
  93 registered with your kerberos servers.
  94 .TP
  95 .B \-t
  96 Write retrieved values to a set of temporary files.  This is useful for
  97 dealing with non-ASCII values such as jpegPhoto or audio.
  98 .TP
  99 .B \-A
 100 Retrieve attributes only (no values).  This is useful when you just want to
 101 see if an attribute is present in an entry and are not interested in the
 102 specific values.
 103 .TP
 104 .B \-B
 105 Do not suppress display of non-ascii values.  This is useful when
 106 dealing with values that appear in alternate characters sets such as
 107 ISO-8859.1.  This option is implied by -L (see below).
 108 .TP
 109 .B \-L
 110 Display search results in
 111 .BR ldif (5)
 112 format.  This option also turns on the -B option, and causes the -F option
 113 to be ignored.
 114 .TP
 115 .B \-R
 116 Do not automatically follow referrals returned while searching.
 117 .B ldapsearch
 118 must be compiled with LDAP_REFERRALS defined for referrals to be
 119 automatically followed by default, and for this option to have any effect.
 120 .TP
 121 .BI \-F \ sep
 122 Use \fIsep\fP as the field separator between attribute names and values.
 123 The default separator is `=', unless the -L flag has been specified, in
 124 which case this option is ignored.
 125 .TP
 126 .BI \-S \ attribute
 127 Sort the entries returned based on \fIattribute\fP. The default is not
 128 to sort entries returned.  If \fIattribute\fP is a zero-length string (""),
 129 the entries are sorted by the components of their Distingished Name.  See
 130 .BR ldap_sort (3)
 131 for more details. Note that
 132 .B ldapsearch
 133 normally prints out entries as it receives them. The use of the
 134 .B \-S
 135 option defeats this behavior, causing all entries to be retrieved,
 136 then sorted, then printed.
 137 .TP
 138 .BI \-d \ debuglevel
 139 Set the LDAP debugging level to \fIdebuglevel\fP.
 140 .B ldapsearch
 141 must be compiled with LDAP_DEBUG defined for this option to have any effect.
 142 .TP
 143 .BI \-f \ file
 144 Read a series of lines from \fIfile\fP, performing one LDAP search for
 145 each line.  In this case, the \fIfilter\fP given on the command line
 146 is treated as a pattern where the first occurrence of \fB%s\fP is
 147 replaced with a line from \fIfile\fP.  If \fIfile\fP is a single \fI-\fP
 148 character, then the lines are read from standard input.
 149 .TP
 150 .BI \-D \ binddn
 151 Use \fIbinddn\fP to bind to the LDAP directory. \fIbinddn\fP should be
 152 a string-represented DN as defined in RFC 1779.
 153 .TP
 154 .B \-W
 155 Prompt for simple authentication.
 156 This is used instead of specifying the password on the command line.
 157 .TP
 158 .BI \-w \ bindpasswd
 159 Use \fIbindpasswd\fP as the password for simple authentication.
 160 .TP
 161 .BI \-h \ ldaphost
 162 Specify an alternate host on which the ldap server is running.
 163 .TP
 164 .BI \-p \ ldapport
 165 Specify an alternate TCP port where the ldap server is listening.
 166 .TP
 167 .BI \-b \ searchbase
 168 Use \fIsearchbase\fP as the starting point for the search instead of
 169 the default.
 170 .TP
 171 .BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub
 172 Specify the scope of the search to be one of
 173 .IR base ,
 174 .IR one ,
 175 or
 176 .I sub
 177 to specify a base object, one-level, or subtree search.  The default
 178 is
 179 .IR sub .
 180 .TP
 181 .BI \-a \ never\fR\||\|\fIalways\fR\||\|\fIsearch\fR\||\|\fIfind
 182 Specify how aliases dereferencing is done.  Should be one of
 183 .IR never ,
 184 .IR always ,
 185 .IR search ,
 186 or
 187 .I find
 188 to specify that aliases are never dereferenced, always dereferenced,
 189 dereferenced when searching, or dereferenced only when locating the
 190 base object for the search.  The default is to never dereference aliases.
 191 .TP
 192 .BI \-l \ timelimit
 193 wait at most \fItimelimit\fP seconds for a search to complete.  A
 194 timelimit of
 195 .I 0
 196 (zero) removes the
 197 .B ldap.conf
 198 limit.
 199 A server may impose a maximal timelimit which only
 200 the root user may override.
 201 .TP
 202 .BI \-z \ sizelimit
 203 retrieve at most \fIsizelimit\fP entries for a search.  A sizelimit
 204 of
 205 .I 0
 206 (zero) removes the
 207 .B ldap.conf
 208 limit.
 209 A server may impose a maximal sizelimit which only
 210 the root user may override.
 211 .SH OUTPUT FORMAT
 212 If one or more entries are found, each entry is written to standard output
 213 in the form:
 214 .LP
 215 .nf
 216     Distinguished Name (DN)
 217     User Friendly Name (this line present only if the -u option is used)
 218     attributename=value
 219     attributename=value
 220     attributename=value
 221     ...
 222 .fi
 223 .LP
 224 Multiple entries are separated with a single blank line.  If the -F option
 225 is used to specify a separator character, it will be used instead of the
 226 `=' character.  If the -t option is used, the name of a temporary file
 227 is used in place of the actual value.  If the -A option
 228 is given, only the "attributename" part is written.
 229 .SH EXAMPLE
 230 The following command:
 231 .LP
 232 .nf
 233     ldapsearch "cn=mark smith" cn telephoneNumber
 234 .fi
 235 .LP
 236 will perform a subtree search (using the default search base) for entries
 237 with a commonName of "mark smith".  The commonName and telephoneNumber
 238 values will be retrieved and printed to standard output.
 239 The output might look something like this if two entries are found:
 240 .LP
 241 .nf
 242 cn=Mark D Smith, ou="College of Literature, Science, and the Arts", ou=Students, ou=People, o=University of Michigan, c=US
 243 cn=Mark Smith
 244 cn=Mark David Smith
 245 cn=Mark D Smith 1
 246 cn=Mark D Smith
 247 telephoneNumber=+1 313 930-9489
 248
 249 cn=Mark C Smith, ou=Information Technology Division, ou=Faculty and Staff, ou=People, o=University of Michigan, c=US
 250 cn=Mark Smith
 251 cn=Mark C Smith 1
 252 cn=Mark C Smith
 253 telephoneNumber=+1 313 764-2277
 254 .fi
 255 .LP
 256 The command:
 257 .LP
 258 .nf
 259     ldapsearch -u -t "uid=mcs" jpegPhoto audio
 260 .fi
 261 .LP
 262 will perform a subtree search using the default search base for entries
 263 with user id of "mcs".  The user friendly form of the entry's DN will be
 264 output after the line that contains the DN itself, and the jpegPhoto
 265 and audio values will be retrieved and written to temporary files.  The
 266 output might look like this if one entry with one value for each of the
 267 requested attributes is found:
 268 .LP
 269 .nf
 270 cn=Mark C Smith, ou=Information Technology Division, ou=Faculty and Staff, ou=People, o=University of Michigan, c=US
 271 Mark C Smith, Information Technology Division, Faculty and Staff, People, University of Michigan, US
 272 audio=/tmp/ldapsearch-audio-a19924
 273 jpegPhoto=/tmp/ldapsearch-jpegPhoto-a19924
 274 .fi
 275 .LP
 276 This command:
 277 .LP
 278 .nf
 279     ldapsearch -L -s one -b "c=US" "o=university*" o description
 280 .fi
 281 .LP
 282 will perform a one-level search at the c=US level for all organizations
 283 whose organizationName begins with \fBuniversity\fP.  Search results
 284 will be displayed in the LDIF format.
 285 The organizationName and description attribute values will be retrieved
 286 and printed to standard output, resulting in output similar to this:
 287 .LP
 288 .nf
 289 dn: o=University of Alaska Fairbanks, c=US
 290 o: University of Alaska Fairbanks
 291 description: Preparing Alaska for a brave new yesterday
 292 description: leaf node only
 293
 294 dn: o=University of Colorado at Boulder, c=US
 295 o: University of Colorado at Boulder
 296 description: No personnel information
 297 description: Institution of education and research
 298
 299 dn: o=University of Colorado at Denver, c=US
 300 o: University of Colorado at Denver
 301 o: UCD
 302 o: CU/Denver
 303 o: CU-Denver
 304 description: Institute for Higher Learning and Research
 305
 306 dn: o=University of Florida, c=US
 307 o: University of Florida
 308 o: UFl
 309 description: Warper of young minds
 310
 311 etc....
 312 .fi
 313 .SH DIAGNOSTICS
 314 Exit status is 0 if no errors occur.  Errors result in a non-zero exit
 315 status and a diagnostic message being written to standard error.
 316 .SH "SEE ALSO"
 317 .BR ldapadd (1),
 318 .BR ldapdelete (1),
 319 .BR ldapmodify (1),
 320 .BR ldapmodrdn (1),
 321 .BR ldap.conf (5),
 322 .BR ldap (3),
 323 .BR ldap_search (3)
 324 .LP
 325 Kille, S.,
 326 .IR "A String Representation of Distinguished Names",
 327 .SM RFC
 328 1779,
 329 ISODE Consortium, March 1995.
 330 .LP
 331 Howes, T.,
 332 .IR "A String Representation of LDAP Search Filters",
 333 .SM RFC
 334 1558,
 335 University of Michigan, December 1993.
 336 .SH ACKNOWLEDGEMENTS
 337 .B      OpenLDAP
 338 is developed and maintained by The OpenLDAP Project (http://www.openldap.org/).
 339 .B      OpenLDAP
 340 is derived from University of Michigan LDAP 3.3 Release.