2 # Copyright 2007-2008 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
7 Overlays are software components that provide hooks to functions analogous to
8 those provided by backends, which can be stacked on top of the backend calls
9 and as callbacks on top of backend responses to alter their behavior.
11 Overlays may be compiled statically into {{slapd}}, or when module support
12 is enabled, they may be dynamically loaded. Most of the overlays
13 are only allowed to be configured on individual databases.
15 Some can be stacked on the {{EX:frontend}} as well, for global use. This means that
16 they can be executed after a request is parsed and validated, but right before the
17 appropriate database is selected. The main purpose is to affect operations
18 regardless of the database they will be handled by, and, in some cases,
19 to influence the selection of the database by massaging the request DN.
21 Essentially, overlays represent a means to:
23 * customize the behavior of existing backends without changing the backend
24 code and without requiring one to write a new custom backend with
25 complete functionality
26 * write functionality of general usefulness that can be applied to
27 different backend types
29 When using {{slapd.conf}}(5), overlays that are configured before any other
30 databases are considered global, as mentioned above. In fact they are implicitly
31 stacked on top of the {{EX:frontend}} database. They can also be explicitly
35 > overlay <overlay name>
37 Overlays are usually documented by separate specific man pages in section 5;
38 the naming convention is
40 > slapo-<overlay name>
42 All distributed core overlays have a man page. Feel free to contribute to any,
43 if you think there is anything missing in describing the behavior of the component
44 and the implications of all the related configuration directives.
46 Official overlays are located in
48 > servers/slapd/overlays/
50 That directory also contains the file slapover.txt, which describes the
51 rationale of the overlay implementation, and may serve as a guideline for the
52 development of custom overlays.
54 Contribware overlays are located in
56 > contrib/slapd-modules/<overlay name>/
58 along with other types of run-time loadable components; they are officially
59 distributed, but not maintained by the project.
61 All the current overlays in OpenLDAP are listed and described in detail in the
70 This overlay can record accesses to a given backend database on another
73 This allows all of the activity on a given database to be reviewed using arbitrary
74 LDAP queries, instead of just logging to local flat text files. Configuration
75 options are available for selecting a subset of operation types to log, and to
76 automatically prune older log records from the logging database. Log records
77 are stored with audit schema to assure their readability whether viewed as LDIF
80 It is also used for {{SECT:delta-syncrepl replication}}
82 H3: Access Logging Configuration
84 The following is a basic example that implements Access Logging:
87 > suffix dc=example,dc=com
92 > logold (objectclass=person)
99 > by dn.base="cn=admin,dc=example,dc=com" read
101 The following is an example used for {{SECT:delta-syncrepl replication}}:
104 > suffix cn=accesslog
105 > directory /usr/local/var/openldap-accesslog
106 > rootdn cn=accesslog
108 > index entryCSN,objectClass,reqEnd,reqResult,reqStart
110 Accesslog overlay definitions for the primary db
113 > suffix dc=example,dc=com
119 > # scan the accesslog DB every day, and purge entries older than 7 days
120 > logpurge 07+00:00 01+00:00
122 An example search result against {{B:cn=accesslog}} might look like:
124 > [ghenry@suretec ghenry]# ldapsearch -x -b cn=accesslog
128 > # base <cn=accesslog> with scope subtree
129 > # filter: (objectclass=*)
135 > objectClass: auditContainer
138 > # 20080110163829.000004Z, accesslog
139 > dn: reqStart=20080110163829.000004Z,cn=accesslog
140 > objectClass: auditModify
141 > reqStart: 20080110163829.000004Z
142 > reqEnd: 20080110163829.000005Z
145 > reqAuthzID: cn=admin,dc=suretecsystems,dc=com
146 > reqDN: uid=suretec-46022f8$,ou=Users,dc=suretecsystems,dc=com
148 > reqMod: sambaPwdCanChange:- ###CENSORED###
149 > reqMod: sambaPwdCanChange:+ ###CENSORED###
150 > reqMod: sambaNTPassword:- ###CENSORED###
151 > reqMod: sambaNTPassword:+ ###CENSORED###
152 > reqMod: sambaPwdLastSet:- ###CENSORED###
153 > reqMod: sambaPwdLastSet:+ ###CENSORED###
154 > reqMod: entryCSN:= 20080110163829.095157Z#000000#000#000000
155 > reqMod: modifiersName:= cn=admin,dc=suretecsystems,dc=com
156 > reqMod: modifyTimestamp:= 20080110163829Z
165 For more information, please see {{slapo-accesslog(5)}} and the {{SECT:delta-syncrepl replication}} section.
170 The Audit Logging overlay can be used to record all changes on a given backend database to a specified log file.
174 If the need arises whereby changes need to be logged as standard LDIF, then the auditlog overlay {{B:slapo-auditlog (5)}}
175 can be used. Full examples are available in the man page {{B:slapo-auditlog (5)}}
177 H3: Audit Logging Configuration
179 If the directory is running vi {{F:slapd.d}}, then the following LDIF could be used to add the overlay to the overlay list
180 in {{B:cn=config}} and set what file the {{TERM:LDIF}} gets logged to (adjust to suit)
182 > dn: olcOverlay=auditlog,olcDatabase={1}hdb,cn=config
184 > objectClass: olcOverlayConfig
185 > objectClass: olcAuditLogConfig
186 > olcOverlay: auditlog
187 > olcAuditlogFile: /tmp/auditlog.ldif
190 In this example for testing, we are logging changes to {{F:/tmp/auditlog.ldif}}
192 A typical {{TERM:LDIF}} file created by {{B:slapo-auditlog (5)}} would look like:
194 > # add 1196797576 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com
195 > dn: dc=suretecsystems,dc=com
197 > objectClass: dcObject
198 > objectClass: organization
200 > o: Suretec Systems Ltd.
201 > structuralObjectClass: organization
202 > entryUUID: 1606f8f8-f06e-1029-8289-f0cc9d81e81a
203 > creatorsName: cn=admin,dc=suretecsystems,dc=com
204 > modifiersName: cn=admin,dc=suretecsystems,dc=com
205 > createTimestamp: 20051123130912Z
206 > modifyTimestamp: 20051123130912Z
207 > entryCSN: 20051123130912.000000Z#000001#000#000000
208 > auditContext: cn=accesslog
209 > # end add 1196797576
211 > # add 1196797577 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com
212 > dn: ou=Groups,dc=suretecsystems,dc=com
215 > objectClass: organizationalUnit
217 > structuralObjectClass: organizationalUnit
218 > entryUUID: 160aaa2a-f06e-1029-828a-f0cc9d81e81a
219 > creatorsName: cn=admin,dc=suretecsystems,dc=com
220 > modifiersName: cn=admin,dc=suretecsystems,dc=com
221 > createTimestamp: 20051123130912Z
222 > modifyTimestamp: 20051123130912Z
223 > entryCSN: 20051123130912.000000Z#000002#000#000000
224 > # end add 1196797577
232 The chain overlay provides basic chaining capability to the underlying
235 What is chaining? It indicates the capability of a DSA to follow referrals on
236 behalf of the client, so that distributed systems are viewed as a single
237 virtual DSA by clients that are otherwise unable to "chase" (i.e. follow)
238 referrals by themselves.
240 The chain overlay is built on top of the ldap backend; it is compiled by
241 default when {{B:--enable-ldap}}.
244 H3: Chaining Configuration
246 In order to demonstrate how this overlay works, we shall discuss a typical
247 scenario which might be one master server and three Syncrepl slaves.
249 On each replica, add this near the top of the {{slapd.conf}}(5) file
250 (global), before any database definitions:
253 > chain-uri "ldap://ldapmaster.example.com"
254 > chain-idassert-bind bindmethod="simple"
255 > binddn="cn=Manager,dc=example,dc=com"
256 > credentials="<secret>"
259 > chain-return-error TRUE
261 Add this below your {{syncrepl}} statement:
263 > updateref "ldap://ldapmaster.example.com/"
265 The {{B:chain-tls}} statement enables TLS from the slave to the ldap master.
266 The DITs are exactly the same between these machines, therefore whatever user
267 bound to the slave will also exist on the master. If that DN does not have
268 update privileges on the master, nothing will happen.
270 You will need to restart the slave after these {{slapd.conf}} changes.
271 Then, if you are using {{loglevel stats}} (256), you can monitor an
272 {{ldapmodify}} on the slave and the master. (If you're using {{cn=config}}
273 no restart is required.)
275 Now start an {{ldapmodify}} on the slave and watch the logs. You should expect
278 > Sep 6 09:27:25 slave1 slapd[29274]: conn=11 fd=31 ACCEPT from IP=143.199.102.216:45181 (IP=143.199.102.216:389)
279 > Sep 6 09:27:25 slave1 slapd[29274]: conn=11 op=0 STARTTLS
280 > Sep 6 09:27:25 slave1 slapd[29274]: conn=11 op=0 RESULT oid= err=0 text=
281 > Sep 6 09:27:25 slave1 slapd[29274]: conn=11 fd=31 TLS established tls_ssf=256 ssf=256
282 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 BIND dn="uid=user1,ou=people,dc=example,dc=com" method=128
283 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 BIND dn="uid=user1,ou=People,dc=example,dc=com" mech=SIMPLE ssf=0
284 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 RESULT tag=97 err=0 text=
285 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD dn="uid=user1,ou=People,dc=example,dc=com"
286 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD attr=mail
287 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 RESULT tag=103 err=0 text=
288 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=3 UNBIND
289 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 fd=31 closed
290 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: LDAP_RES_SEARCH_ENTRY(LDAP_SYNC_MODIFY)
291 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_search (0)
292 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: uid=user1,ou=People,dc=example,dc=com
293 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_modify (0)
295 And on the master you will see this:
297 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 PROXYAUTHZ dn="uid=user1,ou=people,dc=example,dc=com"
298 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD dn="uid=user1,ou=People,dc=example,dc=com"
299 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD attr=mail
300 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 RESULT tag=103 err=0 text=
302 Note: You can clearly see the PROXYAUTHZ line on the master, indicating the
303 proper identity assertion for the update on the master. Also note the slave
304 immediately receiving the Syncrepl update from the master.
306 H3: Handling Chaining Errors
308 By default, if chaining fails, the original referral is returned to the client
309 under the assumption that the client might want to try and follow the referral.
311 With the following directive however, if the chaining fails at the provider
312 side, the actual error is returned to the client.
314 > chain-return-error TRUE
322 This overlay enforces a regular expression constraint on all values
323 of specified attributes during an LDAP modify request that contains add or modify
324 commands. It is used to enforce a more rigorous syntax when the underlying attribute
325 syntax is too general.
328 H3: Constraint Configuration
330 Configuration via {{slapd.conf}}(5) would look like:
333 > constraint_attribute mail regex ^[:alnum:]+@mydomain.com$
334 > constraint_attribute title uri
335 > ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
337 A specification like the above would reject any {{mail}} attribute which did not
338 look like {{<alpha-numeric string>@mydomain.com}}.
340 It would also reject any title attribute whose values were not listed in the
341 title attribute of any {{titleCatalog}} entries in the given scope.
343 An example for use with {{cn=config}}:
345 > dn: olcOverlay=constraint,olcDatabase={1}hdb,cn=config
347 > objectClass: olcOverlayConfig
348 > objectClass: olcConstraintConfig
349 > olcOverlay: constraint
350 > olcConstraintAttribute: mail regex ^[:alnum:]+@mydomain.com$
351 > olcConstraintAttribute: title uri ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
354 H2: Dynamic Directory Services
359 The {{dds}} overlay to {{slapd}}(8) implements dynamic objects as per {{REF:RFC2589}}.
360 The name {{dds}} stands for Dynamic Directory Services. It allows to define
361 dynamic objects, characterized by the {{dynamicObject}} objectClass.
363 Dynamic objects have a limited lifetime, determined by a time-to-live (TTL)
364 that can be refreshed by means of a specific refresh extended operation. This
365 operation allows to set the Client Refresh Period (CRP), namely the period
366 between refreshes that is required to preserve the dynamic object from expiration.
367 The expiration time is computed by adding the requested TTL to the current time.
368 When dynamic objects reach the end of their lifetime without being further
369 refreshed, they are automatically {{deleted}}. There is no guarantee of immediate
370 deletion, so clients should not count on it.
372 H3: Dynamic Directory Service Configuration
374 A usage of dynamic objects might be to implement dynamic meetings; in this case,
375 all the participants to the meeting are allowed to refresh the meeting object,
376 but only the creator can delete it (otherwise it will be deleted when the TTL expires).
378 If we add the overlay to an example database, specifying a Max TTL of 1 day, a
379 min of 10 seconds, with a default TTL of 1 hour. We'll also specify an interval
380 of 120 (less than 60s might be too small) seconds between expiration checks and a
381 tolerance of 5 second (lifetime of a dynamic object will be {{entryTtl + tolerance}}).
392 > entryExpireTimestamp
394 Creating a meeting is as simple as adding the following:
396 > dn: cn=OpenLDAP Documentation Meeting,ou=Meetings,dc=example,dc=com
397 > objectClass: groupOfNames
398 > objectClass: dynamicObject
399 > cn: OpenLDAP Documentation Meeting
400 > member: uid=ghenry,ou=People,dc=example,dc=com
401 > member: uid=hyc,ou=People,dc=example,dc=com
403 H4: Dynamic Directory Service ACLs
405 Allow users to start a meeting and to join it; restrict refresh to the {{member}};
406 restrict delete to the creator:
408 > access to attrs=userPassword
412 > access to dn.base="ou=Meetings,dc=example,dc=com"
416 > access to dn.onelevel="ou=Meetings,dc=example,dc=com"
418 > by dnattr=creatorsName write
421 > access to dn.onelevel="ou=Meetings,dc=example,dc=com"
423 > by dnattr=creatorsName write
427 > access to dn.onelevel="ou=Meetings,dc=example,dc=com"
429 > by dnattr=member manage
432 In simple terms, the user who created the {{OpenLDAP Documentation Meeting}} can add new attendees,
433 refresh the meeting using (basically complete control):
435 > ldapexop -x -H ldap://ldaphost "refresh" "cn=OpenLDAP Documentation Meeting,ou=Meetings,dc=example,dc=com" "120" -D "uid=ghenry,ou=People,dc=example,dc=com" -W
437 Any user can join the meeting, but not add another attendee, but they can refresh the meeting. The ACLs above are quite straight forward to understand.
444 This overlay extends the Compare operation to detect
445 members of a dynamic group. This overlay is now deprecated
446 as all of its functions are available using the
447 {{SECT:Dynamic Lists}} overlay.
450 H3: Dynamic Group Configuration
458 This overlay allows expansion of dynamic groups and lists. Instead of having the
459 group members or list attributes hard coded, this overlay allows us to define
460 an LDAP search whose results will make up the group or list.
462 H3: Dynamic List Configuration
464 This module can behave both as a dynamic list and dynamic group, depending on
465 the configuration. The syntax is as follows:
468 > dynlist-attrset <group-oc> <URL-ad> [member-ad]
470 The parameters to the {{F:dynlist-attrset}} directive have the following meaning:
471 * {{F:<group-oc>}}: specifies which object class triggers the subsequent LDAP search.
472 Whenever an entry with this object class is retrieved, the search is performed.
473 * {{F:<URL-ad>}}: is the name of the attribute which holds the search URI. It
474 has to be a subtype of {{F:labeledURI}}. The attributes and values present in
475 the search result are added to the entry unless {{F:member-ad}} is used (see
477 * {{F:member-ad}}: if present, changes the overlay behavior into a dynamic group.
478 Instead of inserting the results of the search in the entry, the distinguished name
479 of the results are added as values of this attribute.
481 Here is an example which will allow us to have an email alias which automatically
482 expands to all user's emails according to our LDAP filter:
484 In {{slapd.conf}}(5):
486 > dynlist-attrset nisMailAlias labeledURI
488 This means that whenever an entry which has the {{F:nisMailAlias}} object class is
489 retrieved, the search specified in the {{F:labeledURI}} attribute is performed.
491 Let's say we have this entry in our directory:
492 > cn=all,ou=aliases,dc=example,dc=com
494 > objectClass: nisMailAlias
495 > labeledURI: ldap:///ou=People,dc=example,dc=com?mail?one?(objectClass=inetOrgPerson)
497 If this entry is retrieved, the search specified in {{F:labeledURI}} will be
498 performed and the results will be added to the entry just as if they have always
499 been there. In this case, the search filter selects all entries directly
500 under {{F:ou=People}} that have the {{F:inetOrgPerson}} object class and retrieves
501 the {{F:mail}} attribute, if it exists.
503 This is what gets added to the entry when we have two users under {{F:ou=People}}
504 that match the filter:
505 !import "allmail-en.png"; align="center"; title="Dynamic list for email aliases"
506 FT[align="Center"] Figure X.Y: Dynamic List for all emails
508 The configuration for a dynamic group is similar. Let's see an example which would
509 automatically populate an {{F:allusers}} group with all the user accounts in the
512 In {{F:slapd.conf}}(5):
514 > dynlist-attrset groupOfNames labeledURI member
516 Let's apply it to the following entry:
517 > cn=allusers,ou=group,dc=example,dc=com
519 > objectClass: groupOfNames
520 > labeledURI: ldap:///ou=people,dc=example,dc=com??one?(objectClass=inetOrgPerson)
522 The behavior is similar to the dynamic list configuration we had before:
523 whenever an entry with the {{F:groupOfNames}} object class is retrieved, the
524 search specified in the {{F:labeledURI}} attribute is performed. But this time,
525 only the distinguished names of the results are added, and as values of the
526 {{F:member}} attribute.
529 !import "allusersgroup-en.png"; align="center"; title="Dynamic group for all users"
530 FT[align="Center"] Figure X.Y: Dynamic Group for all users
532 Note that a side effect of this scheme of dynamic groups is that the members
533 need to be specified as full DNs. So, if you are planning in using this for
534 {{F:posixGroup}}s, be sure to use RFC2307bis and some attribute which can hold
535 distinguished names. The {{F:memberUid}} attribute used in the {{F:posixGroup}}
536 object class can hold only names, not DNs, and is therefore not suitable for
539 H2: Reverse Group Membership Maintenance
543 In some scenarios, it may be desirable for a client to be able to determine
544 which groups an entry is a member of, without performing an additional search.
545 Examples of this are applications using the {{TERM:DIT}} for access control
546 based on group authorization.
548 The {{B:memberof}} overlay updates an attribute (by default {{B:memberOf}}) whenever
549 changes occur to the membership attribute (by default {{B:member}}) of entries of the
550 objectclass (by default {{B:groupOfNames}}) configured to trigger updates.
552 Thus, it provides maintenance of the list of groups an entry is a member of,
553 when usual maintenance of groups is done by modifying the members on the group
556 H3: Member Of Configuration
558 The typical use of this overlay requires just enabling the overlay for a
559 specific database. For example, with the following minimal slapd.conf:
561 > include /usr/share/openldap/schema/core.schema
562 > include /usr/share/openldap/schema/cosine.schema
563 > modulepath /usr/lib/openldap
564 > moduleload memberof.la
565 > authz-regexp "gidNumber=0\\\+uidNumber=0,cn=peercred,cn=external,cn=auth"
566 > "cn=Manager,dc=example,dc=com"
568 > suffix "dc=example,dc=com"
569 > rootdn "cn=Manager,dc=example,dc=com"
571 > directory /var/lib/ldap2.4
573 > index objectClass eq
578 adding the following ldif:
581 > dn: dc=example,dc=com
582 > objectclass: domain
585 > dn: ou=Group,dc=example,dc=com
586 > objectclass: organizationalUnit
589 > dn: ou=People,dc=example,dc=com
590 > objectclass: organizationalUnit
593 > dn: uid=test1,ou=People,dc=example,dc=com
594 > objectclass: account
597 > dn: cn=testgroup,ou=Group,dc=example,dc=com
598 > objectclass: groupOfNames
600 > member: uid=test1,ou=People,dc=example,dc=com
602 Results in the following output from a search on the test1 user:
604 > # ldapsearch -LL -Y EXTERNAL -H ldapi:/// "(uid=test1)" -b dc=example,dc=com memberOf
605 > SASL/EXTERNAL authentication started
606 > SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
610 > dn: uid=test1,ou=People,dc=example,dc=com
611 > memberOf: cn=testgroup,ou=Group,dc=example,dc=com
613 Note that the {{B:memberOf}} attribute is an operational attribute, so it must be
614 requested explicitly.
617 H2: The Proxy Cache Engine
619 {{TERM:LDAP}} servers typically hold one or more subtrees of a
620 {{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of
621 entries held by one or more master servers. Changes are propagated
622 from the master server to replica (slave) servers using LDAP Sync
623 replication. An LDAP cache is a special type of replica which holds
624 entries corresponding to search filters instead of subtrees.
628 The proxy cache extension of slapd is designed to improve the
629 responsiveness of the ldap and meta backends. It handles a search
631 by first determining whether it is contained in any cached search
632 filter. Contained requests are answered from the proxy cache's local
633 database. Other requests are passed on to the underlying ldap or
634 meta backend and processed as usual.
636 E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
637 {{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}
639 Correct matching rules and syntaxes are used while comparing
640 assertions for query containment. To simplify the query containment
641 problem, a list of cacheable "templates" (defined below) is specified
642 at configuration time. A query is cached or answered only if it
643 belongs to one of these templates. The entries corresponding to
644 cached queries are stored in the proxy cache local database while
645 its associated meta information (filter, scope, base, attributes)
646 is stored in main memory.
648 A template is a prototype for generating LDAP search requests.
649 Templates are described by a prototype search filter and a list of
650 attributes which are required in queries generated from the template.
651 The representation for prototype filter is similar to {{REF:RFC4515}},
652 except that the assertion values are missing. Examples of prototype
653 filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by
654 search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively.
656 The cache replacement policy removes the least recently used (LRU)
657 query and entries belonging to only that query. Queries are allowed
658 a maximum time to live (TTL) in the cache thus providing weak
659 consistency. A background task periodically checks the cache for
660 expired queries and removes them.
662 The Proxy Cache paper
663 ({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
664 design and implementation details.
667 H3: Proxy Cache Configuration
669 The cache configuration specific directives described below must
670 appear after a {{EX:overlay proxycache}} directive within a
671 {{EX:"database meta"}} or {{EX:database ldap}} section of
672 the server's {{slapd.conf}}(5) file.
674 H4: Setting cache parameters
676 > proxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period>
678 This directive enables proxy caching and sets general cache
679 parameters. The <DB> parameter specifies which underlying database
680 is to be used to hold cached entries. It should be set to
681 {{EX:bdb}} or {{EX:hdb}}. The <maxentries> parameter specifies the
682 total number of entries which may be held in the cache. The
683 <nattrsets> parameter specifies the total number of attribute sets
684 (as specified by the {{EX:proxyAttrSet}} directive) that may be
685 defined. The <entrylimit> parameter specifies the maximum number of
686 entries in a cacheable query. The <period> specifies the consistency
687 check period (in seconds). In each period, queries with expired
690 H4: Defining attribute sets
692 > proxyAttrset <index> <attrs...>
694 Used to associate a set of attributes to an index. Each attribute
695 set is associated with an index number from 0 to <numattrsets>-1.
696 These indices are used by the proxyTemplate directive to define
699 H4: Specifying cacheable templates
701 > proxyTemplate <prototype_string> <attrset_index> <TTL>
703 Specifies a cacheable template and the "time to live" (in sec) <TTL>
704 for queries belonging to the template. A template is described by
705 its prototype filter string and set of required attributes identified
711 An example {{slapd.conf}}(5) database section for a caching server
712 which proxies for the {{EX:"dc=example,dc=com"}} subtree held
713 at server {{EX:ldap.example.com}}.
716 > suffix "dc=example,dc=com"
717 > rootdn "dc=example,dc=com"
718 > uri ldap://ldap.example.com/
720 > proxycache bdb 100000 1 1000 100
721 > proxyAttrset 0 mail postaladdress telephonenumber
722 > proxyTemplate (sn=) 0 3600
723 > proxyTemplate (&(sn=)(givenName=)) 0 3600
724 > proxyTemplate (&(departmentNumber=)(secretary=*)) 0 3600
727 > directory ./testrun/db.2.a
728 > index objectClass eq
729 > index cn,sn,uid,mail pres,eq,sub
732 H5: Cacheable Queries
734 A LDAP search query is cacheable when its filter matches one of the
735 templates as defined in the "proxyTemplate" statements and when it references
736 only the attributes specified in the corresponding attribute set.
737 In the example above the attribute set number 0 defines that only the
738 attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
743 > Filter: (&(sn=Richard*)(givenName=jack))
744 > Attrs: mail telephoneNumber
746 is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
747 attributes are contained in proxyAttrset 0.
749 > Filter: (&(sn=Richard*)(telephoneNumber))
752 is not cacheable, because the filter does not match the template,
753 nor is the attribute givenName stored in the cache
755 > Filter: (|(sn=Richard*)(givenName=jack))
756 > Attrs: mail telephoneNumber
758 is not cacheable, because the filter does not match the template ( logical
759 OR "|" condition instead of logical AND "&" )
762 H2: Password Policies
767 This overlay follows the specifications contained in the draft RFC titled
768 draft-behera-ldap-password-policy-09. While the draft itself is expired, it has
769 been implemented in several directory servers, including slapd. Nonetheless,
770 it is important to note that it is a draft, meaning that it is subject to change
771 and is a work-in-progress.
773 The key abilities of the password policy overlay are as follows:
775 * Enforce a minimum length for new passwords
776 * Make sure passwords are not changed too frequently
777 * Cause passwords to expire, provide warnings before they need to be changed, and allow a fixed number of 'grace' logins to allow them to be changed after they have expired
778 * Maintain a history of passwords to prevent password re-use
779 * Prevent password guessing by locking a password for a specified period of time after repeated authentication failures
780 * Force a password to be changed at the next authentication
781 * Set an administrative lock on an account
782 * Support multiple password policies on a default or a per-object basis.
783 * Perform arbitrary quality checks using an external loadable module. This is a non-standard extension of the draft RFC.
786 H3: Password Policy Configuration
788 Instantiate the module in the database where it will be used, after adding the
789 new ppolicy schema and loading the ppolicy module. The following example shows
790 the ppolicy module being added to the database that handles the naming
791 context "dc=example,dc=com". In this example we are also specifying the DN of
792 a policy object to use if none other is specified in a user's object.
795 > suffix "dc=example,dc=com"
796 > [...additional database configuration directives go here...]
799 > ppolicy_default "cn=default,ou=policies,dc=example,dc=com"
802 Now we need a container for the policy objects. In our example the password
803 policy objects are going to be placed in a section of the tree called
804 "ou=policies,dc=example,dc=com":
806 > dn: ou=policies,dc=example,dc=com
807 > objectClass: organizationalUnit
812 The default policy object that we are creating defines the following policies:
814 * The user is allowed to change his own password. Note that the directory ACLs for this attribute can also affect this ability (pwdAllowUserChange: TRUE).
815 * The name of the password attribute is "userPassword" (pwdAttribute: userPassword). Note that this is the only value that is accepted by OpenLDAP for this attribute.
816 * The server will check the syntax of the password. If the server is unable to check the syntax (i.e., it was hashed or otherwise encoded by the client) it will return an error refusing the password (pwdCheckQuality: 2).
817 * When a client includes the Password Policy Request control with a bind request, the server will respond with a password expiration warning if it is going to expire in ten minutes or less (pwdExpireWarning: 600). The warnings themselves are returned in a Password Policy Response control.
818 * When the password for a DN has expired, the server will allow five additional "grace" logins (pwdGraceAuthNLimit: 5).
819 * The server will maintain a history of the last five passwords that were used for a DN (pwdInHistory: 5).
820 * The server will lock the account after the maximum number of failed bind attempts has been exceeded (pwdLockout: TRUE).
821 * When the server has locked an account, the server will keep it locked until an administrator unlocks it (pwdLockoutDuration: 0)
822 * The server will reset its failed bind count after a period of 30 seconds.
823 * Passwords will not expire (pwdMaxAge: 0).
824 * Passwords can be changed as often as desired (pwdMinAge: 0).
825 * Passwords must be at least 5 characters in length (pwdMinLength: 5).
826 * The password does not need to be changed at the first bind or when the administrator has reset the password (pwdMustChange: FALSE)
827 * The current password does not need to be included with password change requests (pwdSafeModify: FALSE)
828 * The server will only allow five failed binds in a row for a particular DN (pwdMaxFailure: 5).
831 The actual policy would be:
833 > dn: cn=default,ou=policies,dc=example,dc=com
835 > objectClass: pwdPolicy
836 > objectClass: person
838 > pwdAllowUserChange: TRUE
839 > pwdAttribute: userPassword
841 > pwdExpireWarning: 600
842 > pwdFailureCountInterval: 30
843 > pwdGraceAuthNLimit: 5
846 > pwdLockoutDuration: 0
851 > pwdMustChange: FALSE
852 > pwdSafeModify: FALSE
855 You can create additional policy objects as needed.
858 There are two ways password policy can be applied to individual objects:
860 1. Default password policy - If, as in the example above, the password policy
861 module was configured with the DN of a default policy object and if that object
862 exists, then the policy defined in that object is applied.
864 2. The pwdPolicySubentry in a user's object - If a user's object contains a
865 value for the pwdPolicySubEntry attribute, and if that object exists, then
866 the policy defined by that object is applied. Remember that we need to add
867 object class pwdPolicy to the user's object as well.
869 Please see {{slapo-ppolicy(5)}} for complete explanations of features and discussion of
870 "Password Management Issues" at {{URL:http://www.connexitor.com/forums/viewtopic.php?f=6&t=25}}
874 H2: Referential Integrity
879 This overlay can be used with a backend database such as slapd-bdb(5)
880 to maintain the cohesiveness of a schema which utilizes reference
883 Whenever a {{modrdn}} or {{delete}} is performed, that is, when an entry's DN
884 is renamed or an entry is removed, the server will search the directory for
885 references to this DN (in selected attributes: see below) and update them
886 accordingly. If it was a {{delete}} operation, the reference is deleted. If it
887 was a {{modrdn}} operation, then the reference is updated with the new DN.
889 For example, a very common administration task is to maintain group membership
890 lists, specially when users are removed from the directory. When an
891 user account is deleted or renamed, all groups this user is a member of have to be
892 updated. LDAP administrators usually have scripts for that. But we can use the
893 {{F:refint}} overlay to automate this task. In this example, if the user is
894 removed from the directory, the overlay will take care to remove the user from
895 all the groups he/she was a member of. No more scripting for this.
897 H3: Referential Integrity Configuration
899 The configuration for this overlay is as follows:
901 > refint_attributes <attribute [attribute ...]>
902 > refint_nothing <string>
904 * {{F:refint_attributes}}: this parameter specifies a space separated list of
905 attributes which will have the referential integrity maintained. When an entry is
906 removed or has its DN renamed, the server will do an internal search for any of the
907 {{F:refint_attributes}} that point to the affected DN and update them accordingly. IMPORTANT:
908 the attributes listed here must have the {{F:distinguishedName}} syntax, that is,
910 * {{F:refint_nothing}}: some times, while trying to maintain the referential
911 integrity, the server has to remove the last attribute of its kind from an
912 entry. This may be prohibited by the schema: for example, the
913 {{F:groupOfNames}} object class requires at least one member. In these cases,
914 the server will add the attribute value specified in {{F:refint_nothing}}
917 To illustrate this overlay, we will use the group membership scenario.
921 > refint_attributes member
922 > refint_nothing "cn=admin,dc=example,dc=com"
924 This configuration tells the overlay to maintain the referential integrity of the {{F:member}}
925 attribute. This attribute is used in the {{F:groupOfNames}} object class which always needs
926 a member, so we add the {{F:refint_nothing}} directive to fill in the group with a standard
927 member should all the members vanish.
929 If we have the following group membership, the refint overlay will
930 automatically remove {{F:john}} from the group if his entry is removed from the
933 !import "refint.png"; align="center"; title="Group membership"
934 FT[align="Center"] Figure X.Y: Maintaining referential integrity in groups
936 Notice that if we rename ({{F:modrdn}}) the {{F:john}} entry to, say, {{F:jsmith}}, the refint
937 overlay will also rename the reference in the {{F:member}} attribute, so the group membership
940 If we removed all users from the directory who are a member of this group, then the end result
941 would be a single member in the group: {{F:cn=admin,dc=example,dc=com}}. This is the
942 {{F:refint_nothing}} parameter kicking into action so that the schema is not violated.
949 This overlay is useful to test the behavior of clients when
950 server-generated erroneous and/or unusual responses occur.
953 H3: Return Code Configuration
961 It performs basic DN/data rewrite and
962 objectClass/attributeType mapping.
965 H3: Rewrite/Remap Configuration
973 This overlay implements the provider-side support for syncrepl
974 replication, including persistent search functionality
977 H3: Sync Provider Configuration
980 H2: Translucent Proxy
985 This overlay can be used with a backend database such as slapd-bdb (5)
986 to create a "translucent proxy".
988 Content of entries retrieved from a remote LDAP server can be partially
989 overridden by the database.
992 H3: Translucent Proxy Configuration
995 H2: Attribute Uniqueness
1000 This overlay can be used with a backend database such as slapd-bdb (5)
1001 to enforce the uniqueness of some or all attributes within a subtree.
1004 H3: Attribute Uniqueness Configuration
1012 This overlay can be used to enforce a specific order for the values
1013 of an attribute when it is returned in a search.
1016 H3: Value Sorting Configuration
1019 H2: Overlay Stacking
1024 Overlays can be stacked, which means that more than one overlay
1025 can be instantiated for each database, or for the {{EX:frontend}}.
1026 As a consequence, each overlays function is called, if defined,
1027 when overlay execution is invoked.
1028 Multiple overlays are executed in reverse order (as a stack)
1029 with respect to their definition in slapd.conf (5), or with respect
1030 to their ordering in the config database, as documented in slapd-config (5).
1033 H3: Example Scenarios