1SLAPD-META(5)                 File Formats Manual                SLAPD-META(5)
2
3
4

NAME

6       slapd-meta - metadirectory backend to slapd
7

SYNOPSIS

9       /etc/openldap/slapd.conf
10

DESCRIPTION

12       The  meta backend to slapd(8) performs basic LDAP proxying with respect
13       to a set of remote LDAP servers,  called  "targets".   The  information
14       contained  in  these  servers can be presented as belonging to a single
15       Directory Information Tree (DIT).
16
17       A basic knowledge of the functionality of the slapd-ldap(5) backend  is
18       recommended.   This  backend has been designed as an enhancement of the
19       ldap backend.  The two backends share many features (actually they also
20       share  portions  of code).  While the ldap backend is intended to proxy
21       operations directed to a single server, the meta backend is mainly  in‐
22       tended  for  proxying  of  multiple servers and possibly naming context
23       masquerading.  These features, although useful in many  scenarios,  may
24       result  in  excessive overhead for some applications, so its use should
25       be carefully considered.  In the examples section, some typical scenar‐
26       ios will be discussed.
27
28       The  proxy instance of slapd(8) must contain schema information for the
29       attributes and objectClasses used in filters, request DN  and  request-
30       related data in general.  It should also contain schema information for
31       the data returned by the proxied server.  It is the  responsibility  of
32       the  proxy  administrator to keep the schema of the proxy lined up with
33       that of the proxied server.
34
35
36       Note: When looping back to the same instance of slapd(8), each  connec‐
37       tion  requires a new thread; as a consequence, the slapd(8) threads pa‐
38       rameter may need some tuning. In those cases, unless the multiple  tar‐
39       get feature is required, one may consider using slapd-relay(5) instead,
40       which performs the relayed operation internally  and  thus  reuses  the
41       same connection.
42
43

EXAMPLES

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

CONFIGURATION

49       These slapd.conf options apply to the META backend database.  That  is,
50       they  must follow a "database meta" line and come before any subsequent
51       "backend" or "database" lines.  Other database options are described in
52       the slapd.conf(5) manual page.
53
54       Note:  In  early versions of back-ldap and back-meta it was recommended
55       to always set
56
57              lastmod  off
58
59       for ldap and meta databases.  This was required because operational at‐
60       tributes related to entry creation and modification should not be prox‐
61       ied, as they could be mistakenly written to the target server(s),  gen‐
62       erating  an error.  The current implementation automatically sets last‐
63       mod to off, so its use is redundant and should be omitted.
64
65

SPECIAL CONFIGURATION DIRECTIVES

67       Target configuration starts with the "uri" directive.  All the configu‐
68       ration  directives  that  are not specific to targets should be defined
69       first for clarity, including those that are  common  to  all  backends.
70       They are:
71
72
73       conn-pool-max <int>
74              This  directive  defines the maximum size of the privileged con‐
75              nections pool.
76
77
78       conn-ttl <time>
79              This directive causes a  cached  connection  to  be  dropped  an
80              recreated after a given ttl, regardless of being idle or not.
81
82
83       default-target none
84              This directive forces the backend to reject all those operations
85              that must resolve to a single target in case  none  or  multiple
86              targets  are  selected.  They include: add, delete, modify, mod‐
87              rdn; compare is not included, as well as  bind  since,  as  they
88              don't  alter  entries, in case of multiple matches an attempt is
89              made to perform the operation on any candidate target, with  the
90              constraint  that  at  most one must succeed.  This directive can
91              also be used when processing targets to mark a  specific  target
92              as default.
93
94
95       dncache-ttl {DISABLED|forever|<ttl>}
96              This  directive  sets  the  time-to-live  of the DN cache.  This
97              caches the target that holds a given DN to speed up  target  se‐
98              lection  in  case multiple targets would result from an uncached
99              search; forever means cache never expires; disabled means no  DN
100              caching;  otherwise a valid ( > 0 ) ttl is required, in the for‐
101              mat illustrated for the idle-timeout directive.
102
103
104       onerr {CONTINUE|report|stop}
105              This directive allows one to select the behavior in case an  er‐
106              ror  is  returned  by  one target during a search.  The default,
107              continue, consists in continuing the operation, trying to return
108              as  much  data  as  possible.   If the value is set to stop, the
109              search is terminated as soon as an error is returned by one tar‐
110              get,  and the error is immediately propagated to the client.  If
111              the value is set to report, the search is continued to  the  end
112              but,  in  case  at  least one target returned an error code, the
113              first non-success error code is returned.
114
115
116       norefs <NO|yes>
117              If yes, do not return search reference responses.   By  default,
118              they  are  returned unless request is LDAPv2.  If set before any
119              target specification, it affects all targets, unless  overridden
120              by any per-target directive.
121
122
123       noundeffilter <NO|yes>
124              If yes, return success instead of searching if a filter is unde‐
125              fined or contains undefined portions.  By default, the search is
126              propagated  after  replacing  undefined portions with (!(object‐
127              Class=*)), which corresponds to the empty result  set.   If  set
128              before  any target specification, it affects all targets, unless
129              overridden by any per-target directive.
130
131
132       protocol-version {0,2,3}
133              This directive indicates what protocol version must be  used  to
134              contact the remote server.  If set to 0 (the default), the proxy
135              uses the same protocol version used by the client, otherwise the
136              requested  protocol  is used.  The proxy returns unwillingToPer‐
137              form if an operation that is  incompatible  with  the  requested
138              protocol  is attempted.  If set before any target specification,
139              it affects all targets, unless overridden by any per-target  di‐
140              rective.
141
142
143       pseudoroot-bind-defer {YES|no}
144              This  directive,  when  set to yes, causes the authentication to
145              the remote servers with the pseudo-root identity  (the  identity
146              defined  in  each  idassert-bind directive) to be deferred until
147              actually needed by subsequent operations.  Otherwise, all  binds
148              as the rootdn are propagated to the targets.
149
150
151       quarantine <interval>,<num>[;<interval>,<num>[...]]
152              Turns  on  quarantine of URIs that returned LDAP_UNAVAILABLE, so
153              that an attempt to reconnect only occurs at given intervals  in‐
154              stead  of  any time a client requests an operation.  The pattern
155              is: retry only after at least  interval  seconds  elapsed  since
156              last  attempt, for exactly num times; then use the next pattern.
157              If num for the last pattern is "+", it retries  forever;  other‐
158              wise,  no more retries occur.  This directive must appear before
159              any target specification; it affects all targets with  the  same
160              pattern.
161
162
163       rebind-as-user {NO|yes}
164              If  this  option is given, the client's bind credentials are re‐
165              membered for rebinds, when trying to re-establish a broken  con‐
166              nection,  or  when chasing a referral, if chase-referrals is set
167              to yes.
168
169
170       session-tracking-request {NO|yes}
171              Adds session tracking control for all requests.  The client's IP
172              and  hostname,  and  the identity associated to each request, if
173              known, are sent to the remote server for informational purposes.
174              This  directive is incompatible with setting protocol-version to
175              2.  If set before any target specification, it affects all  tar‐
176              gets, unless overridden by any per-target directive.
177
178
179       single-conn {NO|yes}
180              Discards current cached connection when the client rebinds.
181
182
183       use-temporary-conn {NO|yes}
184              when  set to yes, create a temporary connection whenever compet‐
185              ing with other threads for a shared one; otherwise,  wait  until
186              the shared connection is available.
187
188

TARGET SPECIFICATION

190       Target specification starts with a "uri" directive:
191
192
193       uri <protocol>://[<host>]/<naming context> [...]
194              The  <protocol>  part can be anything ldap_initialize(3) accepts
195              ({ldap|ldaps|ldapi} and variants); the <host>  may  be  omitted,
196              defaulting to whatever is set in ldap.conf(5).  The <naming con‐
197              text> part is mandatory for the first URI, but it must be  omit‐
198              ted  for  subsequent ones, if any.  The naming context part must
199              be within the naming context defined for the backend, e.g.:
200
201              suffix "dc=foo,dc=com"
202              uri    "ldap://x.foo.com/dc=x,dc=foo,dc=com"
203
204              The <naming context> part doesn't need to be unique  across  the
205              targets; it may also match one of the values of the "suffix" di‐
206              rective.  Multiple URIs may be defined in a  single  URI  state‐
207              ment.   The  additional URIs must be separate arguments and must
208              not have any <naming context> part.  This causes the  underlying
209              library  to  contact the first server of the list that responds.
210              For example, if l1.foo.com and l2.foo.com  are  shadows  of  the
211              same server, the directive
212
213              suffix "dc=foo,dc=com"
214              uri    "ldap://l1.foo.com/dc=foo,dc=com" "ldap://l2.foo.com/"
215
216              causes  l2.foo.com  to be contacted whenever l1.foo.com does not
217              respond.  In that case, the URI list is  internally  rearranged,
218              by  moving  unavailable URIs to the end, so that further connec‐
219              tion attempts occur with respect to the last URI that succeeded.
220
221
222       acl-authcDN <administrative DN for access control purposes>
223              DN which is used to query the target server for acl checking, as
224              in  the  LDAP backend; it is supposed to have read access on the
225              target server to attributes used on the proxy for acl  checking.
226              There  is no risk of giving away such values; they are only used
227              to check permissions.  The acl-authcDN identity is by  no  means
228              implicitly  used  by  the  proxy when the client connects anony‐
229              mously.
230
231
232       acl-passwd <password>
233              Password used with the acl-authcDN above.
234
235
236       bind-timeout <microseconds>
237              This directive defines the timeout, in microseconds,  used  when
238              polling for response after an asynchronous bind connection.  The
239              initial call to ldap_result(3) is  performed  with  a  trade-off
240              timeout  of  100000  us;  if that results in a timeout exceeded,
241              subsequent calls use the value provided with bind-timeout.   The
242              default  value is used also for subsequent calls if bind-timeout
243              is not specified.  If set before any  target  specification,  it
244              affects  all targets, unless overridden by any per-target direc‐
245              tive.
246
247
248       chase-referrals {YES|no}
249              enable/disable automatic referral chasing, which is delegated to
250              the  underlying  libldap, with rebinding eventually performed if
251              the rebind-as-user directive is used.  The default is  to  chase
252              referrals.   If  set before any target specification, it affects
253              all targets, unless overridden by any per-target directive.
254
255
256       client-pr {accept-unsolicited|DISABLE|<size>}
257              This feature allows one to use RFC 2696  Paged  Results  control
258              when  performing search operations with a specific target, irre‐
259              spective of the client's request.  When set to a numeric  value,
260              Paged Results control is always used with size as the page size.
261              When set to accept-unsolicited, unsolicited Paged  Results  con‐
262              trol  responses  are accepted and honored for compatibility with
263              broken remote DSAs.  The client is not exposed to paged  results
264              handling  between  slapd-meta(5) and the remote servers.  By de‐
265              fault (disabled), Paged Results control  is  not  used  and  re‐
266              sponses  are  not accepted.  If set before any target specifica‐
267              tion, it affects all targets, unless overridden by any  per-tar‐
268              get directive.
269
270
271       default-target [<target>]
272              The  "default-target"  directive  can also be used during target
273              specification.  With no arguments it marks the current target as
274              the  default.   The optional number marks target <target> as the
275              default one, starting from 1.  Target <target> must be defined.
276
277
278       filter <pattern>
279              This directive allows specifying a regex(5) pattern to  indicate
280              what search filter terms are actually served by a target.
281
282              In  a  search  request, if the search filter matches the pattern
283              the target is considered while fulfilling the request; otherwise
284              the  target is ignored. There may be multiple occurrences of the
285              filter directive for each target.
286
287
288       idassert-authzFrom <authz-regexp>
289              if defined, selects what local identities are authorized to  ex‐
290              ploit the identity assertion feature.  The string <authz-regexp>
291              follows the rules defined  for  the  authzFrom  attribute.   See
292              slapd.conf(5),  section  related to authz-policy, for details on
293              the syntax of this field.
294
295
296       idassert-bind    bindmethod=none|simple|sasl    [binddn=<simple    DN>]
297              [credentials=<simple     password>]    [saslmech=<SASL    mech>]
298              [secprops=<properties>] [realm=<realm>] [authcId=<authentication
299              ID>]  [authzId=<authorization  ID>]  [authz={native|proxyauthz}]
300              [mode=<mode>]     [flags=<flags>]     [starttls=no|yes|critical]
301              [tls_cert=<file>]      [tls_key=<file>]      [tls_cacert=<file>]
302              [tls_cacertdir=<path>]      [tls_reqcert=never|allow|try|demand]
303              [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
304              [tls_ecname=<ciphers>]      [tls_protocol_min=<major>[.<minor>]]
305              [tls_crlcheck=none|peer|all]
306              Allows one to define the parameters of the authentication method
307              that is internally used by the proxy  to  authorize  connections
308              that are authenticated by other databases.  The identity defined
309              by this directive, according to the properties associated to the
310              authentication  method,  is  supposed to have auth access on the
311              target server to attributes used on the proxy for authentication
312              and  authorization,  and  to  be allowed to authorize the users.
313              This requires to have proxyAuthz privileges on  a  wide  set  of
314              DNs,  e.g.  authzTo=dn.subtree:"", and the remote server to have
315              authz-policy set to to or both.  See slapd.conf(5)  for  details
316              on  these  statements  and for remarks and drawbacks about their
317              usage.  The supported bindmethods are
318
319              none|simple|sasl
320
321              where none  is  the  default,  i.e.  no  identity  assertion  is
322              performed.
323
324              The authz parameter is used to instruct the SASL bind to exploit
325              native SASL authorization, if available; since  connections  are
326              cached,  this  should only be used when authorizing with a fixed
327              identity (e.g. by means of the authzDN or  authzID  parameters).
328              Otherwise,  the  default proxyauthz is used, i.e. the proxyAuthz
329              control (Proxied  Authorization,  RFC  4370)  is  added  to  all
330              operations.
331
332              The supported modes are:
333
334              <mode> := {legacy|anonymous|none|self}
335
336              If <mode> is not present, and authzId is given, the proxy always
337              authorizes that identity.  <authorization ID> can be
338
339              u:<user>
340
341              [dn:]<DN>
342
343              The former is supposed to  be  expanded  by  the  remote  server
344              according to the authz rules; see slapd.conf(5) for details.  In
345              the latter case, whether or not the dn: prefix is  present,  the
346              string must pass DN validation and normalization.
347
348              The  default  mode  is legacy, which implies that the proxy will
349              either perform a simple bind as the authcDN or a  SASL  bind  as
350              the  authcID  and  assert  the  client's identity when it is not
351              anonymous.  Direct binds are always proxied.   The  other  modes
352              imply that the proxy will always either perform a simple bind as
353              the authcDN or a SASL bind as the authcID, unless restricted  by
354              idassert-authzFrom   rules   (see  below),  in  which  case  the
355              operation will fail;  eventually,  it  will  assert  some  other
356              identity  according  to  <mode>.  Other identity assertion modes
357              are anonymous and self, which respectively mean that  the  empty
358              or  the  client's  identity  will be asserted; none, which means
359              that no proxyAuthz control will be used, so the authcDN  or  the
360              authcID  identity  will be asserted.  For all modes that require
361              the use of the proxyAuthz control,  on  the  remote  server  the
362              proxy identity must have appropriate authzTo permissions, or the
363              asserted identities must have appropriate authzFrom permissions.
364              Note,  however,  that  the ID assertion feature is mostly useful
365              when the asserted identities do not exist on the remote  server.
366              When  bindmethod  is  SASL,  the  authcDN  must  be specified in
367              addition to the authcID, although it  is  not  used  within  the
368              authentication process.
369
370              Flags can be
371
372              override,[non-]prescriptive,proxy-authz-[non-]critical
373
374              When  the  override flag is used, identity assertion takes place
375              even when the database is authorizing for the  identity  of  the
376              client,  i.e. after binding with the provided identity, and thus
377              authenticating it, the proxy  performs  the  identity  assertion
378              using the configured identity and authentication method.
379
380              When  the  prescriptive  flag  is used (the default), operations
381              fail with inappropriateAuthentication for those identities whose
382              assertion is not allowed by the idassert-authzFrom patterns.  If
383              the non-prescriptive flag  is  used,  operations  are  performed
384              anonymously  for those identities whose assertion is not allowed
385              by the idassert-authzFrom patterns.
386
387              When the proxy-authz-non-critical flag is  used  (the  default),
388              the  proxyAuthz  control is not marked as critical, in violation
389              of RFC 4370.  Use of proxy-authz-critical is recommended.
390
391              The TLS settings default to the  same  as  the  main  slapd  TLS
392              settings, except for tls_reqcert which defaults to "demand", and
393              tls_reqsan which defaults to "allow"..
394
395              The identity associated to  this  directive  is  also  used  for
396              privileged  operations  whenever  idassert-bind  is  defined and
397              acl-bind is not.  See acl-bind for details.
398
399
400       idle-timeout <time>
401              This directive causes a  cached  connection  to  be  dropped  an
402              recreated  after  it  has been idle for the specified time.  The
403              value can be specified as
404
405              [<d>d][<h>h][<m>m][<s>[s]]
406
407              where <d>, <h>, <m> and <s> are respectively  treated  as  days,
408              hours,   minutes   and   seconds.   If  set  before  any  target
409              specification, it affects all targets, unless overridden by  any
410              per-target directive.
411
412
413       keepalive <idle>:<probes>:<interval>
414              The  keepalive  parameter  sets  the values of idle, probes, and
415              interval used to check whether a socket is alive;  idle  is  the
416              number  of  seconds a connection needs to remain idle before TCP
417              starts sending keepalive probes; probes is the maximum number of
418              keepalive probes TCP should send before dropping the connection;
419              interval is interval in  seconds  between  individual  keepalive
420              probes.   Only  some  systems support the customization of these
421              values;  the  keepalive  parameter  is  ignored  otherwise,  and
422              system-wide settings are used.
423
424
425       tcp-user-timeout <milliseconds>
426              If  non-zero,  corresponds  to  the  TCP_USER_TIMEOUT set on the
427              target connections, overriding  the  operating  system  setting.
428              Only  some  systems support the customization of this parameter,
429              it is ignored otherwise and system-wide settings are used.
430
431
432       map {attribute|objectclass} [<local name>|*] {<foreign name>|*}
433              This maps object classes and attributes as in the LDAP  backend.
434              See slapd-ldap(5).
435
436
437       network-timeout <time>
438              Sets  the  network  timeout  value after which poll(2)/select(2)
439              following a connect(2) returns in  case  of  no  activity.   The
440              value   is   in   seconds,  and  it  can  be  specified  as  for
441              idle-timeout.   If  set  before  any  target  specification,  it
442              affects   all  targets,  unless  overridden  by  any  per-target
443              directive.
444
445
446       nretries {forever|never|<nretries>}
447              This directive defines how many times a bind should  be  retried
448              in case of temporary failure in contacting a target.  If defined
449              before any target specification, it applies to all  targets  (by
450              default,  3  times);  the  global  value  can  be  overridden by
451              redefinitions inside each target specification.
452
453
454       rewrite* ...
455              The rewrite options are described in the "REWRITING" section.
456
457
458       subtree-{exclude|include} <rule>
459              This directive allows one to indicate what subtrees are actually
460              served by a target.  The syntax of the supported rules is
461
462              <rule>: [dn[.<style>]:]<pattern>
463
464              <style>: subtree|children|regex
465
466              When <style> is either subtree or children the <pattern> is a DN
467              that must be within the naming context  served  by  the  target.
468              When  <style>  is regex the <pattern> is a regex(5) pattern.  If
469              the dn.<style>: prefix is  omitted,  dn.subtree:  is  implicitly
470              assumed for backward compatibility.
471
472              In  the  subtree-exclude form if the request DN matches at least
473              one rule, the target is  not  considered  while  fulfilling  the
474              request;  otherwise, the target is considered based on the value
475              of the request DN.  When the request is a search, also the scope
476              is considered.
477
478              In  the  subtree-include form if the request DN matches at least
479              one rule, the target is considered while fulfilling the request;
480              otherwise the target is ignored.
481
482
483                  |  match  | exclude |
484                  +---------+---------+-------------------+
485                  |    T    |    T    | not candidate     |
486                  |    F    |    T    | continue checking |
487                  +---------+---------+-------------------+
488                  |    T    |    F    | candidate         |
489                  |    F    |    F    | not candidate     |
490                  +---------+---------+-------------------+
491
492              There  may  be  multiple  occurrences  of the subtree-exclude or
493              subtree-include directive for each of the targets, but they  are
494              mutually exclusive.
495
496
497       suffixmassage <virtual naming context> <real naming context>
498              All  the directives starting with "rewrite" refer to the rewrite
499              engine that  has  been  added  to  slapd.   The  "suffixmassage"
500              directive  was  introduced  in  the LDAP backend to allow suffix
501              massaging  while  proxying.   It  has  been  obsoleted  by   the
502              rewriting  tools.   However, both for backward compatibility and
503              for  ease  of  configuration  when  simple  suffix  massage   is
504              required,  it  has been preserved.  It wraps the basic rewriting
505              instructions that perform suffix massaging.  See the "REWRITING"
506              section for a detailed list of the rewrite rules it implies.
507
508
509       t-f-support {NO|yes|discover}
510              enable  if  the remote server supports absolute filters (see RFC
511              4526 for details).  If set to discover, support is  detected  by
512              reading  the remote server's root DSE.  If set before any target
513              specification, it affects all targets, unless overridden by  any
514              per-target directive.
515
516
517       timeout [<op>=]<val> [...]
518              This   directive  allows  one  to  set  per-operation  timeouts.
519              Operations can be
520
521              <op> ::= bind, add, delete, modrdn, modify, compare, search
522
523              The overall duration  of  the  search  operation  is  controlled
524              either  by  the  timelimit  parameter or by server-side enforced
525              time limits (see  timelimit  and  limits  in  slapd.conf(5)  for
526              details).   This  timeout parameter controls how long the target
527              can be irresponsive before the operation is aborted.  Timeout is
528              meaningless  for  the  remaining operations, unbind and abandon,
529              which do not imply any response, while it is not yet implemented
530              in  currently supported extended operations.  If no operation is
531              specified, the timeout val affects all supported operations.  If
532              specified  before  any target definition, it affects all targets
533              unless overridden by per-target directives.
534
535              Note: if the timeout is exceeded,  the  operation  is  cancelled
536              (according  to  the  cancel  directive);  the  protocol does not
537              provide any means to rollback operations, so the client will not
538              be  notified  about  the  result  of  the  operation,  which may
539              eventually succeeded or not.  In case the  timeout  is  exceeded
540              during  a bind operation, the connection is destroyed, according
541              to RFC4511.
542
543
544       tls {none|[try-]start|[try-]propagate|ldaps}
545              [starttls=no]         [tls_cert=<file>]         [tls_key=<file>]
546              [tls_cacert=<file>]                       [tls_cacertdir=<path>]
547              [tls_reqcert=never|allow|try|demand]
548              [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
549              [tls_ecname=<names>] [tls_crlcheck=none|peer|all]
550              Specify TLS settings regular connections.
551
552              If the first parameter is not "none" then  this  configures  the
553              TLS  settings  to be used for regular connections.  The StartTLS
554              extended operation will be used when establishing the connection
555              unless  the  URI directive protocol scheme is ldaps://.  In that
556              case this keyword may only be set to "ldaps"  and  the  StartTLS
557              operation will not be used.
558
559              With  propagate, the proxy issues the StartTLS operation only if
560              the original connection has a TLS layer set up.  The try- prefix
561              instructs  the  proxy  to  continue  operations  if the StartTLS
562              operation failed; its use is not recommended.
563
564              The TLS settings default to the  same  as  the  main  slapd  TLS
565              settings,  except  for  tls_reqcert  which defaults to "demand",
566              tls_reqsan which defaults to  "allow",  and  starttls  which  is
567              overshadowed by the first keyword and thus ignored.
568
569              If  set before any target specification, it affects all targets,
570              unless overridden by any per-target directive.
571
572

SCENARIOS

574       A powerful (and in some sense dangerous) rewrite engine has been  added
575       to  both the LDAP and Meta backends.  While the former can gain limited
576       beneficial effects from rewriting  stuff,  the  latter  can  become  an
577       amazingly powerful tool.
578
579       Consider a couple of scenarios first.
580
581       1)  Two  directory  servers  share  two  levels  of naming context; say
582       "dc=a,dc=foo,dc=com" and "dc=b,dc=foo,dc=com".   Then,  an  unambiguous
583       Meta database can be configured as:
584
585              database meta
586              suffix   "dc=foo,dc=com"
587              uri      "ldap://a.foo.com/dc=a,dc=foo,dc=com"
588              uri      "ldap://b.foo.com/dc=b,dc=foo,dc=com"
589
590       Operations directed to a specific target can be easily resolved because
591       there are no ambiguities.  The  only  operation  that  may  resolve  to
592       multiple  targets  is  a  search with base "dc=foo,dc=com" and scope at
593       least "one", which results in spawning two searches to the targets.
594
595       2a) Two directory servers don't share any portion  of  naming  context,
596       but  they'd  present  as a single DIT [Caveat: uniqueness of (massaged)
597       entries among the two servers is  assumed;  integrity  checks  risk  to
598       incur  in  excessive  overhead  and have not been implemented].  Say we
599       have "dc=bar,dc=org" and "o=Foo,c=US", and we'd like them to appear  as
600       branches    of    "dc=foo,dc=com",    say    "dc=a,dc=foo,dc=com"   and
601       "dc=b,dc=foo,dc=com".  Then we need to configure our Meta backend as:
602
603              database      meta
604              suffix        "dc=foo,dc=com"
605
606              uri           "ldap://a.bar.com/dc=a,dc=foo,dc=com"
607              suffixmassage "dc=a,dc=foo,dc=com" "dc=bar,dc=org"
608
609              uri           "ldap://b.foo.com/dc=b,dc=foo,dc=com"
610              suffixmassage "dc=b,dc=foo,dc=com" "o=Foo,c=US"
611
612       Again, operations can be  resolved  without  ambiguity,  although  some
613       rewriting  is required.  Notice that the virtual naming context of each
614       target is a branch of the database's naming context;  it  is  rewritten
615       back  and  forth  when  operations  are  performed  towards  the target
616       servers.  What "back and forth" means will be clarified later.
617
618       When a search with base "dc=foo,dc=com" is attempted, if the  scope  is
619       "base"  it fails with "no such object"; in fact, the common root of the
620       two targets (prior to massaging) does  not  exist.   If  the  scope  is
621       "one",  both  targets  are  contacted  with  the  base replaced by each
622       target's base; the scope is derated to "base".   In  general,  a  scope
623       "one"  search  is  honored,  and  the  scope  is derated, only when the
624       incoming base is at most one level lower of a target's  naming  context
625       (prior to massaging).
626
627       Finally,  if  the  scope is "sub" the incoming base is replaced by each
628       target's unmassaged naming context, and the scope is not altered.
629
630       2b) Consider the above reported scenario with the two  servers  sharing
631       the same naming context:
632
633              database      meta
634              suffix        "dc=foo,dc=com"
635
636              uri           "ldap://a.bar.com/dc=foo,dc=com"
637              suffixmassage "dc=foo,dc=com" "dc=bar,dc=org"
638
639              uri           "ldap://b.foo.com/dc=foo,dc=com"
640              suffixmassage "dc=foo,dc=com" "o=Foo,c=US"
641
642       All  the  previous considerations hold, except that now there is no way
643       to unambiguously resolve a DN.  In this case, all the  operations  that
644       require  an  unambiguous  target  selection  will fail unless the DN is
645       already  cached  or  a  default  target  has   been   set.    Practical
646       configurations may result as a combination of all the above scenarios.
647

ACLs

649       Note  on  ACLs:  at present you may add whatever ACL rule you desire to
650       the Meta (and LDAP) backends.  However, the meaning  of  an  ACL  on  a
651       proxy  may  require  some  considerations.   Two  philosophies  may  be
652       considered:
653
654       a) the remote server dictates the permissions; the proxy simply  passes
655       back what it gets from the remote server.
656
657       b) the remote server unveils "everything"; the proxy is responsible for
658       protecting data from unauthorized access.
659
660       Of course the latter  sounds  unreasonable,  but  it  is  not.   It  is
661       possible  to  imagine  scenarios  in which a remote host discloses data
662       that can be considered "public" inside an intranet, and  a  proxy  that
663       connects it to the internet may impose additional constraints.  To this
664       purpose, the proxy should be able to comply with all the  ACL  matching
665       criteria  that the server supports.  This has been achieved with regard
666       to all the criteria supported by slapd except  a  special  subtle  case
667       (please   file   an   ITS   if   you   can   find   other   exceptions:
668       <http://www.openldap.org/its/>).  The rule
669
670              access to dn="<dn>" attrs=<attr>
671                     by dnattr=<dnattr> read
672                     by * none
673
674       cannot be matched iff the attribute that is being requested, <attr>, is
675       NOT  <dnattr>,  and the attribute that determines membership, <dnattr>,
676       has not been requested (e.g. in a search)
677
678       In fact this ACL is resolved by slapd using the  portion  of  entry  it
679       retrieved   from  the  remote  server  without  requiring  any  further
680       intervention of the backend, so, if the <dnattr> attribute has not been
681       fetched,  the  match  cannot  be  assessed because the attribute is not
682       present, not because no value matches the requirement!
683
684       Note on ACLs and attribute mapping: ACLs  are  applied  to  the  mapped
685       attributes;  for  instance,  if the attribute locally known as "foo" is
686       mapped to "bar" on a remote server, then local ACLs apply to  attribute
687       "foo"  and  are  totally unaware of its remote name.  The remote server
688       will check permissions for "bar", and the local  server  will  possibly
689       enforce additional restrictions to "foo".
690

REWRITING

692       A  string  is  rewritten according to a set of rules, called a `rewrite
693       context'.   The  rules  are  based  on  POSIX  (''extended'')   regular
694       expressions   (regex)   with   substring   matching;   basic   variable
695       substitution and map resolution of substrings is  allowed  by  specific
696       mechanisms   detailed  in  the  following.   The  behavior  of  pattern
697       matching/substitution can be altered by a set of flags.
698
699       The underlying concept is to build a lightweight rewrite module for the
700       slapd server (initially dedicated to the LDAP backend).
701

Passes

703       An  incoming  string is matched against a set of rules.  Rules are made
704       of a regex match pattern, a substitution pattern and a set of  actions,
705       described  by  a  set of flags.  In case of match a string rewriting is
706       performed according to the substitution  pattern  that  allows  one  to
707       refer  to  substrings  matched in the incoming string.  The actions, if
708       any, are  finally  performed.   The  substitution  pattern  allows  map
709       resolution  of  substrings.   A  map  is  a  generic object that maps a
710       substitution pattern to a value.  The flags  are  divided  in  "Pattern
711       matching  Flags"  and  "Action Flags"; the former alter the regex match
712       pattern behavior while the latter alter the action that is taken  after
713       substitution.
714

Pattern Matching Flags

716       `C'    honors case in matching (default is case insensitive)
717
718       `R'    use    POSIX   ''basic''   regular   expressions   (default   is
719              ''extended'')
720
721       `M{n}' allow no more than n recursive passes for a specific rule;  does
722              not  alter the max total count of passes, so it can only enforce
723              a stricter limit for a specific rule.
724

Action Flags

726       `:'    apply the rule once only (default is recursive)
727
728       `@'    stop applying rules in case of match; the current rule is  still
729              applied  recursively; combine with `:' to apply the current rule
730              only once and then stop.
731
732       `#'    stop current  operation  if  the  rule  matches,  and  issue  an
733              `unwilling to perform' error.
734
735       `G{n}' jump  n  rules  back  and  forth  (watch for loops!).  Note that
736              `G{1}' is implicit in every rule.
737
738       `I'    ignores errors in rule; this  means,  in  case  of  error,  e.g.
739              issued  by  a  map, the error is treated as a missed match.  The
740              `unwilling to perform' is not overridden.
741
742       `U{n}' uses n as return code if the rule matches;  the  flag  does  not
743              alter  the  recursive  behavior  of  the  rule,  so,  to have it
744              performed only once, it must be used in  combination  with  `:',
745              e.g.    `:U{16}'  returns  the  value  `16'  after  exactly  one
746              execution  of  the  rule,  if  the  pattern   matches.    As   a
747              consequence,  its behavior is equivalent to `@', with the return
748              code set to n; or, in other words, `@' is equivalent to  `U{0}'.
749              By convention, the freely available codes are above 16 included;
750              the others are reserved.
751
752       The ordering of the flags can be significant.   For  instance:  `IG{2}'
753       means  ignore errors and jump two lines ahead both in case of match and
754       in case of error, while `G{2}I' means ignore errors, but jump two lines
755       ahead only in case of match.
756
757       More flags (mainly Action Flags) will be added as needed.
758

Pattern matching:

760       See regex(7) and/or re_format(7).
761

Substitution Pattern Syntax:

763       Everything starting with `%' requires substitution;
764
765       the only obvious exception is `%%', which is left as is;
766
767       the basic substitution is `%d', where `d' is a digit; 0 means the whole
768       string, while 1-9 is a submatch;
769
770       a `%' followed by a `{' invokes an advanced substitution.  The  pattern
771       is:
772
773              `%' `{' [ <op> ] <name> `(' <substitution> `)' `}'
774
775       where <name> must be a legal name for the map, i.e.
776
777              <name> ::= [a-z][a-z0-9]* (case insensitive)
778              <op> ::= `>' `|' `&' `&&' `*' `**' `$'
779
780       and <substitution> must be a legal substitution pattern, with no limits
781       on the nesting level.
782
783       The operators are:
784
785       >      sub context invocation; <name> must be a legal, already  defined
786              rewrite context name
787
788       |      external  command  invocation;  <name>  must  refer  to a legal,
789              already defined command name (NOT IMPL.)
790
791       &      variable assignment; <name> defines a variable  in  the  running
792              operation  structure which can be dereferenced later; operator &
793              assigns a variable in the rewrite  context  scope;  operator  &&
794              assigns  a  variable  that  scopes  the entire session, e.g. its
795              value can be dereferenced later by other rewrite contexts
796
797       *      variable dereferencing; <name> must refer to a variable that  is
798              defined  and  assigned  for  the  running  operation; operator *
799              dereferences a variable scoping the rewrite context; operator **
800              dereferences  a  variable  scoping  the  whole session, e.g. the
801              value is passed across rewrite contexts
802
803       $      parameter  dereferencing;  <name>  must  refer  to  an  existing
804              parameter;  the  idea is to make some run-time parameters set by
805              the system available to the rewrite engine, as the  client  host
806              name,  the  bind  DN  if any, constant parameters initialized at
807              config time, and so on; no parameter is currently set by  either
808              back-ldap  or  back-meta, but constant parameters can be defined
809              in the configuration file by using the rewriteParam directive.
810
811       Substitution escaping has been delegated to the `%'  symbol,  which  is
812       used  instead  of  `\'  in  string substitution patterns because `\' is
813       already  escaped  by  slapd's  low  level  parsing   routines;   as   a
814       consequence,   regex   escaping   requires   two   `\'   symbols,  e.g.
815       `.*\.foo\.bar' must be written as `.*\\.foo\\.bar'.
816

Rewrite context:

818       A rewrite context is a set of rules which are applied in sequence.  The
819       basic idea is to have an application initialize a rewrite engine (think
820       of Apache's mod_rewrite ...) with  a  set  of  rewrite  contexts;  when
821       string  rewriting  is  required,  one  invokes  the appropriate rewrite
822       context with the input string and obtains the newly rewritten one if no
823       errors occur.
824
825       Each  basic  server  operation is associated to a rewrite context; they
826       are divided in two main groups: client -> server and server  ->  client
827       rewriting.
828
829       client -> server:
830
831              (default)            if defined and no specific context
832                                   is available
833              bindDN               bind
834              searchBase           search
835              searchFilter         search
836              searchFilterAttrDN   search
837              compareDN            compare
838              compareAttrDN        compare AVA
839              addDN                add
840              addAttrDN            add AVA
841              modifyDN             modify
842              modifyAttrDN         modify AVA
843              modrDN               modrdn
844              newSuperiorDN        modrdn
845              deleteDN             delete
846              exopPasswdDN         password modify extended operation DN if proxy
847
848       server -> client:
849
850              searchResult         search (only if defined; no default;
851                                   acts on DN and DN-syntax attributes
852                                   of search results)
853              searchAttrDN         search AVA
854              matchedDN            all ops (only if applicable)
855

Basic configuration syntax

857       rewriteEngine { on | off }
858              If  `on',  the  requested  rewriting  is performed; if `off', no
859              rewriting takes place (an easy way  to  stop  rewriting  without
860              altering too much the configuration file).
861
862       rewriteContext <context name> [ alias <aliased context name> ]
863              <Context name> is the name that identifies the context, i.e. the
864              name used by the application to refer to the  set  of  rules  it
865              contains.   It  is used also to reference sub contexts in string
866              rewriting.  A context may alias another one.  In this  case  the
867              alias  context  contains  no  rule, and any reference to it will
868              result in accessing the aliased one.
869
870       rewriteRule <regex match pattern> <substitution pattern> [ <flags> ]
871              Determines how a  string  can  be  rewritten  if  a  pattern  is
872              matched.  Examples are reported below.
873

Additional configuration syntax:

875       rewriteMap <map type> <map name> [ <map attrs> ]
876              Allows  one  to define a map that transforms substring rewriting
877              into  something  else.   The  map  is  referenced   inside   the
878              substitution pattern of a rule.
879
880       rewriteParam <param name> <param value>
881              Sets  a value with global scope, that can be dereferenced by the
882              command `%{$paramName}'.
883
884       rewriteMaxPasses <number of passes> [<number of passes per rule>]
885              Sets the maximum number of total rewriting passes  that  can  be
886              performed  in  a  single  rewrite operation (to avoid loops).  A
887              safe default is set to 100; note that  reaching  this  limit  is
888              still  treated  as  a  success; recursive invocation of rules is
889              simply  interrupted.   The  count  applies  to   the   rewriting
890              operation  as  a whole, not to any single rule; an optional per-
891              rule limit can be set.  This  limit  is  overridden  by  setting
892              specific per-rule limits with the `M{n}' flag.
893

Configuration examples:

895       # set to `off' to disable rewriting
896       rewriteEngine on
897
898       # the rules the "suffixmassage" directive implies
899       rewriteEngine on
900       # all dataflow from client to server referring to DNs
901       rewriteContext default
902       rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
903       # empty filter rule
904       rewriteContext searchFilter
905       # all dataflow from server to client
906       rewriteContext searchResult
907       rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
908       rewriteContext searchAttrDN alias searchResult
909       rewriteContext matchedDN alias searchResult
910
911       # Everything defined here goes into the `default' context.
912       # This rule changes the naming context of anything sent
913       # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
914
915       rewriteRule "(.*)dc=home,[ ]?dc=net"
916                   "%1dc=OpenLDAP, dc=org"  ":"
917
918       # since a pretty/normalized DN does not include spaces
919       # after rdn separators, e.g. `,', this rule suffices:
920
921       rewriteRule "(.*)dc=home,dc=net"
922                   "%1dc=OpenLDAP,dc=org"  ":"
923
924       # Start a new context (ends input of the previous one).
925       # This rule adds blanks between DN parts if not present.
926       rewriteContext  addBlanks
927       rewriteRule     "(.*),([^ ].*)" "%1, %2"
928
929       # This one eats blanks
930       rewriteContext  eatBlanks
931       rewriteRule     "(.*),[ ](.*)" "%1,%2"
932
933       # Here control goes back to the default rewrite
934       # context; rules are appended to the existing ones.
935       # anything that gets here is piped into rule `addBlanks'
936       rewriteContext  default
937       rewriteRule     ".*" "%{>addBlanks(%0)}" ":"
938
939       # Rewrite the search base according to `default' rules.
940       rewriteContext  searchBase alias default
941
942       # Search results with OpenLDAP DN are rewritten back with
943       # `dc=home,dc=net' naming context, with spaces eaten.
944       rewriteContext  searchResult
945       rewriteRule     "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
946                       "%{>eatBlanks(%1)}dc=home,dc=net"    ":"
947
948       # Bind with email instead of full DN: we first need
949       # an ldap map that turns attributes into a DN (the
950       # argument used when invoking the map is appended to
951       # the URI and acts as the filter portion)
952       rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
953
954       # Then we need to detect DN made up of a single email,
955       # e.g. `mail=someone@example.com'; note that the rule
956       # in case of match stops rewriting; in case of error,
957       # it is ignored.  In case we are mapping virtual
958       # to real naming contexts, we also need to rewrite
959       # regular DNs, because the definition of a bindDn
960       # rewrite context overrides the default definition.
961       rewriteContext bindDN
962       rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I"
963
964       # This is a rather sophisticated example. It massages a
965       # search filter in case who performs the search has
966       # administrative privileges.  First we need to keep
967       # track of the bind DN of the incoming request, which is
968       # stored in a variable called `binddn' with session scope,
969       # and left in place to allow regular binding:
970       rewriteContext  bindDN
971       rewriteRule     ".+" "%{&&binddn(%0)}%0" ":"
972
973       # A search filter containing `uid=' is rewritten only
974       # if an appropriate DN is bound.
975       # To do this, in the first rule the bound DN is
976       # dereferenced, while the filter is decomposed in a
977       # prefix, in the value of the `uid=<arg>' AVA, and
978       # in a suffix. A tag `<>' is appended to the DN.
979       # If the DN refers to an entry in the `ou=admin' subtree,
980       # the filter is rewritten OR-ing the `uid=<arg>' with
981       # `cn=<arg>'; otherwise it is left as is. This could be
982       # useful, for instance, to allow apache's auth_ldap-1.4
983       # module to authenticate users with both `uid' and
984       # `cn', but only if the request comes from a possible
985       # `cn=Web auth,ou=admin,dc=home,dc=net' user.
986       rewriteContext searchFilter
987       rewriteRule "(.*\\()uid=([a-z0-9_]+)(\\).*)"
988         "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}"
989         ":I"
990       rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
991         "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I"
992       rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"
993
994       # This example shows how to strip unwanted DN-valued
995       # attribute values from a search result; the first rule
996       # matches DN values below "ou=People,dc=example,dc=com";
997       # in case of match the rewriting exits successfully.
998       # The second rule matches everything else and causes
999       # the value to be rejected.
1000       rewriteContext searchResult
1001       rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@"
1002       rewriteRule ".*" "" "#"
1003

LDAP Proxy resolution (a possible evolution of slapd-ldap(5)):

1005       In  case  the  rewritten  DN is an LDAP URI, the operation is initiated
1006       towards the host[:port] indicated in the uri, if it does not  refer  to
1007       the local server.  E.g.:
1008
1009         rewriteRule '^cn=root,.*' '%0'                     'G{3}'
1010         rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@'
1011         rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@'
1012         rewriteRule '.*'          'ldap://ldap3.my.org/%0' ':@'
1013
1014       (Rule  1 is simply there to illustrate the `G{n}' action; it could have
1015       been written:
1016
1017         rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@'
1018
1019       with the advantage of saving one rewrite pass ...)
1020
1021

ACCESS CONTROL

1023       The meta backend does not honor  all  ACL  semantics  as  described  in
1024       slapd.access(5).   In  general,  access  checking  is  delegated to the
1025       remote server(s).  Only read (=r) access to the entry  pseudo-attribute
1026       and to the other attribute values of the entries returned by the search
1027       operation is honored, which is performed by the frontend.
1028
1029

PROXY CACHE OVERLAY

1031       The  proxy  cache  overlay  allows  caching  of  LDAP  search  requests
1032       (queries) in a local database.  See slapo-pcache(5) for details.
1033
1034

DEPRECATED STATEMENTS

1036       The  following  statements have been deprecated and should no longer be
1037       used.
1038
1039
1040       pseudorootdn <substitute DN in case of rootdn bind>
1041              Use idassert-bind instead.
1042
1043
1044       pseudorootpw <substitute password in case of rootdn bind>
1045              Use idassert-bind instead.
1046
1047
1048
1049

FILES

1051       /etc/openldap/slapd.conf
1052              default slapd configuration file
1053

SEE ALSO

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

AUTHOR

1059       Pierangelo Masarati, based on back-ldap by Howard Chu
1060
1061
1062
1063OpenLDAP 2.6.2                    2022/05/04                     SLAPD-META(5)
Impressum