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

TARGET SPECIFICATION

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

SCENARIOS

526       A  powerful (and in some sense dangerous) rewrite engine has been added
527       to both the LDAP and Meta backends.  While the former can gain  limited
528       beneficial  effects  from  rewriting  stuff,  the  latter can become an
529       amazingly powerful tool.
530
531       Consider a couple of scenarios first.
532
533       1) Two directory servers  share  two  levels  of  naming  context;  say
534       "dc=a,dc=foo,dc=com"  and  "dc=b,dc=foo,dc=com".   Then, an unambiguous
535       Meta database can be configured as:
536
537              database meta
538              suffix   "dc=foo,dc=com"
539              uri      "ldap://a.foo.com/dc=a,dc=foo,dc=com"
540              uri      "ldap://b.foo.com/dc=b,dc=foo,dc=com"
541
542       Operations directed to a specific target can be easily resolved because
543       there  are  no  ambiguities.   The  only  operation that may resolve to
544       multiple targets is a search with base  "dc=foo,dc=com"  and  scope  at
545       least "one", which results in spawning two searches to the targets.
546
547       2a)  Two  directory  servers don't share any portion of naming context,
548       but they'd present as a single DIT [Caveat:  uniqueness  of  (massaged)
549       entries  among  the  two  servers  is assumed; integrity checks risk to
550       incur in excessive overhead and have not  been  implemented].   Say  we
551       have  "dc=bar,dc=org" and "o=Foo,c=US", and we'd like them to appear as
552       branches   of    "dc=foo,dc=com",    say    "dc=a,dc=foo,dc=com"    and
553       "dc=b,dc=foo,dc=com".  Then we need to configure our Meta backend as:
554
555              database      meta
556              suffix        "dc=foo,dc=com"
557
558              uri           "ldap://a.bar.com/dc=a,dc=foo,dc=com"
559              suffixmassage "dc=a,dc=foo,dc=com" "dc=bar,dc=org"
560
561              uri           "ldap://b.foo.com/dc=b,dc=foo,dc=com"
562              suffixmassage "dc=b,dc=foo,dc=com" "o=Foo,c=US"
563
564       Again,  operations  can  be  resolved  without ambiguity, although some
565       rewriting is required.  Notice that the virtual naming context of  each
566       target  is  a  branch of the database's naming context; it is rewritten
567       back and  forth  when  operations  are  performed  towards  the  target
568       servers.  What "back and forth" means will be clarified later.
569
570       When  a  search with base "dc=foo,dc=com" is attempted, if the scope is
571       "base" it fails with "no such object"; in fact, the common root of  the
572       two  targets  (prior  to  massaging)  does  not exist.  If the scope is
573       "one", both targets are  contacted  with  the  base  replaced  by  each
574       target's  base;  the  scope  is derated to "base".  In general, a scope
575       "one" search is honored, and  the  scope  is  derated,  only  when  the
576       incoming  base  is at most one level lower of a target's naming context
577       (prior to massaging).
578
579       Finally, if the scope is "sub" the incoming base is  replaced  by  each
580       target's unmassaged naming context, and the scope is not altered.
581
582       2b)  Consider  the above reported scenario with the two servers sharing
583       the same naming context:
584
585              database      meta
586              suffix        "dc=foo,dc=com"
587
588              uri           "ldap://a.bar.com/dc=foo,dc=com"
589              suffixmassage "dc=foo,dc=com" "dc=bar,dc=org"
590
591              uri           "ldap://b.foo.com/dc=foo,dc=com"
592              suffixmassage "dc=foo,dc=com" "o=Foo,c=US"
593
594       All the previous considerations hold, except that now there is  no  way
595       to  unambiguously  resolve a DN.  In this case, all the operations that
596       require an unambiguous target selection will  fail  unless  the  DN  is
597       already   cached   or   a  default  target  has  been  set.   Practical
598       configurations may result as a combination of all the above scenarios.
599

ACLs

601       Note on ACLs: at present you may add whatever ACL rule  you  desire  to
602       the  Meta  (and  LDAP)  backends.   However, the meaning of an ACL on a
603       proxy  may  require  some  considerations.   Two  philosophies  may  be
604       considered:
605
606       a)  the remote server dictates the permissions; the proxy simply passes
607       back what it gets from the remote server.
608
609       b) the remote server unveils "everything"; the proxy is responsible for
610       protecting data from unauthorized access.
611
612       Of  course  the  latter  sounds  unreasonable,  but  it  is not.  It is
613       possible to imagine scenarios in which a  remote  host  discloses  data
614       that  can  be  considered "public" inside an intranet, and a proxy that
615       connects it to the internet may impose additional constraints.  To this
616       purpose,  the  proxy should be able to comply with all the ACL matching
617       criteria that the server supports.  This has been achieved with  regard
618       to  all  the  criteria  supported by slapd except a special subtle case
619       (please   file   an   ITS   if   you   can   find   other   exceptions:
620       <http://www.openldap.org/its/>).  The rule
621
622              access to dn="<dn>" attrs=<attr>
623                     by dnattr=<dnattr> read
624                     by * none
625
626       cannot be matched iff the attribute that is being requested, <attr>, is
627       NOT <dnattr>, and the attribute that determines  membership,  <dnattr>,
628       has not been requested (e.g. in a search)
629
630       In  fact  this  ACL  is resolved by slapd using the portion of entry it
631       retrieved  from  the  remote  server  without  requiring  any   further
632       intervention of the backend, so, if the <dnattr> attribute has not been
633       fetched, the match cannot be assessed  because  the  attribute  is  not
634       present, not because no value matches the requirement!
635
636       Note  on  ACLs  and  attribute  mapping: ACLs are applied to the mapped
637       attributes; for instance, if the attribute locally known  as  "foo"  is
638       mapped  to "bar" on a remote server, then local ACLs apply to attribute
639       "foo" and are totally unaware of its remote name.   The  remote  server
640       will  check  permissions  for "bar", and the local server will possibly
641       enforce additional restrictions to "foo".
642

REWRITING

644       A string is rewritten according to a set of rules,  called  a  `rewrite
645       context'.    The  rules  are  based  on  POSIX  (''extended'')  regular
646       expressions   (regex)   with   substring   matching;   basic   variable
647       substitution  and  map  resolution of substrings is allowed by specific
648       mechanisms  detailed  in  the  following.   The  behavior  of   pattern
649       matching/substitution can be altered by a set of flags.
650
651       The underlying concept is to build a lightweight rewrite module for the
652       slapd server (initially dedicated to the LDAP backend).
653

Passes

655       An incoming string is matched against a set of rules.  Rules  are  made
656       of  a regex match pattern, a substitution pattern and a set of actions,
657       described by a set of flags.  In case of match a  string  rewriting  is
658       performed  according  to  the  substitution  pattern that allows one to
659       refer to substrings matched in the incoming string.   The  actions,  if
660       any,  are  finally  performed.   The  substitution  pattern  allows map
661       resolution of substrings.  A map  is  a  generic  object  that  maps  a
662       substitution  pattern  to  a  value.  The flags are divided in "Pattern
663       matching Flags" and "Action Flags"; the former alter  the  regex  match
664       pattern  behavior while the latter alter the action that is taken after
665       substitution.
666

Pattern Matching Flags

668       `C'    honors case in matching (default is case insensitive)
669
670       `R'    use   POSIX   ''basic''   regular   expressions   (default    is
671              ''extended'')
672
673       `M{n}' allow  no more than n recursive passes for a specific rule; does
674              not alter the max total count of passes, so it can only  enforce
675              a stricter limit for a specific rule.
676

Action Flags

678       `:'    apply the rule once only (default is recursive)
679
680       `@'    stop  applying rules in case of match; the current rule is still
681              applied recursively; combine with `:' to apply the current  rule
682              only once and then stop.
683
684       `#'    stop  current  operation  if  the  rule  matches,  and  issue an
685              `unwilling to perform' error.
686
687       `G{n}' jump n rules back and  forth  (watch  for  loops!).   Note  that
688              `G{1}' is implicit in every rule.
689
690       `I'    ignores  errors  in  rule;  this  means,  in case of error, e.g.
691              issued by a map, the error is treated as a  missed  match.   The
692              `unwilling to perform' is not overridden.
693
694       `U{n}' uses  n  as  return  code if the rule matches; the flag does not
695              alter the recursive  behavior  of  the  rule,  so,  to  have  it
696              performed  only  once,  it must be used in combination with `:',
697              e.g.   `:U{16}'  returns  the  value  `16'  after  exactly   one
698              execution   of   the   rule,  if  the  pattern  matches.   As  a
699              consequence, its behavior is equivalent to `@', with the  return
700              code  set to n; or, in other words, `@' is equivalent to `U{0}'.
701              By convention, the freely available codes are above 16 included;
702              the others are reserved.
703
704       The  ordering  of  the flags can be significant.  For instance: `IG{2}'
705       means ignore errors and jump two lines ahead both in case of match  and
706       in case of error, while `G{2}I' means ignore errors, but jump two lines
707       ahead only in case of match.
708
709       More flags (mainly Action Flags) will be added as needed.
710

Pattern matching:

712       See regex(7) and/or re_format(7).
713

Substitution Pattern Syntax:

715       Everything starting with `%' requires substitution;
716
717       the only obvious exception is `%%', which is left as is;
718
719       the basic substitution is `%d', where `d' is a digit; 0 means the whole
720       string, while 1-9 is a submatch;
721
722       a  `%' followed by a `{' invokes an advanced substitution.  The pattern
723       is:
724
725              `%' `{' [ <op> ] <name> `(' <substitution> `)' `}'
726
727       where <name> must be a legal name for the map, i.e.
728
729              <name> ::= [a-z][a-z0-9]* (case insensitive)
730              <op> ::= `>' `|' `&' `&&' `*' `**' `$'
731
732       and <substitution> must be a legal substitution pattern, with no limits
733       on the nesting level.
734
735       The operators are:
736
737       >      sub  context invocation; <name> must be a legal, already defined
738              rewrite context name
739
740       |      external command invocation;  <name>  must  refer  to  a  legal,
741              already defined command name (NOT IMPL.)
742
743       &      variable  assignment;  <name>  defines a variable in the running
744              operation structure which can be dereferenced later; operator  &
745              assigns  a  variable  in  the rewrite context scope; operator &&
746              assigns a variable that scopes  the  entire  session,  e.g.  its
747              value can be dereferenced later by other rewrite contexts
748
749       *      variable  dereferencing; <name> must refer to a variable that is
750              defined and assigned  for  the  running  operation;  operator  *
751              dereferences a variable scoping the rewrite context; operator **
752              dereferences a variable scoping  the  whole  session,  e.g.  the
753              value is passed across rewrite contexts
754
755       $      parameter  dereferencing;  <name>  must  refer  to  an  existing
756              parameter; the idea is to make some run-time parameters  set  by
757              the  system  available to the rewrite engine, as the client host
758              name, the bind DN if any,  constant  parameters  initialized  at
759              config  time, and so on; no parameter is currently set by either
760              back-ldap or back-meta, but constant parameters can  be  defined
761              in the configuration file by using the rewriteParam directive.
762
763       Substitution  escaping  has  been delegated to the `%' symbol, which is
764       used instead of `\' in string  substitution  patterns  because  `\'  is
765       already   escaped   by   slapd's  low  level  parsing  routines;  as  a
766       consequence,  regex   escaping   requires   two   `\'   symbols,   e.g.
767       `.*\.foo\.bar' must be written as `.*\\.foo\\.bar'.
768

Rewrite context:

770       A rewrite context is a set of rules which are applied in sequence.  The
771       basic idea is to have an application initialize a rewrite engine (think
772       of  Apache's  mod_rewrite  ...)  with  a  set of rewrite contexts; when
773       string rewriting is  required,  one  invokes  the  appropriate  rewrite
774       context with the input string and obtains the newly rewritten one if no
775       errors occur.
776
777       Each basic server operation is associated to a  rewrite  context;  they
778       are  divided  in two main groups: client -> server and server -> client
779       rewriting.
780
781       client -> server:
782
783              (default)            if defined and no specific context
784                                   is available
785              bindDN               bind
786              searchBase           search
787              searchFilter         search
788              searchFilterAttrDN   search
789              compareDN            compare
790              compareAttrDN        compare AVA
791              addDN                add
792              addAttrDN            add AVA
793              modifyDN             modify
794              modifyAttrDN         modify AVA
795              modrDN               modrdn
796              newSuperiorDN        modrdn
797              deleteDN             delete
798              exopPasswdDN         password modify extended operation DN if proxy
799
800       server -> client:
801
802              searchResult         search (only if defined; no default;
803                                   acts on DN and DN-syntax attributes
804                                   of search results)
805              searchAttrDN         search AVA
806              matchedDN            all ops (only if applicable)
807

Basic configuration syntax

809       rewriteEngine { on | off }
810              If `on', the requested rewriting  is  performed;  if  `off',  no
811              rewriting  takes  place  (an  easy way to stop rewriting without
812              altering too much the configuration file).
813
814       rewriteContext <context name> [ alias <aliased context name> ]
815              <Context name> is the name that identifies the context, i.e. the
816              name  used  by  the  application to refer to the set of rules it
817              contains.  It is used also to reference sub contexts  in  string
818              rewriting.   A  context may alias another one.  In this case the
819              alias context contains no rule, and any  reference  to  it  will
820              result in accessing the aliased one.
821
822       rewriteRule <regex match pattern> <substitution pattern> [ <flags> ]
823              Determines  how  a  string  can  be  rewritten  if  a pattern is
824              matched.  Examples are reported below.
825

Additional configuration syntax:

827       rewriteMap <map type> <map name> [ <map attrs> ]
828              Allows one to define a map that transforms  substring  rewriting
829              into   something   else.   The  map  is  referenced  inside  the
830              substitution pattern of a rule.
831
832       rewriteParam <param name> <param value>
833              Sets a value with global scope, that can be dereferenced by  the
834              command `%{$paramName}'.
835
836       rewriteMaxPasses <number of passes> [<number of passes per rule>]
837              Sets  the  maximum  number of total rewriting passes that can be
838              performed in a single rewrite operation  (to  avoid  loops).   A
839              safe  default  is  set  to 100; note that reaching this limit is
840              still treated as a success; recursive  invocation  of  rules  is
841              simply   interrupted.    The  count  applies  to  the  rewriting
842              operation as a whole, not to any single rule; an  optional  per-
843              rule  limit  can  be  set.   This limit is overridden by setting
844              specific per-rule limits with the `M{n}' flag.
845

Configuration examples:

847       # set to `off' to disable rewriting
848       rewriteEngine on
849
850       # the rules the "suffixmassage" directive implies
851       rewriteEngine on
852       # all dataflow from client to server referring to DNs
853       rewriteContext default
854       rewriteRule "(.*)<virtualnamingcontext>$" "%1<realnamingcontext>" ":"
855       # empty filter rule
856       rewriteContext searchFilter
857       # all dataflow from server to client
858       rewriteContext searchResult
859       rewriteRule "(.*)<realnamingcontext>$" "%1<virtualnamingcontext>" ":"
860       rewriteContext searchAttrDN alias searchResult
861       rewriteContext matchedDN alias searchResult
862
863       # Everything defined here goes into the `default' context.
864       # This rule changes the naming context of anything sent
865       # to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
866
867       rewriteRule "(.*)dc=home,[ ]?dc=net"
868                   "%1dc=OpenLDAP, dc=org"  ":"
869
870       # since a pretty/normalized DN does not include spaces
871       # after rdn separators, e.g. `,', this rule suffices:
872
873       rewriteRule "(.*)dc=home,dc=net"
874                   "%1dc=OpenLDAP,dc=org"  ":"
875
876       # Start a new context (ends input of the previous one).
877       # This rule adds blanks between DN parts if not present.
878       rewriteContext  addBlanks
879       rewriteRule     "(.*),([^ ].*)" "%1, %2"
880
881       # This one eats blanks
882       rewriteContext  eatBlanks
883       rewriteRule     "(.*),[ ](.*)" "%1,%2"
884
885       # Here control goes back to the default rewrite
886       # context; rules are appended to the existing ones.
887       # anything that gets here is piped into rule `addBlanks'
888       rewriteContext  default
889       rewriteRule     ".*" "%{>addBlanks(%0)}" ":"
890
891       # Rewrite the search base according to `default' rules.
892       rewriteContext  searchBase alias default
893
894       # Search results with OpenLDAP DN are rewritten back with
895       # `dc=home,dc=net' naming context, with spaces eaten.
896       rewriteContext  searchResult
897       rewriteRule     "(.*[^ ]?)[ ]?dc=OpenLDAP,[ ]?dc=org"
898                       "%{>eatBlanks(%1)}dc=home,dc=net"    ":"
899
900       # Bind with email instead of full DN: we first need
901       # an ldap map that turns attributes into a DN (the
902       # argument used when invoking the map is appended to
903       # the URI and acts as the filter portion)
904       rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
905
906       # Then we need to detect DN made up of a single email,
907       # e.g. `mail=someone@example.com'; note that the rule
908       # in case of match stops rewriting; in case of error,
909       # it is ignored.  In case we are mapping virtual
910       # to real naming contexts, we also need to rewrite
911       # regular DNs, because the definition of a bindDn
912       # rewrite context overrides the default definition.
913       rewriteContext bindDN
914       rewriteRule "^mail=[^,]+@[^,]+$" "%{attr2dn(%0)}" ":@I"
915
916       # This is a rather sophisticated example. It massages a
917       # search filter in case who performs the search has
918       # administrative privileges.  First we need to keep
919       # track of the bind DN of the incoming request, which is
920       # stored in a variable called `binddn' with session scope,
921       # and left in place to allow regular binding:
922       rewriteContext  bindDN
923       rewriteRule     ".+" "%{&&binddn(%0)}%0" ":"
924
925       # A search filter containing `uid=' is rewritten only
926       # if an appropriate DN is bound.
927       # To do this, in the first rule the bound DN is
928       # dereferenced, while the filter is decomposed in a
929       # prefix, in the value of the `uid=<arg>' AVA, and
930       # in a suffix. A tag `<>' is appended to the DN.
931       # If the DN refers to an entry in the `ou=admin' subtree,
932       # the filter is rewritten OR-ing the `uid=<arg>' with
933       # `cn=<arg>'; otherwise it is left as is. This could be
934       # useful, for instance, to allow apache's auth_ldap-1.4
935       # module to authenticate users with both `uid' and
936       # `cn', but only if the request comes from a possible
937       # `cn=Web auth,ou=admin,dc=home,dc=net' user.
938       rewriteContext searchFilter
939       rewriteRule "(.*\\()uid=([a-z0-9_]+)(\\).*)"
940         "%{**binddn}<>%{&prefix(%1)}%{&arg(%2)}%{&suffix(%3)}"
941         ":I"
942       rewriteRule "[^,]+,ou=admin,dc=home,dc=net"
943         "%{*prefix}|(uid=%{*arg})(cn=%{*arg})%{*suffix}" ":@I"
944       rewriteRule ".*<>" "%{*prefix}uid=%{*arg}%{*suffix}" ":"
945
946       # This example shows how to strip unwanted DN-valued
947       # attribute values from a search result; the first rule
948       # matches DN values below "ou=People,dc=example,dc=com";
949       # in case of match the rewriting exits successfully.
950       # The second rule matches everything else and causes
951       # the value to be rejected.
952       rewriteContext searchResult
953       rewriteRule ".*,ou=People,dc=example,dc=com" "%0" ":@"
954       rewriteRule ".*" "" "#"
955

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

957       In case the rewritten DN is an LDAP URI,  the  operation  is  initiated
958       towards  the  host[:port] indicated in the uri, if it does not refer to
959       the local server.  E.g.:
960
961         rewriteRule '^cn=root,.*' '%0'                     'G{3}'
962         rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@'
963         rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@'
964         rewriteRule '.*'          'ldap://ldap3.my.org/%0' ':@'
965
966       (Rule 1 is simply there to illustrate the `G{n}' action; it could  have
967       been written:
968
969         rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@'
970
971       with the advantage of saving one rewrite pass ...)
972
973

ACCESS CONTROL

975       The  meta  backend  does  not  honor  all ACL semantics as described in
976       slapd.access(5).  In general,  access  checking  is  delegated  to  the
977       remote  server(s).  Only read (=r) access to the entry pseudo-attribute
978       and to the other attribute values of the entries returned by the search
979       operation is honored, which is performed by the frontend.
980
981

PROXY CACHE OVERLAY

983       The  proxy  cache  overlay  allows  caching  of  LDAP  search  requests
984       (queries) in a local database.  See slapo-pcache(5) for details.
985
986

DEPRECATED STATEMENTS

988       The following statements have been deprecated and should no  longer  be
989       used.
990
991
992       pseudorootdn <substitute DN in case of rootdn bind>
993              Use idassert-bind instead.
994
995
996       pseudorootpw <substitute password in case of rootdn bind>
997              Use idassert-bind instead.
998
999
1000
1001

FILES

1003       /etc/openldap/slapd.conf
1004              default slapd configuration file
1005

SEE ALSO

1007       slapd.conf(5),   slapd-ldap(5),  slapo-pcache(5),  slapd(8),  regex(7),
1008       re_format(7).
1009

AUTHOR

1011       Pierangelo Masarati, based on back-ldap by Howard Chu
1012
1013
1014
1015OpenLDAP                          2021/06/03                     SLAPD-META(5)
Impressum