.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$
.\" 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
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
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.
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
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
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>[...]]
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 .
+.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}
+.B use\-temporary\-conn {NO|yes}
when set to
.BR yes ,
create a temporary connection whenever competing with other threads
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 <naming 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/"
+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 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
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.
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>"
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.
If specified before any target definition, it affects all targets
unless overridden by per-target directives.
-Note: if the timelimit is exceeded, the operation is cancelled
+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,
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.
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
they are divided in two main groups: client \-> server and
server \-> client rewriting.
.LP
-client -> server:
+client \-> server:
.LP
.RS
.nf
.fi
.RE
.LP
-server -> client:
+server \-> client:
.LP
.RS
.nf
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
projects / openldap / blobdiff