.TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2005 The OpenLDAP Foundation, All Rights Reserved.
+.\" Copyright 1998-2010 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$
.\" and maybe manual pages for librewrite.
.\"
.SH NAME
-slapd-meta \- metadirectory backend
+slapd\-meta \- metadirectory backend to slapd
.SH SYNOPSIS
ETCDIR/slapd.conf
.SH DESCRIPTION
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,
+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
.BR slapd.conf (5)
manual page.
.LP
-Note: as with the
-.B ldap
-backend, operational attributes related to entry creation/modification
-should not be used, as they would be passed to the target servers,
-generating an error.
-Moreover, it makes little sense to use such attributes in proxying, as
-the proxy server doesn't actually store data, so it should have no
-knowledge of such attributes.
-While code to strip the modification attributes has been put in place
-(and #ifdef'd), it implies unmotivated overhead.
-So it is strongly recommended to set
+Note: In early versions of back-ldap and back-meta it was recommended to always set
+.LP
.RS
+.nf
lastmod off
+.fi
.RE
-for every
+.LP
+for
.B ldap
and
.B meta
-backend.
+databases.
+This was required because operational attributes related to entry creation
+and modification should not be proxied, as they could be mistakenly written
+to the target server(s), generating an error.
+The current implementation automatically sets lastmod to \fBoff\fP,
+so its use is redundant and should be omitted.
+
.SH SPECIAL CONFIGURATION DIRECTIVES
Target configuration starts with the "uri" directive.
All the configuration directives that are not specific to targets
should be defined first for clarity, including those that are common
to all backends.
They are:
+
+.TP
+.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.
target, with the constraint that at most one must succeed.
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.
+caching; otherwise a valid ( > 0 ) ttl is required, in the format
+illustrated for the
+.B idle\-timeout
+directive.
+
+.TP
+.B onerr {CONTINUE|report|stop}
+This directive allows to select the behavior in case an error is returned
+by one target during a search.
+The default, \fBcontinue\fP, consists in continuing the operation,
+trying to return as much data as possible.
+If the value 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.
+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
+the remote server.
+If set to 0 (the default), the proxy uses the same protocol version
+used by the client, otherwise the requested protocol is used.
+The proxy returns \fIunwillingToPerform\fP if an operation that is
+incompatible with the requested protocol is attempted.
+If set before any target specification, it affects all targets, unless
+overridden by any per-target directive.
+
+.TP
+.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 (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>[...]]
+Turns on quarantine of URIs that returned
+.IR LDAP_UNAVAILABLE ,
+so that an attempt to reconnect only occurs at given intervals instead
+of any time a client requests an operation.
+The pattern is: retry only after at least
+.I interval
+seconds elapsed since last attempt, for exactly
+.I num
+times; then use the next pattern.
+If
+.I num
+for the last pattern is "\fB+\fP", it retries forever; otherwise,
+no more retries occur.
+This directive must appear before any target specification;
+it affects all targets with the same pattern.
+
+.TP
+.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
+is set to
+.IR yes .
+
+.TP
+.B session\-tracking\-request {NO|yes}
+Adds session tracking control for all requests.
+The client's IP and hostname, and the identity associated to each request,
+if known, are sent to the remote server for informational purposes.
+This directive is incompatible with setting \fIprotocol\-version\fP to 2.
+If set before any target specification, it affects all targets, unless
+overridden by any per-target directive.
+
+.TP
+.B single\-conn {NO|yes}
+Discards current cached connection when the client rebinds.
+
+.TP
+.B use\-temporary\-conn {NO|yes}
+when set to
+.BR yes ,
+create a temporary connection whenever competing with other threads
+for a shared one; otherwise, wait until the shared connection is available.
+
.SH TARGET SPECIFICATION
Target specification starts with a "uri" directive:
+
.TP
-.B uri <protocol>://[<host>[:<port>]]/<naming context>
-The "server" directive that was allowed in the LDAP backend (although
-deprecated) has been completely discarded in the Meta backend.
+.B uri <protocol>://[<host>]/<naming context> [...]
The <protocol> part can be anything
.BR ldap_initialize (3)
-accepts ({ldap|ldaps|ldapi} and variants); <host> and <port> may be
+accepts ({ldap|ldaps|ldapi} and variants); the <host> may be
omitted, defaulting to whatever is set in
.BR ldap.conf (5).
-The <naming context> part is mandatory.
-It must end with one of the naming contexts defined for the backend,
+The <naming context> part is \fImandatory\fP for the first URI,
+but it \fImust be omitted\fP for subsequent ones, if any.
+The naming context part must be within the naming context defined for the backend,
e.g.:
.LP
.RS
.RS
The <naming context> part doesn't need to be unique across the targets;
it may also match one of the values of the "suffix" directive.
-Multiple URIs may be defined in a single argument. The URIs must
-be separated by TABs (e.g. '\\t'; commas or spaces, unlike back-ldap,
-will not work,
-because they are legal in the <naming context>, and we don't want to use
-URL-encoded <namimg context>s), and the additional URIs must have
-no <naming context> part. This causes the underlying library
+Multiple URIs may be defined in a single URI statement.
+The additional URIs must be separate arguments and must not have any
+<naming context> part. This causes the underlying library
to contact the first server of the list that responds.
+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
+
.RE
+.RS
+causes \fIl2.foo.com\fP to be contacted whenever \fIl1.foo.com\fP
+does not respond.
+In that case, the URI list is internally rearranged, by moving unavailable
+URIs to the end, so that further connection attempts occur with respect to
+the last URI that succeeded.
+.RE
+
.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 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 rebind-as-user
-If this option is given, the client's bind credentials are remembered
-for rebinds when chasing referrals.
+.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
+underlying libldap, with rebinding eventually performed if the
+\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.
+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 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=<version>]
+.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
+
+[<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 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 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 .
+If set before any target specification, it affects all targets, unless
+overridden by any per-target directive.
+
+.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>"
-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.
+Deprecated; use
+.B idassert\-bind
+instead.
+
.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.
-.LP
-Note: cleartext credentials must be supplied here; as a consequence,
-using the pseudorootdn/pseudorootpw directives is inherently unsafe.
+Deprecated; use
+.B idassert\-bind
+instead.
+
.TP
.B rewrite* ...
The rewrite options are described in the "REWRITING" section.
+
+.TP
+.B subtree\-exclude "<DN>"
+This directive instructs back-meta to ignore the current target
+for operations whose requestDN is subordinate to
+.BR DN .
+There may be multiple occurrences of the
+.B subtree\-exclude
+directive for each of the targets.
+
.TP
.B suffixmassage "<virtual naming context>" "<real naming context>"
All the directives starting with "rewrite" refer to the rewrite engine
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 [<op>=]<val> [...]
+This directive allows to set per-operation timeouts.
+Operations can be
+
+\fB<op> ::= bind, add, delete, modrdn, modify, compare, search\fP
+
+The overall duration of the \fBsearch\fP operation is controlled either
+by the \fBtimelimit\fP parameter or by server-side enforced
+time limits (see \fBtimelimit\fP and \fBlimits\fP in
+.BR slapd.conf (5)
+for details).
+This \fBtimeout\fP parameter controls how long the target can be
+irresponsive before the operation is aborted.
+Timeout is meaningless for the remaining operations,
+\fBunbind\fP and \fBabandon\fP, which do not imply any response,
+while it is not yet implemented in currently supported \fBextended\fP
+operations.
+If no operation is specified, the timeout \fBval\fP affects all
+supported operations.
+If specified before any target definition, it affects all targets
+unless overridden by per-target directives.
+
+Note: if the timeout is exceeded, the operation is cancelled
+(according to the \fBcancel\fP directive);
+the protocol does not provide any means to rollback operations,
+so the client will not be notified about the result of the operation,
+which may eventually succeeded or not.
+In case the timeout is exceeded during a bind operation, the connection
+is destroyed, according to RFC4511.
+
+.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.
.LP
.RS
.nf
-access to dn="<dn>" attr=<attr>
+access to dn="<dn>" attr
s=<attr>
by dnattr=<dnattr> read
by * none
.fi
The underlying concept is to build a lightweight rewrite module
for the slapd server (initially dedicated to the LDAP backend).
.SH Passes
-An incoming string is matched agains a set of rules.
+An incoming string is matched against a set of rules.
Rules are made of a regex match pattern, a substitution pattern
and a set of actions, described by a set of flags.
In case of match a string rewriting is performed according to the
The substitution pattern allows map resolution of substrings.
A map is a generic object that maps a substitution pattern to a value.
The flags are divided in "Pattern matching Flags" and "Action Flags";
-the former alter the regex match pattern behaviorm while the latter
+the former alter the regex match pattern behavior while the latter
alter the action that is taken after substitution.
.SH "Pattern Matching Flags"
.TP
assigns a variable in the rewrite context scope; operator
.B &&
assigns a variable that scopes the entire session, e.g. its value
-can be derefenced later by other rewrite contexts
+can be dereferenced later by other rewrite contexts
.TP
.B *
variable dereferencing; <name> must refer to a variable that is
they are divided in two main groups: client \-> server and
server \-> client rewriting.
.LP
-client -> server:
+client \-> server:
.LP
.RS
.nf
modrDN modrdn
newSuperiorDN modrdn
deleteDN delete
-exopPasswdDN passwd exop DN if proxy
+exopPasswdDN password modify extended operation DN if proxy
.fi
.RE
.LP
-server -> client:
+server \-> client:
.LP
.RS
.nf
<Context name> is the name that identifies the context, i.e. the name
used by the application to refer to the set of rules it contains.
It is used also to reference sub contexts in string rewriting.
-A context may aliase another one.
+A context may alias another one.
In this case the alias context contains no rule, and any reference to
it will result in accessing the aliased one.
.TP
.fi
.LP
with the advantage of saving one rewrite pass ...)
+
+.SH ACCESS CONTROL
+The
+.B meta
+backend does not honor all ACL semantics as described in
+.BR slapd.access (5).
+In general, access checking is delegated to the remote server(s).
+Only
+.B read (=r)
+access to the
+.B entry
+pseudo-attribute and to the other attribute values of the entries
+returned by the
+.B search
+operation is honored, which is performed by the frontend.
+
.SH PROXY CACHE OVERLAY
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 FILES
.TP
projects / openldap / blobdiff