X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman1%2Fldapcompare.1;h=18b1ef13d0698700b15507f153bf3b2d6569c000;hb=619cebee126b6f3cdee3a336504989566cffa02e;hp=b1fffcd59c57787ef4add363e0ccdad510b42c87;hpb=b43ad1dd0eac7f09ef5a6d205cd7f614411bee0c;p=openldap diff --git a/doc/man/man1/ldapcompare.1 b/doc/man/man1/ldapcompare.1 index b1fffcd59c..18b1ef13d0 100644 --- a/doc/man/man1/ldapcompare.1 +++ b/doc/man/man1/ldapcompare.1 @@ -1,6 +1,6 @@ .TH LDAPCOMPARE 1 "RELEASEDATE" "OpenLDAP LDVERSION" .\" $OpenLDAP$ -.\" Copyright 1998-2002 The OpenLDAP Foundation All Rights Reserved. +.\" Copyright 1998-2011 The OpenLDAP Foundation All Rights Reserved. .\" Copying restrictions apply. See COPYRIGHT/LICENSE. .SH NAME ldapcompare \- LDAP compare tool @@ -13,11 +13,7 @@ ldapcompare \- LDAP compare tool [\c .BR \-z ] [\c -.BR \-k ] -[\c -.BR \-K ] -[\c -.BR \-M[M] ] +.BR \-M [ M ]] [\c .BI \-d \ debuglevel\fR] [\c @@ -25,7 +21,9 @@ ldapcompare \- LDAP compare tool [\c .BR \-W ] [\c -.BI \-w \ bindpasswd\fR] +.BI \-w \ passwd\fR] +[\c +.BI \-y \ passwdfile\fR] [\c .BI \-H \ ldapuri\fR] [\c @@ -33,9 +31,13 @@ ldapcompare \- LDAP compare tool [\c .BI \-p \ ldapport\fR] [\c -.BI \-P \ 2\fR\||\|\fI3\fR] +.BR \-P \ { 2 \||\| 3 }] +[\c +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] +[\c +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ]] [\c -.BR \-O \ security-properties ] +.BI \-O \ security-properties\fR] [\c .BR \-I ] [\c @@ -43,20 +45,24 @@ ldapcompare \- LDAP compare tool [\c .BI \-U \ authcid\fR] [\c +.BI \-R \ realm\fR] +[\c .BR \-x ] [\c .BI \-X \ authzid\fR] [\c .BI \-Y \ mech\fR] [\c -.BR \-Z[Z] ] -.IR DN \ < -.BR attr:value \ | -.BR attr::b64value \ > +.BR \-Z [ Z ]] +.IR DN +{\c +.BI attr: value +| +.BI attr:: b64value\fR} .SH DESCRIPTION .I ldapcompare is a shell-accessible interface to the -.BR ldap_compare (3) +.BR ldap_compare_ext (3) library call. .LP .B ldapcompare @@ -65,13 +71,15 @@ using specified parameters. The \fIDN\fP should be a distinguished name in the directory. \fIAttr\fP should be a known attribute. If followed by one colon, the assertion \fIvalue\fP should be provided as a string. If followed by two colons, the base64 encoding of the -value is provided. +value is provided. The result code of the compare is provided as +the exit code and, unless ran with \fB\-z\fP, the program prints +TRUE, FALSE, or UNDEFINED on standard output. .LP .SH OPTIONS .TP .B \-n Show what would be done, but don't actually perform the compare. Useful for -debugging in conjunction with -v. +debugging in conjunction with \fB\-v\fP. .TP .B \-v Run in verbose mode, with many diagnostics written to standard output. @@ -80,18 +88,7 @@ Run in verbose mode, with many diagnostics written to standard output. Run in quiet mode, no output is written. You must check the return status. Useful in shell scripts. .TP -.B \-k -Use Kerberos IV authentication instead of simple authentication. It is -assumed that you already have a valid ticket granting ticket. -.B ldapcompare -must be compiled with Kerberos support for this option to have any effect. -.TP -.B \-K -Same as \-k, but only does step 1 of the Kerberos IV bind. This is useful -when connecting to a slapd and there is no x500dsa.hostname principal -registered with your Kerberos Domain Controller(s). -.TP -.B \-M[M] +.BR \-M [ M ] Enable manage DSA IT control. .B \-MM makes control critical. @@ -106,28 +103,77 @@ Use simple authentication instead of SASL. .TP .BI \-D \ binddn Use the Distinguished Name \fIbinddn\fP to bind to the LDAP directory. +For SASL binds, the server is expected to ignore this value. .TP .B \-W 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. +Note that \fIcomplete\fP means that any leading or trailing whitespaces, +including newlines, will be considered part of the password and, +unlike other software, they will not be stripped. +As a consequence, passwords stored in files by commands like +.BR echo (1) +will not behave as expected, since +.BR echo (1) +by default appends a trailing newline to the echoed string. +The recommended portable way to store a cleartext password in a file +for use with this option is to use +.BR slappasswd (8) +with \fI{CLEARTEXT}\fP as hash and the option \fB\-n\fP. .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. -Deprecated in favor of -H. +Deprecated in favor of \fB\-H\fP. .TP .BI \-p \ ldapport Specify an alternate TCP port where the ldap server is listening. -Deprecated in favor of -H. +Deprecated in favor of \fB\-H\fP. .TP -.BI \-P \ 2\fR\||\|\fI3 +.BR \-P \ { 2 \||\| 3 } Specify the LDAP protocol version to use. .TP +.BR \-e \ [ ! ] \fIext\fP [ =\fIextparam\fP ] +.TP +.BR \-E \ [ ! ] \fIext\fP [ =\fIextparam\fP ] + +Specify general extensions with \fB\-e\fP and compare extensions with \fB\-E\fP. +\'\fB!\fP\' indicates criticality. + +General extensions: +.nf + [!]assert= (an RFC 4515 Filter) + !authzid= ("dn:" or "u:") + [!]bauthzid (RFC 3829 authzid control) + [!]chaining[=[/]] + [!]manageDSAit + [!]noop + ppolicy + [!]postread[=] (a comma-separated attribute list) + [!]preread[=] (a comma-separated attribute list) + [!]relax + sessiontracking[=] + abandon,cancel,ignore (SIGINT sends abandon/cancel, + or ignores response; if critical, doesn't wait for SIGINT. + not really controls) +.fi + +Compare extensions: +.nf + !dontUseCopy +.fi +.TP .BI \-O \ security-properties Specify SASL security properties. .TP @@ -142,50 +188,42 @@ Enable SASL Quiet mode. Never prompt. 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. .I authzid must be one of the following formats: -.B dn:\c -.I +.BI dn: "" or -.B u:\c -.I +.BI u: .TP .BI \-Y \ mech Specify the SASL mechanism to be used for authentication. If it's not specified, the program will choose the best mechanism the server knows. .TP -.B \-Z[Z] +.BR \-Z [ Z ] Issue StartTLS (Transport Layer Security) extended operation. If you use -.B \-ZZ\c -, the command will require the operation to be successful. -.SH EXAMPLE +\fB\-ZZ\fP, the command will require the operation to be successful. +.SH EXAMPLES .nf - ldapcompare "uid=babs,dc=example,dc=com" sn Jensen ldapcompare "uid=babs,dc=example,dc=com" sn:Jensen ldapcompare "uid=babs,dc=example,dc=com" sn::SmVuc2Vu .fi are all equivalent. -.SH DIAGNOSTICS -When -z is used, exit status is either 5 if the compare is false, or 6 -when the compare is true. Errors result in other non-zero values. -.br -When -z is not used, exit status is zero if no errors occur. -Errors result in a non-zero exit status and -a diagnostic message being written to standard error. -.SH BUGS -Should have a way to specify a url for options or for large binary -file compares. +.SH LIMITATIONS +Requiring the value be passed on the command line is limiting +and introduces some security concerns. The command should support +a mechanism to specify the location (file name or URL) to read +the value from. .SH "SEE ALSO" .BR ldap.conf (5), .BR ldif (5), .BR ldap (3), -.BR ldap_compare (3) +.BR ldap_compare_ext (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