]> git.sur5r.net Git - openldap/blob - doc/guide/admin/overlays.sdf
Merge remote-tracking branch 'origin/mdb.master'
[openldap] / doc / guide / admin / overlays.sdf
1 # $OpenLDAP$
2 # Copyright 2007-2012 The OpenLDAP Foundation, All Rights Reserved.
3 # COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5 H1: Overlays
6
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. 
10
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.
14
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. 
20
21 Essentially, overlays represent a means to:
22
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
28
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
32 configured as such:
33
34 >        database frontend
35 >        overlay <overlay name>
36
37 Overlays are usually documented by separate specific man pages in section 5; 
38 the naming convention is
39
40 >        slapo-<overlay name>
41
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.
45
46 Official overlays are located in
47
48 >        servers/slapd/overlays/
49
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.
53
54 Contribware overlays are located in
55
56 >        contrib/slapd-modules/<overlay name>/
57
58 along with other types of run-time loadable components; they are officially 
59 distributed, but not maintained by the project.
60
61 All the current overlays in OpenLDAP are listed and described in detail in the 
62 following sections.
63
64
65 H2: Access Logging
66
67
68 H3: Overview
69
70 This overlay can record accesses to a given backend database on another
71 database.
72
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 
78 or in raw form.
79
80 It is also used for {{SECT:delta-syncrepl replication}}
81
82 H3: Access Logging Configuration
83
84 The following is a basic example that implements Access Logging:
85
86 >        database bdb
87 >        suffix dc=example,dc=com
88 >        ...
89 >        overlay accesslog
90 >        logdb cn=log
91 >        logops writes reads
92 >        logold (objectclass=person)
93 >        
94 >        database bdb
95 >        suffix cn=log
96 >        ...
97 >        index reqStart eq
98 >        access to *
99 >          by dn.base="cn=admin,dc=example,dc=com" read
100
101 The following is an example used for {{SECT:delta-syncrepl replication}}:
102
103 >        database hdb
104 >        suffix cn=accesslog
105 >        directory /usr/local/var/openldap-accesslog
106 >        rootdn cn=accesslog
107 >        index default eq
108 >        index entryCSN,objectClass,reqEnd,reqResult,reqStart
109
110 Accesslog overlay definitions for the primary db
111
112 >        database bdb
113 >        suffix dc=example,dc=com
114 >        ...
115 >        overlay accesslog
116 >        logdb cn=accesslog
117 >        logops writes
118 >        logsuccess TRUE
119 >        # scan the accesslog DB every day, and purge entries older than 7 days
120 >        logpurge 07+00:00 01+00:00
121
122 An example search result against {{B:cn=accesslog}} might look like:
123
124 >        [ghenry@suretec ghenry]# ldapsearch -x -b cn=accesslog
125 >        # extended LDIF
126 >        #
127 >        # LDAPv3
128 >        # base <cn=accesslog> with scope subtree
129 >        # filter: (objectclass=*)
130 >        # requesting: ALL
131 >        #
132 >        
133 >        # accesslog
134 >        dn: cn=accesslog
135 >        objectClass: auditContainer
136 >        cn: accesslog
137 >        
138 >        # 20080110163829.000004Z, accesslog
139 >        dn: reqStart=20080110163829.000004Z,cn=accesslog
140 >        objectClass: auditModify
141 >        reqStart: 20080110163829.000004Z
142 >        reqEnd: 20080110163829.000005Z
143 >        reqType: modify
144 >        reqSession: 196696
145 >        reqAuthzID: cn=admin,dc=suretecsystems,dc=com
146 >        reqDN: uid=suretec-46022f8$,ou=Users,dc=suretecsystems,dc=com
147 >        reqResult: 0
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
157 >        
158 >        # search result
159 >        search: 2
160 >        result: 0 Success
161 >        
162 >        # numResponses: 3
163 >        # numEntries: 2
164
165
166 H3: Further Information
167
168 {{slapo-accesslog(5)}} and the {{SECT:delta-syncrepl replication}} section.
169
170
171 H2: Audit Logging
172
173 The Audit Logging overlay can be used to record all changes on a given backend database to a specified log file.
174
175 H3: Overview
176
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)}}
179
180 H3: Audit Logging Configuration
181
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)
184
185 >       dn: olcOverlay=auditlog,olcDatabase={1}hdb,cn=config
186 >       changetype: add
187 >       objectClass: olcOverlayConfig
188 >       objectClass: olcAuditLogConfig
189 >       olcOverlay: auditlog
190 >       olcAuditlogFile: /tmp/auditlog.ldif
191
192
193 In this example for testing, we are logging changes to {{F:/tmp/auditlog.ldif}}
194
195 A typical {{TERM:LDIF}} file created by {{B:slapo-auditlog(5)}} would look like:
196
197 >       # add 1196797576 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com
198 >       dn: dc=suretecsystems,dc=com
199 >       changetype: add
200 >       objectClass: dcObject
201 >       objectClass: organization
202 >       dc: suretecsystems
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
213 >       
214 >       # add 1196797577 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com
215 >       dn: ou=Groups,dc=suretecsystems,dc=com
216 >       changetype: add
217 >       objectClass: top
218 >       objectClass: organizationalUnit
219 >       ou: Groups
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
228
229
230 H3: Further Information
231
232 {{:slapo-auditlog(5)}}
233
234
235 H2: Chaining
236
237
238 H3: Overview
239
240 The chain overlay provides basic chaining capability to the underlying 
241 database.
242
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.
247
248 The chain overlay is built on top of the ldap backend; it is compiled by 
249 default when {{B:--enable-ldap}}.
250
251
252 H3: Chaining Configuration
253
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. 
256
257 On each replica, add this near the top of the {{slapd.conf}}(5) file
258 (global), before any database definitions:
259
260 >        overlay                    chain
261 >        chain-uri                  "ldap://ldapmaster.example.com"
262 >        chain-idassert-bind        bindmethod="simple"
263 >                                   binddn="cn=Manager,dc=example,dc=com"
264 >                                   credentials="<secret>" 
265 >                                   mode="self"
266 >        chain-tls                  start
267 >        chain-return-error         TRUE 
268
269 Add this below your {{syncrepl}} statement:
270
271 >        updateref                  "ldap://ldapmaster.example.com/"
272
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.
277
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.)
282
283 Now start an {{ldapmodify}} on the slave and watch the logs. You should expect 
284 something like:
285
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)
302
303 And on the master you will see this:
304
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=
309
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.
313
314 H3: Handling Chaining Errors
315
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.
318
319 With the following directive however, if the chaining fails at the provider 
320 side, the actual error is returned to the client.
321
322 >        chain-return-error TRUE
323
324
325 H3: Read-Back of Chained Modifications
326
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 provider, 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.
332
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.
337
338
339 H3: Further Information
340
341 {{:slapo-chain(5)}}
342
343
344 H2: Constraints
345
346
347 H3: Overview
348
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.
353
354
355 H3: Constraint Configuration
356
357 Configuration via {{slapd.conf}}(5) would look like:
358
359 >        overlay constraint
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)
363
364 A specification like the above would reject any {{mail}} attribute which did not
365 look like {{<alpha-numeric string>@mydomain.com}}.
366
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.   
369
370 An example for use with {{cn=config}}:
371
372 >       dn: olcOverlay=constraint,olcDatabase={1}hdb,cn=config
373 >       changetype: add
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)
379
380
381 H3: Further Information
382
383 {{:slapo-constraint(5)}}
384
385    
386 H2: Dynamic Directory Services
387
388
389 H3: Overview
390
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.
394
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.
403
404 H3: Dynamic Directory Service Configuration
405
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).
409
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}}).
414
415 >       overlay dds
416 >       dds-max-ttl     1d
417 >       dds-min-ttl     10s
418 >       dds-default-ttl 1h
419 >       dds-interval    120s
420 >       dds-tolerance   5s
421
422 and add an index:
423
424 >       entryExpireTimestamp
425
426 Creating a meeting is as simple as adding the following:
427
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
434
435 H4: Dynamic Directory Service ACLs
436
437 Allow users to start a meeting and to join it; restrict refresh to the {{member}}; 
438 restrict delete to the creator:
439
440 >       access to attrs=userPassword
441 >          by self write
442 >          by * read
443 >       
444 >       access to dn.base="ou=Meetings,dc=example,dc=com"
445 >                 attrs=children
446 >            by users write
447 >       
448 >       access to dn.onelevel="ou=Meetings,dc=example,dc=com"
449 >                 attrs=entry
450 >            by dnattr=creatorsName write
451 >            by * read
452 >       
453 >       access to dn.onelevel="ou=Meetings,dc=example,dc=com"
454 >                 attrs=participant
455 >            by dnattr=creatorsName write
456 >            by users selfwrite
457 >            by * read
458 >       
459 >       access to dn.onelevel="ou=Meetings,dc=example,dc=com"
460 >                 attrs=entryTtl
461 >            by dnattr=member manage
462 >            by * read
463
464 In simple terms, the user who created the {{OpenLDAP Documentation Meeting}} can add new attendees, 
465 refresh the meeting using (basically complete control):
466
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
468
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.
470
471
472 H3: Further Information
473
474 {{:slapo-dds(5)}}
475
476
477 H2: Dynamic Groups
478
479
480 H3: Overview
481
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.
486
487
488 H3: Dynamic Group Configuration
489
490
491 H2: Dynamic Lists
492    
493    
494 H3: Overview
495
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.
499
500 H3: Dynamic List Configuration
501
502 This module can behave both as a dynamic list and dynamic group, depending on
503 the configuration. The syntax is as follows:
504
505 >       overlay dynlist
506 >       dynlist-attrset <group-oc> <URL-ad> [member-ad]
507
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
514 below).
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.
518
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:
521
522 In {{slapd.conf}}(5):
523
524 >       overlay dynlist
525 >       dynlist-attrset nisMailAlias labeledURI
526
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.
529
530 Let's say we have this entry in our directory:
531
532 >       cn=all,ou=aliases,dc=example,dc=com
533 >       cn: all
534 >       objectClass: nisMailAlias
535 >       labeledURI: ldap:///ou=People,dc=example,dc=com?mail?one?(objectClass=inetOrgPerson)
536
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.
542
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
547
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
550 directory.
551
552 In {{F:slapd.conf}}(5):
553
554 >       include /path/to/dyngroup.schema
555 >       ...
556 >       overlay dynlist
557 >       dynlist-attrset groupOfURLs labeledURI member
558 +
559 +Note: We must include the {{F:dyngroup.schema}} file that defines the
560 +{{F:groupOfURLs}} objectClass used in this example.
561
562 Let's apply it to the following entry:
563
564 >       cn=allusers,ou=group,dc=example,dc=com
565 >       cn: all
566 >       objectClass: groupOfURLs
567 >       labeledURI: ldap:///ou=people,dc=example,dc=com??one?(objectClass=inetOrgPerson)
568
569 The behavior is similar to the dynamic list configuration we had before:
570 whenever an entry with the {{F:groupOfURLs}} object class is retrieved, the
571 search specified in the {{F:labeledURI}} attribute is performed. But this time,
572 only the distinguished names of the results are added, and as values of the
573 {{F:member}} attribute.
574
575 This is what we get:
576 !import "allusersgroup-en.png"; align="center"; title="Dynamic group for all users"
577 FT[align="Center"] Figure X.Y: Dynamic Group for all users
578
579 Note that a side effect of this scheme of dynamic groups is that the members
580 need to be specified as full DNs. So, if you are planning in using this for
581 {{F:posixGroup}}s, be sure to use RFC2307bis and some attribute which can hold
582 distinguished names. The {{F:memberUid}} attribute used in the {{F:posixGroup}}
583 object class can hold only names, not DNs, and is therefore not suitable for
584 dynamic groups.
585
586
587 H3: Further Information
588
589 {{:slapo-dynlist(5)}}
590
591
592 H2: Reverse Group Membership Maintenance
593
594 H3: Overview
595
596 In some scenarios, it may be desirable for a client to be able to determine
597 which groups an entry is a member of, without performing an additional search.
598 Examples of this are applications using the {{TERM:DIT}} for access control
599 based on group authorization.
600
601 The {{B:memberof}} overlay updates an attribute (by default {{B:memberOf}}) whenever
602 changes occur to the membership attribute (by default {{B:member}}) of entries of the
603 objectclass (by default {{B:groupOfNames}}) configured to trigger updates.
604
605 Thus, it provides maintenance of the list of groups an entry is a member of,
606 when usual maintenance of groups is done by modifying the members on the group
607 entry.
608
609 H3: Member Of Configuration
610
611 The typical use of this overlay requires just enabling the overlay for a
612 specific database. For example, with the following minimal slapd.conf:
613
614 >        include /usr/share/openldap/schema/core.schema
615 >        include /usr/share/openldap/schema/cosine.schema
616 >
617 >        authz-regexp "gidNumber=0\\\+uidNumber=0,cn=peercred,cn=external,cn=auth"
618 >                "cn=Manager,dc=example,dc=com"
619 >        database        bdb
620 >        suffix          "dc=example,dc=com"
621 >        rootdn          "cn=Manager,dc=example,dc=com"
622 >        rootpw          secret
623 >        directory       /var/lib/ldap2.4
624 >        checkpoint 256 5
625 >        index   objectClass   eq
626 >        index   uid           eq,sub
627 >        
628 >        overlay memberof
629
630 adding the following ldif:
631
632 >        cat memberof.ldif
633 >        dn: dc=example,dc=com
634 >        objectclass: domain
635 >        dc: example
636 >        
637 >        dn: ou=Group,dc=example,dc=com
638 >        objectclass: organizationalUnit
639 >        ou: Group
640 >        
641 >        dn: ou=People,dc=example,dc=com
642 >        objectclass: organizationalUnit
643 >        ou: People
644 >        
645 >        dn: uid=test1,ou=People,dc=example,dc=com
646 >        objectclass: account
647 >        uid: test1
648 >        
649 >        dn: cn=testgroup,ou=Group,dc=example,dc=com
650 >        objectclass: groupOfNames
651 >        cn: testgroup
652 >        member: uid=test1,ou=People,dc=example,dc=com
653
654 Results in the following output from a search on the test1 user:
655
656 > # ldapsearch -LL -Y EXTERNAL -H ldapi:/// "(uid=test1)" -b dc=example,dc=com memberOf
657 > SASL/EXTERNAL authentication started
658 > SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
659 > SASL SSF: 0
660 > version: 1
661
662 > dn: uid=test1,ou=People,dc=example,dc=com
663 > memberOf: cn=testgroup,ou=Group,dc=example,dc=com
664
665 Note that the {{B:memberOf}} attribute is an operational attribute, so it must be
666 requested explicitly.
667
668
669 H3: Further Information
670
671 {{:slapo-memberof(5)}}
672
673
674 H2: The Proxy Cache Engine
675
676 {{TERM:LDAP}} servers typically hold one or more subtrees of a
677 {{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of
678 entries held by one or more master servers.  Changes are propagated
679 from the master server to replica (slave) servers using LDAP Sync
680 replication.  An LDAP cache is a special type of replica which holds
681 entries corresponding to search filters instead of subtrees.
682
683 H3: Overview
684
685 The proxy cache extension of slapd is designed to improve the
686 responsiveness of the ldap and meta backends. It handles a search
687 request (query)
688 by first determining whether it is contained in any cached search
689 filter. Contained requests are answered from the proxy cache's local
690 database. Other requests are passed on to the underlying ldap or
691 meta backend and processed as usual.
692
693 E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
694 {{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}
695
696 Correct matching rules and syntaxes are used while comparing
697 assertions for query containment. To simplify the query containment
698 problem, a list of cacheable "templates" (defined below) is specified
699 at configuration time. A query is cached or answered only if it
700 belongs to one of these templates. The entries corresponding to
701 cached queries are stored in the proxy cache local database while
702 its associated meta information (filter, scope, base, attributes)
703 is stored in main memory. 
704
705 A template is a prototype for generating LDAP search requests.
706 Templates are described by a prototype search filter and a list of
707 attributes which are required in queries generated from the template.
708 The representation for prototype filter is similar to {{REF:RFC4515}},
709 except that the assertion values are missing. Examples of prototype
710 filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by
711 search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively.
712
713 The cache replacement policy removes the least recently used (LRU)
714 query and entries belonging to only that query. Queries are allowed
715 a maximum time to live (TTL) in the cache thus providing weak
716 consistency. A background task periodically checks the cache for
717 expired queries and removes them.
718
719 The Proxy Cache paper
720 ({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
721 design and implementation details.
722
723
724 H3: Proxy Cache Configuration
725
726 The cache configuration specific directives described below must
727 appear after a {{EX:overlay pcache}} directive within a
728 {{EX:"database meta"}} or {{EX:"database ldap"}} section of
729 the server's {{slapd.conf}}(5) file.
730
731 H4: Setting cache parameters
732
733 > pcache <DB> <maxentries> <nattrsets> <entrylimit> <period>
734
735 This directive enables proxy caching and sets general cache
736 parameters.  The <DB> parameter specifies which underlying database
737 is to be used to hold cached entries.  It should be set to
738 {{EX:bdb}} or {{EX:hdb}}.  The <maxentries> parameter specifies the
739 total number of entries which may be held in the cache.  The
740 <nattrsets> parameter specifies the total number of attribute sets
741 (as specified by the {{EX:pcacheAttrset}} directive) that may be
742 defined.  The <entrylimit> parameter specifies the maximum number of
743 entries in a cacheable query.  The <period> specifies the consistency
744 check period (in seconds).  In each period, queries with expired
745 TTLs are removed.
746
747 H4: Defining attribute sets
748
749 > pcacheAttrset <index> <attrs...>
750
751 Used to associate a set of attributes to an index. Each attribute
752 set is associated with an index number from 0 to <numattrsets>-1.
753 These indices are used by the pcacheTemplate directive to define
754 cacheable templates.
755
756 H4: Specifying cacheable templates 
757
758 > pcacheTemplate <prototype_string> <attrset_index> <TTL>
759
760 Specifies a cacheable template and the "time to live" (in sec) <TTL>
761 for queries belonging to the template. A template is described by
762 its prototype filter string and set of required attributes identified
763 by <attrset_index>.
764
765
766 H4: Example for slapd.conf
767
768 An example {{slapd.conf}}(5) database section for a caching server
769 which proxies for the {{EX:"dc=example,dc=com"}} subtree held
770 at server {{EX:ldap.example.com}}.
771  
772 >       database        ldap
773 >       suffix          "dc=example,dc=com" 
774 >       rootdn          "dc=example,dc=com" 
775 >       uri             ldap://ldap.example.com/
776 >       overlay pcache
777 >       pcache         bdb 100000 1 1000 100
778 >       pcacheAttrset  0 mail postaladdress telephonenumber 
779 >       pcacheTemplate (sn=) 0 3600
780 >       pcacheTemplate (&(sn=)(givenName=)) 0 3600
781 >       pcacheTemplate (&(departmentNumber=)(secretary=*)) 0 3600
782 >
783 >       cachesize 20
784 >       directory ./testrun/db.2.a
785 >       index       objectClass eq
786 >       index       cn,sn,uid,mail  pres,eq,sub
787
788 H4: Example for slapd-config
789
790 The same example as a LDIF file for back-config for a caching server
791 which proxies for the {{EX:"dc=example,dc=com"}} subtree held
792 at server {{EX:ldap.example.com}}.
793
794 >   dn: olcDatabase={2}ldap
795 >   objectClass: olcDatabaseConfig
796 >   objectClass: olcLDAPConfig
797 >   olcDatabase: {2}ldap
798 >   olcSuffix: dc=example,dc=com
799 >   olcRootDN: dc=example,dc=com
800 >   olcDbURI: "ldap://ldap.example.com"
801 >   
802 >   dn: olcOverlay={0}pcache
803 >   objectClass: olcOverlayConfig
804 >   objectClass: olcPcacheConfig
805 >   olcOverlay: {0}pcache
806 >   olcPcache: bdb 100000 1 1000 100
807 >   olcPcacheAttrset: 0 mail postalAddress telephoneNumber
808 >   olcPcacheTemplate: "(sn=)" 0 3600 0 0 0
809 >   olcPcacheTemplate: "(&(sn=)(givenName=))" 0 3600 0 0 0
810 >   olcPcacheTemplate: "(&(departmentNumber=)(secretary=))" 0 3600
811 >   
812 >   dn: olcDatabase={0}hdb
813 >   objectClass: olcHdbConfig
814 >   objectClass: olcPcacheDatabase
815 >   olcDatabase: {0}hdb
816 >   olcDbDirectory: ./testrun/db.2.a
817 >   olcDbCacheSize: 20
818 >   olcDbIndex: objectClass eq
819 >   olcDbIndex: cn,sn,uid,mail  pres,eq,sub
820
821
822 H5: Cacheable Queries
823
824 A LDAP search query is cacheable when its filter matches one of the
825 templates as defined in the "pcacheTemplate" statements and when it references
826 only the attributes specified in the corresponding attribute set. 
827 In the example above the attribute set number 0 defines that only the
828 attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
829 pcacheTemplates.
830
831 H5: Examples:
832
833 >       Filter: (&(sn=Richard*)(givenName=jack)) 
834 >       Attrs: mail telephoneNumber
835
836     is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
837     attributes are contained in pcacheAttrset 0.
838
839 >       Filter: (&(sn=Richard*)(telephoneNumber))
840 >       Attrs: givenName 
841
842     is not cacheable, because the filter does not match the template,
843     nor is the attribute givenName stored in the cache
844
845 >       Filter: (|(sn=Richard*)(givenName=jack))
846 >       Attrs: mail telephoneNumber
847
848     is not cacheable, because the filter does not match the template ( logical
849     OR "|" condition instead of logical AND "&" )
850
851
852 H3: Further Information
853
854 {{:slapo-pcache(5)}}
855                            
856                            
857 H2: Password Policies
858
859
860 H3: Overview
861
862 This overlay follows the specifications contained in the draft RFC titled 
863 draft-behera-ldap-password-policy-09. While the draft itself is expired, it has 
864 been implemented in several directory servers, including slapd. Nonetheless, 
865 it is important to note that it is a draft, meaning that it is subject to change 
866 and is a work-in-progress.
867
868 The key abilities of the password policy overlay are as follows:
869
870 * Enforce a minimum length for new passwords
871 * Make sure passwords are not changed too frequently
872 * 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
873 * Maintain a history of passwords to prevent password re-use
874 * Prevent password guessing by locking a password for a specified period of time after repeated authentication failures
875 * Force a password to be changed at the next authentication
876 * Set an administrative lock on an account
877 * Support multiple password policies on a default or a per-object basis.
878 * Perform arbitrary quality checks using an external loadable module. This is a non-standard extension of the draft RFC.
879
880
881 H3: Password Policy Configuration
882
883 Instantiate the module in the database where it will be used, after adding the 
884 new ppolicy schema and loading the ppolicy module. The following example shows 
885 the ppolicy module being added to the database that handles the naming 
886 context "dc=example,dc=com". In this example we are also specifying the DN of 
887 a policy object to use if none other is specified in a user's object.
888
889 >       database bdb
890 >       suffix "dc=example,dc=com"
891 >       [...additional database configuration directives go here...]
892 >       
893 >       overlay ppolicy
894 >       ppolicy_default "cn=default,ou=policies,dc=example,dc=com"
895
896
897 Now we need a container for the policy objects. In our example the password 
898 policy objects are going to be placed in a section of the tree called 
899 "ou=policies,dc=example,dc=com":
900
901 >       dn: ou=policies,dc=example,dc=com
902 >       objectClass: organizationalUnit
903 >       objectClass: top
904 >       ou: policies
905
906
907 The default policy object that we are creating defines the following policies:
908
909 * The user is allowed to change his own password. Note that the directory ACLs for this attribute can also affect this ability (pwdAllowUserChange: TRUE).
910 * 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.
911 * 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).
912 * 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.
913 * When the password for a DN has expired, the server will allow five additional "grace" logins (pwdGraceAuthNLimit: 5).
914 * The server will maintain a history of the last five passwords that were used for a DN (pwdInHistory: 5).
915 * The server will lock the account after the maximum number of failed bind attempts has been exceeded (pwdLockout: TRUE).
916 * When the server has locked an account, the server will keep it locked until an administrator unlocks it (pwdLockoutDuration: 0)
917 * The server will reset its failed bind count after a period of 30 seconds.
918 * Passwords will not expire (pwdMaxAge: 0).
919 * Passwords can be changed as often as desired (pwdMinAge: 0).
920 * Passwords must be at least 5 characters in length (pwdMinLength: 5).
921 * The password does not need to be changed at the first bind or when the administrator has reset the password (pwdMustChange: FALSE)
922 * The current password does not need to be included with password change requests (pwdSafeModify: FALSE)
923 * The server will only allow five failed binds in a row for a particular DN (pwdMaxFailure: 5).
924
925
926 The actual policy would be:
927
928 >       dn: cn=default,ou=policies,dc=example,dc=com
929 >       cn: default
930 >       objectClass: pwdPolicy
931 >       objectClass: person
932 >       objectClass: top
933 >       pwdAllowUserChange: TRUE
934 >       pwdAttribute: userPassword
935 >       pwdCheckQuality: 2
936 >       pwdExpireWarning: 600
937 >       pwdFailureCountInterval: 30
938 >       pwdGraceAuthNLimit: 5
939 >       pwdInHistory: 5
940 >       pwdLockout: TRUE
941 >       pwdLockoutDuration: 0
942 >       pwdMaxAge: 0
943 >       pwdMaxFailure: 5
944 >       pwdMinAge: 0
945 >       pwdMinLength: 5
946 >       pwdMustChange: FALSE
947 >       pwdSafeModify: FALSE
948 >       sn: dummy value
949
950 You can create additional policy objects as needed. 
951
952
953 There are two ways password policy can be applied to individual objects:
954
955 1. The pwdPolicySubentry in a user's object - If a user's object has a
956 pwdPolicySubEntry attribute specifying the DN of a policy object, then 
957 the policy defined by that object is applied.
958
959 2. Default password policy - If there is no specific pwdPolicySubentry set
960 for an object, and the password policy module was configured with the DN of a
961 default policy object and if that object exists, then the policy defined in
962 that object is applied.
963
964 Please see {{slapo-ppolicy(5)}} for complete explanations of features and discussion of
965  "Password Management Issues" at {{URL:http://www.symas.com/blog/?page_id=66}}
966
967
968 H3: Further Information
969
970 {{:slapo-ppolicy(5)}}
971
972
973 H2: Referential Integrity
974
975
976 H3: Overview
977
978 This overlay can be used with a backend database such as slapd-bdb(5)
979 to maintain the cohesiveness of a schema which utilizes reference
980 attributes.
981
982 Whenever a {{modrdn}} or {{delete}} is performed, that is, when an entry's DN
983 is renamed or an entry is removed, the server will search the directory for
984 references to this DN (in selected attributes: see below) and update them
985 accordingly. If it was a {{delete}} operation, the reference is deleted. If it
986 was a {{modrdn}} operation, then the reference is updated with the new DN.
987
988 For example, a very common administration task is to maintain group membership
989 lists, specially when users are removed from the directory. When an
990 user account is deleted or renamed, all groups this user is a member of have to be
991 updated. LDAP administrators usually have scripts for that. But we can use the
992 {{F:refint}} overlay to automate this task. In this example, if the user is
993 removed from the directory, the overlay will take care to remove the user from
994 all the groups he/she was a member of. No more scripting for this.
995
996 H3: Referential Integrity Configuration
997
998 The configuration for this overlay is as follows:
999
1000 >       overlay refint
1001 >       refint_attributes <attribute [attribute ...]>
1002 >       refint_nothing <string>
1003
1004 * {{F:refint_attributes}}: this parameter specifies a space separated list of
1005 attributes which will have the referential integrity maintained. When an entry is
1006 removed or has its DN renamed, the server will do an internal search for any of the
1007 {{F:refint_attributes}} that point to the affected DN and update them accordingly. IMPORTANT:
1008 the attributes listed here must have the {{F:distinguishedName}} syntax, that is,
1009 hold DNs as values.
1010 * {{F:refint_nothing}}: some times, while trying to maintain the referential
1011 integrity, the server has to remove the last attribute of its kind from an
1012 entry. This may be prohibited by the schema: for example, the
1013 {{F:groupOfNames}} object class requires at least one member. In these cases,
1014 the server will add the attribute value specified in {{F:refint_nothing}}
1015 to the entry.
1016
1017 To illustrate this overlay, we will use the group membership scenario.
1018
1019 In {{F:slapd.conf}}:
1020
1021 >       overlay refint
1022 >       refint_attributes member
1023 >       refint_nothing "cn=admin,dc=example,dc=com"
1024
1025 This configuration tells the overlay to maintain the referential integrity of the {{F:member}}
1026 attribute. This attribute is used in the {{F:groupOfNames}} object class which always needs
1027 a member, so we add the {{F:refint_nothing}} directive to fill in the group with a standard
1028 member should all the members vanish.
1029
1030 If we have the following group membership, the refint overlay will
1031 automatically remove {{F:john}} from the group if his entry is removed from the
1032 directory:
1033
1034 !import "refint.png"; align="center"; title="Group membership"
1035 FT[align="Center"] Figure X.Y: Maintaining referential integrity in groups
1036
1037 Notice that if we rename ({{F:modrdn}}) the {{F:john}} entry to, say, {{F:jsmith}}, the refint
1038 overlay will also rename the reference in the {{F:member}} attribute, so the group membership
1039 stays correct.
1040
1041 If we removed all users from the directory who are a member of this group, then the end result
1042 would be a single member in the group: {{F:cn=admin,dc=example,dc=com}}. This is the
1043 {{F:refint_nothing}} parameter kicking into action so that the schema is not violated.
1044
1045 The {{rootdn}} must be set for the database as refint runs as the {{rootdn}} to gain access to
1046 make its updates.  The {{rootpw}} does not need to be set.
1047
1048 H3: Further Information
1049
1050 {{:slapo-refint(5)}}
1051
1052
1053 H2: Return Code
1054
1055
1056 H3: Overview
1057
1058 This overlay is useful to test the behavior of clients when
1059 server-generated erroneous and/or unusual responses occur,
1060 for example; error codes, referrals, excessive response times and so on.
1061
1062 This would be classed as a debugging tool whilst developing client software
1063 or additional Overlays.
1064
1065 For detailed information, please see the {{slapo-retcode(5)}} man page.
1066
1067
1068 H3: Return Code Configuration
1069
1070 The retcode overlay utilizes the "return code" schema described in the man page.  
1071 This schema is specifically designed for use with this overlay and is not intended 
1072 to be used otherwise. 
1073
1074 Note: The necessary schema is loaded automatically by the overlay.
1075
1076 An example configuration might be:
1077
1078 >       overlay         retcode
1079 >       retcode-parent  "ou=RetCodes,dc=example,dc=com"
1080 >       include         ./retcode.conf
1081 >       
1082 >       retcode-item    "cn=Unsolicited"                0x00 unsolicited="0"
1083 >       retcode-item    "cn=Notice of Disconnect"       0x00 unsolicited="1.3.6.1.4.1.1466.20036"
1084 >       retcode-item    "cn=Pre-disconnect"             0x34 flags="pre-disconnect"
1085 >       retcode-item    "cn=Post-disconnect"            0x34 flags="post-disconnect"
1086
1087 Note: {{retcode.conf}} can be found in the openldap source at: {{F:tests/data/retcode.conf}}
1088
1089 An excerpt of a {{F:retcode.conf}} would be something like:
1090
1091 >       retcode-item    "cn=success"                            0x00
1092 >       
1093 >       retcode-item    "cn=success w/ delay"                   0x00    sleeptime=2
1094 >       
1095 >       retcode-item    "cn=operationsError"                    0x01
1096 >       retcode-item    "cn=protocolError"                      0x02
1097 >       retcode-item    "cn=timeLimitExceeded"                  0x03    op=search
1098 >       retcode-item    "cn=sizeLimitExceeded"                  0x04    op=search
1099 >       retcode-item    "cn=compareFalse"                       0x05    op=compare
1100 >       retcode-item    "cn=compareTrue"                        0x06    op=compare
1101 >       retcode-item    "cn=authMethodNotSupported"             0x07
1102 >       retcode-item    "cn=strongAuthNotSupported"             0x07    text="same as authMethodNotSupported"
1103 >       retcode-item    "cn=strongAuthRequired"                 0x08
1104 >       retcode-item    "cn=strongerAuthRequired"               0x08    text="same as strongAuthRequired"
1105
1106 Please see {{F:tests/data/retcode.conf}} for a complete {{F:retcode.conf}}
1107
1108
1109 H3: Further Information
1110
1111 {{:slapo-retcode(5)}}
1112
1113
1114 H2: Rewrite/Remap
1115             
1116             
1117 H3: Overview
1118
1119 It performs basic DN/data rewrite and objectClass/attributeType mapping. Its 
1120 usage is mostly intended to provide virtual views of existing data either 
1121 remotely, in conjunction with the proxy backend described in {{slapd-ldap(5)}}, 
1122 or locally, in conjunction with the relay backend described in {{slapd-relay(5)}}.
1123
1124 This overlay is extremely configurable and advanced, therefore recommended 
1125 reading is the {{slapo-rwm(5)}} man page.
1126
1127
1128 H3: Rewrite/Remap Configuration
1129
1130
1131 H3: Further Information
1132
1133 {{:slapo-rwm(5)}}
1134
1135
1136 H2: Sync Provider
1137
1138
1139 H3: Overview
1140
1141 This overlay implements the provider-side support for the LDAP Content Synchronization 
1142 ({{REF:RFC4533}}) as well as syncrepl replication support, including persistent search functionality.
1143
1144 H3: Sync Provider Configuration
1145
1146 There is very little configuration needed for this overlay, in fact for many situations merely loading 
1147 the overlay will suffice.
1148
1149 However, because the overlay creates a contextCSN attribute in the root entry of the database which is
1150 updated for every write operation performed against the database and only updated in memory, it is 
1151 recommended to configure a checkpoint so that the contextCSN is written into the underlying database to 
1152 minimize recovery time after an unclean shutdown:
1153
1154 >       overlay syncprov
1155 >       syncprov-checkpoint 100 10
1156
1157 For every 100 operations or 10 minutes, which ever is sooner, the contextCSN will be checkpointed.
1158
1159 The four configuration directives available are {{B:syncprov-checkpoint}}, {{B:syncprov-sessionlog}},
1160 {{B:syncprov-nopresent}} and {{B:syncprov-reloadhint}} which are covered in the man page discussing
1161 various other scenarios where this overlay can be used. 
1162
1163 H3: Further Information
1164
1165 The {{:slapo-syncprov(5)}} man page and the {{SECT:Configuring the different replication types}} section
1166
1167
1168 H2: Translucent Proxy
1169
1170
1171 H3: Overview
1172
1173 This overlay can be used with a backend database such as {{:slapd-bdb}}(5)
1174 to create a "translucent proxy".
1175
1176 Entries retrieved from a remote LDAP server may have some or all attributes 
1177 overridden, or new attributes added, by entries in the local database before 
1178 being presented to the client.
1179
1180 A search operation is first populated with entries from the remote LDAP server, 
1181 the attributes of which are then overridden with any attributes defined in the
1182 local database. Local overrides may be populated with the add, modify, and 
1183 modrdn operations, the use of which is restricted to the root user of the 
1184 translucent local database.
1185
1186 A compare operation will perform a comparison with attributes defined in the
1187 local database record (if any) before any comparison is made with data in the 
1188 remote database.
1189
1190
1191 H3: Translucent Proxy Configuration
1192
1193 There are various options available with this overlay, but for this example we
1194 will demonstrate adding new attributes to a remote entry and also searching 
1195 against these newly added local attributes. For more information about overriding remote
1196 entries and search configuration, please see {{:slapo-translucent(5)}}
1197
1198 Note: The Translucent Proxy overlay will disable schema checking in the local
1199 database, so that an entry consisting of overlay attributes need not adhere
1200  to the complete schema.
1201
1202 First we configure the overlay in the normal manner:
1203
1204 >       include     /usr/local/etc/openldap/schema/core.schema
1205 >       include     /usr/local/etc/openldap/schema/cosine.schema
1206 >       include     /usr/local/etc/openldap/schema/nis.schema
1207 >       include     /usr/local/etc/openldap/schema/inetorgperson.schema
1208 >       
1209 >       pidfile     ./slapd.pid
1210 >       argsfile    ./slapd.args
1211 >       
1212 >       database    bdb
1213 >       suffix      "dc=suretecsystems,dc=com"
1214 >       rootdn      "cn=trans,dc=suretecsystems,dc=com"
1215 >       rootpw      secret
1216 >       directory   ./openldap-data
1217 >       
1218 >       index       objectClass eq
1219 >       
1220 >       overlay     translucent
1221 >       translucent_local carLicense
1222 >       
1223 >       uri         ldap://192.168.X.X:389
1224 >       lastmod     off
1225 >       acl-bind    binddn="cn=admin,dc=suretecsystems,dc=com" credentials="blahblah"
1226
1227 You will notice the overlay directive and a directive to say what attribute we 
1228 want to be able to search against in the local database. We must also load the 
1229 ldap backend which will connect to the remote directory server.
1230
1231 Now we take an example LDAP group:
1232
1233 >       # itsupport, Groups, suretecsystems.com
1234 >       dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com
1235 >       objectClass: posixGroup
1236 >       objectClass: sambaGroupMapping
1237 >       cn: itsupport
1238 >       gidNumber: 1000
1239 >       sambaSID: S-1-5-21-XXX
1240 >       sambaGroupType: 2
1241 >       displayName: itsupport
1242 >       memberUid: ghenry
1243 >       memberUid: joebloggs
1244
1245 and create an LDIF file we can use to add our data to the local database, using
1246  some pretty strange choices of new attributes for demonstration purposes:
1247
1248 >       [ghenry@suretec test_configs]$ cat test-translucent-add.ldif 
1249 >       dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com
1250 >       businessCategory: frontend-override
1251 >       carLicense: LIVID
1252 >       employeeType: special
1253 >       departmentNumber: 9999999
1254 >       roomNumber: 41L-535
1255
1256 Searching against the proxy gives:
1257
1258 >       [ghenry@suretec test_configs]$ ldapsearch -x -H ldap://127.0.0.1:9001 "(cn=itsupport)"
1259 >       # itsupport, Groups, OxObjects, suretecsystems.com
1260 >       dn: cn=itsupport,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com
1261 >       objectClass: posixGroup
1262 >       objectClass: sambaGroupMapping
1263 >       cn: itsupport
1264 >       gidNumber: 1003
1265 >       SAMBASID: S-1-5-21-XXX
1266 >       SAMBAGROUPTYPE: 2
1267 >       displayName: itsupport
1268 >       memberUid: ghenry
1269 >       memberUid: joebloggs
1270 >       roomNumber: 41L-535
1271 >       departmentNumber: 9999999
1272 >       employeeType: special
1273 >       carLicense: LIVID
1274 >       businessCategory: frontend-override
1275
1276 Here we can see that the 5 new attributes are added to the remote entry before 
1277 being returned to the our client.
1278
1279 Because we have configured a local attribute to search against:
1280
1281 >       overlay     translucent
1282 >       translucent_local carLicense
1283
1284 we can also search for that to return the completely fabricated entry:
1285
1286 >       ldapsearch -x -H ldap://127.0.0.1:9001 (carLicense=LIVID)
1287
1288 This is an extremely feature because you can then extend a remote directory server
1289 locally and also search against the local entries.
1290
1291 Note: Because the translucent overlay does not perform any DN rewrites, the local
1292  and remote database instances must have the same suffix. Other configurations 
1293 will probably fail with No Such Object and other errors
1294
1295 H3: Further Information
1296
1297 {{:slapo-translucent(5)}}
1298
1299
1300 H2: Attribute Uniqueness
1301
1302
1303 H3: Overview
1304
1305 This overlay can be used with a backend database such as {{slapd-bdb(5)}}
1306 to enforce the uniqueness of some or all attributes within a subtree.
1307
1308
1309 H3: Attribute Uniqueness Configuration
1310
1311 This overlay is only effective on new data from the point the overlay is enabled. To
1312 check uniqueness for existing data, you can export and import your data again via the
1313 LDAP Add operation, which will not be suitable for large amounts of data, unlike {{B:slapcat}}.
1314
1315 For the following example, if uniqueness were enforced for the {{B:mail}} attribute, 
1316 the subtree would be searched for any other records which also have a {{B:mail}} attribute 
1317 containing the same value presented with an {{B:add}}, {{B:modify}} or {{B:modrdn}} operation 
1318 which are unique within the configured scope. If any are found, the request is rejected.
1319
1320 Note:  If no attributes are specified, for example {{B:ldap:///??sub?}}, then the URI applies to all non-operational attributes. However,
1321 the keyword {{B:ignore}} can be specified to exclude certain non-operational attributes. 
1322
1323 To search at the base dn of the current backend database ensuring uniqueness of the {{B:mail}}
1324 attribute, we simply add the following configuration:
1325
1326 >       overlay unique
1327 >       unique_uri ldap:///?mail?sub?
1328
1329 For an existing entry of:
1330
1331 >       dn: cn=gavin,dc=suretecsystems,dc=com
1332 >       objectClass: top
1333 >       objectClass: inetorgperson
1334 >       cn: gavin
1335 >       sn: henry
1336 >       mail: ghenry@suretecsystems.com
1337
1338 and we then try to add a new entry of:
1339
1340 >       dn: cn=robert,dc=suretecsystems,dc=com
1341 >       objectClass: top
1342 >       objectClass: inetorgperson
1343 >       cn: robert
1344 >       sn: jones
1345 >       mail: ghenry@suretecsystems.com
1346
1347 would result in an error like so:
1348
1349 >       adding new entry "cn=robert,dc=example,dc=com"
1350 >       ldap_add: Constraint violation (19)
1351 >               additional info: some attributes not unique
1352
1353 The overlay can have multiple URIs specified within a domain, allowing complex
1354 selections of objects and also have multiple {{B:unique_uri}} statements or 
1355 {{B:olcUniqueURI}} attributes which will create independent domains.
1356
1357 For more information and details about the {{B:strict}} and {{B:ignore}} keywords,
1358 please see the {{:slapo-unique(5)}} man page.
1359
1360 H3: Further Information
1361
1362 {{:slapo-unique(5)}}
1363
1364
1365 H2: Value Sorting
1366
1367
1368 H3: Overview
1369
1370 The Value Sorting overlay can be used with a backend database to sort the 
1371 values of specific multi-valued attributes within a subtree. The sorting occurs 
1372 whenever the attributes are returned in a search response.
1373
1374 H3: Value Sorting Configuration
1375
1376 Sorting can be specified in ascending or descending order, using either numeric 
1377 or alphanumeric sort methods. Additionally, a "weighted" sort can be specified,
1378  which uses a numeric weight prepended to the attribute values. 
1379
1380 The weighted sort is always performed in ascending order, but may be combined 
1381 with the other methods for values that all have equal weights. The weight is 
1382 specified by prepending an integer weight {<weight>} in front of each value 
1383 of the attribute for which weighted sorting is desired. This weighting factor 
1384 is stripped off and never returned in search results.
1385
1386 Here are a few examples:
1387
1388 >       loglevel    sync stats
1389 >       
1390 >       database    hdb
1391 >       suffix      "dc=suretecsystems,dc=com"
1392 >       directory   /usr/local/var/openldap-data
1393 >       
1394 >       ......
1395 >       
1396 >       overlay valsort
1397 >       valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com alpha-ascend
1398
1399 For example, ascend:
1400
1401 >       # sharedemail, Groups, suretecsystems.com
1402 >       dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com
1403 >       objectClass: posixGroup
1404 >       objectClass: top
1405 >       cn: sharedemail
1406 >       gidNumber: 517
1407 >       memberUid: admin
1408 >       memberUid: dovecot
1409 >       memberUid: laura
1410 >       memberUid: suretec
1411
1412 For weighted, we change our data to:
1413
1414 >       # sharedemail, Groups, suretecsystems.com
1415 >       dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com
1416 >       objectClass: posixGroup
1417 >       objectClass: top
1418 >       cn: sharedemail
1419 >       gidNumber: 517
1420 >       memberUid: {4}admin
1421 >       memberUid: {2}dovecot
1422 >       memberUid: {1}laura
1423 >       memberUid: {3}suretec
1424
1425 and change the config to:
1426
1427 >       overlay valsort
1428 >       valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com weighted
1429
1430 Searching now results in:
1431
1432 >       # sharedemail, Groups, OxObjects, suretecsystems.com
1433 >       dn: cn=sharedemail,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com
1434 >       objectClass: posixGroup
1435 >       objectClass: top
1436 >       cn: sharedemail
1437 >       gidNumber: 517
1438 >       memberUid: laura
1439 >       memberUid: dovecot
1440 >       memberUid: suretec
1441 >       memberUid: admin
1442
1443
1444 H3: Further Information
1445
1446 {{:slapo-valsort(5)}}
1447
1448
1449 H2: Overlay Stacking
1450
1451
1452 H3: Overview
1453
1454 Overlays can be stacked, which means that more than one overlay
1455 can be instantiated for each database, or for the {{EX:frontend}}.
1456 As a consequence, each overlays function is called, if defined,
1457 when overlay execution is invoked.
1458 Multiple overlays are executed in reverse order (as a stack)
1459 with respect to their definition in slapd.conf (5), or with respect
1460 to their ordering in the config database, as documented in slapd-config (5).
1461
1462
1463 H3: Example Scenarios
1464
1465
1466 H4: Samba