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, but some
14 may also be configured globally.
16 Essentially, they represent a means to:
18 * customize the behavior of existing backends without changing the backend
19 code and without requiring one to write a new custom backend with
20 complete functionality
21 * write functionality of general usefulness that can be applied to
22 different backend types
24 Overlays are usually documented by separate specific man pages in section 5;
25 the naming convention is
27 > slapo-<overlay name>
29 All distributed core overlays have a man page. Feel free to contribute to any,
30 if you think there is anything missing in describing the behavior of the component
31 and the implications of all the related configuration directives.
33 Official overlays are located in
35 > servers/slapd/overlays/
37 That directory also contains the file slapover.txt, which describes the
38 rationale of the overlay implementation, and may serve as guideline for the
39 development of custom overlays.
41 Contribware overlays are located in
43 > contrib/slapd-modules/<overlay name>/
45 along with other types of run-time loadable components; they are officially
46 distributed, but not maintained by the project.
48 They can be stacked on the frontend as well; this means that they can be
49 executed after a request is parsed and validated, but right before the
50 appropriate database is selected. The main purpose is to affect operations
51 regardless of the database they will be handled by, and, in some cases,
52 to influence the selection of the database by massaging the request DN.
54 All the current overlays in 2.4 are listed and described in detail in the
63 This overlay can record accesses to a given backend database on another
66 This allows all of the activity on a given database to be reviewed using arbitrary
67 LDAP queries, instead of just logging to local flat text files. Configuration
68 options are available for selecting a subset of operation types to log, and to
69 automatically prune older log records from the logging database. Log records
70 are stored with audit schema to assure their readability whether viewed as LDIF
73 It is also used for {{SECT:delta-syncrepl replication}}
75 H3: Access Logging Configuration
77 The following is a basic example that implements Access Logging:
80 > suffix dc=example,dc=com
85 > logold (objectclass=person)
92 > by dn.base="cn=admin,dc=example,dc=com" read
94 The following is an example used for {{SECT:delta-syncrepl replication}}:
98 > directory /usr/local/var/openldap-accesslog
101 > index entryCSN,objectClass,reqEnd,reqResult,reqStart
103 Accesslog overlay definitions for the primary db
106 > suffix dc=example,dc=com
112 > # scan the accesslog DB every day, and purge entries older than 7 days
113 > logpurge 07+00:00 01+00:00
115 An example search result against {{B:cn=accesslog}} might look like:
117 > [ghenry@suretec ghenry]# ldapsearch -x -b cn=accesslog
121 > # base <cn=accesslog> with scope subtree
122 > # filter: (objectclass=*)
128 > objectClass: auditContainer
131 > # 20080110163829.000004Z, accesslog
132 > dn: reqStart=20080110163829.000004Z,cn=accesslog
133 > objectClass: auditModify
134 > reqStart: 20080110163829.000004Z
135 > reqEnd: 20080110163829.000005Z
138 > reqAuthzID: cn=admin,dc=suretecsystems,dc=com
139 > reqDN: uid=suretec-46022f8$,ou=Users,dc=suretecsystems,dc=com
141 > reqMod: sambaPwdCanChange:- ###CENSORED###
142 > reqMod: sambaPwdCanChange:+ ###CENSORED###
143 > reqMod: sambaNTPassword:- ###CENSORED###
144 > reqMod: sambaNTPassword:+ ###CENSORED###
145 > reqMod: sambaPwdLastSet:- ###CENSORED###
146 > reqMod: sambaPwdLastSet:+ ###CENSORED###
147 > reqMod: entryCSN:= 20080110163829.095157Z#000000#000#000000
148 > reqMod: modifiersName:= cn=admin,dc=suretecsystems,dc=com
149 > reqMod: modifyTimestamp:= 20080110163829Z
158 For more information, please see {{slapo-accesslog(5)}} and the {{SECT:delta-syncrepl replication}} section.
163 The Audit Logging overlay can be used to record all changes on a given backend database to a specified log file.
167 If the need arises whereby changes need to be logged as standard LDIF, then the auditlog overlay {{B:slapo-auditlog (5)}}
168 can be used. Full examples are available in the man page {{B:slapo-auditlog (5)}}
170 H3: Audit Logging Configuration
172 If the directory is running vi {{F:slapd.d}}, then the following LDIF could be used to add the overlay to the overlay list
173 in {{B:cn=config}} and set what file the {{TERM:LDIF}} gets logged to (adjust to suit)
175 > dn: olcOverlay=auditlog,olcDatabase={1}hdb,cn=config
177 > objectClass: olcOverlayConfig
178 > objectClass: olcAuditLogConfig
179 > olcOverlay: auditlog
180 > olcAuditlogFile: /tmp/auditlog.ldif
183 In this example for testing, we are logging changes to {{F:/tmp/auditlog.ldif}}
185 A typical {{TERM:LDIF}} file created by {{B:slapo-auditlog (5)}} would look like:
187 > # add 1196797576 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com
188 > dn: dc=suretecsystems,dc=com
190 > objectClass: dcObject
191 > objectClass: organization
193 > o: Suretec Systems Ltd.
194 > structuralObjectClass: organization
195 > entryUUID: 1606f8f8-f06e-1029-8289-f0cc9d81e81a
196 > creatorsName: cn=admin,dc=suretecsystems,dc=com
197 > modifiersName: cn=admin,dc=suretecsystems,dc=com
198 > createTimestamp: 20051123130912Z
199 > modifyTimestamp: 20051123130912Z
200 > entryCSN: 20051123130912.000000Z#000001#000#000000
201 > auditContext: cn=accesslog
202 > # end add 1196797576
204 > # add 1196797577 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com
205 > dn: ou=Groups,dc=suretecsystems,dc=com
208 > objectClass: organizationalUnit
210 > structuralObjectClass: organizationalUnit
211 > entryUUID: 160aaa2a-f06e-1029-828a-f0cc9d81e81a
212 > creatorsName: cn=admin,dc=suretecsystems,dc=com
213 > modifiersName: cn=admin,dc=suretecsystems,dc=com
214 > createTimestamp: 20051123130912Z
215 > modifyTimestamp: 20051123130912Z
216 > entryCSN: 20051123130912.000000Z#000002#000#000000
217 > # end add 1196797577
225 The chain overlay provides basic chaining capability to the underlying
228 What is chaining? It indicates the capability of a DSA to follow referrals on
229 behalf of the client, so that distributed systems are viewed as a single
230 virtual DSA by clients that are otherwise unable to "chase" (i.e. follow)
231 referrals by themselves.
233 The chain overlay is built on top of the ldap backend; it is compiled by
234 default when {{B:--enable-ldap}}.
237 H3: Chaining Configuration
239 In order to demonstrate how this overlay works, we shall discuss a typical
240 scenario which might be one master server and three Syncrepl slaves.
242 On each replica, add this near the top of the file (global), before any database
246 > chain-uri "ldap://ldapmaster.example.com"
247 > chain-idassert-bind bindmethod="simple"
248 > binddn="cn=Manager,dc=example,dc=com"
249 > credentials="<secret>"
252 > chain-return-error TRUE
254 Add this below your {{syncrepl}} statement:
256 > updateref "ldap://ldapmaster.example.com/"
258 The {{B:chain-tls}} statement enables TLS from the slave to the ldap master.
259 The DITs are exactly the same between these machines, therefore whatever user
260 bound to the slave will also exist on the master. If that DN does not have
261 update privileges on the master, nothing will happen.
263 You will need to restart the slave after these changes. Then, if you are using
264 {{loglevel stats}} (256), you can monitor an {{ldapmodify}} on the slave and the master.
266 Now start an {{ldapmodify}} on the slave and watch the logs. You should expect
269 > 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)
270 > Sep 6 09:27:25 slave1 slapd[29274]: conn=11 op=0 STARTTLS
271 > Sep 6 09:27:25 slave1 slapd[29274]: conn=11 op=0 RESULT oid= err=0 text=
272 > Sep 6 09:27:25 slave1 slapd[29274]: conn=11 fd=31 TLS established tls_ssf=256 ssf=256
273 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 BIND dn="uid=user1,ou=people,dc=example,dc=com" method=128
274 > 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
275 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 RESULT tag=97 err=0 text=
276 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD dn="uid=user1,ou=People,dc=example,dc=com"
277 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD attr=mail
278 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 RESULT tag=103 err=0 text=
279 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=3 UNBIND
280 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 fd=31 closed
281 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: LDAP_RES_SEARCH_ENTRY(LDAP_SYNC_MODIFY)
282 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_search (0)
283 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: uid=user1,ou=People,dc=example,dc=com
284 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_modify (0)
286 And on the master you will see this:
288 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 PROXYAUTHZ dn="uid=user1,ou=people,dc=example,dc=com"
289 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD dn="uid=user1,ou=People,dc=example,dc=com"
290 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD attr=mail
291 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 RESULT tag=103 err=0 text=
293 Note: You can clearly see the PROXYAUTHZ line on the master, indicating the
294 proper identity assertion for the update on the master. Also note the slave
295 immediately receiving the Syncrepl update from the master.
297 H3: Handling Chaining Errors
299 By default, if chaining fails, the original referral is returned to the client
300 under the assumption that the client might want to try and follow the referral.
302 With the following directive however, if the chaining fails at the provider
303 side, the actual error is returned to the client.
305 > chain-return-error TRUE
313 This overlay enforces a regular expression constraint on all values
314 of specified attributes during an LDAP modify request that contains add or modify
315 commands. It is used to enforce a more rigorous syntax when the underlying attribute
316 syntax is too general.
319 H3: Constraint Configuration
321 Configuration via {{slapd.conf}}(5) would look like:
324 > constraint_attribute mail regex ^[:alnum:]+@mydomain.com$
325 > constraint_attribute title uri
326 > ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
328 A specification like the above would reject any {{mail}} attribute which did not
329 look like {{<alpha-numeric string>@mydomain.com}}.
331 It would also reject any title attribute whose values were not listed in the
332 title attribute of any {{titleCatalog}} entries in the given scope.
334 An example for use with {{cn=config}}:
336 > dn: olcOverlay=constraint,olcDatabase={1}hdb,cn=config
338 > objectClass: olcOverlayConfig
339 > objectClass: olcConstraintConfig
340 > olcOverlay: constraint
341 > olcConstraintAttribute: mail regex ^[:alnum:]+@mydomain.com$
342 > olcConstraintAttribute: title uri ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
345 H2: Dynamic Directory Services
350 The {{dds}} overlay to {{slapd}}(8) implements dynamic objects as per {{REF:RFC2589}}.
351 The name {{dds}} stands for Dynamic Directory Services. It allows to define
352 dynamic objects, characterized by the {{dynamicObject}} objectClass.
354 Dynamic objects have a limited lifetime, determined by a time-to-live (TTL)
355 that can be refreshed by means of a specific refresh extended operation. This
356 operation allows to set the Client Refresh Period (CRP), namely the period
357 between refreshes that is required to preserve the dynamic object from expiration.
358 The expiration time is computed by adding the requested TTL to the current time.
359 When dynamic objects reach the end of their lifetime without being further
360 refreshed, they are automatically {{deleted}}. There is no guarantee of immediate
361 deletion, so clients should not count on it.
363 H3: Dynamic Directory Service Configuration
365 A usage of dynamic objects might be to implement dynamic meetings; in this case,
366 all the participants to the meeting are allowed to refresh the meeting object,
367 but only the creator can delete it (otherwise it will be deleted when the TTL expires).
369 If we add the overlay to an example database, specifying a Max TTL of 1 day, a
370 min of 10 seconds, with a default TTL of 1 hour. We'll also specify an interval
371 of 120 (less than 60s might be too small) seconds between expiration checks and a
372 tolerance of 5 second (lifetime of a dynamic object will be {{entryTtl + tolerance}}).
383 > entryExpireTimestamp
385 Create a meeting is as simple as adding the following:
387 > dn: cn=OpenLDAP Documentation Meeting,ou=Meetings,dc=example,dc=com
388 > objectClass: groupOfNames
389 > objectClass: dynamicObject
390 > cn: OpenLDAP Documentation Meeting
391 > member: uid=ghenry,ou=People,dc=example,dc=com
392 > member: uid=hyc,ou=People,dc=example,dc=com
394 H4: Dynamic Directory Service ACLs
396 Allow users to start a meeting and to join it; restrict refresh to the {{member}};
397 restrict delete to the creator:
399 > access to attrs=userPassword
403 > access to dn.base="ou=Meetings,dc=example,dc=com"
407 > access to dn.onelevel="ou=Meetings,dc=example,dc=com"
409 > by dnattr=creatorsName write
412 > access to dn.onelevel="ou=Meetings,dc=example,dc=com"
414 > by dnattr=creatorsName write
418 > access to dn.onelevel="ou=Meetings,dc=example,dc=com"
420 > by dnattr=member manage
423 In simple terms, the user who created the {{OpenLDAP Documentation Meeting}} can add new attendees,
424 refresh the meeting using (basically complete control):
426 > 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
428 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.
435 This overlay extends the Compare operation to detect
436 members of a dynamic group. This overlay is now deprecated
437 as all of its functions are available using the
438 {{SECT:Dynamic Lists}} overlay.
441 H3: Dynamic Group Configuration
449 This overlay allows expansion of dynamic groups and lists. Instead of having the
450 group members or list attributes hard coded, this overlay allows us to define
451 an LDAP search whose results will make up the group or list.
453 H3: Dynamic List Configuration
455 This module can behave both as a dynamic list and dynamic group, depending on
456 the configuration. The syntax is as follows:
459 > dynlist-attrset <group-oc> <URL-ad> [member-ad]
461 The parameters to the {{F:dynlist-attrset}} directive have the following meaning:
462 * {{F:<group-oc>}}: specifies which object class triggers the subsequent LDAP search.
463 Whenever an entry with this object class is retrieved, the search is performed.
464 * {{F:<URL-ad>}}: is the name of the attribute which holds the search URI. It
465 has to be a subtype of {{F:labeledURI}}. The attributes and values present in
466 the search result are added to the entry unless {{F:member-ad}} is used (see
468 * {{F:member-ad}}: if present, changes the overlay behavior into a dynamic group.
469 Instead of inserting the results of the search in the entry, the distinguished name
470 of the results are added as values of this attribute.
472 Here is an example which will allow us to have an email alias which automatically
473 expands to all user's emails according to our LDAP filter:
475 In {{slapd.conf}}(5):
477 > dynlist-attrset nisMailAlias labeledURI
479 This means that whenever an entry which has the {{F:nisMailAlias}} object class is
480 retrieved, the search specified in the {{F:labeledURI}} attribute is performed.
482 Let's say we have this entry in our directory:
483 > cn=all,ou=aliases,dc=example,dc=com
485 > objectClass: nisMailAlias
486 > labeledURI: ldap:///ou=People,dc=example,dc=com?mail?one?(objectClass=inetOrgPerson)
488 If this entry is retrieved, the search specified in {{F:labeledURI}} will be
489 performed and the results will be added to the entry just as if they have always
490 been there. In this case, the search filter selects all entries directly
491 under {{F:ou=People}} that have the {{F:inetOrgPerson}} object class and retrieves
492 the {{F:mail}} attribute, if it exists.
494 This is what gets added to the entry when we have two users under {{F:ou=People}}
495 that match the filter:
496 !import "allmail-en.png"; align="center"; title="Dynamic list for email aliases"
497 FT[align="Center"] Figure X.Y: Dynamic List for all emails
499 The configuration for a dynamic group is similar. Let's see an example which would
500 automatically populate an {{F:allusers}} group with all the user accounts in the
503 In {{F:slapd.conf}}(5):
505 > dynlist-attrset groupOfNames labeledURI member
507 Let's apply it to the following entry:
508 > cn=allusers,ou=group,dc=example,dc=com
510 > objectClass: groupOfNames
511 > labeledURI: ldap:///ou=people,dc=example,dc=com??one?(objectClass=inetOrgPerson)
513 The behavior is similar to the dynamic list configuration we had before:
514 whenever an entry with the {{F:groupOfNames}} object class is retrieved, the
515 search specified in the {{F:labeledURI}} attribute is performed. But this time,
516 only the distinguished names of the results are added, and as values of the
517 {{F:member}} attribute.
520 !import "allusersgroup-en.png"; align="center"; title="Dynamic group for all users"
521 FT[align="Center"] Figure X.Y: Dynamic Group for all users
523 Note that a side effect of this scheme of dynamic groups is that the members
524 need to be specified as full DNs. So, if you are planning in using this for
525 {{F:posixGroup}}s, be sure to use RFC2307bis and some attribute which can hold
526 distinguished names. The {{F:memberUid}} attribute used in the {{F:posixGroup}}
527 object class can hold only names, not DNs, and is therefore not suitable for
530 H2: Reverse Group Membership Maintenance
534 In some scenarios, it may be desirable for a client to be able to determine
535 which groups an entry is a member of, without performing an additional search.
536 Examples of this are applications using the {{TERM:DIT}} for access control
537 based on group authorization.
539 The {{B:memberof}} overlay updates an attribute (by default {{B:memberOf}}) whenever
540 changes occur to the membership attribute (by default {{B:member}}) of entries of the
541 objectclass (by default {{B:groupOfNames}}) configured to trigger updates.
543 Thus, it provides maintenance of the list of groups an entry is a member of,
544 when usual maintenance of groups is done by modifying the members on the group
547 H3: Member Of Configuration
549 The typical use of this overlay requires just enabling the overlay for a
550 specific database. For example, with the following minimal slapd.conf:
552 > include /usr/share/openldap/schema/core.schema
553 > include /usr/share/openldap/schema/cosine.schema
554 > modulepath /usr/lib/openldap
555 > moduleload memberof.la
556 > authz-regexp "gidNumber=0\\\+uidNumber=0,cn=peercred,cn=external,cn=auth"
557 > "cn=Manager,dc=example,dc=com"
559 > suffix "dc=example,dc=com"
560 > rootdn "cn=Manager,dc=example,dc=com"
562 > directory /var/lib/ldap2.4
564 > index objectClass eq
569 adding the following ldif:
572 > dn: dc=example,dc=com
573 > objectclass: domain
576 > dn: ou=Group,dc=example,dc=com
577 > objectclass: organizationalUnit
580 > dn: ou=People,dc=example,dc=com
581 > objectclass: organizationalUnit
584 > dn: uid=test1,ou=People,dc=example,dc=com
585 > objectclass: account
588 > dn: cn=testgroup,ou=Group,dc=example,dc=com
589 > objectclass: groupOfNames
591 > member: uid=test1,ou=People,dc=example,dc=com
593 Results in the following output from a search on the test1 user:
595 > # ldapsearch -LL -Y EXTERNAL -H ldapi:/// "(uid=test1)" -b dc=example,dc=com memberOf
596 > SASL/EXTERNAL authentication started
597 > SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
601 > dn: uid=test1,ou=People,dc=example,dc=com
602 > memberOf: cn=testgroup,ou=Group,dc=example,dc=com
604 Note that the {{B:memberOf}} attribute is an operational attribute, so it must be
605 requested explicitly.
608 H2: The Proxy Cache Engine
610 {{TERM:LDAP}} servers typically hold one or more subtrees of a
611 {{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of
612 entries held by one or more master servers. Changes are propagated
613 from the master server to replica (slave) servers using LDAP Sync
614 replication. An LDAP cache is a special type of replica which holds
615 entries corresponding to search filters instead of subtrees.
619 The proxy cache extension of slapd is designed to improve the
620 responsiveness of the ldap and meta backends. It handles a search
622 by first determining whether it is contained in any cached search
623 filter. Contained requests are answered from the proxy cache's local
624 database. Other requests are passed on to the underlying ldap or
625 meta backend and processed as usual.
627 E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
628 {{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}
630 Correct matching rules and syntaxes are used while comparing
631 assertions for query containment. To simplify the query containment
632 problem, a list of cacheable "templates" (defined below) is specified
633 at configuration time. A query is cached or answered only if it
634 belongs to one of these templates. The entries corresponding to
635 cached queries are stored in the proxy cache local database while
636 its associated meta information (filter, scope, base, attributes)
637 is stored in main memory.
639 A template is a prototype for generating LDAP search requests.
640 Templates are described by a prototype search filter and a list of
641 attributes which are required in queries generated from the template.
642 The representation for prototype filter is similar to {{REF:RFC4515}},
643 except that the assertion values are missing. Examples of prototype
644 filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by
645 search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively.
647 The cache replacement policy removes the least recently used (LRU)
648 query and entries belonging to only that query. Queries are allowed
649 a maximum time to live (TTL) in the cache thus providing weak
650 consistency. A background task periodically checks the cache for
651 expired queries and removes them.
653 The Proxy Cache paper
654 ({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
655 design and implementation details.
658 H3: Proxy Cache Configuration
660 The cache configuration specific directives described below must
661 appear after a {{EX:overlay proxycache}} directive within a
662 {{EX:"database meta"}} or {{EX:database ldap}} section of
663 the server's {{slapd.conf}}(5) file.
665 H4: Setting cache parameters
667 > proxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period>
669 This directive enables proxy caching and sets general cache
670 parameters. The <DB> parameter specifies which underlying database
671 is to be used to hold cached entries. It should be set to
672 {{EX:bdb}} or {{EX:hdb}}. The <maxentries> parameter specifies the
673 total number of entries which may be held in the cache. The
674 <nattrsets> parameter specifies the total number of attribute sets
675 (as specified by the {{EX:proxyAttrSet}} directive) that may be
676 defined. The <entrylimit> parameter specifies the maximum number of
677 entries in a cacheable query. The <period> specifies the consistency
678 check period (in seconds). In each period, queries with expired
681 H4: Defining attribute sets
683 > proxyAttrset <index> <attrs...>
685 Used to associate a set of attributes to an index. Each attribute
686 set is associated with an index number from 0 to <numattrsets>-1.
687 These indices are used by the proxyTemplate directive to define
690 H4: Specifying cacheable templates
692 > proxyTemplate <prototype_string> <attrset_index> <TTL>
694 Specifies a cacheable template and the "time to live" (in sec) <TTL>
695 for queries belonging to the template. A template is described by
696 its prototype filter string and set of required attributes identified
702 An example {{slapd.conf}}(5) database section for a caching server
703 which proxies for the {{EX:"dc=example,dc=com"}} subtree held
704 at server {{EX:ldap.example.com}}.
707 > suffix "dc=example,dc=com"
708 > rootdn "dc=example,dc=com"
709 > uri ldap://ldap.example.com/
711 > proxycache bdb 100000 1 1000 100
712 > proxyAttrset 0 mail postaladdress telephonenumber
713 > proxyTemplate (sn=) 0 3600
714 > proxyTemplate (&(sn=)(givenName=)) 0 3600
715 > proxyTemplate (&(departmentNumber=)(secretary=*)) 0 3600
718 > directory ./testrun/db.2.a
719 > index objectClass eq
720 > index cn,sn,uid,mail pres,eq,sub
723 H5: Cacheable Queries
725 A LDAP search query is cacheable when its filter matches one of the
726 templates as defined in the "proxyTemplate" statements and when it references
727 only the attributes specified in the corresponding attribute set.
728 In the example above the attribute set number 0 defines that only the
729 attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
734 > Filter: (&(sn=Richard*)(givenName=jack))
735 > Attrs: mail telephoneNumber
737 is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
738 attributes are contained in proxyAttrset 0.
740 > Filter: (&(sn=Richard*)(telephoneNumber))
743 is not cacheable, because the filter does not match the template,
744 nor is the attribute givenName stored in the cache
746 > Filter: (|(sn=Richard*)(givenName=jack))
747 > Attrs: mail telephoneNumber
749 is not cacheable, because the filter does not match the template ( logical
750 OR "|" condition instead of logical AND "&" )
753 H2: Password Policies
758 This overlay provides a variety of password control mechanisms,
759 e.g. password aging, password reuse and duplication control, mandatory
760 password resets, etc.
763 H3: Password Policy Configuration
766 H2: Referential Integrity
771 This overlay can be used with a backend database such as slapd-bdb(5)
772 to maintain the cohesiveness of a schema which utilizes reference
775 Whenever a {{modrdn}} or {{delete}} is performed, that is, when an entry's DN
776 is renamed or an entry is removed, the server will search the directory for
777 references to this DN (in selected attributes: see below) and update them
778 accordingly. If it was a {{delete}} operation, the reference is deleted. If it
779 was a {{modrdn}} operation, then the reference is updated with the new DN.
781 For example, a very common administration task is to maintain group membership
782 lists, specially when users are removed from the directory. When an
783 user account is deleted or renamed, all groups this user is a member of have to be
784 updated. LDAP administrators usually have scripts for that. But we can use the
785 {{F:refint}} overlay to automate this task. In this example, if the user is
786 removed from the directory, the overlay will take care to remove the user from
787 all the groups he/she was a member of. No more scripting for this.
789 H3: Referential Integrity Configuration
791 The configuration for this overlay is as follows:
793 > refint_attributes <attribute [attribute ...]>
794 > refint_nothing <string>
796 * {{F:refint_attributes}}: this parameter specifies a space separated list of
797 attributes which will have the referential integrity maintained. When an entry is
798 removed or has its DN renamed, the server will do an internal search for any of the
799 {{F:refint_attributes}} that point to the affected DN and update them accordingly. IMPORTANT:
800 the attributes listed here must have the {{F:distinguishedName}} syntax, that is,
802 * {{F:refint_nothing}}: some times, while trying to maintain the referential
803 integrity, the server has to remove the last attribute of its kind from an
804 entry. This may be prohibited by the schema: for example, the
805 {{F:groupOfNames}} object class requires at least one member. In these cases,
806 the server will add the attribute value specified in {{F:refint_nothing}}
809 To illustrate this overlay, we will use the group membership scenario.
813 > refint_attributes member
814 > refint_nothing "cn=admin,dc=example,dc=com"
816 This configuration tells the overlay to maintain the referential integrity of the {{F:member}}
817 attribute. This attribute is used in the {{F:groupOfNames}} object class which always needs
818 a member, so we add the {{F:refint_nothing}} directive to fill in the group with a standard
819 member should all the members vanish.
821 If we have the following group membership, the refint overlay will
822 automatically remove {{F:john}} from the group if his entry is removed from the
825 !import "refint.png"; align="center"; title="Group membership"
826 FT[align="Center"] Figure X.Y: Maintaining referential integrity in groups
828 Notice that if we rename ({{F:modrdn}}) the {{F:john}} entry to, say, {{F:jsmith}}, the refint
829 overlay will also rename the reference in the {{F:member}} attribute, so the group membership
832 If we removed all users from the directory who are a member of this group, then the end result
833 would be a single member in the group: {{F:cn=admin,dc=example,dc=com}}. This is the
834 {{F:refint_nothing}} parameter kicking into action so that the schema is not violated.
841 This overlay is useful to test the behavior of clients when
842 server-generated erroneous and/or unusual responses occur.
845 H3: Return Code Configuration
853 It performs basic DN/data rewrite and
854 objectClass/attributeType mapping.
857 H3: Rewrite/Remap Configuration
865 This overlay implements the provider-side support for syncrepl
866 replication, including persistent search functionality
869 H3: Sync Provider Configuration
872 H2: Translucent Proxy
877 This overlay can be used with a backend database such as slapd-bdb (5)
878 to create a "translucent proxy".
880 Content of entries retrieved from a remote LDAP server can be partially
881 overridden by the database.
884 H3: Translucent Proxy Configuration
887 H2: Attribute Uniqueness
892 This overlay can be used with a backend database such as slapd-bdb (5)
893 to enforce the uniqueness of some or all attributes within a subtree.
896 H3: Attribute Uniqueness Configuration
904 This overlay can be used to enforce a specific order for the values
905 of an attribute when it is returned in a search.
908 H3: Value Sorting Configuration
916 Overlays can be stacked, which means that more than one overlay
917 can be instantiated for each database, or for the frontend.
918 As a consequence, each overlays function is called, if defined,
919 when overlay execution is invoked.
920 Multiple overlays are executed in reverse order (it's a stack, all in all)
921 with respect to their definition in slapd.conf (5), or with respect
922 to their ordering in the config database, as documented in slapd-config (5).
925 H3: Example Scenarios