X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman1%2Fldapsearch.1;h=7d5997ae210bcbd56ce038173d6d21ba4e8cadfb;hb=607c80df81596e1bdfe39cf0ded31ea1d90ea6d2;hp=45aafa2285973d39a5f874f3ff02c0e90846b577;hpb=2f8f8b588e9bc7565796936ad17ec963b1ba0b19;p=openldap diff --git a/doc/man/man1/ldapsearch.1 b/doc/man/man1/ldapsearch.1 index 45aafa2285..7d5997ae21 100644 --- a/doc/man/man1/ldapsearch.1 +++ b/doc/man/man1/ldapsearch.1 @@ -1,6 +1,6 @@ -.TH LDAPSEARCH 1 "3 October 2000" "OpenLDAP LDVERSION" +.TH LDAPSEARCH 1 "RELEASEDATE" "OpenLDAP LDVERSION" .\" $OpenLDAP$ -.\" Copyright 1998-2000 The OpenLDAP Foundation All Rights Reserved. +.\" Copyright 1998-2006 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldapsearch \- LDAP search tool @@ -9,33 +9,39 @@ ldapsearch \- LDAP search tool [\c .BR \-n ] [\c +.BR \-c ] +[\c .BR \-u ] [\c .BR \-v ] [\c -.BR \-k ] +.BR \-t[t] ] [\c -.BR \-K ] +.BI \-T \ path\fR] [\c -.BR \-t ] +.BI \-F \ prefix\fR] [\c .BR \-A ] [\c -.BR \-C ] -[\c .BR \-L[L[L]] ] [\c .BR \-M[M] ] [\c +.BI \-S \ attribute\fR] +[\c .BI \-d \ debuglevel\fR] [\c .BI \-f \ file\fR] [\c +.BR \-x ] +[\c .BI \-D \ binddn\fR] [\c .BR \-W ] [\c -.BI \-w \ bindpasswd\fR] +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] [\c .BI \-H \ ldapuri\fR] [\c @@ -43,14 +49,18 @@ ldapsearch \- LDAP search tool [\c .BI \-p \ ldapport\fR] [\c -.BI \-P \ 2\fR\||\|\fI3\fR] -[\c .BI \-b \ searchbase\fR] [\c -.BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub\fR] +.BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub\fR\||\|\fIchildren\fR] [\c .BI \-a \ never\fR\||\|\fIalways\fR\||\|\fIsearch\fR\||\|\fIfind\fR] [\c +.BI \-P \ 2\fR\||\|\fI3\fR] +[\c +.BR \-e \ [!]ext[=extparam]] +[\c +.BR \-E \ [!]ext[=extparam]] +[\c .BI \-l \ timelimit\fR] [\c .BI \-z \ sizelimit\fR] @@ -61,9 +71,9 @@ ldapsearch \- LDAP search tool [\c .BR \-Q ] [\c -.BI \-U \ username\fR] +.BI \-U \ authcid\fR] [\c -.BR \-x ] +.BI \-R \ realm\fR] [\c .BI \-X \ authzid\fR] [\c @@ -76,20 +86,21 @@ ldapsearch \- LDAP search tool .SH DESCRIPTION .I ldapsearch is a shell-accessible interface to the -.BR ldap_search (3) +.BR ldap_search_ext (3) library call. .LP .B ldapsearch opens a connection to an LDAP server, binds, and performs a search using specified parameters. The \fIfilter\fP should conform to -the string representation for search filters as defined in RFC 2254. +the string representation for search filters as defined in RFC 4515. If not provided, the default filter, (objectClass=*), is used. .LP If -.B ldapsearch finds one or more entries, the attributes specified by +.B ldapsearch +finds one or more entries, the attributes specified by \fIattrs\fP are returned. If * is listed, all user attributes are returned. If + is listed, all operational attributes are returned. -If no \fIattrs\fP are listed, all attributes are returned. If only +If no \fIattrs\fP are listed, all user attributes are returned. If only 1.1 is listed, no attributes will be returned. .SH OPTIONS .TP @@ -97,6 +108,11 @@ If no \fIattrs\fP are listed, all attributes are returned. If only Show what would be done, but don't actually perform the search. Useful for debugging in conjunction with -v. .TP +.B \-c +Continuous operation mode. Errors are reported, but ldapsearch will continue +with searches. The default is to exit after reporting an error. Only useful +in conjunction with -f. +.TP .B \-u Include the User Friendly Name form of the Distinguished Name (DN) in the output. @@ -104,20 +120,19 @@ in the output. .B \-v Run in verbose mode, with many diagnostics written to standard output. .TP -.B \-k -Use Kerberos authentication instead of simple authentication. It is -assumed that you already have a valid ticket granting ticket. -.B ldapsearch -must be compiled with Kerberos support for this option to have any effect. +.B \-t[t] +A single -t writes retrieved non-printable values to a set of temporary +files. This is useful for dealing with values containing non-character +data such as jpegPhoto or audio. A second -t writes all retrieved values to +files. .TP -.B \-K -Same as \-k, but only does step 1 of the Kerberos bind. This is useful -when connecting to a slapd and there is no x500dsa.hostname principal -registered with your Kerberos servers. +.BI \-T \ path +Write temporary files to directory specified by \fIpath\fP (default: +/var/tmp/) .TP -.B \-t -Write retrieved values to a set of temporary files. This is useful for -dealing with non-ASCII values such as jpegPhoto or audio. +.BI \-F \ prefix +URL prefix for temporary files. Default is file://\fIpath\fP/ where +\fIpath\fP is /var/tmp/ or specified with -T. .TP .B \-A Retrieve attributes only (no values). This is useful when you just want to @@ -137,13 +152,10 @@ Enable manage DSA IT control. .B \-MM makes control critical. .TP -.B \-C -Automatically chase referrals. -.TP .BI \-S \ attribute Sort the entries returned based on \fIattribute\fP. The default is not to sort entries returned. If \fIattribute\fP is a zero-length string (""), -the entries are sorted by the components of their Distingished Name. See +the entries are sorted by the components of their Distinguished Name. See .BR ldap_sort (3) for more details. Note that .B ldapsearch @@ -160,9 +172,16 @@ must be compiled with LDAP_DEBUG defined for this option to have any effect. .BI \-f \ file Read a series of lines from \fIfile\fP, performing one LDAP search for each line. In this case, the \fIfilter\fP given on the command line -is treated as a pattern where the first occurrence of \fB%s\fP is -replaced with a line from \fIfile\fP. If \fIfile\fP is a single \fI-\fP -character, then the lines are read from standard input. +is treated as a pattern where the first and only occurrence of \fB%s\fP +is replaced with a line from \fIfile\fP. Any other occurence of the +the \fB%\fP character in the pattern will be regarded as an error. +Where it is desired that the search filter include a \fB%\fP character, +the character should be encoded as \fB\\25\fP (see RFC 4515). +If \fIfile\fP is a single +\fI-\fP character, then the lines are read from standard input. +.B ldapsearch +will exit when the first non-successful search result is returned, +unless -c is used. .TP .B \-x Use simple authentication instead of SASL. @@ -174,11 +193,17 @@ Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory. Prompt for simple authentication. This is used instead of specifying the password on the command line. .TP -.BI \-w \ bindpasswd -Use \fIbindpasswd\fP as the password for simple authentication. +.BI \-w \ passwd +Use \fIpasswd\fP as the password for simple authentication. +.TP +.BI \-y \ passwdfile +Use complete contents of \fIpasswdfile\fP as the password for +simple authentication. .TP .BI \-H \ ldapuri -Specify URI(s) referring to the ldap server(s). +Specify URI(s) referring to the ldap server(s); only the protocol/host/port +fields are allowed; a list of URI, separated by whitespace or commas +is expected. .TP .BI \-h \ ldaphost Specify an alternate host on which the ldap server is running. @@ -192,15 +217,19 @@ Deprecated in favor of -H. Use \fIsearchbase\fP as the starting point for the search instead of the default. .TP -.BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub +.BI \-s \ base\fR\||\|\fIone\fR\||\|\fIsub\fR\||\|\fIchildren Specify the scope of the search to be one of .IR base , .IR one , +.IR sub , or -.I sub -to specify a base object, one-level, or subtree search. The default -is +.I children +to specify a base object, one-level, subtree, or children search. +The default is .IR sub . +Note: +.I children +scope requires LDAPv3 subordinate feature extension. .TP .BI \-a \ never\fR\||\|\fIalways\fR\||\|\fIsearch\fR\||\|\fIfind Specify how aliases dereferencing is done. Should be one of @@ -216,23 +245,58 @@ base object for the search. The default is to never dereference aliases. .BI \-P \ 2\fR\||\|\fI3 Specify the LDAP protocol version to use. .TP +.B \-e \fI[!]ext[=extparam]\fP +.TP +.B \-E \fI[!]ext[=extparam]\fP + +Specify general extensions with -e and search extensions with -E. +\'!\' indicates criticality. + +General extensions: +.nf + [!]assert= (an RFC 4515 Filter) + [!]authzid= ("dn:" or "u:") + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + abandon, cancel (SIGINT sends abandon/cancel; not really controls) +.fi + +Search extensions: +.nf + [!]domainScope (domain scope) + [!]mv= (matched values filter) + [!]pr=[/prompt|noprompt] (paged results/prompt) + [!]subentries[=true|false] (subentries) + [!]sync=ro[/] (LDAP Sync refreshOnly) + rp[/][/] (LDAP Sync refreshAndPersist) +.fi +.TP .BI \-l \ timelimit -wait at most \fItimelimit\fP seconds for a search to complete. A -timelimit of +wait at most \fItimelimit\fP seconds for a search to complete. +A timelimit of .I 0 -(zero) removes the -.B ldap.conf -limit. +(zero) or +.I none +means no limit. +A timelimit of +.I max +means the maximum integer allowable by the protocol. A server may impose a maximal timelimit which only the root user may override. .TP .BI \-z \ sizelimit -retrieve at most \fIsizelimit\fP entries for a search. A sizelimit -of +retrieve at most \fIsizelimit\fP entries for a search. +A sizelimit of .I 0 -(zero) removes the -.B ldap.conf -limit. +(zero) or +.I none +means no limit. +A sizelimit of +.I max +means the maximum integer allowable by the protocol. A server may impose a maximal sizelimit which only the root user may override. .TP @@ -246,9 +310,13 @@ only as needed. .B \-Q Enable SASL Quiet mode. Never prompt. .TP -.BI \-U \ username -Specify the username for SASL bind. The syntax of the username depends on the -actual SASL mechanism used. +.BI \-U \ authcid +Specify the authentication ID for SASL bind. The form of the ID +depends on the actual SASL mechanism used. +.TP +.BI \-R \ realm +Specify the realm of authentication ID for SASL bind. The form of the realm +depends on the actual SASL mechanism used. .TP .BI \-X \ authzid Specify the requested authorization ID for SASL bind. @@ -274,15 +342,15 @@ output in LDAP Data Interchange Format or .BR ldif (5): .LP .nf - version: 1 + version: 1 - # bjensen, example, net - dn: uid=bjensen, dc=example, dc=net - objectClass: person - objectClass: dcObject - uid: bjensen - cn: Barbara Jensen - sn: Jensen + # bjensen, example, net + dn: uid=bjensen,dc=example,dc=net + objectClass: person + objectClass: dcObject + uid: bjensen + cn: Barbara Jensen + sn: Jensen ... .fi .LP @@ -296,8 +364,8 @@ The following command: ldapsearch -LLL "(sn=smith)" cn sn telephoneNumber .fi .LP -will perform a subtree search (using the default search base defined -in +will perform a subtree search (using the default search base and +other parameters defined in .BR ldap.conf (5)) for entries with a surname (sn) of smith. The common name (cn), surname (sn) and telephoneNumber values will be retrieved and printed to @@ -305,21 +373,21 @@ standard output. The output might look something like this if two entries are found: .LP .nf - dn: uid=jts, dc=example, dc=com - cn: John Smith - cn: John T. Smith - sn: Smith - sn;lang-en: Smith - sn;lang-de: Schmidt - telephoneNumber: 1 555 123-4567 + dn: uid=jts,dc=example,dc=com + cn: John Smith + cn: John T. Smith + sn: Smith + sn;lang-en: Smith + sn;lang-de: Schmidt + telephoneNumber: 1 555 123-4567 - dn: uid=sss, dc=example, dc=com - cn: Steve Smith - cn: Steve S. Smith - sn: Smith - sn;lang-en: Smith - sn;lang-de: Schmidt - telephoneNumber: 1 555 765-4321 + dn: uid=sss,dc=example,dc=com + cn: Steve Smith + cn: Steve S. Smith + sn: Smith + sn;lang-en: Smith + sn;lang-de: Schmidt + telephoneNumber: 1 555 765-4321 .fi .LP The command: @@ -336,10 +404,10 @@ output might look like this if one entry with one value for each of the requested attributes is found: .LP .nf - dn: uid=xyz, dc=example, dc=com + dn: uid=xyz,dc=example,dc=com ufn: xyz, example, com - audio:< file::/tmp/ldapsearch-audio-a19924 - jpegPhoto:< file::=/tmp/ldapsearch-jpegPhoto-a19924 + audio:< file:///tmp/ldapsearch-audio-a19924 + jpegPhoto:< file:///tmp/ldapsearch-jpegPhoto-a19924 .fi .LP This command: @@ -354,29 +422,29 @@ The organization name and description attribute values will be retrieved and printed to standard output, resulting in output similar to this: .LP .nf - dn: o=University of Alaska Fairbanks, c=US + dn: o=University of Alaska Fairbanks,c=US o: University of Alaska Fairbanks description: Preparing Alaska for a brave new yesterday description: leaf node only - dn: o=University of Colorado at Boulder, c=US + dn: o=University of Colorado at Boulder,c=US o: University of Colorado at Boulder description: No personnel information description: Institution of education and research - dn: o=University of Colorado at Denver, c=US + dn: o=University of Colorado at Denver,c=US o: University of Colorado at Denver o: UCD o: CU/Denver o: CU-Denver description: Institute for Higher Learning and Research - dn: o=University of Florida, c=US + dn: o=University of Florida,c=US o: University of Florida o: UFl description: Warper of young minds - etc.... + ... .fi .SH DIAGNOSTICS Exit status is zero if no errors occur. @@ -390,11 +458,9 @@ a diagnostic message being written to standard error. .BR ldap.conf (5), .BR ldif (5), .BR ldap (3), -.BR ldap_search (3) +.BR ldap_search_ext (3), +.BR ldap_sort (3) .SH AUTHOR The OpenLDAP Project .SH ACKNOWLEDGEMENTS -.B OpenLDAP -is developed and maintained by The OpenLDAP Project (http://www.openldap.org/). -.B OpenLDAP -is derived from University of Michigan LDAP 3.3 Release. +.so ../Project