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
22       intended  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
60       attributes  related  to  entry  creation and modification should not be
61       proxied, as they could be mistakenly written to the  target  server(s),
62       generating  an  error.   The  current implementation automatically sets
63       lastmod 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
93              selection 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
101              error 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
135              directive.
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
149              instead 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
160              remembered  for  rebinds,  when  trying to re-establish a broken
161              connection, or when chasing a referral,  if  chase-referrals  is
162              set 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"
201              directive.   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       client-pr {accept-unsolicited|DISABLE|<size>}
252              This  feature  allows  one to use RFC 2696 Paged Results control
253              when performing search operations with a specific target,  irre‐
254              spective  of the client's request.  When set to a numeric value,
255              Paged Results control is always used with size as the page size.
256              When  set  to accept-unsolicited, unsolicited Paged Results con‐
257              trol responses are accepted and honored for  compatibility  with
258              broken  remote DSAs.  The client is not exposed to paged results
259              handling between  slapd-meta(5)  and  the  remote  servers.   By
260              default  (disabled),  Paged  Results  control  is  not  used and
261              responses are not accepted.  If set before any target specifica‐
262              tion,  it affects all targets, unless overridden by any per-tar‐
263              get directive.
264
265
266       default-target [<target>]
267              The "default-target" directive can also be  used  during  target
268              specification.  With no arguments it marks the current target as
269              the default.  The optional number marks target <target>  as  the
270              default one, starting from 1.  Target <target> must be defined.
271
272
273       filter <pattern>
274              This  directive allows specifying a regex(5) pattern to indicate
275              what search filter terms are actually served by a target.
276
277              In a search request, if the search filter  matches  the  pattern
278              the target is considered while fulfilling the request; otherwise
279              the target is ignored. There may be multiple occurrences of  the
280              filter directive for each target.
281
282
283       idassert-authzFrom <authz-regexp>
284              if  defined,  selects  what  local  identities are authorized to
285              exploit the identity assertion feature.  The string  <authz-reg‐
286              exp> follows the rules defined for the authzFrom attribute.  See
287              slapd.conf(5), section related to authz-policy, for  details  on
288              the syntax of this field.
289
290
291       idassert-bind    bindmethod=none|simple|sasl    [binddn=<simple    DN>]
292              [credentials=<simple    password>]    [saslmech=<SASL     mech>]
293              [secprops=<properties>] [realm=<realm>] [authcId=<authentication
294              ID>]  [authzId=<authorization  ID>]  [authz={native|proxyauthz}]
295              [mode=<mode>]     [flags=<flags>]     [starttls=no|yes|critical]
296              [tls_cert=<file>]      [tls_key=<file>]      [tls_cacert=<file>]
297              [tls_cacertdir=<path>]      [tls_reqcert=never|allow|try|demand]
298              [tls_cipher_suite=<ciphers>]
299              [tls_protocol_min=<major>[.<minor>]]
300              [tls_crlcheck=none|peer|all]
301              Allows one to define the parameters of the authentication method
302              that  is  internally  used by the proxy to authorize connections
303              that are authenticated by other databases.  The identity defined
304              by this directive, according to the properties associated to the
305              authentication method, is supposed to have auth  access  on  the
306              target server to attributes used on the proxy for authentication
307              and authorization, and to be allowed  to  authorize  the  users.
308              This  requires  to  have  proxyAuthz privileges on a wide set of
309              DNs, e.g.  authzTo=dn.subtree:"", and the remote server to  have
310              authz-policy  set  to to or both.  See slapd.conf(5) for details
311              on these statements and for remarks and  drawbacks  about  their
312              usage.  The supported bindmethods are
313
314              none|simple|sasl
315
316              where  none  is  the  default,  i.e.  no  identity  assertion is
317              performed.
318
319              The authz parameter is used to instruct the SASL bind to exploit
320              native  SASL  authorization, if available; since connections are
321              cached, this should only be used when authorizing with  a  fixed
322              identity  (e.g.  by means of the authzDN or authzID parameters).
323              Otherwise, the default proxyauthz is used, i.e.  the  proxyAuthz
324              control  (Proxied  Authorization,  RFC  4370)  is  added  to all
325              operations.
326
327              The supported modes are:
328
329              <mode> := {legacy|anonymous|none|self}
330
331              If <mode> is not present, and authzId is given, the proxy always
332              authorizes that identity.  <authorization ID> can be
333
334              u:<user>
335
336              [dn:]<DN>
337
338              The  former  is  supposed  to  be  expanded by the remote server
339              according to the authz rules; see slapd.conf(5) for details.  In
340              the  latter  case, whether or not the dn: prefix is present, the
341              string must pass DN validation and normalization.
342
343              The default mode is legacy, which implies that  the  proxy  will
344              either  perform  a  simple bind as the authcDN or a SASL bind as
345              the authcID and assert the client's  identity  when  it  is  not
346              anonymous.   Direct  binds  are always proxied.  The other modes
347              imply that the proxy will always either perform a simple bind as
348              the  authcDN or a SASL bind as the authcID, unless restricted by
349              idassert-authzFrom  rules  (see  below),  in  which   case   the
350              operation  will  fail;  eventually,  it  will  assert some other
351              identity according to <mode>.  Other  identity  assertion  modes
352              are  anonymous  and self, which respectively mean that the empty
353              or the client's identity will be  asserted;  none,  which  means
354              that  no  proxyAuthz control will be used, so the authcDN or the
355              authcID identity will be asserted.  For all modes  that  require
356              the  use  of  the  proxyAuthz  control, on the remote server the
357              proxy identity must have appropriate authzTo permissions, or the
358              asserted identities must have appropriate authzFrom permissions.
359              Note, however, that the ID assertion feature  is  mostly  useful
360              when the asserted identities do not exist on the remote server.
361
362              Flags can be
363
364              override,[non-]prescriptive,proxy-authz-[non-]critical
365
366              When  the  override flag is used, identity assertion takes place
367              even when the database is authorizing for the  identity  of  the
368              client,  i.e. after binding with the provided identity, and thus
369              authenticating it, the proxy  performs  the  identity  assertion
370              using the configured identity and authentication method.
371
372              When  the  prescriptive  flag  is used (the default), operations
373              fail with inappropriateAuthentication for those identities whose
374              assertion is not allowed by the idassert-authzFrom patterns.  If
375              the non-prescriptive flag  is  used,  operations  are  performed
376              anonymously  for those identities whose assertion is not allowed
377              by the idassert-authzFrom patterns.
378
379              When the proxy-authz-non-critical flag is  used  (the  default),
380              the  proxyAuthz  control is not marked as critical, in violation
381              of RFC 4370.  Use of proxy-authz-critical is recommended.
382
383              The TLS settings default to the  same  as  the  main  slapd  TLS
384              settings, except for tls_reqcert which defaults to "demand".
385
386              The  identity  associated  to  this  directive  is also used for
387              privileged operations  whenever  idassert-bind  is  defined  and
388              acl-bind is not.  See acl-bind for details.
389
390
391       idle-timeout <time>
392              This  directive  causes  a  cached  connection  to be dropped an
393              recreated after it has been idle for the  specified  time.   The
394              value can be specified as
395
396              [<d>d][<h>h][<m>m][<s>[s]]
397
398              where  <d>,  <h>,  <m> and <s> are respectively treated as days,
399              hours,  minutes  and  seconds.   If  set   before   any   target
400              specification,  it affects all targets, unless overridden by any
401              per-target directive.
402
403
404       keepalive <idle>:<probes>:<interval>
405              The keepalive parameter sets the values  of  idle,  probes,  and
406              interval  used  to  check whether a socket is alive; idle is the
407              number of seconds a connection needs to remain idle  before  TCP
408              starts sending keepalive probes; probes is the maximum number of
409              keepalive probes TCP should send before dropping the connection;
410              interval  is  interval  in  seconds between individual keepalive
411              probes.  Only some systems support the  customization  of  these
412              values;  the  keepalive  parameter  is  ignored  otherwise,  and
413              system-wide settings are used.
414
415
416       map {attribute|objectclass} [<local name>|*] {<foreign name>|*}
417              This maps object classes and attributes as in the LDAP  backend.
418              See slapd-ldap(5).
419
420
421       network-timeout <time>
422              Sets  the  network  timeout  value after which poll(2)/select(2)
423              following a connect(2) returns in  case  of  no  activity.   The
424              value   is   in   seconds,  and  it  can  be  specified  as  for
425              idle-timeout.   If  set  before  any  target  specification,  it
426              affects   all  targets,  unless  overridden  by  any  per-target
427              directive.
428
429
430       nretries {forever|never|<nretries>}
431              This directive defines how many times a bind should  be  retried
432              in case of temporary failure in contacting a target.  If defined
433              before any target specification, it applies to all  targets  (by
434              default,  3  times);  the  global  value  can  be  overridden by
435              redefinitions inside each target specification.
436
437
438       rewrite* ...
439              The rewrite options are described in the "REWRITING" section.
440
441
442       subtree-{exclude|include} <rule>
443              This directive allows one to indicate what subtrees are actually
444              served by a target.  The syntax of the supported rules is
445
446              <rule>: [dn[.<style>]:]<pattern>
447
448              <style>: subtree|children|regex
449
450              When <style> is either subtree or children the <pattern> is a DN
451              that must be within the naming context  served  by  the  target.
452              When  <style>  is regex the <pattern> is a regex(5) pattern.  If
453              the dn.<style>: prefix is  omitted,  dn.subtree:  is  implicitly
454              assumed for backward compatibility.
455
456              In  the  subtree-exclude form if the request DN matches at least
457              one rule, the target is  not  considered  while  fulfilling  the
458              request;  otherwise, the target is considered based on the value
459              of the request DN.  When the request is a search, also the scope
460              is considered.
461
462              In  the  subtree-include form if the request DN matches at least
463              one rule, the target is considered while fulfilling the request;
464              otherwise the target is ignored.
465
466
467                  |  match  | exclude |
468                  +---------+---------+-------------------+
469                  |    T    |    T    | not candidate     |
470                  |    F    |    T    | continue checking |
471                  +---------+---------+-------------------+
472                  |    T    |    F    | candidate         |
473                  |    F    |    F    | not candidate     |
474                  +---------+---------+-------------------+
475
476              There  may  be  multiple  occurrences  of the subtree-exclude or
477              subtree-include directive for each of the targets, but they  are
478              mutually exclusive.
479
480
481       suffixmassage <virtual naming context> <real naming context>
482              All  the directives starting with "rewrite" refer to the rewrite
483              engine that  has  been  added  to  slapd.   The  "suffixmassage"
484              directive  was  introduced  in  the LDAP backend to allow suffix
485              massaging  while  proxying.   It  has  been  obsoleted  by   the
486              rewriting  tools.   However, both for backward compatibility and
487              for  ease  of  configuration  when  simple  suffix  massage   is
488              required,  it  has been preserved.  It wraps the basic rewriting
489              instructions that perform suffix massaging.  See the "REWRITING"
490              section for a detailed list of the rewrite rules it implies.
491
492
493       t-f-support {NO|yes|discover}
494              enable  if  the remote server supports absolute filters (see RFC
495              4526 for details).  If set to discover, support is  detected  by
496              reading  the remote server's root DSE.  If set before any target
497              specification, it affects all targets, unless overridden by  any
498              per-target directive.
499
500
501       timeout [<op>=]<val> [...]
502              This   directive  allows  one  to  set  per-operation  timeouts.
503              Operations can be
504
505              <op> ::= bind, add, delete, modrdn, modify, compare, search
506
507              The overall duration  of  the  search  operation  is  controlled
508              either  by  the  timelimit  parameter or by server-side enforced
509              time limits (see  timelimit  and  limits  in  slapd.conf(5)  for
510              details).   This  timeout parameter controls how long the target
511              can be irresponsive before the operation is aborted.  Timeout is
512              meaningless  for  the  remaining operations, unbind and abandon,
513              which do not imply any response, while it is not yet implemented
514              in  currently supported extended operations.  If no operation is
515              specified, the timeout val affects all supported operations.  If
516              specified  before  any target definition, it affects all targets
517              unless overridden by per-target directives.
518
519              Note: if the timeout is exceeded,  the  operation  is  cancelled
520              (according  to  the  cancel  directive);  the  protocol does not
521              provide any means to rollback operations, so the client will not
522              be  notified  about  the  result  of  the  operation,  which may
523              eventually succeeded or not.  In case the  timeout  is  exceeded
524              during  a bind operation, the connection is destroyed, according
525              to RFC4511.
526
527
528       tls {[try-]start|[try-]propagate}
529              execute the StartTLS extended operation when the  connection  is
530              initialized;  only works if the URI directive protocol scheme is
531              not ldaps://.  propagate issues the StartTLS operation  only  if
532              the  original  connection  did.   The  try- prefix instructs the
533              proxy to continue operations if the StartTLS  operation  failed;
534              its  use  is  highly  deprecated.   If  set  before  any  target
535              specification, it affects all targets, unless overridden by  any
536              per-target directive.
537
538

SCENARIOS

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

ACLs

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

REWRITING

658       A string is rewritten according to a set of rules,  called  a  `rewrite
659       context'.    The  rules  are  based  on  POSIX  (''extended'')  regular
660       expressions   (regex)   with   substring   matching;   basic   variable
661       substitution  and  map  resolution of substrings is allowed by specific
662       mechanisms  detailed  in  the  following.   The  behavior  of   pattern
663       matching/substitution can be altered by a set of flags.
664
665       The underlying concept is to build a lightweight rewrite module for the
666       slapd server (initially dedicated to the LDAP backend).
667

Passes

669       An incoming string is matched against a set of rules.  Rules  are  made
670       of  a regex match pattern, a substitution pattern and a set of actions,
671       described by a set of flags.  In case of match a  string  rewriting  is
672       performed  according  to  the  substitution  pattern that allows one to
673       refer to substrings matched in the incoming string.   The  actions,  if
674       any,  are  finally  performed.   The  substitution  pattern  allows map
675       resolution of substrings.  A map  is  a  generic  object  that  maps  a
676       substitution  pattern  to  a  value.  The flags are divided in "Pattern
677       matching Flags" and "Action Flags"; the former alter  the  regex  match
678       pattern  behavior while the latter alter the action that is taken after
679       substitution.
680

Pattern Matching Flags

682       `C'    honors case in matching (default is case insensitive)
683
684       `R'    use   POSIX   ''basic''   regular   expressions   (default    is
685              ''extended'')
686
687       `M{n}' allow  no more than n recursive passes for a specific rule; does
688              not alter the max total count of passes, so it can only  enforce
689              a stricter limit for a specific rule.
690

Action Flags

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

Pattern matching:

726       See regex(7) and/or re_format(7).
727

Substitution Pattern Syntax:

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

Rewrite context:

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

Basic configuration syntax

823       rewriteEngine { on | off }
824              If `on', the requested rewriting  is  performed;  if  `off',  no
825              rewriting  takes  place  (an  easy way to stop rewriting without
826              altering too much the configuration file).
827
828       rewriteContext <context name> [ alias <aliased context name> ]
829              <Context name> is the name that identifies the context, i.e. the
830              name  used  by  the  application to refer to the set of rules it
831              contains.  It is used also to reference sub contexts  in  string
832              rewriting.   A  context may alias another one.  In this case the
833              alias context contains no rule, and any  reference  to  it  will
834              result in accessing the aliased one.
835
836       rewriteRule <regex match pattern> <substitution pattern> [ <flags> ]
837              Determines  how  a  string  can  be  rewritten  if  a pattern is
838              matched.  Examples are reported below.
839

Additional configuration syntax:

841       rewriteMap <map type> <map name> [ <map attrs> ]
842              Allows one to define a map that transforms  substring  rewriting
843              into   something   else.   The  map  is  referenced  inside  the
844              substitution pattern of a rule.
845
846       rewriteParam <param name> <param value>
847              Sets a value with global scope, that can be dereferenced by  the
848              command `%{$paramName}'.
849
850       rewriteMaxPasses <number of passes> [<number of passes per rule>]
851              Sets  the  maximum  number of total rewriting passes that can be
852              performed in a single rewrite operation  (to  avoid  loops).   A
853              safe  default  is  set  to 100; note that reaching this limit is
854              still treated as a success; recursive  invocation  of  rules  is
855              simply   interrupted.    The  count  applies  to  the  rewriting
856              operation as a whole, not to any single rule; an  optional  per-
857              rule  limit  can  be  set.   This limit is overridden by setting
858              specific per-rule limits with the `M{n}' flag.
859

Configuration examples:

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

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

971       In case the rewritten DN is an LDAP URI,  the  operation  is  initiated
972       towards  the  host[:port] indicated in the uri, if it does not refer to
973       the local server.  E.g.:
974
975         rewriteRule '^cn=root,.*' '%0'                     'G{3}'
976         rewriteRule '^cn=[a-l].*' 'ldap://ldap1.my.org/%0' ':@'
977         rewriteRule '^cn=[m-z].*' 'ldap://ldap2.my.org/%0' ':@'
978         rewriteRule '.*'          'ldap://ldap3.my.org/%0' ':@'
979
980       (Rule 1 is simply there to illustrate the `G{n}' action; it could  have
981       been written:
982
983         rewriteRule '^cn=root,.*' 'ldap://ldap3.my.org/%0' ':@'
984
985       with the advantage of saving one rewrite pass ...)
986
987

ACCESS CONTROL

989       The  meta  backend  does  not  honor  all ACL semantics as described in
990       slapd.access(5).  In general,  access  checking  is  delegated  to  the
991       remote  server(s).  Only read (=r) access to the entry pseudo-attribute
992       and to the other attribute values of the entries returned by the search
993       operation is honored, which is performed by the frontend.
994
995

PROXY CACHE OVERLAY

997       The  proxy  cache  overlay  allows  caching  of  LDAP  search  requests
998       (queries) in a local database.  See slapo-pcache(5) for details.
999
1000

DEPRECATED STATEMENTS

1002       The following statements have been deprecated and should no  longer  be
1003       used.
1004
1005
1006       pseudorootdn <substitute DN in case of rootdn bind>
1007              Use idassert-bind instead.
1008
1009
1010       pseudorootpw <substitute password in case of rootdn bind>
1011              Use idassert-bind instead.
1012
1013
1014
1015

FILES

1017       /etc/openldap/slapd.conf
1018              default slapd configuration file
1019

SEE ALSO

1021       slapd.conf(5),   slapd-ldap(5),  slapo-pcache(5),  slapd(8),  regex(7),
1022       re_format(7).
1023

AUTHOR

1025       Pierangelo Masarati, based on back-ldap by Howard Chu
1026
1027
1028
1029OpenLDAP 2.4.46                   2018/03/22                     SLAPD-META(5)
Impressum