.TH SLAPD-META 5 "RELEASEDATE" "OpenLDAP LDVERSION"
-.\" Copyright 1998-2007 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 to slapd
+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 .
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
.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 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 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
.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.
.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.
-
-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>"
+.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
+.B subtree\-exclude
directive for each of the targets.
.TP
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).
If set to
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.
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 FILES
.TP