From b9ad78f71e61564b149f4d6cc18e277ddf06f55a Mon Sep 17 00:00:00 2001
From: Kurt Zeilenga <kurt@openldap.org>
Date: Tue, 20 Dec 2005 20:09:30 +0000
Subject: [PATCH] doc updates

---
 doc/man/man5/slapd-ldap.5   |  23 ++---
 doc/man/man5/slapd-meta.5   | 174 ++++++++++++++++++++++--------------
 doc/man/man5/slapo-chain.5  |   5 +-
 doc/man/man5/slapo-pcache.5 |   5 ++
 4 files changed, 128 insertions(+), 79 deletions(-)

diff --git a/doc/man/man5/slapd-ldap.5 b/doc/man/man5/slapd-ldap.5
index b683085b0b..3f62d0c37e 100644
--- a/doc/man/man5/slapd-ldap.5
+++ b/doc/man/man5/slapd-ldap.5
@@ -93,21 +93,19 @@ internally used by the proxy to collect info related to access control.
 The identity defined by this directive, according to the properties
 associated to the authentication method, is supposed to have read access 
 on the target server to attributes used on the proxy for ACL checking.
-The
-.B secprops
-field is currently ignored.
 There is no risk of giving away such values; they are only used to
 check permissions.
 The default is to use
-.BR simple ,
-with empty binddn and credentials,
+.BR simple 
+bind, with empty \fIbinddn\fP and \fIcredentials\fP,
 which means that the related operations will be performed anonymously.
 
 .B This identity is by no means implicitly used by the proxy 
 .B when the client connects anonymously.
-See the
+The
 .B idassert-bind
-feature instead.
+feature, instead, in some cases can be crafted to implement that behavior,
+which is \fIintrinsically unsafe and should be used with extreme care\fP.
 This directive obsoletes
 .BR acl-authcDN ,
 and
@@ -304,12 +302,12 @@ underlying libldap, with rebinding eventually performed if the
 
 .TP
 .B tls {[try-]start|[try-]propagate}
-execute the start TLS extended operation when the connection is initialized;
+execute the StartTLS extended operation when the connection is initialized;
 only works if the URI directive protocol scheme is not \fBldaps://\fP.
-\fBpropagate\fP issues the Start TLS exop only if the original
+\fBpropagate\fP issues the StartTLS operation only if the original
 connection did.
 The \fBtry-\fP prefix instructs the proxy to continue operations
-if start TLS failed; its use is highly deprecated.
+if the StartTLS operation failed; its use is highly deprecated.
 
 .TP
 .B t-f-support {NO|yes|discover}
@@ -334,6 +332,11 @@ Note: if the timelimit is exceeded, the operation is abandoned;
 the protocol does not provide any means to rollback the operation,
 so the client will not know if the operation eventually succeeded or not.
 
+.TP
+.B idle-timeout <time>
+This directive causes a cached connection to be dropped an recreated
+after it has been idle for the specified time.
+
 .SH BACKWARD COMPATIBILITY
 The LDAP backend has been heavily reworked between releases 2.2 and 2.3;
 as a side-effect, some of the traditional directives have been
diff --git a/doc/man/man5/slapd-meta.5 b/doc/man/man5/slapd-meta.5
index 548e9a2bbc..e9054bfe17 100644
--- a/doc/man/man5/slapd-meta.5
+++ b/doc/man/man5/slapd-meta.5
@@ -90,21 +90,15 @@ This directive can also be used when processing targets to mark a
 specific target as default.
 
 .TP
-.B dncache-ttl {forever|disabled|<ttl>}
+.B dncache-ttl {DISABLED|forever|<ttl>}
 This directive sets the time-to-live of the DN cache.
 This caches the target that holds a given DN to speed up target
 selection in case multiple targets would result from an uncached
 search; forever means cache never expires; disabled means no DN
-caching; otherwise a valid ( > 0 ) ttl in seconds is required.
-
-.TP
-.B nretries {forever|never|<nretries>}
-This directive defines how many times a bind should be retried
-in case of temporary failure in contacting a target.  If defined
-before any target specification, it applies to all targets (by default,
-.BR never );
-the global value can be overridden by redefinitions inside each target
-specification.
+caching; otherwise a valid ( > 0 ) ttl is required, in the format
+illustrated for the 
+.B idle-timeout
+directive.
 
 .TP
 .B onerr {CONTINUE|stop}
@@ -116,6 +110,13 @@ If this statement is set to \fBstop\fP, the search is terminated as soon
 as an error is returned by one target, and the error is immediately 
 propagated to the client.
 
+.TP
+.B pseudoroot-bind-defer {NO|yes}
+This directive, when set to 
+.BR yes ,
+causes the authentication to the remote servers with the pseudo-root
+identity to be deferred until actually needed by subsequent operations.
+
 .TP
 .B rebind-as-user {NO|yes}
 If this option is given, the client's bind credentials are remembered
@@ -154,15 +155,19 @@ because they are legal in the <naming context>, and we don't want to use
 URL-encoded <naming context>s), and the additional URIs must have
 no <naming context> part.  This causes the underlying library
 to contact the first server of the list that responds.
-.RE
+For example, if \fIl1.foo.com\fP and \fIl2.foo.com\fP are shadows
+of the same server, the directive
+.LP
+.nf
+suffix "\fBdc=foo,dc=com\fP"
+uri    "ldap://l1.foo.com/\fBdc=foo,dc=com\fP	ldap://l2.foo.com/"
+.fi
 
-.TP
-.B default-target [<target>]
-The "default-target" directive can also be used during target specification.
-With no arguments it marks the current target as the default.
-The optional number marks target <target> as the default one, starting
-from 1.
-Target <target> must be defined.
+.RE
+.RS
+causes \fIl2.foo.com\fP to be contacted whenever \fIl1.foo.com\fP
+does not respond.
+.RE
 
 .TP
 .B acl-authcDN "<administrative DN for access control purposes>"
@@ -181,6 +186,20 @@ Password used with the
 acl-authcDN
 above.
 
+.TP
+.B bind-timeout <microseconds>
+This directive defines the timeout, in microseconds, used when polling
+for response after an asynchronous bind connection.  The initial call
+to ldap_result(3) is performed with a trade-off timeout of 100000 us;
+if that results in a timeout exceeded, subsequent calls use the value
+provided with
+.BR bind-timeout .
+The default value is used also for subsequent calls if
+.B bind-timeout
+is not specified.
+If set before any target specification, it affects all targets, unless
+overridden by any per-target directive.
+
 .TP
 .B chase-referrals {YES|no}
 enable/disable automatic referral chasing, which is delegated to the
@@ -190,43 +209,41 @@ If set before any target specification, it affects all targets, unless
 overridden by any per-target directive.
 
 .TP
-.B tls {[try-]start|[try-]propagate}
-execute the start TLS extended operation when the connection is initialized;
-only works if the URI directive protocol scheme is not \fBldaps://\fP.
-\fBpropagate\fP issues the Start TLS exop only if the original
-connection did.
-The \fBtry-\fP prefix instructs the proxy to continue operations
-if start TLS failed; its use is highly deprecated.
-If set before any target specification, it affects all targets, unless
-overridden by any per-target directive.
+.B default-target [<target>]
+The "default-target" directive can also be used during target specification.
+With no arguments it marks the current target as the default.
+The optional number marks target <target> as the default one, starting
+from 1.
+Target <target> must be defined.
 
 .TP
-.B t-f-support {NO|yes|discover}
-enable if the remote server supports absolute filters
-(see \fIdraft-zeilenga-ldap-t-f\fP for details).
-If set to
-.BR discover ,
-support is detected by reading the remote server's root DSE.
+.B idle-timeout <time>
+This directive causes a cached connection to be dropped an recreated
+after it has been idle for the specified time.
+The value can be specified as
+
+[<d>d][<h>h][<m>m][<s>[s]]
+
+where <d>, <h>, <m> and <s> are respectively treated as days, hours, 
+minutes and seconds.
 If set before any target specification, it affects all targets, unless
 overridden by any per-target directive.
 
 .TP
-.B timeout [{add|delete|modify|modrdn}=]<val> [...]
-This directive allows to set per-database, per-target and per-operation
-timeouts.
-If no operation is specified, it affects all.
-Currently, only write operations are addressed, because searches
-can already be limited by means of the
-.B limits
-directive (see 
-.BR slapd.conf (5)
-for details), and other operations are not supposed to incur into the
-need for timeouts.
-Note: if the timelimit is exceeded, the operation is abandoned;
-the protocol does not provide any means to rollback the operation,
-so the client will not know if the operation eventually succeeded or not.
-If set before any target specification, it affects all targets, unless
-overridden by any per-target directive.
+.B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}"
+This maps object classes and attributes as in the LDAP backend.
+See
+.BR slapd-ldap (5).
+
+.TP
+.B nretries {forever|never|<nretries>}
+This directive defines how many times a bind should be retried
+in case of temporary failure in contacting a target.  If defined
+before any target specification, it applies to all targets (by default,
+.BR 3
+times);
+the global value can be overridden by redefinitions inside each target
+specification.
 
 .TP
 .B pseudorootdn "<substitute DN in case of rootdn bind>"
@@ -244,13 +261,6 @@ the target using the "pseudorootdn" DN.
 Note: cleartext credentials must be supplied here; as a consequence,
 using the pseudorootdn/pseudorootpw directives is inherently unsafe.
 
-.TP
-.B pseudoroot-bind-defer {NO|yes}
-This directive, when set to 
-.BR yes ,
-causes the authentication to the remote servers with the pseudo-root
-identity to be deferred until actually needed by subsequent operations.
-
 .TP
 .B rewrite* ...
 The rewrite options are described in the "REWRITING" section.
@@ -267,18 +277,46 @@ when simple suffix massage is required, it has been preserved.
 It wraps the basic rewriting instructions that perform suffix
 massaging.  See the "REWRITING" section for a detailed list 
 of the rewrite rules it implies.
-.LP
-Note: this also fixes a flaw in suffix massaging, which operated
-on (case insensitive) DNs instead of normalized DNs,
-so "dc=foo, dc=com" would not match "dc=foo,dc=com".
-.LP
-See the "REWRITING" section.
 
 .TP
-.B map "{attribute|objectclass} [<local name>|*] {<foreign name>|*}"
-This maps object classes and attributes as in the LDAP backend.
-See
-.BR slapd-ldap (5).
+.B t-f-support {NO|yes|discover}
+enable if the remote server supports absolute filters
+(see \fIdraft-zeilenga-ldap-t-f\fP for details).
+If set to
+.BR discover ,
+support is detected by reading the remote server's root DSE.
+If set before any target specification, it affects all targets, unless
+overridden by any per-target directive.
+
+.TP
+.B timeout [{add|delete|modify|modrdn}=]<seconds> [...]
+This directive allows to set per-database, per-target and per-operation
+timeouts.
+If no operation is specified, it affects all.
+Currently, only write operations are addressed, because searches
+can already be limited by means of the
+.B limits
+directive (see 
+.BR slapd.conf (5)
+for details), and other operations are not supposed to incur into the
+need for timeouts.
+Note: if the timelimit is exceeded, the operation is abandoned;
+the protocol does not provide any means to rollback the operation,
+so the client will not know if the operation eventually succeeded or not.
+If set before any target specification, it affects all targets, unless
+overridden by any per-target directive.
+
+.TP
+.B tls {[try-]start|[try-]propagate}
+execute the StartTLS extended operation when the connection is initialized;
+only works if the URI directive protocol scheme is not \fBldaps://\fP.
+\fBpropagate\fP issues the StartTLS operation only if the original
+connection did.
+The \fBtry-\fP prefix instructs the proxy to continue operations
+if the StartTLS operation failed; its use is highly deprecated.
+If set before any target specification, it affects all targets, unless
+overridden by any per-target directive.
+
 .SH SCENARIOS
 A powerful (and in some sense dangerous) rewrite engine has been added
 to both the LDAP and Meta backends.
@@ -624,7 +662,7 @@ modifyAttrDN         modify AVA
 modrDN               modrdn
 newSuperiorDN        modrdn
 deleteDN             delete
-exopPasswdDN         passwd exop DN if proxy
+exopPasswdDN         password modify extended operation DN if proxy
 .fi
 .RE
 .LP
diff --git a/doc/man/man5/slapo-chain.5 b/doc/man/man5/slapo-chain.5
index 96cc0d4904..0e82dae29b 100644
--- a/doc/man/man5/slapo-chain.5
+++ b/doc/man/man5/slapo-chain.5
@@ -71,10 +71,13 @@ The values \fBr\fP and \fBc\fP can be any of
 If the \fBcritical\fP flag affects the control criticality if provided.
 [This control is experimental and its support may change in the future.]
 .TP
-.B chain-cache-uris {FALSE|true}
+.B chain-cache-uri {FALSE|true}
 This directive instructs the \fIchain\fP overlay to cache
 connections to URIs parsed out of referrals that are not predefined,
 to be reused for later chaining.
+These URIs inherit the properties configured for the underlying 
+\fBslapd-ldap\fP(5) before any occurrence of the \fBchain-uri\fP
+directive; in detail, they are essentially chained anonymously.
 .TP
 .B chain-uri <ldapuri>
 This directive instantiates a new underlying \fIldap\fP database
diff --git a/doc/man/man5/slapo-pcache.5 b/doc/man/man5/slapo-pcache.5
index a0e1bb6370..d5b1948f5b 100644
--- a/doc/man/man5/slapo-pcache.5
+++ b/doc/man/man5/slapo-pcache.5
@@ -140,6 +140,11 @@ for the duration of the
 .B proxytemplate
 .BR TTL .
 
+The remote server should expose the
+.B objectClass 
+attribute because the underlying database that actually caches the entries 
+may need it for optimal local processing of the queries.
+
 Another potential (and subtle) inconsistency may occur when data is retrieved 
 with different identities and specific per-identity access control
 is enforced by the remote server.
-- 
2.39.5