Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SLAPD-META(5)		      File Formats Manual		 SLAPD-META(5)

       slapd-meta - metadirectory backend to slapd


       The  meta backend to slapd(8) performs basic LDAP proxying with respect
       to a set	of remote LDAP servers,	 called	 "targets".   The  information
       contained  in  these  servers can be presented as belonging to a	single
       Directory Information Tree (DIT).

       A basic knowledge of the	functionality of the slapd-ldap(5) backend  is
       recommended.   This  backend has	been designed as an enhancement	of the
       ldap backend.  The two backends share many features (actually they also
       share  portions	of code).  While the ldap backend is intended to proxy
       operations directed to a	single server, the meta	backend	is mainly  in-
       tended  for  proxying  of  multiple servers and possibly	naming context
       masquerading.  These features, although useful in many  scenarios,  may
       result  in  excessive overhead for some applications, so	its use	should
       be carefully considered.	 In the	examples section, some typical scenar-
       ios will	be discussed.

       The  proxy instance of 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.

       Note: When looping back to the same instance of slapd(8), each  connec-
       tion  requires a	new thread; as a consequence, the slapd(8) threads pa-
       rameter may need	some tuning. In	those cases, unless the	multiple  tar-
       get feature is required,	one may	consider using slapd-relay(5) instead,
       which performs the relayed operation internally	and  thus  reuses  the
       same connection.

       There  are  examples  in	various	places in this document, as well as in
       the slapd/back-meta/data/ directory in the OpenLDAP source tree.

       These slapd.conf	options	apply to the META backend database.  That  is,
       they  must follow a "database meta" line	and come before	any subsequent
       "backend" or "database" lines.  Other database options are described in
       the slapd.conf(5) manual	page.

       Note:  In  early	versions of back-ldap and back-meta it was recommended
       to always set

	      lastmod  off

       for ldap	and meta databases.  This was required because operational at-
       tributes	related	to entry creation and modification should not be prox-
       ied, as they could be mistakenly	written	to the target server(s),  gen-
       erating	an error.  The current implementation automatically sets last-
       mod to off, so its use is redundant and should be omitted.

       Target configuration starts with	the "uri" directive.  All the configu-
       ration  directives  that	 are not specific to targets should be defined
       first for clarity, including those that are  common  to	all  backends.
       They are:

       conn-pool-max <int>
	      This  directive  defines the maximum size	of the privileged con-
	      nections pool.

       conn-ttl	<time>
	      This directive causes a  cached  connection  to  be  dropped  an
	      recreated	after a	given ttl, regardless of being idle or not.

       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.  They include: add, delete, modify, mod-
	      rdn; compare is not included, as well as	bind  since,  as  they
	      don't  alter  entries, in	case of	multiple matches an attempt is
	      made to perform the operation on any candidate 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.

       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  se-
	      lection  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 for-
	      mat illustrated for the idle-timeout directive.

       onerr {CONTINUE|report|stop}
	      This directive allows one	to select the behavior in case an  er-
	      ror  is  returned	 by  one target	during a search.  The default,
	      continue,	consists in continuing the operation, trying to	return
	      as  much	data  as  possible.   If the value is set to stop, the
	      search is	terminated as soon as an error is returned by one tar-
	      get,  and	the error is immediately propagated to the client.  If
	      the value	is set to report, the search is	continued to  the  end
	      but,  in	case  at  least	one target returned an error code, the
	      first non-success	error code is returned.

       norefs <NO|yes>
	      If 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.

       noundeffilter <NO|yes>
	      If yes, return success instead of	searching if a filter is unde-
	      fined or contains	undefined portions.  By	default, the search is
	      propagated  after	 replacing  undefined portions with (!(object-
	      Class=*)), which corresponds to the empty	result	set.   If  set
	      before  any target specification,	it affects all targets,	unless
	      overridden by any	per-target directive.

       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 unwillingToPer-
	      form 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  di-

       pseudoroot-bind-defer {YES|no}
	      This  directive,	when  set to yes, causes the authentication to
	      the remote servers with the pseudo-root identity	(the  identity
	      defined  in  each	 idassert-bind directive) to be	deferred until
	      actually needed by subsequent operations.	 Otherwise, all	 binds
	      as the rootdn are	propagated to the targets.

       quarantine <interval>,<num>[;<interval>,<num>[...]]
	      Turns  on	 quarantine of URIs that returned LDAP_UNAVAILABLE, so
	      that an attempt to reconnect only	occurs at given	intervals  in-
	      stead  of	 any time a client requests an operation.  The pattern
	      is: retry	only after at least  interval  seconds	elapsed	 since
	      last  attempt, for exactly num times; then use the next pattern.
	      If num for the last pattern is "+", it retries  forever;	other-
	      wise,  no	more retries occur.  This directive must appear	before
	      any target specification;	it affects all targets with  the  same

       rebind-as-user {NO|yes}
	      If  this	option is given, the client's bind credentials are re-
	      membered for rebinds, when trying	to re-establish	a broken  con-
	      nection,	or  when chasing a referral, if	chase-referrals	is set
	      to yes.

       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 protocol-version to
	      2.  If set before	any target specification, it affects all  tar-
	      gets, unless overridden by any per-target	directive.

       single-conn {NO|yes}
	      Discards current cached connection when the client rebinds.

       use-temporary-conn {NO|yes}
	      when  set	to yes,	create a temporary connection whenever compet-
	      ing with other threads for a shared one; otherwise,  wait	 until
	      the shared connection is available.

       Target specification starts with	a "uri"	directive:

       uri <protocol>://[<host>]/<naming context> [...]
	      The  <protocol>  part can	be anything ldap_initialize(3) accepts
	      ({ldap|ldaps|ldapi} and variants); the <host>  may  be  omitted,
	      defaulting to whatever is	set in ldap.conf(5).  The <naming con-
	      text> part is mandatory for the first URI, but it	must be	 omit-
	      ted  for	subsequent ones, if any.  The naming context part must
	      be within	the naming context defined for the backend, e.g.:

	      suffix "dc=foo,dc=com"
	      uri    "ldap://,dc=foo,dc=com"

	      The <naming context> part	doesn't	need to	be unique  across  the
	      targets; it may also match one of	the values of the "suffix" di-
	      rective.	Multiple URIs may be defined in	a  single  URI	state-
	      ment.   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 and	 are  shadows  of  the
	      same server, the directive

	      suffix "dc=foo,dc=com"
	      uri    "ldap://,dc=com" "ldap://"

	      causes  to be	contacted whenever does not
	      respond.	In that	case, the URI list is  internally  rearranged,
	      by  moving  unavailable URIs to the end, so that further connec-
	      tion attempts occur with respect to the last URI that succeeded.

       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.  The acl-authcDN identity is by  no	 means
	      implicitly  used	by  the	 proxy when the	client connects	anony-

       acl-passwd <password>
	      Password used with the acl-authcDN above.

       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 bind-timeout.   The
	      default  value is	used also for subsequent calls if bind-timeout
	      is not specified.	 If set	before any  target  specification,  it
	      affects  all targets, unless overridden by any per-target	direc-

       chase-referrals {YES|no}
	      enable/disable automatic referral	chasing, which is delegated to
	      the  underlying  libldap,	with rebinding eventually performed if
	      the rebind-as-user 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.

       client-pr {accept-unsolicited|DISABLE|<size>}
	      This feature allows one to use RFC 2696  Paged  Results  control
	      when  performing search operations with a	specific target, irre-
	      spective of the client's request.	 When set to a numeric	value,
	      Paged Results control is always used with	size as	the page size.
	      When set to accept-unsolicited, unsolicited Paged	 Results  con-
	      trol  responses  are accepted and	honored	for compatibility with
	      broken remote DSAs.  The client is not exposed to	paged  results
	      handling	between	 slapd-meta(5) and the remote servers.	By de-
	      fault (disabled),	Paged Results control  is  not	used  and  re-
	      sponses  are  not	accepted.  If set before any target specifica-
	      tion, it affects all targets, unless overridden by any  per-tar-
	      get directive.

       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.

       filter <pattern>
	      This directive allows specifying a 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 pattern
	      the target is considered while fulfilling	the request; otherwise
	      the  target is ignored. There may	be multiple occurrences	of the
	      filter directive for each	target.

       idassert-authzFrom <authz-regexp>
	      if defined, selects what local identities	are authorized to  ex-
	      ploit the	identity assertion feature.  The string	<authz-regexp>
	      follows the rules	defined	 for  the  authzFrom  attribute.   See
	      slapd.conf(5),  section  related to authz-policy,	for details on
	      the syntax of this field.

       idassert-bind	bindmethod=none|simple|sasl    [binddn=<simple	  DN>]
	      [credentials=<simple     password>]    [saslmech=<SASL	mech>]
	      [secprops=<properties>] [realm=<realm>] [authcId=<authentication
	      ID>]  [authzId=<authorization  ID>]  [authz={native|proxyauthz}]
	      [mode=<mode>]	[flags=<flags>]	    [starttls=no|yes|critical]
	      [tls_cert=<file>]	     [tls_key=<file>]	   [tls_cacert=<file>]
	      [tls_cacertdir=<path>]	  [tls_reqcert=never|allow|try|demand]
	      [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
	      [tls_ecname=<ciphers>]	  [tls_protocol_min=<major>[.<minor>]]
	      Allows one 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 proxyAuthz privileges on  a	 wide  set  of
	      DNs,  e.g.  authzTo=dn.subtree:"", and the remote	server to have
	      authz-policy set to to or	both.  See slapd.conf(5)  for  details
	      on  these	 statements  and for remarks and drawbacks about their
	      usage.  The supported bindmethods	are


	      where none  is  the  default,  i.e.  no  identity	 assertion  is

	      The authz	parameter is used to instruct the SASL bind to exploit
	      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 authzDN or	 authzID  parameters).
	      Otherwise,  the  default proxyauthz is used, i.e.	the proxyAuthz
	      control (Proxied	Authorization,	RFC  4370)  is	added  to  all

	      The supported modes are:

	      <mode> :=	{legacy|anonymous|none|self}

	      If <mode>	is not present,	and authzId is given, the proxy	always
	      authorizes that identity.	 <authorization	ID> can	be



	      The former is supposed to	 be  expanded  by  the	remote	server
	      according	to the authz rules; see	slapd.conf(5) for details.  In
	      the latter case, whether or not the dn: prefix is	 present,  the
	      string must pass DN validation and normalization.

	      The  default  mode  is legacy, which implies that	the proxy will
	      either perform a simple bind as the authcDN or a	SASL  bind  as
	      the  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 authcDN or a SASL bind as the	authcID, unless	restricted  by
	      idassert-authzFrom   rules   (see	 below),  in  which  case  the
	      operation	will fail;  eventually,	 it  will  assert  some	 other
	      identity	according  to  <mode>.	Other identity assertion modes
	      are anonymous and	self, which respectively mean that  the	 empty
	      or  the  client's	 identity  will	be asserted; none, which means
	      that no proxyAuthz control will be used, so the authcDN  or  the
	      authcID  identity	 will be asserted.  For	all modes that require
	      the use of the proxyAuthz	control,  on  the  remote  server  the
	      proxy identity must have appropriate authzTo permissions,	or the
	      asserted identities must have appropriate	authzFrom permissions.
	      Note,  however,  that  the ID assertion feature is mostly	useful
	      when the asserted	identities do not exist	on the remote  server.
	      When  bindmethod	is  SASL,  the	authcDN	 must  be specified in
	      addition to the authcID, although	it  is	not  used  within  the
	      authentication process.

	      Flags can	be


	      When  the	 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	 prescriptive  flag  is	used (the default), operations
	      fail with	inappropriateAuthentication for	those identities whose
	      assertion	is not allowed by the idassert-authzFrom patterns.  If
	      the non-prescriptive flag	 is  used,  operations	are  performed
	      anonymously  for those identities	whose assertion	is not allowed
	      by the idassert-authzFrom	patterns.

	      When the proxy-authz-non-critical	flag is	 used  (the  default),
	      the  proxyAuthz  control is not marked as	critical, in violation
	      of RFC 4370.  Use	of proxy-authz-critical	is recommended.

	      The TLS settings default to the  same  as	 the  main  slapd  TLS
	      settings,	except for tls_reqcert which defaults to "demand", and
	      tls_reqsan which defaults	to "allow"..

	      The identity associated to  this	directive  is  also  used  for
	      privileged  operations  whenever	idassert-bind  is  defined and
	      acl-bind is not.	See acl-bind for details.

       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


	      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.

       keepalive <idle>:<probes>:<interval>
	      The  keepalive  parameter	 sets  the values of idle, probes, and
	      interval used to check whether a socket is alive;	 idle  is  the
	      number  of  seconds a connection needs to	remain idle before TCP
	      starts sending keepalive probes; probes is the maximum number of
	      keepalive	probes TCP should send before dropping the connection;
	      interval is interval in  seconds	between	 individual  keepalive
	      probes.	Only  some  systems support the	customization of these
	      values;  the  keepalive  parameter  is  ignored  otherwise,  and
	      system-wide settings are used.

       tcp-user-timeout	<milliseconds>
	      If  non-zero,  corresponds  to  the  TCP_USER_TIMEOUT set	on the
	      target connections, overriding  the  operating  system  setting.
	      Only  some  systems support the customization of this parameter,
	      it is ignored otherwise and system-wide settings are used.

       map {attribute|objectclass} [<local name>|*] {<foreign name>|*}
	      This maps	object classes and attributes as in the	LDAP  backend.
	      See slapd-ldap(5).

       network-timeout <time>
	      Sets  the	 network  timeout  value after which poll(2)/select(2)
	      following	a connect(2) returns in	 case  of  no  activity.   The
	      value   is   in	seconds,  and  it  can	be  specified  as  for
	      idle-timeout.   If  set  before  any  target  specification,  it
	      affects	all  targets,  unless  overridden  by  any  per-target

       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,	3  times);  the	 global	 value	can  be	 overridden by
	      redefinitions inside each	target specification.

       rewrite*	...
	      The rewrite options are described	in the "REWRITING" section.

       subtree-{exclude|include} <rule>
	      This directive allows one	to indicate what subtrees are actually
	      served by	a target.  The syntax of the supported rules is

	      <rule>: [dn[.<style>]:]<pattern>

	      <style>: subtree|children|regex

	      When <style> is either subtree or	children the <pattern> is a DN
	      that must	be within the naming context  served  by  the  target.
	      When  <style>  is	regex the <pattern> is a regex(5) pattern.  If
	      the dn.<style>: prefix is	 omitted,  dn.subtree:	is  implicitly
	      assumed for backward compatibility.

	      In  the  subtree-exclude form if the request DN 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 request DN.  When the request is a	search,	also the scope
	      is considered.

	      In  the  subtree-include form if the request DN matches at least
	      one rule,	the target is considered while fulfilling the request;
	      otherwise	the target is ignored.

		  |  match  | exclude |
		  |    T    |	 T    |	not candidate	  |
		  |    F    |	 T    |	continue checking |
		  |    T    |	 F    |	candidate	  |
		  |    F    |	 F    |	not candidate	  |

	      There  may  be  multiple	occurrences  of	the subtree-exclude or
	      subtree-include directive	for each of the	targets, but they  are
	      mutually exclusive.

       suffixmassage <virtual naming context> <real naming context>
	      All  the directives starting with	"rewrite" refer	to the rewrite
	      engine that  has	been  added  to	 slapd.	  The  "suffixmassage"
	      directive	 was  introduced  in  the LDAP backend to allow	suffix
	      massaging	 while	proxying.   It	has  been  obsoleted  by   the
	      rewriting	 tools.	  However, both	for backward compatibility and
	      for  ease	 of  configuration  when  simple  suffix  massage   is
	      required,	 it  has been preserved.  It wraps the basic rewriting
	      instructions that	perform	suffix massaging.  See the "REWRITING"
	      section for a detailed list of the rewrite rules it implies.

       t-f-support {NO|yes|discover}
	      enable  if  the remote server supports absolute filters (see RFC
	      4526 for details).  If set to 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.

       timeout [<op>=]<val> [...]
	      This   directive	allows	one  to	 set  per-operation  timeouts.
	      Operations can be

	      <op> ::= bind, add, delete, modrdn, modify, compare, search

	      The overall duration  of	the  search  operation	is  controlled
	      either  by  the  timelimit  parameter or by server-side enforced
	      time limits (see	timelimit  and	limits	in  slapd.conf(5)  for
	      details).	  This	timeout	parameter controls how long the	target
	      can be irresponsive before the operation is aborted.  Timeout is
	      meaningless  for	the  remaining operations, unbind and abandon,
	      which do not imply any response, while it	is not yet implemented
	      in  currently supported extended operations.  If no operation is
	      specified, the timeout val 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  cancel  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.

       tls {none|[try-]start|[try-]propagate|ldaps}
	      [starttls=no]	    [tls_cert=<file>]	      [tls_key=<file>]
	      [tls_cacert=<file>]			[tls_cacertdir=<path>]
	      [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
	      [tls_ecname=<names>] [tls_crlcheck=none|peer|all]
	      Specify TLS settings regular connections.

	      If the first parameter is	not "none" then	 this  configures  the
	      TLS  settings  to	be used	for regular connections.  The StartTLS
	      extended operation will be used when establishing	the connection
	      unless  the  URI directive protocol scheme is ldaps://.  In that
	      case this	keyword	may only be set	to "ldaps"  and	 the  StartTLS
	      operation	will not be used.

	      With  propagate, the proxy issues	the StartTLS operation only if
	      the original connection has a TLS	layer set up.  The try-	prefix
	      instructs	 the  proxy  to	 continue  operations  if the StartTLS
	      operation	failed;	its use	is not recommended.

	      The TLS settings default to the  same  as	 the  main  slapd  TLS
	      settings,	 except	 for  tls_reqcert  which defaults to "demand",
	      tls_reqsan which defaults	to  "allow",  and  starttls  which  is
	      overshadowed by the first	keyword	and thus ignored.

	      If  set before any target	specification, it affects all targets,
	      unless overridden	by any per-target directive.

       A powerful (and in some sense dangerous)	rewrite	engine has been	 added
       to  both	the LDAP and Meta backends.  While the former can gain limited
       beneficial effects from rewriting  stuff,  the  latter  can  become  an
       amazingly powerful tool.

       Consider	a couple of scenarios first.

       1)  Two	directory  servers  share  two	levels	of naming context; say
       "dc=a,dc=foo,dc=com" and	"dc=b,dc=foo,dc=com".	Then,  an  unambiguous
       Meta database can be configured as:

	      database meta
	      suffix   "dc=foo,dc=com"
	      uri      "ldap://,dc=foo,dc=com"
	      uri      "ldap://,dc=foo,dc=com"

       Operations directed to a	specific target	can be easily resolved because
       there are no ambiguities.  The  only  operation	that  may  resolve  to
       multiple	 targets  is  a	 search	with base "dc=foo,dc=com" and scope at
       least "one", which results in spawning two searches to the targets.

       2a) Two directory servers don't share any portion  of  naming  context,
       but  they'd  present  as	a single DIT [Caveat: uniqueness of (massaged)
       entries among the two servers is	 assumed;  integrity  checks  risk  to
       incur  in  excessive  overhead  and have	not been implemented].	Say we
       have "dc=bar,dc=org" and	"o=Foo,c=US", and we'd like them to appear  as
       branches	   of	 "dc=foo,dc=com",    say    "dc=a,dc=foo,dc=com"   and
       "dc=b,dc=foo,dc=com".  Then we need to configure	our Meta backend as:

	      database	    meta
	      suffix	    "dc=foo,dc=com"

	      uri	    "ldap://,dc=foo,dc=com"
	      suffixmassage "dc=a,dc=foo,dc=com" "dc=bar,dc=org"

	      uri	    "ldap://,dc=foo,dc=com"
	      suffixmassage "dc=b,dc=foo,dc=com" "o=Foo,c=US"

       Again, operations can be	 resolved  without  ambiguity,	although  some
       rewriting  is required.	Notice that the	virtual	naming context of each
       target is a branch of the database's naming context;  it	 is  rewritten
       back  and  forth	 when  operations  are	performed  towards  the	target
       servers.	 What "back and	forth" means will be clarified later.

       When a search with base "dc=foo,dc=com" is attempted, if	the  scope  is
       "base"  it fails	with "no such object"; in fact,	the common root	of the
       two targets (prior to massaging)	does  not  exist.   If	the  scope  is
       "one",  both  targets  are  contacted  with  the	 base replaced by each
       target's	base; the scope	is derated to "base".	In  general,  a	 scope
       "one"  search  is  honored,  and	 the  scope  is	derated, only when the
       incoming	base is	at most	one level lower	of a target's  naming  context
       (prior to massaging).

       Finally,	 if  the  scope	is "sub" the incoming base is replaced by each
       target's	unmassaged naming context, and the scope is not	altered.

       2b) Consider the	above reported scenario	with the two  servers  sharing
       the same	naming context:

	      database	    meta
	      suffix	    "dc=foo,dc=com"

	      uri	    "ldap://,dc=com"
	      suffixmassage "dc=foo,dc=com" "dc=bar,dc=org"

	      uri	    "ldap://,dc=com"
	      suffixmassage "dc=foo,dc=com" "o=Foo,c=US"

       All  the	 previous considerations hold, except that now there is	no way
       to unambiguously	resolve	a DN.  In this case, all the  operations  that
       require	an  unambiguous	 target	 selection  will fail unless the DN is
       already	cached	or  a  default	target	has   been   set.    Practical
       configurations may result as a combination of all the above scenarios.

       Note  on	 ACLs:	at present you may add whatever	ACL rule you desire to
       the Meta	(and LDAP) backends.  However, the meaning  of	an  ACL	 on  a
       proxy  may  require  some  considerations.   Two	 philosophies  may  be

       a) the remote server dictates the permissions; the proxy	simply	passes
       back what it gets from the remote server.

       b) the remote server unveils "everything"; the proxy is responsible for
       protecting data from unauthorized access.

       Of course the latter  sounds  unreasonable,  but	 it  is	 not.	It  is
       possible	 to  imagine  scenarios	 in which a remote host	discloses data
       that can	be considered "public" inside an intranet, and	a  proxy  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	 file	an   ITS   if	you   can   find   other   exceptions:
       <>).	 The rule

	      access to	dn="<dn>" attrs=<attr>
		     by	dnattr=<dnattr>	read
		     by	* none

       cannot be matched iff the attribute that	is being requested, <attr>, is
       NOT  <dnattr>,  and the attribute that determines membership, <dnattr>,
       has not been requested (e.g. in a search)

       In fact this ACL	is resolved by slapd using the	portion	 of  entry  it
       retrieved   from	 the  remote  server  without  requiring  any  further
       intervention of the backend, so,	if the <dnattr>	attribute has not been
       fetched,	 the  match  cannot  be	 assessed because the attribute	is not
       present,	not because no value matches the requirement!

       Note on ACLs and	attribute mapping: ACLs	 are  applied  to  the	mapped
       attributes;  for	 instance,  if the attribute locally known as "foo" is
       mapped to "bar" on a remote server, then	local ACLs apply to  attribute
       "foo"  and  are	totally	unaware	of its remote name.  The remote	server
       will check permissions for "bar", and the local	server	will  possibly
       enforce additional restrictions to "foo".

       A  string  is  rewritten	according to a set of rules, called a `rewrite
       context'.   The	rules  are  based  on  POSIX  (''extended'')   regular
       expressions   (regex)   with   substring	  matching;   basic   variable
       substitution and	map resolution of substrings is	 allowed  by  specific
       mechanisms   detailed  in  the  following.   The	 behavior  of  pattern
       matching/substitution can be altered by a set of	flags.

       The underlying concept is to build a lightweight	rewrite	module for the
       slapd server (initially dedicated to the	LDAP backend).

       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 substitution	pattern	 that  allows  one  to
       refer  to  substrings  matched in the incoming string.  The actions, if
       any, are	 finally  performed.   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 behavior	while the latter alter the action that is taken	 after

Pattern	Matching Flags
       `C'    honors case in matching (default is case insensitive)

       `R'    use    POSIX   ''basic''	 regular   expressions	 (default   is

       `M{n}' allow no more than n recursive passes for	a specific rule;  does
	      not  alter the max total count of	passes,	so it can only enforce
	      a	stricter limit for a specific rule.

Action Flags
       `:'    apply the	rule once only (default	is recursive)

       `@'    stop applying rules in case of match; the	current	rule is	 still
	      applied  recursively; combine with `:' to	apply the current rule
	      only once	and then stop.

       `#'    stop current  operation  if  the	rule  matches,	and  issue  an
	      `unwilling to perform' error.

       `G{n}' jump  n  rules  back  and	 forth	(watch for loops!).  Note that
	      `G{1}' is	implicit in every rule.

       `I'    ignores errors in	rule; this  means,  in	case  of  error,  e.g.
	      issued  by  a  map, the error is treated as a missed match.  The
	      `unwilling to perform' is	not overridden.

       `U{n}' uses n as	return code if the rule	matches;  the  flag  does  not
	      alter  the  recursive  behavior  of  the	rule,  so,  to have it
	      performed	only once, it must be used in  combination  with  `:',
	      e.g.    `:U{16}'	returns	 the  value  `16'  after  exactly  one
	      execution	 of  the  rule,	 if  the  pattern   matches.	As   a
	      consequence,  its	behavior is equivalent to `@', with the	return
	      code set to n; or, in other words, `@' is	equivalent to  `U{0}'.
	      By convention, the freely	available codes	are above 16 included;
	      the others are reserved.

       The ordering of the flags can be	significant.   For  instance:  `IG{2}'
       means  ignore errors and	jump two lines ahead both in case of match and
       in case of error, while `G{2}I' means ignore errors, but	jump two lines
       ahead only in case of match.

       More flags (mainly Action Flags)	will be	added as needed.

Pattern	matching:
       See regex(7) and/or re_format(7).

Substitution Pattern Syntax:
       Everything starting with	`%' requires substitution;

       the only	obvious	exception is `%%', which is left as is;

       the basic substitution is `%d', where `d' is a digit; 0 means the whole
       string, while 1-9 is a submatch;

       a `%' followed by a `{' invokes an advanced substitution.  The  pattern

	      `%' `{' [	<op> ] <name> `(' <substitution> `)' `}'

       where <name> must be a legal name for the map, i.e.

	      <name> ::= [a-z][a-z0-9]*	(case insensitive)
	      <op> ::= `>' `|' `&' `&&'	`*' `**' `$'

       and <substitution> must be a legal substitution pattern,	with no	limits
       on the nesting level.

       The operators are:

       >      sub context invocation; <name> must be a legal, already  defined
	      rewrite context name

       |      external	command	 invocation;  <name>  must  refer  to a	legal,
	      already defined command name (NOT	IMPL.)

       &      variable assignment; <name> defines a variable  in  the  running
	      operation	 structure which can be	dereferenced later; operator &
	      assigns a	variable in the	rewrite	 context  scope;  operator  &&
	      assigns  a  variable  that  scopes  the entire session, e.g. its
	      value can	be dereferenced	later by other rewrite contexts

       *      variable dereferencing; <name> must refer	to a variable that  is
	      defined  and  assigned  for  the	running	 operation; operator *
	      dereferences a variable scoping the rewrite context; operator **
	      dereferences  a  variable	 scoping  the  whole session, e.g. the
	      value is passed across rewrite contexts

       $      parameter	 dereferencing;	 <name>	 must  refer  to  an  existing
	      parameter;  the  idea is to make some run-time parameters	set by
	      the system available to the rewrite engine, as the  client  host
	      name,  the  bind	DN  if any, constant parameters	initialized at
	      config time, and so on; no parameter is currently	set by	either
	      back-ldap	 or  back-meta,	but constant parameters	can be defined
	      in the configuration file	by using the rewriteParam directive.

       Substitution escaping has been delegated	to the `%'  symbol,  which  is
       used  instead  of  `\'  in  string substitution patterns	because	`\' is
       already	escaped	 by  slapd's  low  level  parsing   routines;	as   a
       consequence,   regex   escaping	 requires   two	  `\'	symbols,  e.g.
       `.*\.foo\.bar' must be written as `.*\\.foo\\.bar'.

Rewrite	context:
       A rewrite context is a set of rules which are applied in	sequence.  The
       basic idea is to	have an	application initialize a rewrite engine	(think
       of Apache's mod_rewrite ...) with  a  set  of  rewrite  contexts;  when
       string  rewriting  is  required,	 one  invokes  the appropriate rewrite
       context with the	input string and obtains the newly rewritten one if no
       errors occur.

       Each  basic  server  operation is associated to a rewrite context; they
       are divided in two main groups: client -> server	and server  ->	client

       client -> server:

	      (default)		   if defined and no specific context
				   is available
	      bindDN		   bind
	      searchBase	   search
	      searchFilter	   search
	      searchFilterAttrDN   search
	      compareDN		   compare
	      compareAttrDN	   compare AVA
	      addDN		   add
	      addAttrDN		   add AVA
	      modifyDN		   modify
	      modifyAttrDN	   modify AVA
	      modrDN		   modrdn
	      newSuperiorDN	   modrdn
	      deleteDN		   delete
	      exopPasswdDN	   password modify extended operation DN if proxy

       server -> client:

	      searchResult	   search (only	if defined; no default;
				   acts	on DN and DN-syntax attributes
				   of search results)
	      searchAttrDN	   search AVA
	      matchedDN		   all ops (only if applicable)

Basic configuration syntax
       rewriteEngine { on | off	}
	      If  `on',	 the  requested	 rewriting  is performed; if `off', no
	      rewriting	takes place (an	easy way  to  stop  rewriting  without
	      altering too much	the configuration file).

       rewriteContext <context name> [ alias <aliased context name> ]
	      <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	alias another one.  In this  case  the
	      alias  context  contains	no  rule, and any reference to it will
	      result in	accessing the aliased one.

       rewriteRule <regex match	pattern> <substitution pattern>	[ <flags> ]
	      Determines how a	string	can  be	 rewritten  if	a  pattern  is
	      matched.	Examples are reported below.

Additional configuration syntax:
       rewriteMap <map type> <map name>	[ <map attrs> ]
	      Allows  one  to define a map that	transforms substring rewriting
	      into  something  else.   The  map	 is  referenced	  inside   the
	      substitution pattern of a	rule.

       rewriteParam <param name> <param	value>
	      Sets  a value with global	scope, that can	be dereferenced	by the
	      command `%{$paramName}'.

       rewriteMaxPasses	<number	of passes> [<number of passes per rule>]
	      Sets the maximum number of total rewriting passes	 that  can  be
	      performed	 in  a	single	rewrite	operation (to avoid loops).  A
	      safe default is set to 100; note that  reaching  this  limit  is
	      still  treated  as  a  success; recursive	invocation of rules is
	      simply  interrupted.   The  count	 applies  to   the   rewriting
	      operation	 as  a whole, not to any single	rule; an optional per-
	      rule limit can be	set.  This  limit  is  overridden  by  setting
	      specific per-rule	limits with the	`M{n}' flag.

Configuration examples:
       # set to	`off' to disable rewriting
       rewriteEngine on

       # the rules the "suffixmassage" directive implies
       rewriteEngine on
       # all dataflow from client to server referring to DNs
       rewriteContext default
       rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
       # empty filter rule
       rewriteContext searchFilter
       # all dataflow from server to client
       rewriteContext searchResult
       rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
       rewriteContext searchAttrDN alias searchResult
       rewriteContext matchedDN	alias searchResult

       # Everything defined here goes into the `default' context.
       # This rule changes the naming context of anything sent
       # to `dc=home,dc=net' to	`dc=OpenLDAP, dc=org'

       rewriteRule "(.*)dc=home,[ ]?dc=net"
		   "%1dc=OpenLDAP, dc=org"  ":"

       # since a pretty/normalized DN does not include spaces
       # after rdn separators, e.g. `,', this rule suffices:

       rewriteRule "(.*)dc=home,dc=net"
		   "%1dc=OpenLDAP,dc=org"  ":"

       # Start a new context (ends input of the	previous one).
       # This rule adds	blanks between DN parts	if not present.
       rewriteContext  addBlanks
       rewriteRule     "(.*),([^ ].*)" "%1, %2"

       # This one eats blanks
       rewriteContext  eatBlanks
       rewriteRule     "(.*),[ ](.*)" "%1,%2"

       # Here control goes back	to the default rewrite
       # context; rules	are appended to	the existing ones.
       # anything that gets here is piped into rule `addBlanks'
       rewriteContext  default
       rewriteRule     ".*" "%{>addBlanks(%0)}"	":"

       # Rewrite the search base according to `default'	rules.
       rewriteContext  searchBase alias	default

       # Search	results	with OpenLDAP DN are rewritten back with
       # `dc=home,dc=net' naming context, with spaces eaten.
       rewriteContext  searchResult
       rewriteRule     "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
		       "%{>eatBlanks(%1)}dc=home,dc=net"    ":"

       # Bind with email instead of full DN: we	first need
       # an ldap map that turns	attributes into	a DN (the
       # argument used when invoking the map is	appended to
       # the URI and acts as the filter	portion)
       rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"

       # Then we need to detect	DN made	up of a	single email,
       # e.g. `'; note that the	rule
       # in case of match stops	rewriting; in case of error,
       # it is ignored.	 In case we are	mapping	virtual
       # to real naming	contexts, we also need to rewrite
       # regular DNs, because the definition of	a bindDn
       # rewrite context overrides the default definition.
       rewriteContext bindDN
       rewriteRule "^mail=[^,]+@[^,]+$"	"%{attr2dn(%0)}" ":@I"

       # This is a rather sophisticated	example. It massages a
       # search	filter in case who performs the	search has
       # administrative	privileges.  First we need to keep
       # track of the bind DN of the incoming request, which is
       # stored	in a variable called `binddn' with session scope,
       # and left in place to allow regular binding:
       rewriteContext  bindDN
       rewriteRule     ".+" "%{&&binddn(%0)}%0"	":"

       # A search filter containing `uid=' is rewritten	only
       # if an appropriate DN is bound.
       # To do this, in	the first rule the bound DN is
       # dereferenced, while the filter	is decomposed in a
       # prefix, in the	value of the `uid=<arg>' AVA, and
       # in a suffix. A	tag `<>' is appended to	the DN.
       # If the	DN refers to an	entry in the `ou=admin'	subtree,
       # the filter is rewritten OR-ing	the `uid=<arg>'	with
       # `cn=<arg>'; otherwise it is left as is. This could be
       # useful, for instance, to allow	apache's auth_ldap-1.4
       # module	to authenticate	users with both	`uid' and
       # `cn', but only	if the request comes from a possible
       # `cn=Web auth,ou=admin,dc=home,dc=net' user.
       rewriteContext searchFilter
       rewriteRule "(.*\\()uid=([a-z0-9_]+)(\\).*)"
       rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
	 "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I"
       rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"

       # This example shows how	to strip unwanted DN-valued
       # attribute values from a search	result;	the first rule
       # matches DN values below "ou=People,dc=example,dc=com";
       # in case of match the rewriting	exits successfully.
       # The second rule matches everything else and causes
       # the value to be rejected.
       rewriteContext searchResult
       rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@"
       rewriteRule ".*"	"" "#"

LDAP Proxy resolution (a possible evolution of slapd-ldap(5)):
       In  case	 the  rewritten	 DN is an LDAP URI, the	operation is initiated
       towards the host[:port] indicated in the	uri, if	it does	not  refer  to
       the local server.  E.g.:

	 rewriteRule '^cn=root,.*' '%0'			    'G{3}'
	 rewriteRule '^cn=[a-l].*' 'ldap://' ':@'
	 rewriteRule '^cn=[m-z].*' 'ldap://' ':@'
	 rewriteRule '.*'	   'ldap://' ':@'

       (Rule  1	is simply there	to illustrate the `G{n}' action; it could have
       been written:

	 rewriteRule '^cn=root,.*' 'ldap://' ':@'

       with the	advantage of saving one	rewrite	pass ...)

       The meta	backend	does not honor	all  ACL  semantics  as	 described  in
       slapd.access(5).	  In  general,	access	checking  is  delegated	to the
       remote server(s).  Only read (=r) access	to the entry  pseudo-attribute
       and to the other	attribute values of the	entries	returned by the	search
       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 slapo-pcache(5) for details.

       The  following  statements have been deprecated and should no longer be

       pseudorootdn <substitute	DN in case of rootdn bind>
	      Use idassert-bind	instead.

       pseudorootpw <substitute	password in case of rootdn bind>
	      Use idassert-bind	instead.

	      default slapd configuration file

       slapd.conf(5),  slapd-asyncmeta(5),   slapd-ldap(5),   slapo-pcache(5),
       slapd(8), regex(7), re_format(7).

       Pierangelo Masarati, based on back-ldap by Howard Chu

OpenLDAP 2.6.1			  2022/01/20			 SLAPD-META(5)

NAME | SYNOPSIS | DESCRIPTION | EXAMPLES | CONFIGURATION | SPECIAL CONFIGURATION DIRECTIVES | TARGET SPECIFICATION | SCENARIOS | ACLs | REWRITING | Passes | Pattern Matching Flags | Action Flags | Pattern matching: | Substitution Pattern Syntax: | Rewrite context: | Basic configuration syntax | Additional configuration syntax: | Configuration examples: | LDAP Proxy resolution (a possible evolution of slapd-ldap(5)): | ACCESS CONTROL | PROXY CACHE OVERLAY | DEPRECATED STATEMENTS | FILES | SEE ALSO | AUTHOR

Want to link to this manual page? Use this URL:

home | help