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 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 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       noundeffilter <NO|yes>
302              If  yes,  return  success  instead  of  searching if a filter is
303              undefined or  contains  undefined  portions.   By  default,  the
304              search  is  propagated  after  replacing undefined portions with
305              (!(objectClass=*)), which corresponds to the empty result set.
306
307
308       onerr {CONTINUE|stop}
309              This directive allows to select the behavior in case an error is
310              returned  by  the  remote  server during a search.  The default,
311              continue, consists in returning success.  If the value is set to
312              stop, the error is returned to the client.
313
314
315       protocol-version {0,2,3}
316              This  directive  indicates what protocol version must be used to
317              contact the remote server.  If set to 0 (the default), the proxy
318              uses the same protocol version used by the client, otherwise the
319              requested    protocol    is    used.     The    proxy    returns
320              unwillingToPerform if an operation that is incompatible with the
321              requested protocol is attempted.
322
323
324       proxy-whoami {NO|yes}
325              Turns on proxying of the  WhoAmI  extended  operation.  If  this
326              option  is given, back-ldap will replace slapd's original WhoAmI
327              routine with its own. On slapd sessions that were  authenticated
328              by back-ldap, the WhoAmI request will be forwarded to the remote
329              LDAP server. Other sessions will be handled by the local  slapd,
330              as  before.  This  option  is  mainly useful in conjunction with
331              Proxy Authorization.
332
333
334       quarantine <interval>,<num>[;<interval>,<num>[...]]
335              Turns on quarantine of URIs that returned  LDAP_UNAVAILABLE,  so
336              that  an  attempt  to  reconnect  only occurs at given intervals
337              instead of any time a client requests an operation.  The pattern
338              is:  retry  only  after  at least interval seconds elapsed since
339              last attempt, for exactly num times; then use the next  pattern.
340              If  num  for  the  last  pattern  is  "+",  it  retries forever;
341              otherwise, no more retries occur.  The process can be  restarted
342              by resetting the olcDbQuarantine attribute of the database entry
343              in the configuration backend.
344
345
346       rebind-as-user {NO|yes}
347              If this option is  given,  the  client's  bind  credentials  are
348              remembered  for  rebinds,  when  trying to re-establish a broken
349              connection, or when chasing a referral,  if  chase-referrals  is
350              set to yes.
351
352
353       session-tracking-request {NO|yes}
354              Adds session tracking control for all requests.  The client's IP
355              and hostname, and the identity associated to  each  request,  if
356              known, are sent to the remote server for informational purposes.
357              This directive is incompatible with setting protocol-version  to
358              2.
359
360
361       single-conn {NO|yes}
362              Discards current cached connection when the client rebinds.
363
364
365       t-f-support {NO|yes|discover}
366              enable  if  the remote server supports absolute filters (see RFC
367              4526 for details).  If set to discover, support is  detected  by
368              reading the remote server's root DSE.
369
370
371       timeout [<op>=]<val> [...]
372              This directive allows to set per-operation timeouts.  Operations
373              can be
374
375              <op> ::= bind, add, delete, modrdn, modify, compare, search
376
377              The overall duration  of  the  search  operation  is  controlled
378              either  by  the  timelimit  parameter or by server-side enforced
379              time limits (see  timelimit  and  limits  in  slapd.conf(5)  for
380              details).   This  timeout parameter controls how long the target
381              can be irresponsive before the operation is aborted.  Timeout is
382              meaningless  for  the  remaining operations, unbind and abandon,
383              which do not imply any response, while it is not yet implemented
384              in  currently supported extended operations.  If no operation is
385              specified, the timeout val affects all supported operations.
386
387              Note: if the timelimit is exceeded, the operation  is  cancelled
388              (according  to  the  cancel  directive);  the  protocol does not
389              provide any means to rollback operations, so the client will not
390              be  notified  about  the  result  of  the  operation,  which may
391              eventually succeeded or not.  In case the  timeout  is  exceeded
392              during  a bind operation, the connection is destroyed, according
393              to RFC4511.
394
395              Note: in some cases, this backend may issue binds prior to other
396              operations  (e.g.  to  bind  anonymously or with some prescribed
397              identity according to the  idassert-bind  directive).   In  this
398              case,  the timeout of the operation that resulted in the bind is
399              used.
400
401
402       tls        {[try-]start|[try-]propagate|ldaps}        [tls_cert=<file>]
403              [tls_key=<file>]    [tls_cacert=<file>]   [tls_cacertdir=<path>]
404              [tls_reqcert=never|allow|try|demand]
405              [tls_cipher_suite=<ciphers>] [tls_crlcheck=none|peer|all]
406              Specify the use of TLS when a regular connection is initialized.
407              The StartTLS extended operation will  be  used  unless  the  URI
408              directive protocol scheme is ldaps://. In that case this keyword
409              may only be set to "ldaps" and the StartTLS operation  will  not
410              be  used.   propagate  issues the StartTLS operation only if the
411              original connection did.  The try- prefix instructs the proxy to
412              continue operations if the StartTLS operation failed; its use is
413              not recommended.
414
415              The TLS settings default to the  same  as  the  main  slapd  TLS
416              settings, except for tls_reqcert which defaults to "demand".
417
418
419       use-temporary-conn {NO|yes}
420              when   set  to  yes,  create  a  temporary  connection  whenever
421              competing with other threads for a shared one;  otherwise,  wait
422              until the shared connection is available.
423
424

BACKWARD COMPATIBILITY

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

ACCESS CONTROL

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

OVERLAYS

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

FILES

524       /etc/openldap/slapd.conf
525              default slapd configuration file
526

SEE ALSO

528       slapd.conf(5),    slapd-config(5),    slapd-meta(5),    slapo-chain(5),
529       slapo-pcache(5), slapo-rwm(5), slapo-translucent(5), slapd(8), ldap(3).
530

AUTHOR

532       Howard Chu, with enhancements by Pierangelo Masarati
533
534
535
536OpenLDAP 2.4.44                   2016/02/05                     SLAPD-LDAP(5)
Impressum