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, slapd(8) must be compiled
44       with thread support, and the threads parameter may need some tuning; in
45       those  cases, one may consider using slapd-relay(5) instead, which per‐
46       forms the relayed operation internally and thus reuses the same connec‐
47       tion.
48
49

CONFIGURATION

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

BACKWARD COMPATIBILITY

441       The LDAP backend has been heavily reworked  between  releases  2.2  and
442       2.3,  and  subsequently between 2.3 and 2.4.  As a side-effect, some of
443       the traditional directives have been deprecated and should be no longer
444       used, as they might disappear in future releases.
445
446
447       acl-authcDN <administrative DN for access control purposes>
448              Formerly known as the binddn, it is the DN that is used to query
449              the target server for acl checking; it is supposed to have  read
450              access  on the target server to attributes used on the proxy for
451              acl checking.  There is no risk of giving away such values; they
452              are only used to check permissions.
453
454              The  acl-authcDN  identity is by no means implicitly used by the
455              proxy when the  client  connects  anonymously.   The  idassert-*
456              feature can be used (at own risk) for that purpose instead.
457
458              This  directive  is obsoleted by the binddn arg of acl-bind when
459              bindmethod=simple, and will be dismissed in the future.
460
461
462       acl-passwd <password>
463              Formerly known as the bindpw, it is the password used  with  the
464              above acl-authcDN directive.  This directive is obsoleted by the
465              credentials arg of acl-bind when bindmethod=simple, and will  be
466              dismissed in the future.
467
468
469       idassert-authcDN <administrative DN for proxyAuthz purposes>
470              DN  which  is  used  to  propagate  the client's identity to the
471              target by means of the proxyAuthz control when the  client  does
472              not  belong  to  the DIT fragment that is being proxied by back-
473              ldap.   This  directive  is  obsoleted  by  the  binddn  arg  of
474              idassert-bind  when  bindmethod=simple, and will be dismissed in
475              the future.
476
477
478       idassert-passwd <password>
479              Password used with the idassert-authcDN above.   This  directive
480              is  obsoleted  by  the  crendentials  arg  of idassert-bind when
481              bindmethod=simple, and will be dismissed in the future.
482
483
484       idassert-mode <mode> [<flags>]
485              defines what type of identity assertion is used.  This directive
486              is  obsoleted  by  the  mode  arg  of idassert-bind, and will be
487              dismissed in the future.
488
489
490       idassert-method <method> [<saslargs>]
491              This  directive  is  obsoleted  by   the   bindmethod   arg   of
492              idassert-bind, and will be dismissed in the future.
493
494
495       port <port>
496              this directive is no longer supported.  Use the uri directive as
497              described above.
498
499
500       server <hostname[:port]>
501              this directive is no longer supported.  Use the uri directive as
502              described above.
503
504
505       suffixmassage, map, rewrite*
506              These  directives  are  no  longer supported by back-ldap; their
507              functionality is now delegated to the rwm overlay.  Essentially,
508              add a statement
509
510              overlay rwm
511
512              first, and prefix all rewrite/map statements with rwm- to obtain
513              the original behavior.  See slapo-rwm(5) for details.
514
515

ACCESS CONTROL

517       The ldap backend does not honor  all  ACL  semantics  as  described  in
518       slapd.access(5).   In  general,  access  checking  is  delegated to the
519       remote server(s).  Only read (=r) access to the entry  pseudo-attribute
520       and to the other attribute values of the entries returned by the search
521       operation is honored, which is performed by the frontend.
522
523

OVERLAYS

525       The LDAP  backend  provides  basic  proxying  functionalities  to  many
526       overlays.   The  chain  overlay,  described  in slapo-chain(5), and the
527       translucent  overlay,  described  in  slapo-translucent(5),  deserve  a
528       special mention.
529
530       Conversely,  there  are many overlays that are best used in conjunction
531       with the LDAP backend.  The proxycache overlay allows caching  of  LDAP
532       search requests (queries) in a local database.  See slapo-pcache(5) for
533       details.  The rwm overlay provides DN rewrite and attribute/objectClass
534       mapping  capabilities to the underlying database.  See slapo-rwm(5) for
535       details.
536
537

FILES

539       /etc/openldap/slapd.conf
540              default slapd configuration file
541

SEE ALSO

543       slapd.conf(5),    slapd-config(5),    slapd-meta(5),    slapo-chain(5),
544       slapo-pcache(5), slapo-rwm(5), slapo-translucent(5), slapd(8), ldap(3).
545

AUTHOR

547       Howard Chu, with enhancements by Pierangelo Masarati
548
549
550
551OpenLDAP                          2021/06/03                     SLAPD-LDAP(5)
Impressum