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
166 H3: Further Information
168 {{slapo-accesslog(5)}} and the {{SECT:delta-syncrepl replication}} section.
173 The Audit Logging overlay can be used to record all changes on a given backend database to a specified log file.
177 If the need arises whereby changes need to be logged as standard LDIF, then the auditlog overlay {{B:slapo-auditlog (5)}}
178 can be used. Full examples are available in the man page {{B:slapo-auditlog (5)}}
180 H3: Audit Logging Configuration
182 If the directory is running vi {{F:slapd.d}}, then the following LDIF could be used to add the overlay to the overlay list
183 in {{B:cn=config}} and set what file the {{TERM:LDIF}} gets logged to (adjust to suit)
185 > dn: olcOverlay=auditlog,olcDatabase={1}hdb,cn=config
187 > objectClass: olcOverlayConfig
188 > objectClass: olcAuditLogConfig
189 > olcOverlay: auditlog
190 > olcAuditlogFile: /tmp/auditlog.ldif
193 In this example for testing, we are logging changes to {{F:/tmp/auditlog.ldif}}
195 A typical {{TERM:LDIF}} file created by {{B:slapo-auditlog(5)}} would look like:
197 > # add 1196797576 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com
198 > dn: dc=suretecsystems,dc=com
200 > objectClass: dcObject
201 > objectClass: organization
203 > o: Suretec Systems Ltd.
204 > structuralObjectClass: organization
205 > entryUUID: 1606f8f8-f06e-1029-8289-f0cc9d81e81a
206 > creatorsName: cn=admin,dc=suretecsystems,dc=com
207 > modifiersName: cn=admin,dc=suretecsystems,dc=com
208 > createTimestamp: 20051123130912Z
209 > modifyTimestamp: 20051123130912Z
210 > entryCSN: 20051123130912.000000Z#000001#000#000000
211 > auditContext: cn=accesslog
212 > # end add 1196797576
214 > # add 1196797577 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com
215 > dn: ou=Groups,dc=suretecsystems,dc=com
218 > objectClass: organizationalUnit
220 > structuralObjectClass: organizationalUnit
221 > entryUUID: 160aaa2a-f06e-1029-828a-f0cc9d81e81a
222 > creatorsName: cn=admin,dc=suretecsystems,dc=com
223 > modifiersName: cn=admin,dc=suretecsystems,dc=com
224 > createTimestamp: 20051123130912Z
225 > modifyTimestamp: 20051123130912Z
226 > entryCSN: 20051123130912.000000Z#000002#000#000000
227 > # end add 1196797577
230 H3: Further Information
232 {{:slapo-auditlog(5)}}
240 The chain overlay provides basic chaining capability to the underlying
243 What is chaining? It indicates the capability of a DSA to follow referrals on
244 behalf of the client, so that distributed systems are viewed as a single
245 virtual DSA by clients that are otherwise unable to "chase" (i.e. follow)
246 referrals by themselves.
248 The chain overlay is built on top of the ldap backend; it is compiled by
249 default when {{B:--enable-ldap}}.
252 H3: Chaining Configuration
254 In order to demonstrate how this overlay works, we shall discuss a typical
255 scenario which might be one master server and three Syncrepl slaves.
257 On each replica, add this near the top of the {{slapd.conf}}(5) file
258 (global), before any database definitions:
261 > chain-uri "ldap://ldapmaster.example.com"
262 > chain-idassert-bind bindmethod="simple"
263 > binddn="cn=Manager,dc=example,dc=com"
264 > credentials="<secret>"
267 > chain-return-error TRUE
269 Add this below your {{syncrepl}} statement:
271 > updateref "ldap://ldapmaster.example.com/"
273 The {{B:chain-tls}} statement enables TLS from the slave to the ldap master.
274 The DITs are exactly the same between these machines, therefore whatever user
275 bound to the slave will also exist on the master. If that DN does not have
276 update privileges on the master, nothing will happen.
278 You will need to restart the slave after these {{slapd.conf}} changes.
279 Then, if you are using {{loglevel stats}} (256), you can monitor an
280 {{ldapmodify}} on the slave and the master. (If you're using {{cn=config}}
281 no restart is required.)
283 Now start an {{ldapmodify}} on the slave and watch the logs. You should expect
286 > 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)
287 > Sep 6 09:27:25 slave1 slapd[29274]: conn=11 op=0 STARTTLS
288 > Sep 6 09:27:25 slave1 slapd[29274]: conn=11 op=0 RESULT oid= err=0 text=
289 > Sep 6 09:27:25 slave1 slapd[29274]: conn=11 fd=31 TLS established tls_ssf=256 ssf=256
290 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 BIND dn="uid=user1,ou=people,dc=example,dc=com" method=128
291 > 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
292 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=1 RESULT tag=97 err=0 text=
293 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD dn="uid=user1,ou=People,dc=example,dc=com"
294 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD attr=mail
295 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=2 RESULT tag=103 err=0 text=
296 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 op=3 UNBIND
297 > Sep 6 09:27:28 slave1 slapd[29274]: conn=11 fd=31 closed
298 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: LDAP_RES_SEARCH_ENTRY(LDAP_SYNC_MODIFY)
299 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_search (0)
300 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: uid=user1,ou=People,dc=example,dc=com
301 > Sep 6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_modify (0)
303 And on the master you will see this:
305 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 PROXYAUTHZ dn="uid=user1,ou=people,dc=example,dc=com"
306 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD dn="uid=user1,ou=People,dc=example,dc=com"
307 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD attr=mail
308 > Sep 6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 RESULT tag=103 err=0 text=
310 Note: You can clearly see the PROXYAUTHZ line on the master, indicating the
311 proper identity assertion for the update on the master. Also note the slave
312 immediately receiving the Syncrepl update from the master.
314 H3: Handling Chaining Errors
316 By default, if chaining fails, the original referral is returned to the client
317 under the assumption that the client might want to try and follow the referral.
319 With the following directive however, if the chaining fails at the provider
320 side, the actual error is returned to the client.
322 > chain-return-error TRUE
325 H3: Read-Back of Chained Modifications
327 Occasionally, applications want to read back the data that they just wrote.
328 If a modification requested to a shadow server was silently chained to its
329 producer, an immediate read could result in receiving data not yet synchronized.
330 In those cases, clients should use the {{B:dontusecopy}} control to ensure
331 they are directed to the authoritative source for that piece of data.
333 This control usually causes a referral to the actual source of the data
334 to be returned. However, when the {{slapo-chain(5)}} overlay is used,
335 it intercepts the referral being returned in response to the
336 {{B:dontusecopy}} control, and tries to fetch the requested data.
339 H3: Further Information
349 This overlay enforces a regular expression constraint on all values
350 of specified attributes during an LDAP modify request that contains add or modify
351 commands. It is used to enforce a more rigorous syntax when the underlying attribute
352 syntax is too general.
355 H3: Constraint Configuration
357 Configuration via {{slapd.conf}}(5) would look like:
360 > constraint_attribute mail regex ^[:alnum:]+@mydomain.com$
361 > constraint_attribute title uri
362 > ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
364 A specification like the above would reject any {{mail}} attribute which did not
365 look like {{<alpha-numeric string>@mydomain.com}}.
367 It would also reject any title attribute whose values were not listed in the
368 title attribute of any {{titleCatalog}} entries in the given scope.
370 An example for use with {{cn=config}}:
372 > dn: olcOverlay=constraint,olcDatabase={1}hdb,cn=config
374 > objectClass: olcOverlayConfig
375 > objectClass: olcConstraintConfig
376 > olcOverlay: constraint
377 > olcConstraintAttribute: mail regex ^[:alnum:]+@mydomain.com$
378 > olcConstraintAttribute: title uri ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
381 H3: Further Information
383 {{:slapo-constraint(5)}}
386 H2: Dynamic Directory Services
391 The {{dds}} overlay to {{slapd}}(8) implements dynamic objects as per {{REF:RFC2589}}.
392 The name {{dds}} stands for Dynamic Directory Services. It allows to define
393 dynamic objects, characterized by the {{dynamicObject}} objectClass.
395 Dynamic objects have a limited lifetime, determined by a time-to-live (TTL)
396 that can be refreshed by means of a specific refresh extended operation. This
397 operation allows to set the Client Refresh Period (CRP), namely the period
398 between refreshes that is required to preserve the dynamic object from expiration.
399 The expiration time is computed by adding the requested TTL to the current time.
400 When dynamic objects reach the end of their lifetime without being further
401 refreshed, they are automatically {{deleted}}. There is no guarantee of immediate
402 deletion, so clients should not count on it.
404 H3: Dynamic Directory Service Configuration
406 A usage of dynamic objects might be to implement dynamic meetings; in this case,
407 all the participants to the meeting are allowed to refresh the meeting object,
408 but only the creator can delete it (otherwise it will be deleted when the TTL expires).
410 If we add the overlay to an example database, specifying a Max TTL of 1 day, a
411 min of 10 seconds, with a default TTL of 1 hour. We'll also specify an interval
412 of 120 (less than 60s might be too small) seconds between expiration checks and a
413 tolerance of 5 second (lifetime of a dynamic object will be {{entryTtl + tolerance}}).
424 > entryExpireTimestamp
426 Creating a meeting is as simple as adding the following:
428 > dn: cn=OpenLDAP Documentation Meeting,ou=Meetings,dc=example,dc=com
429 > objectClass: groupOfNames
430 > objectClass: dynamicObject
431 > cn: OpenLDAP Documentation Meeting
432 > member: uid=ghenry,ou=People,dc=example,dc=com
433 > member: uid=hyc,ou=People,dc=example,dc=com
435 H4: Dynamic Directory Service ACLs
437 Allow users to start a meeting and to join it; restrict refresh to the {{member}};
438 restrict delete to the creator:
440 > access to attrs=userPassword
444 > access to dn.base="ou=Meetings,dc=example,dc=com"
448 > access to dn.onelevel="ou=Meetings,dc=example,dc=com"
450 > by dnattr=creatorsName write
453 > access to dn.onelevel="ou=Meetings,dc=example,dc=com"
455 > by dnattr=creatorsName write
459 > access to dn.onelevel="ou=Meetings,dc=example,dc=com"
461 > by dnattr=member manage
464 In simple terms, the user who created the {{OpenLDAP Documentation Meeting}} can add new attendees,
465 refresh the meeting using (basically complete control):
467 > 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
469 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.
472 H3: Further Information
482 This overlay extends the Compare operation to detect
483 members of a dynamic group. This overlay is now deprecated
484 as all of its functions are available using the
485 {{SECT:Dynamic Lists}} overlay.
488 H3: Dynamic Group Configuration
496 This overlay allows expansion of dynamic groups and lists. Instead of having the
497 group members or list attributes hard coded, this overlay allows us to define
498 an LDAP search whose results will make up the group or list.
500 H3: Dynamic List Configuration
502 This module can behave both as a dynamic list and dynamic group, depending on
503 the configuration. The syntax is as follows:
506 > dynlist-attrset <group-oc> <URL-ad> [member-ad]
508 The parameters to the {{F:dynlist-attrset}} directive have the following meaning:
509 * {{F:<group-oc>}}: specifies which object class triggers the subsequent LDAP search.
510 Whenever an entry with this object class is retrieved, the search is performed.
511 * {{F:<URL-ad>}}: is the name of the attribute which holds the search URI. It
512 has to be a subtype of {{F:labeledURI}}. The attributes and values present in
513 the search result are added to the entry unless {{F:member-ad}} is used (see
515 * {{F:member-ad}}: if present, changes the overlay behavior into a dynamic group.
516 Instead of inserting the results of the search in the entry, the distinguished name
517 of the results are added as values of this attribute.
519 Here is an example which will allow us to have an email alias which automatically
520 expands to all user's emails according to our LDAP filter:
522 In {{slapd.conf}}(5):
525 > dynlist-attrset nisMailAlias labeledURI
527 This means that whenever an entry which has the {{F:nisMailAlias}} object class is
528 retrieved, the search specified in the {{F:labeledURI}} attribute is performed.
530 Let's say we have this entry in our directory:
532 > cn=all,ou=aliases,dc=example,dc=com
534 > objectClass: nisMailAlias
535 > labeledURI: ldap:///ou=People,dc=example,dc=com?mail?one?(objectClass=inetOrgPerson)
537 If this entry is retrieved, the search specified in {{F:labeledURI}} will be
538 performed and the results will be added to the entry just as if they have always
539 been there. In this case, the search filter selects all entries directly
540 under {{F:ou=People}} that have the {{F:inetOrgPerson}} object class and retrieves
541 the {{F:mail}} attribute, if it exists.
543 This is what gets added to the entry when we have two users under {{F:ou=People}}
544 that match the filter:
545 !import "allmail-en.png"; align="center"; title="Dynamic list for email aliases"
546 FT[align="Center"] Figure X.Y: Dynamic List for all emails
548 The configuration for a dynamic group is similar. Let's see an example which would
549 automatically populate an {{F:allusers}} group with all the user accounts in the
552 In {{F:slapd.conf}}(5):
555 > dynlist-attrset groupOfNames labeledURI member
557 Let's apply it to the following entry:
559 > cn=allusers,ou=group,dc=example,dc=com
561 > objectClass: groupOfNames
562 > labeledURI: ldap:///ou=people,dc=example,dc=com??one?(objectClass=inetOrgPerson)
564 The behavior is similar to the dynamic list configuration we had before:
565 whenever an entry with the {{F:groupOfNames}} object class is retrieved, the
566 search specified in the {{F:labeledURI}} attribute is performed. But this time,
567 only the distinguished names of the results are added, and as values of the
568 {{F:member}} attribute.
571 !import "allusersgroup-en.png"; align="center"; title="Dynamic group for all users"
572 FT[align="Center"] Figure X.Y: Dynamic Group for all users
574 Note that a side effect of this scheme of dynamic groups is that the members
575 need to be specified as full DNs. So, if you are planning in using this for
576 {{F:posixGroup}}s, be sure to use RFC2307bis and some attribute which can hold
577 distinguished names. The {{F:memberUid}} attribute used in the {{F:posixGroup}}
578 object class can hold only names, not DNs, and is therefore not suitable for
582 H3: Further Information
584 {{:slapo-dynlist(5)}}
587 H2: Reverse Group Membership Maintenance
591 In some scenarios, it may be desirable for a client to be able to determine
592 which groups an entry is a member of, without performing an additional search.
593 Examples of this are applications using the {{TERM:DIT}} for access control
594 based on group authorization.
596 The {{B:memberof}} overlay updates an attribute (by default {{B:memberOf}}) whenever
597 changes occur to the membership attribute (by default {{B:member}}) of entries of the
598 objectclass (by default {{B:groupOfNames}}) configured to trigger updates.
600 Thus, it provides maintenance of the list of groups an entry is a member of,
601 when usual maintenance of groups is done by modifying the members on the group
604 H3: Member Of Configuration
606 The typical use of this overlay requires just enabling the overlay for a
607 specific database. For example, with the following minimal slapd.conf:
609 > include /usr/share/openldap/schema/core.schema
610 > include /usr/share/openldap/schema/cosine.schema
611 > modulepath /usr/lib/openldap
612 > moduleload memberof.la
613 > authz-regexp "gidNumber=0\\\+uidNumber=0,cn=peercred,cn=external,cn=auth"
614 > "cn=Manager,dc=example,dc=com"
616 > suffix "dc=example,dc=com"
617 > rootdn "cn=Manager,dc=example,dc=com"
619 > directory /var/lib/ldap2.4
621 > index objectClass eq
626 adding the following ldif:
629 > dn: dc=example,dc=com
630 > objectclass: domain
633 > dn: ou=Group,dc=example,dc=com
634 > objectclass: organizationalUnit
637 > dn: ou=People,dc=example,dc=com
638 > objectclass: organizationalUnit
641 > dn: uid=test1,ou=People,dc=example,dc=com
642 > objectclass: account
645 > dn: cn=testgroup,ou=Group,dc=example,dc=com
646 > objectclass: groupOfNames
648 > member: uid=test1,ou=People,dc=example,dc=com
650 Results in the following output from a search on the test1 user:
652 > # ldapsearch -LL -Y EXTERNAL -H ldapi:/// "(uid=test1)" -b dc=example,dc=com memberOf
653 > SASL/EXTERNAL authentication started
654 > SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
658 > dn: uid=test1,ou=People,dc=example,dc=com
659 > memberOf: cn=testgroup,ou=Group,dc=example,dc=com
661 Note that the {{B:memberOf}} attribute is an operational attribute, so it must be
662 requested explicitly.
665 H3: Further Information
667 {{:slapo-memberof(5)}}
670 H2: The Proxy Cache Engine
672 {{TERM:LDAP}} servers typically hold one or more subtrees of a
673 {{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of
674 entries held by one or more master servers. Changes are propagated
675 from the master server to replica (slave) servers using LDAP Sync
676 replication. An LDAP cache is a special type of replica which holds
677 entries corresponding to search filters instead of subtrees.
681 The proxy cache extension of slapd is designed to improve the
682 responsiveness of the ldap and meta backends. It handles a search
684 by first determining whether it is contained in any cached search
685 filter. Contained requests are answered from the proxy cache's local
686 database. Other requests are passed on to the underlying ldap or
687 meta backend and processed as usual.
689 E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
690 {{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}
692 Correct matching rules and syntaxes are used while comparing
693 assertions for query containment. To simplify the query containment
694 problem, a list of cacheable "templates" (defined below) is specified
695 at configuration time. A query is cached or answered only if it
696 belongs to one of these templates. The entries corresponding to
697 cached queries are stored in the proxy cache local database while
698 its associated meta information (filter, scope, base, attributes)
699 is stored in main memory.
701 A template is a prototype for generating LDAP search requests.
702 Templates are described by a prototype search filter and a list of
703 attributes which are required in queries generated from the template.
704 The representation for prototype filter is similar to {{REF:RFC4515}},
705 except that the assertion values are missing. Examples of prototype
706 filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by
707 search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively.
709 The cache replacement policy removes the least recently used (LRU)
710 query and entries belonging to only that query. Queries are allowed
711 a maximum time to live (TTL) in the cache thus providing weak
712 consistency. A background task periodically checks the cache for
713 expired queries and removes them.
715 The Proxy Cache paper
716 ({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
717 design and implementation details.
720 H3: Proxy Cache Configuration
722 The cache configuration specific directives described below must
723 appear after a {{EX:overlay proxycache}} directive within a
724 {{EX:"database meta"}} or {{EX:database ldap}} section of
725 the server's {{slapd.conf}}(5) file.
727 H4: Setting cache parameters
729 > proxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period>
731 This directive enables proxy caching and sets general cache
732 parameters. The <DB> parameter specifies which underlying database
733 is to be used to hold cached entries. It should be set to
734 {{EX:bdb}} or {{EX:hdb}}. The <maxentries> parameter specifies the
735 total number of entries which may be held in the cache. The
736 <nattrsets> parameter specifies the total number of attribute sets
737 (as specified by the {{EX:proxyAttrSet}} directive) that may be
738 defined. The <entrylimit> parameter specifies the maximum number of
739 entries in a cacheable query. The <period> specifies the consistency
740 check period (in seconds). In each period, queries with expired
743 H4: Defining attribute sets
745 > proxyAttrset <index> <attrs...>
747 Used to associate a set of attributes to an index. Each attribute
748 set is associated with an index number from 0 to <numattrsets>-1.
749 These indices are used by the proxyTemplate directive to define
752 H4: Specifying cacheable templates
754 > proxyTemplate <prototype_string> <attrset_index> <TTL>
756 Specifies a cacheable template and the "time to live" (in sec) <TTL>
757 for queries belonging to the template. A template is described by
758 its prototype filter string and set of required attributes identified
764 An example {{slapd.conf}}(5) database section for a caching server
765 which proxies for the {{EX:"dc=example,dc=com"}} subtree held
766 at server {{EX:ldap.example.com}}.
769 > suffix "dc=example,dc=com"
770 > rootdn "dc=example,dc=com"
771 > uri ldap://ldap.example.com/
773 > proxycache bdb 100000 1 1000 100
774 > proxyAttrset 0 mail postaladdress telephonenumber
775 > proxyTemplate (sn=) 0 3600
776 > proxyTemplate (&(sn=)(givenName=)) 0 3600
777 > proxyTemplate (&(departmentNumber=)(secretary=*)) 0 3600
780 > directory ./testrun/db.2.a
781 > index objectClass eq
782 > index cn,sn,uid,mail pres,eq,sub
785 H5: Cacheable Queries
787 A LDAP search query is cacheable when its filter matches one of the
788 templates as defined in the "proxyTemplate" statements and when it references
789 only the attributes specified in the corresponding attribute set.
790 In the example above the attribute set number 0 defines that only the
791 attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
796 > Filter: (&(sn=Richard*)(givenName=jack))
797 > Attrs: mail telephoneNumber
799 is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
800 attributes are contained in proxyAttrset 0.
802 > Filter: (&(sn=Richard*)(telephoneNumber))
805 is not cacheable, because the filter does not match the template,
806 nor is the attribute givenName stored in the cache
808 > Filter: (|(sn=Richard*)(givenName=jack))
809 > Attrs: mail telephoneNumber
811 is not cacheable, because the filter does not match the template ( logical
812 OR "|" condition instead of logical AND "&" )
815 H3: Further Information
820 H2: Password Policies
825 This overlay follows the specifications contained in the draft RFC titled
826 draft-behera-ldap-password-policy-09. While the draft itself is expired, it has
827 been implemented in several directory servers, including slapd. Nonetheless,
828 it is important to note that it is a draft, meaning that it is subject to change
829 and is a work-in-progress.
831 The key abilities of the password policy overlay are as follows:
833 * Enforce a minimum length for new passwords
834 * Make sure passwords are not changed too frequently
835 * 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
836 * Maintain a history of passwords to prevent password re-use
837 * Prevent password guessing by locking a password for a specified period of time after repeated authentication failures
838 * Force a password to be changed at the next authentication
839 * Set an administrative lock on an account
840 * Support multiple password policies on a default or a per-object basis.
841 * Perform arbitrary quality checks using an external loadable module. This is a non-standard extension of the draft RFC.
844 H3: Password Policy Configuration
846 Instantiate the module in the database where it will be used, after adding the
847 new ppolicy schema and loading the ppolicy module. The following example shows
848 the ppolicy module being added to the database that handles the naming
849 context "dc=example,dc=com". In this example we are also specifying the DN of
850 a policy object to use if none other is specified in a user's object.
853 > suffix "dc=example,dc=com"
854 > [...additional database configuration directives go here...]
857 > ppolicy_default "cn=default,ou=policies,dc=example,dc=com"
860 Now we need a container for the policy objects. In our example the password
861 policy objects are going to be placed in a section of the tree called
862 "ou=policies,dc=example,dc=com":
864 > dn: ou=policies,dc=example,dc=com
865 > objectClass: organizationalUnit
870 The default policy object that we are creating defines the following policies:
872 * The user is allowed to change his own password. Note that the directory ACLs for this attribute can also affect this ability (pwdAllowUserChange: TRUE).
873 * 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.
874 * 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).
875 * 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.
876 * When the password for a DN has expired, the server will allow five additional "grace" logins (pwdGraceAuthNLimit: 5).
877 * The server will maintain a history of the last five passwords that were used for a DN (pwdInHistory: 5).
878 * The server will lock the account after the maximum number of failed bind attempts has been exceeded (pwdLockout: TRUE).
879 * When the server has locked an account, the server will keep it locked until an administrator unlocks it (pwdLockoutDuration: 0)
880 * The server will reset its failed bind count after a period of 30 seconds.
881 * Passwords will not expire (pwdMaxAge: 0).
882 * Passwords can be changed as often as desired (pwdMinAge: 0).
883 * Passwords must be at least 5 characters in length (pwdMinLength: 5).
884 * The password does not need to be changed at the first bind or when the administrator has reset the password (pwdMustChange: FALSE)
885 * The current password does not need to be included with password change requests (pwdSafeModify: FALSE)
886 * The server will only allow five failed binds in a row for a particular DN (pwdMaxFailure: 5).
889 The actual policy would be:
891 > dn: cn=default,ou=policies,dc=example,dc=com
893 > objectClass: pwdPolicy
894 > objectClass: person
896 > pwdAllowUserChange: TRUE
897 > pwdAttribute: userPassword
899 > pwdExpireWarning: 600
900 > pwdFailureCountInterval: 30
901 > pwdGraceAuthNLimit: 5
904 > pwdLockoutDuration: 0
909 > pwdMustChange: FALSE
910 > pwdSafeModify: FALSE
913 You can create additional policy objects as needed.
916 There are two ways password policy can be applied to individual objects:
918 1. The pwdPolicySubentry in a user's object - If a user's object has a
919 pwdPolicySubEntry attribute specifying the DN of a policy object, then
920 the policy defined by that object is applied.
922 2. Default password policy - If there is no specific pwdPolicySubentry set
923 for an object, and the password policy module was configured with the DN of a
924 default policy object and if that object exists, then the policy defined in
925 that object is applied.
927 Please see {{slapo-ppolicy(5)}} for complete explanations of features and discussion of
928 "Password Management Issues" at {{URL:http://www.connexitor.com/forums/viewtopic.php?f=6&t=25}}
931 H3: Further Information
933 {{:slapo-ppolicy(5)}}
936 H2: Referential Integrity
941 This overlay can be used with a backend database such as slapd-bdb(5)
942 to maintain the cohesiveness of a schema which utilizes reference
945 Whenever a {{modrdn}} or {{delete}} is performed, that is, when an entry's DN
946 is renamed or an entry is removed, the server will search the directory for
947 references to this DN (in selected attributes: see below) and update them
948 accordingly. If it was a {{delete}} operation, the reference is deleted. If it
949 was a {{modrdn}} operation, then the reference is updated with the new DN.
951 For example, a very common administration task is to maintain group membership
952 lists, specially when users are removed from the directory. When an
953 user account is deleted or renamed, all groups this user is a member of have to be
954 updated. LDAP administrators usually have scripts for that. But we can use the
955 {{F:refint}} overlay to automate this task. In this example, if the user is
956 removed from the directory, the overlay will take care to remove the user from
957 all the groups he/she was a member of. No more scripting for this.
959 H3: Referential Integrity Configuration
961 The configuration for this overlay is as follows:
964 > refint_attributes <attribute [attribute ...]>
965 > refint_nothing <string>
967 * {{F:refint_attributes}}: this parameter specifies a space separated list of
968 attributes which will have the referential integrity maintained. When an entry is
969 removed or has its DN renamed, the server will do an internal search for any of the
970 {{F:refint_attributes}} that point to the affected DN and update them accordingly. IMPORTANT:
971 the attributes listed here must have the {{F:distinguishedName}} syntax, that is,
973 * {{F:refint_nothing}}: some times, while trying to maintain the referential
974 integrity, the server has to remove the last attribute of its kind from an
975 entry. This may be prohibited by the schema: for example, the
976 {{F:groupOfNames}} object class requires at least one member. In these cases,
977 the server will add the attribute value specified in {{F:refint_nothing}}
980 To illustrate this overlay, we will use the group membership scenario.
985 > refint_attributes member
986 > refint_nothing "cn=admin,dc=example,dc=com"
988 This configuration tells the overlay to maintain the referential integrity of the {{F:member}}
989 attribute. This attribute is used in the {{F:groupOfNames}} object class which always needs
990 a member, so we add the {{F:refint_nothing}} directive to fill in the group with a standard
991 member should all the members vanish.
993 If we have the following group membership, the refint overlay will
994 automatically remove {{F:john}} from the group if his entry is removed from the
997 !import "refint.png"; align="center"; title="Group membership"
998 FT[align="Center"] Figure X.Y: Maintaining referential integrity in groups
1000 Notice that if we rename ({{F:modrdn}}) the {{F:john}} entry to, say, {{F:jsmith}}, the refint
1001 overlay will also rename the reference in the {{F:member}} attribute, so the group membership
1004 If we removed all users from the directory who are a member of this group, then the end result
1005 would be a single member in the group: {{F:cn=admin,dc=example,dc=com}}. This is the
1006 {{F:refint_nothing}} parameter kicking into action so that the schema is not violated.
1009 H3: Further Information
1011 {{:slapo-refint(5)}}
1019 This overlay is useful to test the behavior of clients when
1020 server-generated erroneous and/or unusual responses occur,
1021 for example; error codes, referrals, excessive response times and so on.
1023 This would be classed as a debugging tool whilst developing client software
1024 or additional Overlays.
1026 For detailed information, please see the {{slapo-retcode(5)}} man page.
1029 H3: Return Code Configuration
1031 The retcode overlay utilizes the "return code" schema described in the man page.
1032 This schema is specifically designed for use with this overlay and is not intended
1033 to be used otherwise.
1035 Note: The necessary schema is loaded automatically by the overlay.
1037 An example configuration might be:
1040 > retcode-parent "ou=RetCodes,dc=example,dc=com"
1041 > include ./retcode.conf
1043 > retcode-item "cn=Unsolicited" 0x00 unsolicited="0"
1044 > retcode-item "cn=Notice of Disconnect" 0x00 unsolicited="1.3.6.1.4.1.1466.20036"
1045 > retcode-item "cn=Pre-disconnect" 0x34 flags="pre-disconnect"
1046 > retcode-item "cn=Post-disconnect" 0x34 flags="post-disconnect"
1048 Note: {{retcode.conf}} can be found in the openldap source at: {{F:tests/data/retcode.conf}}
1050 An excerpt of a {{F:retcode.conf}} would be something like:
1052 > retcode-item "cn=success" 0x00
1054 > retcode-item "cn=success w/ delay" 0x00 sleeptime=2
1056 > retcode-item "cn=operationsError" 0x01
1057 > retcode-item "cn=protocolError" 0x02
1058 > retcode-item "cn=timeLimitExceeded" 0x03 op=search
1059 > retcode-item "cn=sizeLimitExceeded" 0x04 op=search
1060 > retcode-item "cn=compareFalse" 0x05 op=compare
1061 > retcode-item "cn=compareTrue" 0x06 op=compare
1062 > retcode-item "cn=authMethodNotSupported" 0x07
1063 > retcode-item "cn=strongAuthNotSupported" 0x07 text="same as authMethodNotSupported"
1064 > retcode-item "cn=strongAuthRequired" 0x08
1065 > retcode-item "cn=strongerAuthRequired" 0x08 text="same as strongAuthRequired"
1067 Please see {{F:tests/data/retcode.conf}} for a complete {{F:retcode.conf}}
1070 H3: Further Information
1072 {{:slapo-retcode(5)}}
1080 It performs basic DN/data rewrite and objectClass/attributeType mapping. Its
1081 usage is mostly intended to provide virtual views of existing data either
1082 remotely, in conjunction with the proxy backend described in {{slapd-ldap(5)}},
1083 or locally, in conjunction with the relay backend described in {{slapd-relay(5)}}.
1085 This overlay is extremely configurable and advanced, therefore recommended
1086 reading is the {{slapo-rwm(5)}} man page.
1089 H3: Rewrite/Remap Configuration
1092 H3: Further Information
1102 This overlay implements the provider-side support for the LDAP Content Synchronization
1103 ({{REF:RFC4533}}) as well as syncrepl replication support, including persistent search functionality.
1105 H3: Sync Provider Configuration
1107 There is very little configuration needed for this overlay, in fact for many situations merely loading
1108 the overlay will suffice.
1110 However, because the overlay creates a contextCSN attribute in the root entry of the database which is
1111 updated for every write operation performed against the database and only updated in memory, it is
1112 recommended to configure a checkpoint so that the contextCSN is written into the underlying database to
1113 minimize recovery time after an unclean shutdown:
1116 > syncprov-checkpoint 100 10
1118 For every 100 operations or 10 minutes, which ever is sooner, the contextCSN will be checkpointed.
1120 The four configuration directives available are {{B:syncprov-checkpoint}}, {{B:syncprov-sessionlog}},
1121 {{B:syncprov-nopresent}} and {{B:syncprov-reloadhint}} which are covered in the man page discussing
1122 various other scenarios where this overlay can be used.
1124 H3: Further Information
1126 The {{:slapo-syncprov(5)}} man page and the {{SECT:Configuring the different replication types}} section
1129 H2: Translucent Proxy
1134 This overlay can be used with a backend database such as {{:slapd-bdb}}(5)
1135 to create a "translucent proxy".
1137 Entries retrieved from a remote LDAP server may have some or all attributes
1138 overridden, or new attributes added, by entries in the local database before
1139 being presented to the client.
1141 A search operation is first populated with entries from the remote LDAP server,
1142 the attributes of which are then overridden with any attributes defined in the
1143 local database. Local overrides may be populated with the add, modify, and
1144 modrdn operations, the use of which is restricted to the root user of the
1145 translucent local database.
1147 A compare operation will perform a comparison with attributes defined in the
1148 local database record (if any) before any comparison is made with data in the
1152 H3: Translucent Proxy Configuration
1154 There are various options available with this overlay, but for this example we
1155 will demonstrate adding new attributes to a remote entry and also searching
1156 against these newly added local attributes. For more information about overriding remote
1157 entries and search configuration, please see {{:slapo-translucent(5)}}
1159 Note: The Translucent Proxy overlay will disable schema checking in the local
1160 database, so that an entry consisting of overlay attributes need not adhere
1161 to the complete schema.
1163 First we configure the overlay in the normal manner:
1165 > include /usr/local/etc/openldap/schema/core.schema
1166 > include /usr/local/etc/openldap/schema/cosine.schema
1167 > include /usr/local/etc/openldap/schema/nis.schema
1168 > include /usr/local/etc/openldap/schema/inetorgperson.schema
1170 > pidfile ./slapd.pid
1171 > argsfile ./slapd.args
1173 > modulepath /usr/local/libexec/openldap
1174 > moduleload back_bdb.la
1175 > moduleload back_ldap.la
1176 > moduleload translucent.la
1179 > suffix "dc=suretecsystems,dc=com"
1180 > rootdn "cn=trans,dc=suretecsystems,dc=com"
1182 > directory ./openldap-data
1184 > index objectClass eq
1186 > overlay translucent
1187 > translucent_local carLicense
1189 > uri ldap://192.168.X.X:389
1191 > acl-bind binddn="cn=admin,dc=suretecsystems,dc=com" credentials="blahblah"
1193 You will notice the overlay directive and a directive to say what attribute we
1194 want to be able to search against in the local database. We must also load the
1195 ldap backend which will connect to the remote directory server.
1197 Now we take an example LDAP group:
1199 > # itsupport, Groups, suretecsystems.com
1200 > dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com
1201 > objectClass: posixGroup
1202 > objectClass: sambaGroupMapping
1205 > sambaSID: S-1-5-21-XXX
1207 > displayName: itsupport
1209 > memberUid: joebloggs
1211 and create an LDIF file we can use to add our data to the local database, using
1212 some pretty strange choices of new attributes for demonstration purposes:
1214 > [ghenry@suretec test_configs]$ cat test-translucent-add.ldif
1215 > dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com
1216 > businessCategory: frontend-override
1218 > employeeType: special
1219 > departmentNumber: 9999999
1220 > roomNumber: 41L-535
1222 Searching against the proxy gives:
1224 > [ghenry@suretec test_configs]$ ldapsearch -x -H ldap://127.0.0.1:9001 "(cn=itsupport)"
1225 > # itsupport, Groups, OxObjects, suretecsystems.com
1226 > dn: cn=itsupport,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com
1227 > objectClass: posixGroup
1228 > objectClass: sambaGroupMapping
1231 > SAMBASID: S-1-5-21-XXX
1233 > displayName: itsupport
1235 > memberUid: joebloggs
1236 > roomNumber: 41L-535
1237 > departmentNumber: 9999999
1238 > employeeType: special
1240 > businessCategory: frontend-override
1242 Here we can see that the 5 new attributes are added to the remote entry before
1243 being returned to the our client.
1245 Because we have configured a local attribute to search against:
1247 > overlay translucent
1248 > translucent_local carLicense
1250 we can also search for that to return the completely fabricated entry:
1252 > ldapsearch -x -H ldap://127.0.0.1:9001 (carLicense=LIVID)
1254 This is an extremely feature because you can then extend a remote directory server
1255 locally and also search against the local entries.
1257 Note: Because the translucent overlay does not perform any DN rewrites, the local
1258 and remote database instances must have the same suffix. Other configurations
1259 will probably fail with No Such Object and other errors
1261 H3: Further Information
1263 {{:slapo-translucent(5)}}
1266 H2: Attribute Uniqueness
1271 This overlay can be used with a backend database such as {{slapd-bdb(5)}}
1272 to enforce the uniqueness of some or all attributes within a subtree.
1275 H3: Attribute Uniqueness Configuration
1277 This overlay is only effective on new data from the point the overlay is enabled. To
1278 check uniqueness for existing data, you can export and import your data again via the
1279 LDAP Add operation, which will not be suitable for large amounts of data, unlike {{B:slapcat}}.
1281 For the following example, if uniqueness were enforced for the {{B:mail}} attribute,
1282 the subtree would be searched for any other records which also have a {{B:mail}} attribute
1283 containing the same value presented with an {{B:add}}, {{B:modify}} or {{B:modrdn}} operation
1284 which are unique within the configured scope. If any are found, the request is rejected.
1286 Note: If no attributes are specified, for example {{B:ldap:///??sub?}}, then the URI applies to all non-operational attributes. However,
1287 the keyword {{B:ignore}} can be specified to exclude certain non-operational attributes.
1289 To search at the base dn of the current backend database ensuring uniqueness of the {{B:mail}}
1290 attribute, we simply add the following configuration:
1293 > unique_uri ldap:///?mail?sub?
1295 For an existing entry of:
1297 > dn: cn=gavin,dc=suretecsystems,dc=com
1299 > objectClass: inetorgperson
1302 > mail: ghenry@suretecsystems.com
1304 and we then try to add a new entry of:
1306 > dn: cn=robert,dc=suretecsystems,dc=com
1308 > objectClass: inetorgperson
1311 > mail: ghenry@suretecsystems.com
1313 would result in an error like so:
1315 > adding new entry "cn=robert,dc=example,dc=com"
1316 > ldap_add: Constraint violation (19)
1317 > additional info: some attributes not unique
1319 The overlay can have multiple URIs specified within a domain, allowing complex
1320 selections of objects and also have multiple {{B:unique_uri}} statements or
1321 {{B:olcUniqueURI}} attributes which will create independent domains.
1323 For more information and details about the {{B:strict}} and {{B:ignore}} keywords,
1324 please see the {{:slapo-unique(5)}} man page.
1326 H3: Further Information
1328 {{:slapo-unique(5)}}
1336 The Value Sorting overlay can be used with a backend database to sort the
1337 values of specific multi-valued attributes within a subtree. The sorting occurs
1338 whenever the attributes are returned in a search response.
1340 H3: Value Sorting Configuration
1342 Sorting can be specified in ascending or descending order, using either numeric
1343 or alphanumeric sort methods. Additionally, a "weighted" sort can be specified,
1344 which uses a numeric weight prepended to the attribute values.
1346 The weighted sort is always performed in ascending order, but may be combined
1347 with the other methods for values that all have equal weights. The weight is
1348 specified by prepending an integer weight {<weight>} in front of each value
1349 of the attribute for which weighted sorting is desired. This weighting factor
1350 is stripped off and never returned in search results.
1352 Here are a few examples:
1354 > loglevel sync stats
1357 > suffix "dc=suretecsystems,dc=com"
1358 > directory /usr/local/var/openldap-data
1363 > valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com alpha-ascend
1365 For example, ascend:
1367 > # sharedemail, Groups, suretecsystems.com
1368 > dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com
1369 > objectClass: posixGroup
1374 > memberUid: dovecot
1376 > memberUid: suretec
1378 For weighted, we change our data to:
1380 > # sharedemail, Groups, suretecsystems.com
1381 > dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com
1382 > objectClass: posixGroup
1386 > memberUid: {4}admin
1387 > memberUid: {2}dovecot
1388 > memberUid: {1}laura
1389 > memberUid: {3}suretec
1391 and change the config to:
1394 > valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com weighted
1396 Searching now results in:
1398 > # sharedemail, Groups, OxObjects, suretecsystems.com
1399 > dn: cn=sharedemail,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com
1400 > objectClass: posixGroup
1405 > memberUid: dovecot
1406 > memberUid: suretec
1410 H3: Further Information
1412 {{:slapo-valsort(5)}}
1415 H2: Overlay Stacking
1420 Overlays can be stacked, which means that more than one overlay
1421 can be instantiated for each database, or for the {{EX:frontend}}.
1422 As a consequence, each overlays function is called, if defined,
1423 when overlay execution is invoked.
1424 Multiple overlays are executed in reverse order (as a stack)
1425 with respect to their definition in slapd.conf (5), or with respect
1426 to their ordering in the config database, as documented in slapd-config (5).
1429 H3: Example Scenarios