.TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2005 The OpenLDAP Foundation, All Rights Reserved.
+.\" Copyright 1998-2006 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$
excessive overhead for some applications, so its use should be
carefully considered.
In the examples section, some typical scenarios will be discussed.
+
+.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.
.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
+.LP
for every
.B ldap
and
.B meta
-backend.
+database.
+This is 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 off, so its use
+is redundant and should be omitted, because the lastmod directive will
+be deprecated in the future.
+
.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 default-target none
This directive forces the backend to reject all those operations
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 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.
+.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 onerr {CONTINUE|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 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
+for rebinds when chasing referrals.
+
.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
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
+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.
+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.
.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.
+.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 acl-authcDN "<administrative DN for access control purposes>"
DN which is used to query the target server for acl checking,
check permissions.
.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>
Password used with the
.B
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 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 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.
+
.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.
+
.TP
.B rewrite* ...
The rewrite options are described in the "REWRITING" section.
+
.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 [{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.
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
modrDN modrdn
newSuperiorDN modrdn
deleteDN delete
-exopPasswdDN passwd exop DN if proxy
+exopPasswdDN password modify extended operation DN if proxy
.fi
.RE
.LP
<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
projects / openldap / blobdiff