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

BACKWARD COMPATIBILITY

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

ACCESS CONTROL

508       The  ldap  backend  does  not  honor  all ACL semantics as described in
509       slapd.access(5).  In general,  access  checking  is  delegated  to  the
510       remote  server(s).  Only read (=r) access to the entry pseudo-attribute
511       and to the other attribute values of the entries returned by the search
512       operation is honored, which is performed by the frontend.
513
514

OVERLAYS

516       The  LDAP  backend  provides  basic  proxying  functionalities  to many
517       overlays.  The chain overlay,  described  in  slapo-chain(5),  and  the
518       translucent  overlay,  described  in  slapo-translucent(5),  deserve  a
519       special mention.
520
521       Conversely, there are many overlays that are best used  in  conjunction
522       with  the  LDAP backend.  The proxycache overlay allows caching of LDAP
523       search requests (queries) in a local database.  See slapo-pcache(5) for
524       details.  The rwm overlay provides DN rewrite and attribute/objectClass
525       mapping capabilities to the underlying database.  See slapo-rwm(5)  for
526       details.
527
528

FILES

530       /etc/openldap/slapd.conf
531              default slapd configuration file
532

SEE ALSO

534       slapd.conf(5),    slapd-config(5),    slapd-meta(5),    slapo-chain(5),
535       slapo-pcache(5), slapo-rwm(5), slapo-translucent(5), slapd(8), ldap(3).
536

AUTHOR

538       Howard Chu, with enhancements by Pierangelo Masarati
539
540
541
542OpenLDAP 2.4.47                   2018/12/19                     SLAPD-LDAP(5)
Impressum