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

NAME

6       slapd-ldap - LDAP backend to slapd
7

SYNOPSIS

9       /etc/openldap/slapd.conf
10

DESCRIPTION

12       The LDAP backend to slapd(8) is not an actual database; instead it acts
13       as a proxy to forward incoming requests to another LDAP  server.  While
14       processing requests it will also chase referrals, so that referrals are
15       fully processed instead of being returned to the slapd client.
16
17       Sessions that explicitly Bind to the back-ldap database  always  create
18       their  own private connection to the remote LDAP server. Anonymous ses‐
19       sions will share a single anonymous connection to  the  remote  server.
20       For sessions bound through other mechanisms, all sessions with the same
21       DN will share the same connection. This connection pooling strategy can
22       enhance  the  proxy's efficiency by reducing the overhead of repeatedly
23       making/breaking multiple connections.
24
25       The ldap database can also act as  an  information  service,  i.e.  the
26       identity  of  locally  authenticated  clients is asserted to the remote
27       server, possibly in some modified form.  For this  purpose,  the  proxy
28       binds  to  the remote server with some administrative identity, and, if
29       required, authorizes the asserted identity.  See the  idassert-*  rules
30       below.  The administrative identity of the proxy, on the remote server,
31       must be allowed to authorize by means of appropriate authzTo rules; see
32       slapd.conf(5) for details.
33
34       The  proxy instance of slapd(8) must contain schema information for the
35       attributes and objectClasses used in filters, request DNs and  request-
36       related data in general.  It should also contain schema information for
37       the data returned by the proxied server.  It is the  responsibility  of
38       the  proxy  administrator to keep the schema of the proxy lined up with
39       that of the proxied server.
40
41
42       Note: When looping back to the same instance of slapd(8), each  connec‐
43       tion  requires a new thread; as a consequence, the slapd(8) threads pa‐
44       rameter may need some tuning. In those cases, one  may  consider  using
45       slapd-relay(5) instead, which performs the relayed operation internally
46       and thus reuses the same connection.
47
48

CONFIGURATION

50       These slapd.conf options apply to the LDAP backend database.  That  is,
51       they  must follow a "database ldap" line and come before any subsequent
52       "backend" or "database" lines.  Other database options are described in
53       the slapd.conf(5) manual page.
54
55
56       Note: In early versions of back-ldap it was recommended to always set
57
58              lastmod  off
59
60       for ldap and meta databases.  This was required because operational at‐
61       tributes related to entry creation and modification should not be prox‐
62       ied,  as they could be mistakenly written to the target server(s), gen‐
63       erating an error.  The current implementation automatically sets  last‐
64       mod to off, so its use is redundant and should be omitted.
65
66
67       uri <ldapurl>
68              LDAP  server  to use.  Multiple URIs can be set in a single lda‐
69              purl argument, resulting in the underlying library automatically
70              calling the first server of the list that responds, e.g.
71
72              uri "ldap://host/ ldap://backup-host/"
73
74              The  URI list is space- or comma-separated.  Whenever the server
75              that responds is not the first one in the list, the list is  re‐
76              arranged and the responsive server is moved to the head, so that
77              it will be first contacted the next time a connection  needs  to
78              be created.
79
80       acl-bind        bindmethod=simple|sasl       [binddn=<simple       DN>]
81              [credentials=<simple    password>]    [saslmech=<SASL     mech>]
82              [secprops=<properties>] [realm=<realm>] [authcId=<authentication
83              ID>]  [authzId=<authorization  ID>]   [starttls=no|yes|critical]
84              [tls_cert=<file>]      [tls_key=<file>]      [tls_cacert=<file>]
85              [tls_cacertdir=<path>]      [tls_reqcert=never|allow|try|demand]
86              [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
87              [tls_ecname=<names>]        [tls_protocol_min=<major>[.<minor>]]
88              [tls_crlcheck=none|peer|all]
89              Allows one to define the parameters of the authentication method
90              that is internally used by the proxy to collect info related  to
91              access  control,  and  whenever  an  operation  occurs  with the
92              identity of the rootdn of the LDAP proxy database.  The identity
93              defined   by   this   directive,  according  to  the  properties
94              associated to the authentication method,  is  supposed  to  have
95              read access on the target server to attributes used on the proxy
96              for ACL checking.
97
98              There is no risk of giving away such values; they are only  used
99              to  check  permissions.  The default is to use simple bind, with
100              empty binddn and  credentials,  which  means  that  the  related
101              operations  will  be  performed anonymously.  If not set, and if
102              idassert-bind is defined, this latter identity is used  instead.
103              See idassert-bind for details.
104
105              The  connection between the proxy database and the remote server
106              associated to this identity is cached regardless of the lifespan
107              of the client-proxy connection that first established it.
108
109              This  identity  is  not  implicitly  used  by the proxy when the
110              client  connects  anonymously.    The   idassert-bind   feature,
111              instead,  in  some  cases  can  be  crafted  to  implement  that
112              behavior, which is intrinsically unsafe and should be used  with
113              extreme care.
114
115              The  TLS  settings  default  to  the  same as the main slapd TLS
116              settings, except for tls_reqcert which defaults to "demand", and
117              tls_reqsan which defaults to "allow".
118
119
120       cancel {ABANDON|ignore|exop[-discover]}
121              Defines  how  to  handle  operation  cancellation.   By default,
122              abandon is invoked, so the operation is  abandoned  immediately.
123              If set to ignore, no action is taken and any further response is
124              ignored; this may result in  further  response  messages  to  be
125              queued  for  that  connection,  so  it  is recommended that long
126              lasting connections are timed  out  either  by  idle-timeout  or
127              conn-ttl,  so that resources eventually get released.  If set to
128              exop, a cancel operation (RFC 3909) is issued, resulting in  the
129              cancellation  of  the  current  operation;  the cancel operation
130              waits for  remote  server  response,  so  its  use  may  not  be
131              recommended.   If  set  to  exop-discover, support of the cancel
132              extended operation is detected by reading  the  remote  server's
133              root DSE.
134
135
136       chase-referrals {YES|no}
137              enable/disable automatic referral chasing, which is delegated to
138              the underlying libldap, with rebinding eventually  performed  if
139              the  rebind-as-user  directive is used.  The default is to chase
140              referrals.
141
142
143       conn-pool-max <int>
144              This directive  defines  the  maximum  size  of  the  privileged
145              connections pool.
146
147
148       conn-ttl <time>
149              This  directive causes a cached connection to be dropped after a
150              given ttl, regardless  of  being  idle  or  not.   If  a  client
151              connection  outlives  the  remote  connection,  the  client will
152              receive LDAP_UNAVAILABLE when it executes the next operation.
153
154
155
156       idassert-authzFrom <authz-regexp>
157              if defined, selects what  local  identities  are  authorized  to
158              exploit  the  identity  assertion  feature.   The string <authz-
159              regexp> mostly follows  the  rules  defined  for  the  authzFrom
160              attribute.   See slapd.conf(5), section related to authz-policy,
161              for details on the syntax of this field.  This parameter differs
162              from  the  documented  behavior in relation to the meaning of *,
163              which in this case allows anonymous rather than denies.
164
165
166       idassert-bind    bindmethod=none|simple|sasl    [binddn=<simple    DN>]
167              [credentials=<simple     password>]    [saslmech=<SASL    mech>]
168              [secprops=<properties>] [realm=<realm>] [authcId=<authentication
169              ID>]  [authzId=<authorization  ID>]  [authz={native|proxyauthz}]
170              [mode=<mode>]     [flags=<flags>]     [starttls=no|yes|critical]
171              [tls_cert=<file>]      [tls_key=<file>]      [tls_cacert=<file>]
172              [tls_cacertdir=<path>]      [tls_reqcert=never|allow|try|demand]
173              [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>]
174              [tls_ecname=<names>]                [tls_protocol_min=<version>]
175              [tls_crlcheck=none|peer|all]
176              Allows one to define the parameters of the authentication method
177              that is internally used by the proxy  to  authorize  connections
178              that  are  authenticated  by  other databases.  Direct binds are
179              always proxied without any idassert handling.
180
181              The  identity  defined  by  this  directive,  according  to  the
182              properties  associated to the authentication method, is supposed
183              to have auth access on the target server to attributes  used  on
184              the  proxy  for  authentication  and  authorization,  and  to be
185              allowed  to  authorize  the  users.   This  requires   to   have
186              proxyAuthz   privileges   on   a   wide   set   of   DNs,   e.g.
187              authzTo=dn.subtree:"",   and   the   remote   server   to   have
188              authz-policy  set  to to or both.  See slapd.conf(5) for details
189              on these statements and for remarks and  drawbacks  about  their
190              usage.  The supported bindmethods are
191
192              none|simple|sasl
193
194              where  none  is  the  default,  i.e.  no  identity  assertion is
195              performed.
196
197              The authz parameter is used to instruct the SASL bind to exploit
198              native  SASL  authorization, if available; since connections are
199              cached, this should only be used when authorizing with  a  fixed
200              identity  (e.g.  by means of the authzDN or authzID parameters).
201              Otherwise, the default proxyauthz is used, i.e.  the  proxyAuthz
202              control  (Proxied  Authorization,  RFC  4370)  is  added  to all
203              operations.
204
205              The supported modes are:
206
207              <mode> := {legacy|anonymous|none|self}
208
209              If <mode> is not present, and authzId is given, the proxy always
210              authorizes that identity.  <authorization ID> can be
211
212              u:<user>
213
214              [dn:]<DN>
215
216              The  former  is  supposed  to  be  expanded by the remote server
217              according to the authz rules; see slapd.conf(5) for details.  In
218              the  latter  case, whether or not the dn: prefix is present, the
219              string must pass DN validation and normalization.
220
221              The default mode is legacy, which implies that  the  proxy  will
222              either  perform  a  simple bind as the authcDN or a SASL bind as
223              the authcID and assert the client's  identity  when  it  is  not
224              anonymous.   The  other  modes  imply that the proxy will always
225              either perform a simple bind as the authcDN or a  SASL  bind  as
226              the  authcID, unless restricted by idassert-authzFrom rules (see
227              below), in which case the operation will  fail;  eventually,  it
228              will  assert  some  other  identity  according to <mode>.  Other
229              identity  assertion  modes  are  anonymous   and   self,   which
230              respectively  mean  that the empty or the client's identity will
231              be asserted; none, which means that no proxyAuthz  control  will
232              be  used,  so  the  authcDN  or  the  authcID  identity  will be
233              asserted.  For all modes that require the use of the  proxyAuthz
234              control,  on  the  remote  server  the  proxy identity must have
235              appropriate authzTo permissions, or the asserted identities must
236              have appropriate authzFrom permissions.  Note, however, that the
237              ID  assertion  feature  is  mostly  useful  when  the   asserted
238              identities do not exist on the remote server.
239
240              Flags can be
241
242              override,[non-]prescriptive,proxy-authz-[non-]critical,dn-{authzid|whoami}
243
244              When the override flag is used, identity assertion  takes  place
245              even  when  the  database is authorizing for the identity of the
246              client, i.e. after binding with the provided identity, and  thus
247              authenticating  it,  the  proxy  performs the identity assertion
248              using the configured identity and authentication method.
249
250              When the prescriptive flag is  used  (the  default),  operations
251              fail with inappropriateAuthentication for those identities whose
252              assertion is not allowed by the idassert-authzFrom patterns.  If
253              the  non-prescriptive  flag  is  used,  operations are performed
254              anonymously for those identities whose assertion is not  allowed
255              by the idassert-authzFrom patterns.
256
257              When  the  proxy-authz-non-critical  flag is used (the default),
258              the proxyAuthz control is not marked as critical,  in  violation
259              of RFC 4370.  Use of proxy-authz-critical is recommended.
260
261              When  the  dn-authzid  flag is used, RFC 3829 LDAP Authorization
262              Identity Controls is used to retrieve the identity associated to
263              the  SASL  identity;  when  the dn-whoami flag is used, RFC 4532
264              LDAP Who am I? Operation is performed after  the  bind  for  the
265              same purpose.
266
267              The  TLS  settings  default  to  the  same as the main slapd TLS
268              settings, except for tls_reqcert which defaults to "demand", and
269              tls_reqsan which defaults to "allow".
270
271              The  identity  associated  to  this  directive  is also used for
272              privileged operations  whenever  idassert-bind  is  defined  and
273              acl-bind is not.  See acl-bind for details.
274
275
276              idassert-passthru <authz-regexp>
277                     if  defined,  selects  what  local  identities bypass the
278                     identity assertion feature.  Those identities need to  be
279                     known  by  the  remote  host.   The string <authz-regexp>
280                     follows the rules defined for  the  authzFrom  attribute.
281                     See  slapd.conf(5),  section related to authz-policy, for
282                     details on the syntax of this field.
283
284
285              idle-timeout <time>
286                     This directive causes a cached connection to  be  dropped
287                     after  it  has  been  idle  for the specified time.  If a
288                     client connection outlives  the  remote  connection,  the
289                     client will receive LDAP_UNAVAILABLE when it executes the
290                     next operation.
291
292
293              keepalive <idle>:<probes>:<interval>
294                     The keepalive parameter sets the values of idle,  probes,
295                     and  interval  used  to  check whether a socket is alive;
296                     idle is the number  of  seconds  a  connection  needs  to
297                     remain  idle  before TCP starts sending keepalive probes;
298                     probes is the maximum  number  of  keepalive  probes  TCP
299                     should  send  before dropping the connection; interval is
300                     interval in seconds between individual keepalive  probes.
301                     Only  some  systems  support  the  customization of these
302                     values; the keepalive parameter is ignored otherwise, and
303                     system-wide settings are used.
304
305
306              tcp-user-timeout <milliseconds>
307                     If  non-zero,  corresponds to the TCP_USER_TIMEOUT set on
308                     the target connections, overriding the  operating  system
309                     setting.   Only some systems support the customization of
310                     this parameter, it is ignored otherwise  and  system-wide
311                     settings are used.
312
313
314              network-timeout <time>
315                     Sets    the    network    timeout   value   after   which
316                     poll(2)/select(2) following a connect(2) returns in  case
317                     of  no  activity.  The value is in seconds, and it can be
318                     specified as for idle-timeout.
319
320
321              norefs <NO|yes>
322                     If yes, do not return  search  reference  responses.   By
323                     default, they are returned unless request is LDAPv2.
324
325
326              omit-unknown-schema <NO|yes>
327                     If  yes,  do  not return objectClasses or attributes that
328                     are not known to the local server.   The  default  is  to
329                     return all schema elements.
330
331
332              noundeffilter <NO|yes>
333                     If  yes,  return success instead of searching if a filter
334                     is undefined or contains undefined portions.  By default,
335                     the   search  is  propagated  after  replacing  undefined
336                     portions with (!(objectClass=*)),  which  corresponds  to
337                     the empty result set.
338
339
340              onerr {CONTINUE|stop}
341                     This  directive allows one to select the behavior in case
342                     an error is  returned  by  the  remote  server  during  a
343                     search.   The  default,  continue,  consists in returning
344                     success.  If the value is  set  to  stop,  the  error  is
345                     returned to the client.
346
347
348              protocol-version {0,2,3}
349                     This  directive  indicates  what protocol version must be
350                     used to contact the remote server.   If  set  to  0  (the
351                     default),  the  proxy uses the same protocol version used
352                     by the client, otherwise the requested protocol is  used.
353                     The proxy returns unwillingToPerform if an operation that
354                     is incompatible with the requested protocol is attempted.
355
356
357              proxy-whoami {NO|yes}
358                     Turns on proxying of the WhoAmI  extended  operation.  If
359                     this  option  is  given,  back-ldap  will replace slapd's
360                     original WhoAmI routine with its own. On  slapd  sessions
361                     that  were authenticated by back-ldap, the WhoAmI request
362                     will be  forwarded  to  the  remote  LDAP  server.  Other
363                     sessions  will  be handled by the local slapd, as before.
364                     This option is mainly useful in  conjunction  with  Proxy
365                     Authorization.
366
367
368              quarantine <interval>,<num>[;<interval>,<num>[...]]
369                     Turns    on    quarantine    of    URIs   that   returned
370                     LDAP_UNAVAILABLE, so that an attempt  to  reconnect  only
371                     occurs  at  given  intervals instead of any time a client
372                     requests an operation.  The pattern is: retry only  after
373                     at least interval seconds elapsed since last attempt, for
374                     exactly num times; then use the next pattern.  If num for
375                     the  last  pattern is "+", it retries forever; otherwise,
376                     no more retries occur.  The process can be  restarted  by
377                     resetting  the  olcDbQuarantine attribute of the database
378                     entry in the configuration backend.
379
380
381              rebind-as-user {NO|yes}
382                     If this option is given, the  client's  bind  credentials
383                     are remembered for rebinds, when trying to re-establish a
384                     broken  connection,  or  when  chasing  a  referral,   if
385                     chase-referrals  is  set  to  yes.   Note,  however, that
386                     connection is not re-established automatically  after  it
387                     was dropped due to idle-timeout or conn-ttl .
388
389
390              session-tracking-request {NO|yes}
391                     Adds  session  tracking  control  for  all requests.  The
392                     client's IP and hostname, and the identity associated  to
393                     each request, if known, are sent to the remote server for
394                     informational purposes.  This directive  is  incompatible
395                     with setting protocol-version to 2.
396
397
398              single-conn {NO|yes}
399                     Discards   current  cached  connection  when  the  client
400                     rebinds.
401
402
403              t-f-support {NO|yes|discover}
404                     enable if the remote  server  supports  absolute  filters
405                     (see  RFC 4526 for details).  If set to discover, support
406                     is detected by reading the remote server's root DSE.
407
408
409              timeout [<op>=]<val> [...]
410                     This directive allows one to set per-operation  timeouts.
411                     Operations can be
412
413                     <op>  ::=  bind,  add,  delete,  modrdn, modify, compare,
414                     search
415
416                     The  overall  duration  of  the   search   operation   is
417                     controlled  either  by  the  timelimit  parameter  or  by
418                     server-side  enforced  time  limits  (see  timelimit  and
419                     limits  in  slapd.conf(5)  for  details).   This  timeout
420                     parameter  controls  how   long   the   target   can   be
421                     irresponsive before the operation is aborted.  Timeout is
422                     meaningless for  the  remaining  operations,  unbind  and
423                     abandon, which do not imply any response, while it is not
424                     yet   implemented   in   currently   supported   extended
425                     operations.   If  no  operation is specified, the timeout
426                     val affects all supported operations.
427
428                     Note: if the timelimit  is  exceeded,  the  operation  is
429                     cancelled   (according  to  the  cancel  directive);  the
430                     protocol  does  not  provide  any   means   to   rollback
431                     operations,  so the client will not be notified about the
432                     result of the operation, which may  eventually  succeeded
433                     or  not.   In  case the timeout is exceeded during a bind
434                     operation, the  connection  is  destroyed,  according  to
435                     RFC4511.
436
437                     Note:  in  some cases, this backend may issue binds prior
438                     to other operations (e.g. to  bind  anonymously  or  with
439                     some  prescribed  identity according to the idassert-bind
440                     directive).  In this case, the timeout of  the  operation
441                     that resulted in the bind is used.
442
443
444              tls    {none|[try-]start|[try-]propagate|ldaps}    [starttls=no]
445                     [tls_cert=<file>]  [tls_key=<file>]   [tls_cacert=<file>]
446                     [tls_cacertdir=<path>]
447                     [tls_reqcert=never|allow|try|demand]
448                     [tls_reqsan=never|allow|try|demand]
449                     [tls_cipher_suite=<ciphers>]         [tls_ecname=<names>]
450                     [tls_crlcheck=none|peer|all]
451                     Specify TLS settings for regular connections.
452
453                     If the first parameter is not "none" then this configures
454                     the TLS settings to be used for regular connections.  The
455                     StartTLS   extended   operation   will   be   used   when
456                     establishing the  connection  unless  the  URI  directive
457                     protocol  scheme  is ldaps://.  In that case this keyword
458                     may only be set to "ldaps"  and  the  StartTLS  operation
459                     will not be used.
460
461                     With  propagate,  the proxy issues the StartTLS operation
462                     only if the original connection has a TLS layer  set  up.
463                     The   try-   prefix   instructs  the  proxy  to  continue
464                     operations if the StartTLS operation failed; its  use  is
465                     not recommended.
466
467                     The  TLS  settings  default to the same as the main slapd
468                     TLS settings, except for tls_reqcert  which  defaults  to
469                     "demand",  tls_reqsan  which  defaults  to  "allow",  and
470                     starttls which is overshadowed by the first  keyword  and
471                     thus ignored.
472
473
474              use-temporary-conn {NO|yes}
475                     when  set  to yes, create a temporary connection whenever
476                     competing with other threads for a shared one; otherwise,
477                     wait until the shared connection is available.
478
479

ACCESS CONTROL

481       The  ldap  backend  does  not  honor  all ACL semantics as described in
482       slapd.access(5).  In general,  access  checking  is  delegated  to  the
483       remote  server(s).  Only read (=r) access to the entry pseudo-attribute
484       and to the other attribute values of the entries returned by the search
485       operation is honored, which is performed by the frontend.
486
487

OVERLAYS

489       The  LDAP  backend  provides  basic  proxying  functionalities  to many
490       overlays.  The chain overlay,  described  in  slapo-chain(5),  and  the
491       translucent  overlay,  described  in  slapo-translucent(5),  deserve  a
492       special mention.
493
494       Conversely, there are many overlays that are best used  in  conjunction
495       with  the  LDAP backend.  The proxycache overlay allows caching of LDAP
496       search requests (queries) in a local database.  See slapo-pcache(5) for
497       details.  The rwm overlay provides DN rewrite and attribute/objectClass
498       mapping capabilities to the underlying database.  See slapo-rwm(5)  for
499       details.
500
501

FILES

503       /etc/openldap/slapd.conf
504              default slapd configuration file
505

SEE ALSO

507       slapd.conf(5),    slapd-config(5),    slapd-meta(5),    slapo-chain(5),
508       slapo-pcache(5), slapo-rwm(5), slapo-translucent(5), slapd(8), ldap(3).
509

AUTHOR

511       Howard Chu, with enhancements by Pierangelo Masarati
512
513
514
515OpenLDAP 2.6.2                    2022/05/04                     SLAPD-LDAP(5)
Impressum