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

BACKWARD COMPATIBILITY

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

ACCESS CONTROL

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

OVERLAYS

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

FILES

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

SEE ALSO

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

AUTHOR

531       Howard Chu, with enhancements by Pierangelo Masarati
532
533
534
535OpenLDAP 2.4.40                   2014/09/20                     SLAPD-LDAP(5)
Impressum