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
35       Note:  When looping back to the same instance of slapd(8), each connec‐
36       tion requires a new thread; as a consequence, slapd(8) must be compiled
37       with thread support, and the threads parameter may need some tuning; in
38       those cases, one may consider using slapd-relay(5) instead, which  per‐
39       forms the relayed operation internally and thus reuses the same connec‐
40       tion.
41
42

CONFIGURATION

44       These slapd.conf options apply to the LDAP backend database.  That  is,
45       they  must follow a "database ldap" line and come before any subsequent
46       "backend" or "database" lines.  Other database options are described in
47       the slapd.conf(5) manual page.
48
49
50       Note: In early versions of back-ldap it was recommended to always set
51
52              lastmod  off
53
54       for  every  ldap  and  meta  database.   This  is  because  operational
55       attributes related to entry creation and  modification  should  not  be
56       proxied,  as  they could be mistakenly written to the target server(s),
57       generating an error.  The  current  implementation  automatically  sets
58       lastmod  to off, so its use is redundant and should be omitted, because
59       the lastmod directive will be deprecated in the future.
60
61
62       uri <ldapurl>
63              LDAP server to use.  Multiple URIs can be set  in  in  a  single
64              ldapurl  argument, resulting in the underlying library automati‐
65              cally call the first server of the list that responds, e.g.
66
67              uri "ldap://host/ ldap://backup-host/"
68
69              The URI list is space- or comma-separated.
70
71       acl-bind       bindmethod=simple|sasl       [binddn=<simple        DN>]
72              [credentials=<simple     password>]    [saslmech=<SASL    mech>]
73              [secprops=<properties>] [realm=<realm>] [authcId=<authentication
74              ID>] [authzId=<authorization ID>]
75              Allows  to  define  the  parameters of the authentication method
76              that is internally used by the proxy to collect info related  to
77              access   control.   The  identity  defined  by  this  directive,
78              according to the properties  associated  to  the  authentication
79              method,  is supposed to have read access on the target server to
80              attributes used on the proxy for ACL checking.  There is no risk
81              of  giving  away  such  values;  they  are  only  used  to check
82              permissions.  The default is to  use  simple  bind,  with  empty
83              binddn  and credentials, which means that the related operations
84              will be performed anonymously.
85
86              This identity is by no means implicitly used by the  proxy  when
87              the  client  connects  anonymously.   The idassert-bind feature,
88              instead,  in  some  cases  can  be  crafted  to  implement  that
89              behavior,  which is intrinsically unsafe and should be used with
90              extreme care.  This directive obsoletes  acl-authcDN,  and  acl-
91              passwd.
92
93
94       chase-referrals {YES|no}
95              enable/disable automatic referral chasing, which is delegated to
96              the underlying libldap, with rebinding eventually  performed  if
97              the  rebind-as-user  directive is used.  The default is to chase
98              referrals.
99
100
101       conn-ttl <time>
102              This directive causes a  cached  connection  to  be  dropped  an
103              recreated after a given ttl, regardless of being idle or not.
104
105
106       idassert-authzFrom <authz-regexp>
107              if  defined,  selects  what  local  identities are authorized to
108              exploit the identity  assertion  feature.   The  string  <authz-
109              regexp>  follows  the rules defined for the authzFrom attribute.
110              See slapd.conf(5), section related to authz-policy, for  details
111              on the syntax of this field.
112
113
114       idassert-bind    bindmethod=none|simple|sasl    [binddn=<simple    DN>]
115              [credentials=<simple    password>]    [saslmech=<SASL     mech>]
116              [secprops=<properties>] [realm=<realm>] [authcId=<authentication
117              ID>]  [authzId=<authorization  ID>]  [authz={native|proxyauthz}]
118              [mode=<mode>] [flags=<flags>]
119              Allows  to  define  the  parameters of the authentication method
120              that is internally used by the proxy  to  authorize  connections
121              that are authenticated by other databases.  The identity defined
122              by this directive, according to the properties associated to the
123              authentication  method,  is  supposed to have auth access on the
124              target server to attributes used on the proxy for authentication
125              and  authorization,  and  to  be allowed to authorize the users.
126              This requires to have proxyAuthz privileges on  a  wide  set  of
127              DNs,  e.g.  authzTo=dn.subtree:"", and the remote server to have
128              authz-policy set to to or both.  See slapd.conf(5)  for  details
129              on  these  statements  and for remarks and drawbacks about their
130              usage.  The supported bindmethods are
131
132              none|simple|sasl
133
134              where none  is  the  default,  i.e.  no  identity  assertion  is
135              performed.
136
137              The authz parameter is used to instruct the SASL bind to exploit
138              native SASL authorization, if available; since  connections  are
139              cached,  this  should only be used when authorizing with a fixed
140              identity (e.g. by means of the authzDN or  authzID  parameters).
141              Otherwise,  the  default proxyauthz is used, i.e. the proxyAuthz
142              control is added to all operations.
143
144              The supported modes are:
145
146              <mode> := {legacy|anonymous|none|self}
147
148              If <mode> is not present, and authzId is given, the proxy always
149              authorizes that identity.  <authorization ID> can be
150
151              u:<user>
152
153              [dn:]<DN>
154
155              The  former  is  supposed  to  be  expanded by the remote server
156              according to the authz rules; see slapd.conf(5) for details.  In
157              the  latter  case, whether or not the dn: prefix is present, the
158              string must pass DN validation and normalization.
159
160              The default mode is legacy, which implies that  the  proxy  will
161              either  perform  a  simple bind as the authcDN or a SASL bind as
162              the authcID and assert the client's  identity  when  it  is  not
163              anonymous.   Direct  binds  are always proxied.  The other modes
164              imply that the proxy will always either perform a simple bind as
165              the  authcDN or a SASL bind as the authcID, unless restricted by
166              idassert-authzFrom  rules  (see  below),  in  which   case   the
167              operation  will  fail;  eventually,  it  will  assert some other
168              identity according to <mode>.  Other  identity  assertion  modes
169              are  anonymous  and self, which respectively mean that the empty
170              or the client's identity will be  asserted;  none,  which  means
171              that  no  proxyAuthz control will be used, so the authcDN or the
172              authcID identity will be asserted.  For all modes  that  require
173              the  use  of  the  proxyAuthz  control, on the remote server the
174              proxy identity must have appropriate authzTo permissions, or the
175              asserted identities must have appropriate authzFrom permissions.
176              Note, however, that the ID assertion feature  is  mostly  useful
177              when the asserted identities do not exist on the remote server.
178
179              Flags can be
180
181              override,{prescriptive|non-prescriptive}
182
183              When  the  override flag is used, identity assertion takes place
184              even when the database is authorizing for the  identity  of  the
185              client,  i.e. after binding with the provided identity, and thus
186              authenticating it, the proxy  performs  the  identity  assertion
187              using the configured identity and authentication method.
188
189              When  the  prescriptive  flag  is used (the default), operations
190              fail with inappropriateAuthentication for those identities whose
191              assertion is not allowed by the idassert-authzFrom patterns.  If
192              the non-prescriptive flag  is  used,  operations  are  performed
193              anonymously  for those identities whose assertion is not allowed
194              by the idassert-authzFrom patterns.
195
196              This  directive  obsoletes  idassert-authcDN,   idassert-passwd,
197              idassert-mode, and idassert-method.
198
199
200       idle-timeout <time>
201              This  directive  causes  a  cached  connection  to be dropped an
202              recreated after it has been idle for the specified time.
203
204
205       network-timeout <time>
206              Sets the network timeout  value  after  which  poll(2)/select(2)
207              following  a  connect(2)  returns  in  case of no activity.  The
208              value is in seconds, and  it  can  be  specified  as  for  idle-
209              timeout.
210
211
212       protocol-version {0,2,3}
213              This  directive  indicates what protocol version must be used to
214              contact the remote server.  If set to 0 (the default), the proxy
215              uses the same protocol version used by the client, otherwise the
216              requested    protocol    is    used.     The    proxy    returns
217              unwillingToPerform if an operation that is incompatible with the
218              requested protocol is attempted.
219
220
221       proxy-whoami {NO|yes}
222              Turns on proxying of the  WhoAmI  extended  operation.  If  this
223              option  is given, back-ldap will replace slapd's original WhoAmI
224              routine with its own. On slapd sessions that were  authenticated
225              by back-ldap, the WhoAmI request will be forwarded to the remote
226              LDAP server. Other sessions will be handled by the local  slapd,
227              as  before.  This  option  is  mainly useful in conjunction with
228              Proxy Authorization.
229
230
231       rebind-as-user {NO|yes}
232              If this option is  given,  the  client's  bind  credentials  are
233              remembered  for  rebinds,  when  trying to re-establish a broken
234              connection, or when chasing a referral,  if  chase-referrals  is
235              set to yes.
236
237
238       t-f-support {NO|yes|discover}
239              enable  if  the  remote  server  supports  absolute filters (see
240              draft-zeilenga-ldap-t-f  for  details).   If  set  to  discover,
241              support is detected by reading the remote server's root DSE.
242
243
244       timeout [{add|delete|modify|modrdn}=]<val> [...]
245              This  directive  allows  to  set  per-operation timeouts.  If no
246              operation is specified, it affects all.  Currently,  only  write
247              operations  are  addressed,  because  searches  can  already  be
248              limited by means of the limits directive (see slapd.conf(5)  for
249              details),  and  other  operations are not supposed to incur into
250              the need for timeouts.  Note: if the timelimit is exceeded,  the
251              operation  is abandoned; the protocol does not provide any means
252              to rollback the operation, so the client will not  know  if  the
253              operation eventually succeeded or not.
254
255
256       tls {[try-]start|[try-]propagate}
257              execute  the  StartTLS extended operation when the connection is
258              initialized; only works if the URI directive protocol scheme  is
259              not  ldaps://.   propagate issues the StartTLS operation only if
260              the original connection did.   The  try-  prefix  instructs  the
261              proxy  to  continue operations if the StartTLS operation failed;
262              its use is highly deprecated.
263
264

BACKWARD COMPATIBILITY

266       The LDAP backend has been heavily reworked  between  releases  2.2  and
267       2.3;  as  a  side-effect,  some of the traditional directives have been
268       deprecated and should be no longer used, as  they  might  disappear  in
269       future releases.
270
271
272       server <hostname[:port]>
273              this directive is no longer supported.  Use the uri directive as
274              described above.
275
276
277       acl-authcDN <administrative DN for access control purposes>
278              DN which is used to query the target server for acl checking; it
279              is  supposed  to  have  read  access  on  the  target  server to
280              attributes used on the proxy for acl checking.  There is no risk
281              of  giving  away  such  values;  they  are  only  used  to check
282              permissions.  The acl-authcDN identity is by no means implicitly
283              used by the proxy when the client connects anonymously.  See the
284              idassert-* feature instead.  This directive is obsoleted by  the
285              binddn  arg  of  acl-bind  when  bindmethod=simple,  and will be
286              dismissed in the future.
287
288
289       acl-passwd <password>
290              Password  used  with  the  above  acl-authcDN  directive.   This
291              directive  is  obsoleted  by  the  binddn  arg  of acl-bind when
292              bindmethod=simple, and will be dismissed in the future.
293
294
295       idassert-authcDN <administrative DN for proxyAuthz purposes>
296              DN which is used to  propagate  the  client's  identity  to  the
297              target  by  means of the proxyAuthz control when the client does
298              not belong to the DIT fragment that is being  proxied  by  back-
299              ldap.   This  directive  is  obsoleted  by  the  binddn  arg  of
300              idassert-bind when bindmethod=simple, and will be  dismissed  in
301              the future.
302
303
304       idassert-passwd <password>
305              Password  used  with the idassert-authcDN above.  This directive
306              is  obsoleted  by  the  crendentials   of   idassert-bind   when
307              bindmethod=simple, and will be dismissed in the future.
308
309
310       idassert-mode <mode> [<flags>]
311              defines what type of identity assertion is used.  This directive
312              is obsoleted by the mode  arg  of  idassert-bind,  and  will  be
313              dismissed in the future.
314
315
316       idassert-method <method> [<saslargs>]
317              This  directive  is obsoleted by the bindmethod arg of idassert-
318              bind, and will be dismissed in the future.
319
320
321       suffixmassage, map, rewrite*
322              These directives are no longer  supported  by  back-ldap;  their
323              functionality is now delegated to the rwm overlay.  Essentially,
324              add a statement
325
326              overlay rwm
327
328              first, and prefix all rewrite/map statements with rwm- to obtain
329              the original behavior.  See slapo-rwm(5) for details.
330
331

ACCESS CONTROL

333       The  ldap  backend  does  not  honor  all ACL semantics as described in
334       slapd.access(5).  In general,  access  checking  is  delegated  to  the
335       remote  server(s).  Only read (=r) access to the entry pseudo-attribute
336       and to the other attribute values of the entries returned by the search
337       operation is honored, which is performed by the frontend.
338
339

OVERLAYS

341       The  LDAP  backend  provides  basic  proxying  functionalities  to many
342       overlays.  The chain overlay,  described  in  slapo-chain(5),  and  the
343       translucent  overlay,  described  in  slapo-translucent(5),  deserve  a
344       special mention.
345
346       Conversely, there are many overlays that are best used  in  conjunction
347       with  the  LDAP backend.  The proxycache overlay allows caching of LDAP
348       search requests (queries) in a local database.  See slapo-pcache(5) for
349       details.  The rwm overlay provides DN rewrite and attribute/objectClass
350       mapping capabilities to the underlying database.  See slapo-rwm(5)  for
351       details.
352
353

FILES

355       /etc/openldap/slapd.conf
356              default slapd configuration file
357

SEE ALSO

359       slapd.conf(5),    slapd-meta(5),    slapo-chain(5),    slapo-pcache(5),
360       slapo-rwm(5), slapo-translucent(5), slapd(8), ldap(3).
361

AUTHOR

363       Howard Chu, with enhancements by Pierangelo Masarati
364
365
366
367OpenLDAP 2.3.34                    2007/2/16                     SLAPD-LDAP(5)
Impressum