X-Git-Url: https://git.sur5r.net/?a=blobdiff_plain;f=doc%2Fman%2Fman5%2Fslapd-meta.5;h=6e325fa5ecde5ae7c0bdd83ecb2c03ce16e304a0;hb=2214e47a2cf7c7776191c7e19390863cba16da6b;hp=4652efc97910748ba941af6270bf530b37a4bbf1;hpb=8637cdd4ddb2317c798aba06c33d5b2c83bc6ba2;p=openldap

diff --git a/doc/man/man5/slapd-meta.5 b/doc/man/man5/slapd-meta.5
index 4652efc979..6e325fa5ec 100644
--- a/doc/man/man5/slapd-meta.5
+++ b/doc/man/man5/slapd-meta.5
@@ -1,5 +1,5 @@
 .TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2007 The OpenLDAP Foundation, All Rights Reserved.
+.\" Copyright 1998-2013 The OpenLDAP Foundation, All Rights Reserved.
 .\" Copying restrictions apply.  See the COPYRIGHT file.
 .\" Copyright 2001, Pierangelo Masarati, All rights reserved. <ando@sys-net.it>
 .\" $OpenLDAP$
@@ -8,7 +8,7 @@
 .\" and maybe manual pages for librewrite.
 .\"
 .SH NAME
-slapd-meta \- metadirectory backend to slapd
+slapd\-meta \- metadirectory backend to slapd
 .SH SYNOPSIS
 ETCDIR/slapd.conf
 .SH DESCRIPTION
@@ -38,18 +38,27 @@ excessive overhead for some applications, so its use should be
 carefully considered.
 In the examples section, some typical scenarios will be discussed.
 
+The proxy instance of
+.BR slapd (8)
+must contain schema information for the attributes and objectClasses
+used in filters, request DN and request-related data in general.
+It should also contain schema information for the data returned
+by the proxied server.
+It is the responsibility of the proxy administrator to keep the schema
+of the proxy lined up with that of the proxied server.
+
 .LP
 Note: When looping back to the same instance of \fBslapd\fP(8), 
 each connection requires a new thread; as a consequence, \fBslapd\fP(8)
 must be compiled with thread support, and the \fBthreads\fP parameter 
 may need some tuning; in those cases, unless the multiple target feature
-is required, one may consider using \fBslapd-relay\fP(5) instead, 
+is required, one may consider using \fBslapd\-relay\fP(5) instead, 
 which performs the relayed operation internally and thus reuses 
 the same connection.
 
 .SH EXAMPLES
 There are examples in various places in this document, as well as in the
-slapd/back-meta/data/ directory in the OpenLDAP source tree.
+slapd/back\-meta/data/ directory in the OpenLDAP source tree.
 .SH CONFIGURATION
 These
 .B slapd.conf
@@ -87,12 +96,12 @@ to all backends.
 They are:
 
 .TP
-.B conn-ttl <time>
+.B conn\-ttl <time>
 This directive causes a cached connection to be dropped an recreated
 after a given ttl, regardless of being idle or not.
 
 .TP
-.B default-target none
+.B default\-target none
 This directive forces the backend to reject all those operations
 that must resolve to a single target in case none or multiple
 targets are selected.
@@ -104,14 +113,14 @@ This directive can also be used when processing targets to mark a
 specific target as default.
 
 .TP
-.B dncache-ttl {DISABLED|forever|<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 is required, in the format
 illustrated for the 
-.B idle-timeout
+.B idle\-timeout
 directive.
 
 .TP
@@ -127,6 +136,28 @@ If the value is set to \fBreport\fP, the search is continuated to the end
 but, in case at least one target returned an error code, the first
 non-success error code is returned.
 
+.TP
+.B norefs <NO|yes>
+If
+.BR yes ,
+do not return search reference responses.
+By default, they are returned unless request is LDAPv2.
+If set before any target specification, it affects all targets, unless
+overridden by any per-target directive.
+
+.TP
+.B noundeffilter <NO|yes>
+If
+.BR yes ,
+return success instead of searching if a filter is undefined or contains
+undefined portions.
+By default, the search is propagated after replacing undefined portions
+with
+.BR (!(objectClass=*)) ,
+which corresponds to the empty result set.
+If set before any target specification, it affects all targets, unless
+overridden by any per-target directive.
+
 .TP
 .B protocol\-version {0,2,3}
 This directive indicates what protocol version must be used to contact
@@ -139,11 +170,14 @@ If set before any target specification, it affects all targets, unless
 overridden by any per-target directive.
 
 .TP
-.B pseudoroot-bind-defer {NO|yes}
+.B pseudoroot\-bind\-defer {YES|no}
 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.
+identity (the identity defined in each
+.B idassert-bind
+directive) to be deferred until actually needed by subsequent operations.
+Otherwise, all binds as the rootdn are propagated to the targets.
 
 .TP
 .B quarantine <interval>,<num>[;<interval>,<num>[...]]
@@ -164,11 +198,11 @@ This directive must appear before any target specification;
 it affects all targets with the same pattern.
 
 .TP
-.B rebind-as-user {NO|yes}
+.B rebind\-as\-user {NO|yes}
 If this option is given, the client's bind credentials are remembered
 for rebinds, when trying to re-establish a broken connection,
 or when chasing a referral, if 
-.B chase-referrals
+.B chase\-referrals
 is set to
 .IR yes .
 
@@ -186,7 +220,7 @@ overridden by any per-target directive.
 Discards current cached connection when the client rebinds.
 
 .TP
-.B use-temporary-conn {NO|yes}
+.B use\-temporary\-conn {NO|yes}
 when set to 
 .BR yes ,
 create a temporary connection whenever competing with other threads
@@ -239,54 +273,272 @@ the last URI that succeeded.
 .RE
 
 .TP
-.B acl-authcDN "<administrative DN for access control purposes>"
+.B acl\-authcDN "<administrative DN for access control purposes>"
 DN which is used to query the target server for acl checking,
 as in the LDAP backend; it is supposed to have read access 
 on the target server to attributes used on the proxy for acl checking.
 There is no risk of giving away such values; they are only used to
 check permissions.
-.B The acl-authcDN identity is by no means implicitly used by the proxy 
+.B The acl\-authcDN identity is by no means implicitly used by the proxy 
 .B when the client connects anonymously.
 
 .TP
-.B acl-passwd <password>
+.B acl\-passwd <password>
 Password used with the
 .B 
-acl-authcDN
+acl\-authcDN
 above.
 
 .TP
-.B bind-timeout <microseconds>
+.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 .
+.BR bind\-timeout .
 The default value is used also for subsequent calls if
-.B bind-timeout
+.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}
+.B chase\-referrals {YES|no}
 enable/disable automatic referral chasing, which is delegated to the
 underlying libldap, with rebinding eventually performed if the
-\fBrebind-as-user\fP directive is used.  The default is to chase referrals.
+\fBrebind\-as\-user\fP directive is used.  The default is to chase referrals.
 If set before any target specification, it affects all targets, unless
 overridden by any per-target directive.
 
 .TP
-.B default-target [<target>]
-The "default-target" directive can also be used during target specification.
+.B client\-pr {accept-unsolicited|DISABLE|<size>}
+This feature allows to use RFC 2696 Paged Results control when performing
+search operations with a specific target,
+irrespective of the client's request.
+When set to a numeric value, Paged Results control is always
+used with \fIsize\fP as the page size.
+When set to \fIaccept-unsolicited\fP, unsolicited Paged Results
+control responses are accepted and honored
+for compatibility with broken remote DSAs.
+The client is not exposed to paged results handling
+between
+.BR slapd\-meta (5)
+and the remote servers.
+By default (disabled), Paged Results control is not used
+and responses are not accepted.
+If set before any target specification, it affects all targets, unless
+overridden by any per-target directive.
+
+.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.
 
 .TP
-.B idle-timeout <time>
+.B filter <pattern>
+This directive allows specifying a
+.BR regex (5)
+pattern to indicate what search filter terms are actually served by a target.
+
+In a search request, if the search filter matches the \fIpattern\fP
+the target is considered while fulfilling the request; otherwise
+the target is ignored. There may be multiple occurrences of
+the
+.B filter
+directive for each target.
+
+.TP
+.B idassert\-authzFrom <authz-regexp>
+if defined, selects what
+.I local
+identities are authorized to exploit the identity assertion feature.
+The string
+.B <authz-regexp>
+follows the rules defined for the
+.I authzFrom
+attribute.
+See 
+.BR slapd.conf (5),
+section related to
+.BR authz\-policy ,
+for details on the syntax of this field.
+
+.HP
+.hy 0
+.B idassert\-bind
+.B bindmethod=none|simple|sasl [binddn=<simple DN>] [credentials=<simple password>]
+.B [saslmech=<SASL mech>] [secprops=<properties>] [realm=<realm>]
+.B [authcId=<authentication ID>] [authzId=<authorization ID>]
+.B [authz={native|proxyauthz}] [mode=<mode>] [flags=<flags>]
+.B [starttls=no|yes|critical]
+.B [tls_cert=<file>]
+.B [tls_key=<file>]
+.B [tls_cacert=<file>]
+.B [tls_cacertdir=<path>]
+.B [tls_reqcert=never|allow|try|demand]
+.B [tls_ciphersuite=<ciphers>]
+.B [tls_protocol_min=<major>[.<minor>]]
+.B [tls_crlcheck=none|peer|all]
+.RS
+Allows to define the parameters of the authentication method that is 
+internally used by the proxy to authorize connections that are 
+authenticated by other databases.
+The identity defined by this directive, according to the properties
+associated to the authentication method, is supposed to have auth access 
+on the target server to attributes used on the proxy for authentication
+and authorization, and to be allowed to authorize the users.
+This requires to have
+.B proxyAuthz
+privileges on a wide set of DNs, e.g.
+.BR authzTo=dn.subtree:"" ,
+and the remote server to have
+.B authz\-policy
+set to
+.B to
+or
+.BR both .
+See
+.BR slapd.conf (5)
+for details on these statements and for remarks and drawbacks about
+their usage.
+The supported bindmethods are
+
+\fBnone|simple|sasl\fP
+
+where
+.B none
+is the default, i.e. no \fIidentity assertion\fP is performed.
+
+The authz parameter is used to instruct the SASL bind to exploit 
+.B native 
+SASL authorization, if available; since connections are cached,
+this should only be used when authorizing with a fixed identity
+(e.g. by means of the 
+.B authzDN
+or
+.B authzID
+parameters).
+Otherwise, the default
+.B proxyauthz
+is used, i.e. the proxyAuthz control (Proxied Authorization, RFC 4370)
+is added to all operations.
+
+The supported modes are:
+
+\fB<mode> := {legacy|anonymous|none|self}\fP
+
+If 
+.B <mode>
+is not present, and 
+.B authzId
+is given, the proxy always authorizes that identity.
+.B <authorization ID>
+can be 
+
+\fBu:<user>\fP
+
+\fB[dn:]<DN>\fP
+
+The former is supposed to be expanded by the remote server according 
+to the authz rules; see
+.BR slapd.conf (5)
+for details.
+In the latter case, whether or not the 
+.B dn:
+prefix is present, the string must pass DN validation and normalization.
+
+The default mode is 
+.BR legacy ,
+which implies that the proxy will either perform a simple bind as the
+.I authcDN
+or a SASL bind as the
+.I authcID
+and assert the client's identity when it is not anonymous.
+Direct binds are always proxied.
+The other modes imply that the proxy will always either perform a simple bind 
+as the
+.IR authcDN
+or a SASL bind as the
+.IR authcID ,
+unless restricted by
+.BR idassert\-authzFrom
+rules (see below), in which case the operation will fail;
+eventually, it will assert some other identity according to
+.BR <mode> .
+Other identity assertion modes are
+.BR anonymous
+and
+.BR self ,
+which respectively mean that the 
+.I empty 
+or the 
+.IR client 's 
+identity
+will be asserted;
+.BR none ,
+which means that no proxyAuthz control will be used, so the
+.I authcDN
+or the
+.I authcID
+identity will be asserted.
+For all modes that require the use of the
+.I proxyAuthz 
+control, on the remote server the proxy identity must have appropriate 
+.I authzTo
+permissions, or the asserted identities must have appropriate
+.I authzFrom 
+permissions.  Note, however, that the ID assertion feature is mostly 
+useful when the asserted identities do not exist on the remote server.
+
+Flags can be
+
+\fBoverride,[non\-]prescriptive,proxy\-authz\-[non\-]critical\fP
+
+When the 
+.B override
+flag is used, identity assertion takes place even when the database
+is authorizing for the identity of the client, i.e. after binding
+with the provided identity, and thus authenticating it, the proxy
+performs the identity assertion using the configured identity and
+authentication method.
+
+When the
+.B prescriptive
+flag is used (the default), operations fail with
+\fIinappropriateAuthentication\fP
+for those identities whose assertion is not allowed by the
+.B idassert\-authzFrom
+patterns.
+If the 
+.B non\-prescriptive
+flag is used, operations are performed anonymously for those identities 
+whose assertion is not allowed by the
+.B idassert\-authzFrom
+patterns.
+
+When the
+.B proxy\-authz\-non\-critical
+flag is used (the default), the proxyAuthz control is not marked as critical,
+in violation of RFC 4370.  Use of
+.B proxy\-authz\-critical
+is recommended.
+
+The TLS settings default to the same as the main slapd TLS settings,
+except for
+.B tls_reqcert
+which defaults to "demand".
+
+The identity associated to this directive is also used for privileged
+operations whenever \fBidassert\-bind\fP is defined and \fBacl\-bind\fP
+is not.  See \fBacl\-bind\fP for details.
+.RE
+
+.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.
 The value can be specified as
@@ -298,21 +550,40 @@ minutes and seconds.
 If set before any target specification, it affects all targets, unless
 overridden by any per-target directive.
 
+.TP
+.B keepalive  <idle>:<probes>:<interval>
+The
+.B keepalive
+parameter sets the values of \fIidle\fP, \fIprobes\fP, and \fIinterval\fP
+used to check whether a socket is alive;
+.I idle
+is the number of seconds a connection needs to remain idle before TCP
+starts sending keepalive probes;
+.I probes
+is the maximum number of keepalive probes TCP should send before dropping
+the connection;
+.I interval
+is interval in seconds between individual keepalive probes.
+Only some systems support the customization of these values;
+the
+.B keepalive
+parameter is ignored otherwise, and system-wide settings are used.
+
 .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).
+.BR slapd\-ldap (5).
 
 .TP
-.B network-timeout <time>
+.B network\-timeout <time>
 Sets the network timeout value after which
 .BR poll (2)/ select (2) 
 following a 
 .BR connect (2) 
 returns in case of no activity.
 The value is in seconds, and it can be specified as for
-.BR idle-timeout .
+.BR idle\-timeout .
 If set before any target specification, it affects all targets, unless
 overridden by any per-target directive.
 
@@ -327,33 +598,62 @@ the global value can be overridden by redefinitions inside each target
 specification.
 
 .TP
-.B pseudorootdn "<substitute DN in case of rootdn bind>"
-This directive, if present, sets the DN that will be substituted to
-the bind DN if a bind with the backend's "rootdn" succeeds.
-The true "rootdn" of the target server ought not be used; an arbitrary
-administrative DN should used instead.
+.B rewrite* ...
+The rewrite options are described in the "REWRITING" section.
 
 .TP
-.B pseudorootpw "<substitute password in case of rootdn bind>"
-This directive sets the credential that will be used in case a bind
-with the backend's "rootdn" succeeds, and the bind is propagated to
-the target using the "pseudorootdn" DN.
+.B subtree\-{exclude|include} "<rule>"
+This directive allows to indicate what subtrees are actually served
+by a target.
+The syntax of the supported rules is
 
-Note: cleartext credentials must be supplied here; as a consequence,
-using the pseudorootdn/pseudorootpw directives is inherently unsafe.
+\fB<rule>: [dn[.<style>]:]<pattern>\fP
 
-.TP
-.B rewrite* ...
-The rewrite options are described in the "REWRITING" section.
+\fB<style>: subtree|children|regex\fP
 
-.TP
-.B subtree-exclude "<DN>"
-This directive instructs back-meta to ignore the current target
-for operations whose requestDN is subordinate to
-.BR DN .
+When \fB<style>\fP is either \fBsubtree\fP or \fBchildren\fP
+the \fB<pattern>\fP is a DN that must be within the naming context
+served by the target.
+When \fB<style>\fP is \fBregex\fP the \fB<pattern>\fP is a
+.BR regex (5)
+pattern.
+If the \fBdn.<style>:\fP prefix is omitted, \fBdn.subtree:\fP
+is implicitly assumed for backward compatibility.
+
+In the
+.B subtree\-exclude
+form if the \fIrequest DN\fP matches at least one rule,
+the target is not considered while fulfilling the request;
+otherwise, the target is considered based on the value of the \fIrequest DN\fP.
+When the request is a search, also the \fIscope\fP is considered.
+
+In the
+.B subtree\-include
+form if the \fIrequest DN\fP matches at least one rule,
+the target is considered while fulfilling the request;
+otherwise the target is ignored.
+
+.LP
+.RS
+.nf
+    |  match  | exclude |
+    +---------+---------+-------------------+
+    |    T    |    T    | not candidate     |
+    |    F    |    T    | continue checking |
+    +---------+---------+-------------------+
+    |    T    |    F    | candidate         |
+    |    F    |    F    | not candidate     |
+    +---------+---------+-------------------+
+.fi
+
+.RE
+.RS
 There may be multiple occurrences of the
-.B subtree-exclude
-directive for each of the targets.
+.B subtree\-exclude
+or
+.B subtree\-include
+directive for each of the targets, but they are mutually exclusive.
+.RE
 
 .TP
 .B suffixmassage "<virtual naming context>" "<real naming context>"
@@ -369,9 +669,9 @@ massaging.  See the "REWRITING" section for a detailed list
 of the rewrite rules it implies.
 
 .TP
-.B t-f-support {NO|yes|discover}
+.B t\-f\-support {NO|yes|discover}
 enable if the remote server supports absolute filters
-(see \fIdraft-zeilenga-ldap-t-f\fP for details).
+(see \fIRFC 4526\fP for details).
 If set to
 .BR discover ,
 support is detected by reading the remote server's root DSE.
@@ -410,12 +710,12 @@ In case the timeout is exceeded during a bind operation, the connection
 is destroyed, according to RFC4511.
 
 .TP
-.B tls {[try-]start|[try-]propagate}
+.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
+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.
@@ -534,8 +834,8 @@ that connects it to the internet may impose additional constraints.
 To this purpose, the proxy should be able to comply with all the ACL
 matching criteria that the server supports.
 This has been achieved with regard to all the criteria supported by
-slapd except a special subtle case (please drop me a note if you can
-find other exceptions: <ando@openldap.org>).
+slapd except a special subtle case (please file an ITS if you can
+find other exceptions: <http://www.openldap.org/its/>).
 The rule
 .LP
 .RS
@@ -746,7 +1046,7 @@ Each basic server operation is associated to a rewrite context;
 they are divided in two main groups: client \-> server and
 server \-> client rewriting.
 .LP
-client -> server:
+client \-> server:
 .LP
 .RS
 .nf
@@ -769,7 +1069,7 @@ exopPasswdDN         password modify extended operation DN if proxy
 .fi
 .RE
 .LP
-server -> client:
+server \-> client:
 .LP
 .RS
 .nf
@@ -988,8 +1288,26 @@ operation is honored, which is performed by the frontend.
 The proxy cache overlay 
 allows caching of LDAP search requests (queries) in a local database.
 See 
-.BR slapo-pcache (5)
+.BR slapo\-pcache (5)
 for details.
+
+.SH DEPRECATED STATEMENTS
+The following statements have been deprecated and should no longer be used.
+
+.TP
+.B pseudorootdn "<substitute DN in case of rootdn bind>"
+Use
+.B idassert\-bind
+instead.
+
+.TP
+.B pseudorootpw "<substitute password in case of rootdn bind>"
+Use
+.B idassert\-bind
+instead.
+
+
+
 .SH FILES
 .TP
 ETCDIR/slapd.conf