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       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
270              exploit  the identity assertion feature.  The string <authz-reg‐
271              exp> 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_cipher_suite=<ciphers>]
284              [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".
370
371              The identity associated to  this  directive  is  also  used  for
372              privileged  operations  whenever  idassert-bind  is  defined and
373              acl-bind is not.  See acl-bind for details.
374
375
376       idle-timeout <time>
377              This directive causes a  cached  connection  to  be  dropped  an
378              recreated  after  it  has been idle for the specified time.  The
379              value can be specified as
380
381              [<d>d][<h>h][<m>m][<s>[s]]
382
383              where <d>, <h>, <m> and <s> are respectively  treated  as  days,
384              hours,   minutes   and   seconds.   If  set  before  any  target
385              specification, it affects all targets, unless overridden by  any
386              per-target directive.
387
388
389       keepalive <idle>:<probes>:<interval>
390              The  keepalive  parameter  sets  the values of idle, probes, and
391              interval used to check whether a socket is alive;  idle  is  the
392              number  of  seconds a connection needs to remain idle before TCP
393              starts sending keepalive probes; probes is the maximum number of
394              keepalive probes TCP should send before dropping the connection;
395              interval is interval in  seconds  between  individual  keepalive
396              probes.   Only  some  systems support the customization of these
397              values;  the  keepalive  parameter  is  ignored  otherwise,  and
398              system-wide settings are used.
399
400
401       map {attribute|objectclass} [<local name>|*] {<foreign name>|*}
402              This  maps object classes and attributes as in the LDAP backend.
403              See slapd-ldap(5).
404
405
406       network-timeout <time>
407              Sets the network timeout  value  after  which  poll(2)/select(2)
408              following  a  connect(2)  returns  in  case of no activity.  The
409              value  is  in  seconds,  and  it  can  be   specified   as   for
410              idle-timeout.   If  set  before  any  target  specification,  it
411              affects  all  targets,  unless  overridden  by  any   per-target
412              directive.
413
414
415       nretries {forever|never|<nretries>}
416              This  directive  defines how many times a bind should be retried
417              in case of temporary failure in contacting a target.  If defined
418              before  any  target specification, it applies to all targets (by
419              default, 3  times);  the  global  value  can  be  overridden  by
420              redefinitions inside each target specification.
421
422
423       rewrite* ...
424              The rewrite options are described in the "REWRITING" section.
425
426
427       subtree-{exclude|include} <rule>
428              This directive allows one to indicate what subtrees are actually
429              served by a target.  The syntax of the supported rules is
430
431              <rule>: [dn[.<style>]:]<pattern>
432
433              <style>: subtree|children|regex
434
435              When <style> is either subtree or children the <pattern> is a DN
436              that  must  be  within  the naming context served by the target.
437              When <style> is regex the <pattern> is a regex(5)  pattern.   If
438              the  dn.<style>:  prefix  is  omitted, dn.subtree: is implicitly
439              assumed for backward compatibility.
440
441              In the subtree-exclude form if the request DN matches  at  least
442              one  rule,  the  target  is  not considered while fulfilling the
443              request; otherwise, the target is considered based on the  value
444              of the request DN.  When the request is a search, also the scope
445              is considered.
446
447              In the subtree-include form if the request DN matches  at  least
448              one rule, the target is considered while fulfilling the request;
449              otherwise the target is ignored.
450
451
452                  |  match  | exclude |
453                  +---------+---------+-------------------+
454                  |    T    |    T    | not candidate     |
455                  |    F    |    T    | continue checking |
456                  +---------+---------+-------------------+
457                  |    T    |    F    | candidate         |
458                  |    F    |    F    | not candidate     |
459                  +---------+---------+-------------------+
460
461              There may be multiple  occurrences  of  the  subtree-exclude  or
462              subtree-include  directive for each of the targets, but they are
463              mutually exclusive.
464
465
466       suffixmassage <virtual naming context> <real naming context>
467              All the directives starting with "rewrite" refer to the  rewrite
468              engine  that  has  been  added  to  slapd.   The "suffixmassage"
469              directive was introduced in the LDAP  backend  to  allow  suffix
470              massaging   while  proxying.   It  has  been  obsoleted  by  the
471              rewriting tools.  However, both for backward  compatibility  and
472              for   ease  of  configuration  when  simple  suffix  massage  is
473              required, it has been preserved.  It wraps the  basic  rewriting
474              instructions that perform suffix massaging.  See the "REWRITING"
475              section for a detailed list of the rewrite rules it implies.
476
477
478       t-f-support {NO|yes|discover}
479              enable if the remote server supports absolute filters  (see  RFC
480              4526  for  details).  If set to discover, support is detected by
481              reading the remote server's root DSE.  If set before any  target
482              specification,  it affects all targets, unless overridden by any
483              per-target directive.
484
485
486       timeout [<op>=]<val> [...]
487              This  directive  allows  one  to  set  per-operation   timeouts.
488              Operations can be
489
490              <op> ::= bind, add, delete, modrdn, modify, compare, search
491
492              The  overall  duration  of  the  search  operation is controlled
493              either by the timelimit parameter  or  by  server-side  enforced
494              time  limits  (see  timelimit  and  limits  in slapd.conf(5) for
495              details).  This timeout parameter controls how long  the  target
496              can be irresponsive before the operation is aborted.  Timeout is
497              meaningless for the remaining operations,  unbind  and  abandon,
498              which do not imply any response, while it is not yet implemented
499              in currently supported extended operations.  If no operation  is
500              specified, the timeout val affects all supported operations.  If
501              specified before any target definition, it affects  all  targets
502              unless overridden by per-target directives.
503
504              Note:  if  the  timeout  is exceeded, the operation is cancelled
505              (according to the  cancel  directive);  the  protocol  does  not
506              provide any means to rollback operations, so the client will not
507              be notified  about  the  result  of  the  operation,  which  may
508              eventually  succeeded  or  not.  In case the timeout is exceeded
509              during a bind operation, the connection is destroyed,  according
510              to RFC4511.
511
512
513       tls {[try-]start|[try-]propagate}
514              execute  the  StartTLS extended operation when the connection is
515              initialized; only works if the URI directive protocol scheme  is
516              not  ldaps://.   propagate issues the StartTLS operation only if
517              the original connection did.   The  try-  prefix  instructs  the
518              proxy  to  continue operations if the StartTLS operation failed;
519              its  use  is  highly  deprecated.   If  set  before  any  target
520              specification,  it affects all targets, unless overridden by any
521              per-target directive.
522
523

SCENARIOS

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

ACLs

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

REWRITING

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

Passes

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

Pattern Matching Flags

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

Action Flags

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

Pattern matching:

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

Substitution Pattern Syntax:

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

Rewrite context:

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

Basic configuration syntax

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

Additional configuration syntax:

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

Configuration examples:

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

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

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

ACCESS CONTROL

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

PROXY CACHE OVERLAY

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

DEPRECATED STATEMENTS

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

FILES

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

SEE ALSO

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

AUTHOR

1010       Pierangelo Masarati, based on back-ldap by Howard Chu
1011
1012
1013
1014OpenLDAP 2.4.50                   2020/04/28                     SLAPD-META(5)
Impressum