xref: /netbsd-src/external/bsd/openldap/dist/doc/guide/admin/overlays.sdf (revision 6a493d6bc668897c91594964a732d38505b70cbb)
1# OpenLDAP: pkg/openldap-guide/admin/overlays.sdf,v 1.8.2.30 2010/04/15 18:25:42 quanah Exp
2# Copyright 2007-2010 The OpenLDAP Foundation, All Rights Reserved.
3# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
4
5H1: Overlays
6
7Overlays are software components that provide hooks to functions analogous to
8those provided by backends, which can be stacked on top of the backend calls
9and as callbacks on top of backend responses to alter their behavior.
10
11Overlays may be compiled statically into {{slapd}}, or when module support
12is enabled, they may be dynamically loaded. Most of the overlays
13are only allowed to be configured on individual databases.
14
15Some can be stacked on the {{EX:frontend}} as well, for global use. This means that
16they can be executed after a request is parsed and validated, but right before the
17appropriate database is selected. The main purpose is to affect operations
18regardless of the database they will be handled by, and, in some cases,
19to influence the selection of the database by massaging the request DN.
20
21Essentially, 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
29When using {{slapd.conf}}(5), overlays that are configured before any other
30databases are considered global, as mentioned above. In fact they are implicitly
31stacked on top of the {{EX:frontend}} database. They can also be explicitly
32configured as such:
33
34>        database frontend
35>        overlay <overlay name>
36
37Overlays are usually documented by separate specific man pages in section 5;
38the naming convention is
39
40>        slapo-<overlay name>
41
42All distributed core overlays have a man page. Feel free to contribute to any,
43if you think there is anything missing in describing the behavior of the component
44and the implications of all the related configuration directives.
45
46Official overlays are located in
47
48>        servers/slapd/overlays/
49
50That directory also contains the file slapover.txt, which describes the
51rationale of the overlay implementation, and may serve as a guideline for the
52development of custom overlays.
53
54Contribware overlays are located in
55
56>        contrib/slapd-modules/<overlay name>/
57
58along with other types of run-time loadable components; they are officially
59distributed, but not maintained by the project.
60
61All the current overlays in OpenLDAP are listed and described in detail in the
62following sections.
63
64
65H2: Access Logging
66
67
68H3: Overview
69
70This overlay can record accesses to a given backend database on another
71database.
72
73This allows all of the activity on a given database to be reviewed using arbitrary
74LDAP queries, instead of just logging to local flat text files. Configuration
75options are available for selecting a subset of operation types to log, and to
76automatically prune older log records from the logging database. Log records
77are stored with audit schema to assure their readability whether viewed as LDIF
78or in raw form.
79
80It is also used for {{SECT:delta-syncrepl replication}}
81
82H3: Access Logging Configuration
83
84The 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
101The 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
110Accesslog 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
122An 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
166H3: Further Information
167
168{{slapo-accesslog(5)}} and the {{SECT:delta-syncrepl replication}} section.
169
170
171H2: Audit Logging
172
173The Audit Logging overlay can be used to record all changes on a given backend database to a specified log file.
174
175H3: Overview
176
177If the need arises whereby changes need to be logged as standard LDIF, then the auditlog overlay {{B:slapo-auditlog (5)}}
178can be used. Full examples are available in the man page {{B:slapo-auditlog (5)}}
179
180H3: Audit Logging Configuration
181
182If the directory is running vi {{F:slapd.d}}, then the following LDIF could be used to add the overlay to the overlay list
183in {{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
193In this example for testing, we are logging changes to {{F:/tmp/auditlog.ldif}}
194
195A 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
230H3: Further Information
231
232{{:slapo-auditlog(5)}}
233
234
235H2: Chaining
236
237
238H3: Overview
239
240The chain overlay provides basic chaining capability to the underlying
241database.
242
243What is chaining? It indicates the capability of a DSA to follow referrals on
244behalf of the client, so that distributed systems are viewed as a single
245virtual DSA by clients that are otherwise unable to "chase" (i.e. follow)
246referrals by themselves.
247
248The chain overlay is built on top of the ldap backend; it is compiled by
249default when {{B:--enable-ldap}}.
250
251
252H3: Chaining Configuration
253
254In order to demonstrate how this overlay works, we shall discuss a typical
255scenario which might be one master server and three Syncrepl slaves.
256
257On 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
269Add this below your {{syncrepl}} statement:
270
271>        updateref                  "ldap://ldapmaster.example.com/"
272
273The {{B:chain-tls}} statement enables TLS from the slave to the ldap master.
274The DITs are exactly the same between these machines, therefore whatever user
275bound to the slave will also exist on the master. If that DN does not have
276update privileges on the master, nothing will happen.
277
278You will need to restart the slave after these {{slapd.conf}} changes.
279Then, 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}}
281no restart is required.)
282
283Now start an {{ldapmodify}} on the slave and watch the logs. You should expect
284something 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
303And 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
310Note: You can clearly see the PROXYAUTHZ line on the master, indicating the
311proper identity assertion for the update on the master. Also note the slave
312immediately receiving the Syncrepl update from the master.
313
314H3: Handling Chaining Errors
315
316By default, if chaining fails, the original referral is returned to the client
317under the assumption that the client might want to try and follow the referral.
318
319With the following directive however, if the chaining fails at the provider
320side, the actual error is returned to the client.
321
322>        chain-return-error TRUE
323
324
325H3: Read-Back of Chained Modifications
326
327Occasionally, applications want to read back the data that they just wrote.
328If a modification requested to a shadow server was silently chained to its
329producer, an immediate read could result in receiving data not yet synchronized.
330In those cases, clients should use the {{B:dontusecopy}} control to ensure
331they are directed to the authoritative source for that piece of data.
332
333This control usually causes a referral to the actual source of the data
334to be returned.  However, when the {{slapo-chain(5)}} overlay is used,
335it intercepts the referral being returned in response to the
336{{B:dontusecopy}} control, and tries to fetch the requested data.
337
338
339H3: Further Information
340
341{{:slapo-chain(5)}}
342
343
344H2: Constraints
345
346
347H3: Overview
348
349This overlay enforces a regular expression constraint on all values
350of specified attributes during an LDAP modify request that contains add or modify
351commands. It is used to enforce a more rigorous syntax when the underlying attribute
352syntax is too general.
353
354
355H3: Constraint Configuration
356
357Configuration 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
364A specification like the above would reject any {{mail}} attribute which did not
365look like {{<alpha-numeric string>@mydomain.com}}.
366
367It would also reject any title attribute whose values were not listed in the
368title attribute of any {{titleCatalog}} entries in the given scope.
369
370An 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
381H3: Further Information
382
383{{:slapo-constraint(5)}}
384
385
386H2: Dynamic Directory Services
387
388
389H3: Overview
390
391The {{dds}} overlay to {{slapd}}(8) implements dynamic objects as per {{REF:RFC2589}}.
392The name {{dds}} stands for Dynamic Directory Services. It allows to define
393dynamic objects, characterized by the {{dynamicObject}} objectClass.
394
395Dynamic objects have a limited lifetime, determined by a time-to-live (TTL)
396that can be refreshed by means of a specific refresh extended operation. This
397operation allows to set the Client Refresh Period (CRP), namely the period
398between refreshes that is required to preserve the dynamic object from expiration.
399The expiration time is computed by adding the requested TTL to the current time.
400When dynamic objects reach the end of their lifetime without being further
401refreshed, they are automatically {{deleted}}. There is no guarantee of immediate
402deletion, so clients should not count on it.
403
404H3: Dynamic Directory Service Configuration
405
406A usage of dynamic objects might be to implement dynamic meetings; in this case,
407all the participants to the meeting are allowed to refresh the meeting object,
408but only the creator can delete it (otherwise it will be deleted when the TTL expires).
409
410If we add the overlay to an example database, specifying a Max TTL of 1 day, a
411min of 10 seconds, with a default TTL of 1 hour. We'll also specify an interval
412of 120 (less than 60s might be too small) seconds between expiration checks and a
413tolerance 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
422and add an index:
423
424>       entryExpireTimestamp
425
426Creating 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
435H4: Dynamic Directory Service ACLs
436
437Allow users to start a meeting and to join it; restrict refresh to the {{member}};
438restrict 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
464In simple terms, the user who created the {{OpenLDAP Documentation Meeting}} can add new attendees,
465refresh 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
469Any 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
472H3: Further Information
473
474{{:slapo-dds(5)}}
475
476
477H2: Dynamic Groups
478
479
480H3: Overview
481
482This overlay extends the Compare operation to detect
483members of a dynamic group. This overlay is now deprecated
484as all of its functions are available using the
485{{SECT:Dynamic Lists}} overlay.
486
487
488H3: Dynamic Group Configuration
489
490
491H2: Dynamic Lists
492
493
494H3: Overview
495
496This overlay allows expansion of dynamic groups and lists. Instead of having the
497group members or list attributes hard coded, this overlay allows us to define
498an LDAP search whose results will make up the group or list.
499
500H3: Dynamic List Configuration
501
502This module can behave both as a dynamic list and dynamic group, depending on
503the configuration. The syntax is as follows:
504
505>       overlay dynlist
506>       dynlist-attrset <group-oc> <URL-ad> [member-ad]
507
508The parameters to the {{F:dynlist-attrset}} directive have the following meaning:
509* {{F:<group-oc>}}: specifies which object class triggers the subsequent LDAP search.
510Whenever 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
512has to be a subtype of {{F:labeledURI}}. The attributes and values present in
513the search result are added to the entry unless {{F:member-ad}} is used (see
514below).
515* {{F:member-ad}}: if present, changes the overlay behavior into a dynamic group.
516Instead of inserting the results of the search in the entry, the distinguished name
517of the results are added as values of this attribute.
518
519Here is an example which will allow us to have an email alias which automatically
520expands to all user's emails according to our LDAP filter:
521
522In {{slapd.conf}}(5):
523
524>       overlay dynlist
525>       dynlist-attrset nisMailAlias labeledURI
526
527This means that whenever an entry which has the {{F:nisMailAlias}} object class is
528retrieved, the search specified in the {{F:labeledURI}} attribute is performed.
529
530Let'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
537If this entry is retrieved, the search specified in {{F:labeledURI}} will be
538performed and the results will be added to the entry just as if they have always
539been there. In this case, the search filter selects all entries directly
540under {{F:ou=People}} that have the {{F:inetOrgPerson}} object class and retrieves
541the {{F:mail}} attribute, if it exists.
542
543This is what gets added to the entry when we have two users under {{F:ou=People}}
544that match the filter:
545!import "allmail-en.png"; align="center"; title="Dynamic list for email aliases"
546FT[align="Center"] Figure X.Y: Dynamic List for all emails
547
548The configuration for a dynamic group is similar. Let's see an example which would
549automatically populate an {{F:allusers}} group with all the user accounts in the
550directory.
551
552In {{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
562Let'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
569The behavior is similar to the dynamic list configuration we had before:
570whenever an entry with the {{F:groupOfURLs}} object class is retrieved, the
571search specified in the {{F:labeledURI}} attribute is performed. But this time,
572only the distinguished names of the results are added, and as values of the
573{{F:member}} attribute.
574
575This is what we get:
576!import "allusersgroup-en.png"; align="center"; title="Dynamic group for all users"
577FT[align="Center"] Figure X.Y: Dynamic Group for all users
578
579Note that a side effect of this scheme of dynamic groups is that the members
580need 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
582distinguished names. The {{F:memberUid}} attribute used in the {{F:posixGroup}}
583object class can hold only names, not DNs, and is therefore not suitable for
584dynamic groups.
585
586
587H3: Further Information
588
589{{:slapo-dynlist(5)}}
590
591
592H2: Reverse Group Membership Maintenance
593
594H3: Overview
595
596In some scenarios, it may be desirable for a client to be able to determine
597which groups an entry is a member of, without performing an additional search.
598Examples of this are applications using the {{TERM:DIT}} for access control
599based on group authorization.
600
601The {{B:memberof}} overlay updates an attribute (by default {{B:memberOf}}) whenever
602changes occur to the membership attribute (by default {{B:member}}) of entries of the
603objectclass (by default {{B:groupOfNames}}) configured to trigger updates.
604
605Thus, it provides maintenance of the list of groups an entry is a member of,
606when usual maintenance of groups is done by modifying the members on the group
607entry.
608
609H3: Member Of Configuration
610
611The typical use of this overlay requires just enabling the overlay for a
612specific 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
630adding 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
654Results 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
665Note that the {{B:memberOf}} attribute is an operational attribute, so it must be
666requested explicitly.
667
668
669H3: Further Information
670
671{{:slapo-memberof(5)}}
672
673
674H2: 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
678entries held by one or more master servers.  Changes are propagated
679from the master server to replica (slave) servers using LDAP Sync
680replication.  An LDAP cache is a special type of replica which holds
681entries corresponding to search filters instead of subtrees.
682
683H3: Overview
684
685The proxy cache extension of slapd is designed to improve the
686responsiveness of the ldap and meta backends. It handles a search
687request (query)
688by first determining whether it is contained in any cached search
689filter. Contained requests are answered from the proxy cache's local
690database. Other requests are passed on to the underlying ldap or
691meta backend and processed as usual.
692
693E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
694{{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}
695
696Correct matching rules and syntaxes are used while comparing
697assertions for query containment. To simplify the query containment
698problem, a list of cacheable "templates" (defined below) is specified
699at configuration time. A query is cached or answered only if it
700belongs to one of these templates. The entries corresponding to
701cached queries are stored in the proxy cache local database while
702its associated meta information (filter, scope, base, attributes)
703is stored in main memory.
704
705A template is a prototype for generating LDAP search requests.
706Templates are described by a prototype search filter and a list of
707attributes which are required in queries generated from the template.
708The representation for prototype filter is similar to {{REF:RFC4515}},
709except that the assertion values are missing. Examples of prototype
710filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by
711search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively.
712
713The cache replacement policy removes the least recently used (LRU)
714query and entries belonging to only that query. Queries are allowed
715a maximum time to live (TTL) in the cache thus providing weak
716consistency. A background task periodically checks the cache for
717expired queries and removes them.
718
719The Proxy Cache paper
720({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
721design and implementation details.
722
723
724H3: Proxy Cache Configuration
725
726The cache configuration specific directives described below must
727appear after a {{EX:overlay proxycache}} directive within a
728{{EX:"database meta"}} or {{EX:database ldap}} section of
729the server's {{slapd.conf}}(5) file.
730
731H4: Setting cache parameters
732
733> proxyCache <DB> <maxentries> <nattrsets> <entrylimit> <period>
734
735This directive enables proxy caching and sets general cache
736parameters.  The <DB> parameter specifies which underlying database
737is to be used to hold cached entries.  It should be set to
738{{EX:bdb}} or {{EX:hdb}}.  The <maxentries> parameter specifies the
739total 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:proxyAttrSet}} directive) that may be
742defined.  The <entrylimit> parameter specifies the maximum number of
743entries in a cacheable query.  The <period> specifies the consistency
744check period (in seconds).  In each period, queries with expired
745TTLs are removed.
746
747H4: Defining attribute sets
748
749> proxyAttrset <index> <attrs...>
750
751Used to associate a set of attributes to an index. Each attribute
752set is associated with an index number from 0 to <numattrsets>-1.
753These indices are used by the proxyTemplate directive to define
754cacheable templates.
755
756H4: Specifying cacheable templates
757
758> proxyTemplate <prototype_string> <attrset_index> <TTL>
759
760Specifies a cacheable template and the "time to live" (in sec) <TTL>
761for queries belonging to the template. A template is described by
762its prototype filter string and set of required attributes identified
763by <attrset_index>.
764
765
766H4: Example
767
768An example {{slapd.conf}}(5) database section for a caching server
769which proxies for the {{EX:"dc=example,dc=com"}} subtree held
770at 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 proxycache
777>	proxycache    bdb 100000 1 1000 100
778>	proxyAttrset  0 mail postaladdress telephonenumber
779>	proxyTemplate (sn=) 0 3600
780>	proxyTemplate (&(sn=)(givenName=)) 0 3600
781>	proxyTemplate (&(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
789H5: Cacheable Queries
790
791A LDAP search query is cacheable when its filter matches one of the
792templates as defined in the "proxyTemplate" statements and when it references
793only the attributes specified in the corresponding attribute set.
794In the example above the attribute set number 0 defines that only the
795attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
796proxyTemplates.
797
798H5: Examples:
799
800>	Filter: (&(sn=Richard*)(givenName=jack))
801>	Attrs: mail telephoneNumber
802
803    is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
804    attributes are contained in proxyAttrset 0.
805
806>	Filter: (&(sn=Richard*)(telephoneNumber))
807>	Attrs: givenName
808
809    is not cacheable, because the filter does not match the template,
810    nor is the attribute givenName stored in the cache
811
812>	Filter: (|(sn=Richard*)(givenName=jack))
813>	Attrs: mail telephoneNumber
814
815    is not cacheable, because the filter does not match the template ( logical
816    OR "|" condition instead of logical AND "&" )
817
818
819H3: Further Information
820
821{{:slapo-pcache(5)}}
822
823
824H2: Password Policies
825
826
827H3: Overview
828
829This overlay follows the specifications contained in the draft RFC titled
830draft-behera-ldap-password-policy-09. While the draft itself is expired, it has
831been implemented in several directory servers, including slapd. Nonetheless,
832it is important to note that it is a draft, meaning that it is subject to change
833and is a work-in-progress.
834
835The key abilities of the password policy overlay are as follows:
836
837* Enforce a minimum length for new passwords
838* Make sure passwords are not changed too frequently
839* 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
840* Maintain a history of passwords to prevent password re-use
841* Prevent password guessing by locking a password for a specified period of time after repeated authentication failures
842* Force a password to be changed at the next authentication
843* Set an administrative lock on an account
844* Support multiple password policies on a default or a per-object basis.
845* Perform arbitrary quality checks using an external loadable module. This is a non-standard extension of the draft RFC.
846
847
848H3: Password Policy Configuration
849
850Instantiate the module in the database where it will be used, after adding the
851new ppolicy schema and loading the ppolicy module. The following example shows
852the ppolicy module being added to the database that handles the naming
853context "dc=example,dc=com". In this example we are also specifying the DN of
854a policy object to use if none other is specified in a user's object.
855
856>       database bdb
857>       suffix "dc=example,dc=com"
858>       [...additional database configuration directives go here...]
859>
860>       overlay ppolicy
861>       ppolicy_default "cn=default,ou=policies,dc=example,dc=com"
862
863
864Now we need a container for the policy objects. In our example the password
865policy objects are going to be placed in a section of the tree called
866"ou=policies,dc=example,dc=com":
867
868>       dn: ou=policies,dc=example,dc=com
869>       objectClass: organizationalUnit
870>       objectClass: top
871>       ou: policies
872
873
874The default policy object that we are creating defines the following policies:
875
876* The user is allowed to change his own password. Note that the directory ACLs for this attribute can also affect this ability (pwdAllowUserChange: TRUE).
877* 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.
878* 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).
879* 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.
880* When the password for a DN has expired, the server will allow five additional "grace" logins (pwdGraceAuthNLimit: 5).
881* The server will maintain a history of the last five passwords that were used for a DN (pwdInHistory: 5).
882* The server will lock the account after the maximum number of failed bind attempts has been exceeded (pwdLockout: TRUE).
883* When the server has locked an account, the server will keep it locked until an administrator unlocks it (pwdLockoutDuration: 0)
884* The server will reset its failed bind count after a period of 30 seconds.
885* Passwords will not expire (pwdMaxAge: 0).
886* Passwords can be changed as often as desired (pwdMinAge: 0).
887* Passwords must be at least 5 characters in length (pwdMinLength: 5).
888* The password does not need to be changed at the first bind or when the administrator has reset the password (pwdMustChange: FALSE)
889* The current password does not need to be included with password change requests (pwdSafeModify: FALSE)
890* The server will only allow five failed binds in a row for a particular DN (pwdMaxFailure: 5).
891
892
893The actual policy would be:
894
895>       dn: cn=default,ou=policies,dc=example,dc=com
896>       cn: default
897>       objectClass: pwdPolicy
898>       objectClass: person
899>       objectClass: top
900>       pwdAllowUserChange: TRUE
901>       pwdAttribute: userPassword
902>       pwdCheckQuality: 2
903>       pwdExpireWarning: 600
904>       pwdFailureCountInterval: 30
905>       pwdGraceAuthNLimit: 5
906>       pwdInHistory: 5
907>       pwdLockout: TRUE
908>       pwdLockoutDuration: 0
909>       pwdMaxAge: 0
910>       pwdMaxFailure: 5
911>       pwdMinAge: 0
912>       pwdMinLength: 5
913>       pwdMustChange: FALSE
914>       pwdSafeModify: FALSE
915>       sn: dummy value
916
917You can create additional policy objects as needed.
918
919
920There are two ways password policy can be applied to individual objects:
921
9221. The pwdPolicySubentry in a user's object - If a user's object has a
923pwdPolicySubEntry attribute specifying the DN of a policy object, then
924the policy defined by that object is applied.
925
9262. Default password policy - If there is no specific pwdPolicySubentry set
927for an object, and the password policy module was configured with the DN of a
928default policy object and if that object exists, then the policy defined in
929that object is applied.
930
931Please see {{slapo-ppolicy(5)}} for complete explanations of features and discussion of
932 "Password Management Issues" at {{URL:http://www.symas.com/blog/?page_id=66}}
933
934
935H3: Further Information
936
937{{:slapo-ppolicy(5)}}
938
939
940H2: Referential Integrity
941
942
943H3: Overview
944
945This overlay can be used with a backend database such as slapd-bdb(5)
946to maintain the cohesiveness of a schema which utilizes reference
947attributes.
948
949Whenever a {{modrdn}} or {{delete}} is performed, that is, when an entry's DN
950is renamed or an entry is removed, the server will search the directory for
951references to this DN (in selected attributes: see below) and update them
952accordingly. If it was a {{delete}} operation, the reference is deleted. If it
953was a {{modrdn}} operation, then the reference is updated with the new DN.
954
955For example, a very common administration task is to maintain group membership
956lists, specially when users are removed from the directory. When an
957user account is deleted or renamed, all groups this user is a member of have to be
958updated. LDAP administrators usually have scripts for that. But we can use the
959{{F:refint}} overlay to automate this task. In this example, if the user is
960removed from the directory, the overlay will take care to remove the user from
961all the groups he/she was a member of. No more scripting for this.
962
963H3: Referential Integrity Configuration
964
965The configuration for this overlay is as follows:
966
967>       overlay refint
968>       refint_attributes <attribute [attribute ...]>
969>       refint_nothing <string>
970
971* {{F:refint_attributes}}: this parameter specifies a space separated list of
972attributes which will have the referential integrity maintained. When an entry is
973removed or has its DN renamed, the server will do an internal search for any of the
974{{F:refint_attributes}} that point to the affected DN and update them accordingly. IMPORTANT:
975the attributes listed here must have the {{F:distinguishedName}} syntax, that is,
976hold DNs as values.
977* {{F:refint_nothing}}: some times, while trying to maintain the referential
978integrity, the server has to remove the last attribute of its kind from an
979entry. This may be prohibited by the schema: for example, the
980{{F:groupOfNames}} object class requires at least one member. In these cases,
981the server will add the attribute value specified in {{F:refint_nothing}}
982to the entry.
983
984To illustrate this overlay, we will use the group membership scenario.
985
986In {{F:slapd.conf}}:
987
988>       overlay refint
989>       refint_attributes member
990>       refint_nothing "cn=admin,dc=example,dc=com"
991
992This configuration tells the overlay to maintain the referential integrity of the {{F:member}}
993attribute. This attribute is used in the {{F:groupOfNames}} object class which always needs
994a member, so we add the {{F:refint_nothing}} directive to fill in the group with a standard
995member should all the members vanish.
996
997If we have the following group membership, the refint overlay will
998automatically remove {{F:john}} from the group if his entry is removed from the
999directory:
1000
1001!import "refint.png"; align="center"; title="Group membership"
1002FT[align="Center"] Figure X.Y: Maintaining referential integrity in groups
1003
1004Notice that if we rename ({{F:modrdn}}) the {{F:john}} entry to, say, {{F:jsmith}}, the refint
1005overlay will also rename the reference in the {{F:member}} attribute, so the group membership
1006stays correct.
1007
1008If we removed all users from the directory who are a member of this group, then the end result
1009would be a single member in the group: {{F:cn=admin,dc=example,dc=com}}. This is the
1010{{F:refint_nothing}} parameter kicking into action so that the schema is not violated.
1011
1012
1013H3: Further Information
1014
1015{{:slapo-refint(5)}}
1016
1017
1018H2: Return Code
1019
1020
1021H3: Overview
1022
1023This overlay is useful to test the behavior of clients when
1024server-generated erroneous and/or unusual responses occur,
1025for example; error codes, referrals, excessive response times and so on.
1026
1027This would be classed as a debugging tool whilst developing client software
1028or additional Overlays.
1029
1030For detailed information, please see the {{slapo-retcode(5)}} man page.
1031
1032
1033H3: Return Code Configuration
1034
1035The retcode overlay utilizes the "return code" schema described in the man page.
1036This schema is specifically designed for use with this overlay and is not intended
1037to be used otherwise.
1038
1039Note: The necessary schema is loaded automatically by the overlay.
1040
1041An example configuration might be:
1042
1043>       overlay         retcode
1044>       retcode-parent  "ou=RetCodes,dc=example,dc=com"
1045>       include         ./retcode.conf
1046>
1047>       retcode-item    "cn=Unsolicited"                0x00 unsolicited="0"
1048>       retcode-item    "cn=Notice of Disconnect"       0x00 unsolicited="1.3.6.1.4.1.1466.20036"
1049>       retcode-item    "cn=Pre-disconnect"             0x34 flags="pre-disconnect"
1050>       retcode-item    "cn=Post-disconnect"            0x34 flags="post-disconnect"
1051
1052Note: {{retcode.conf}} can be found in the openldap source at: {{F:tests/data/retcode.conf}}
1053
1054An excerpt of a {{F:retcode.conf}} would be something like:
1055
1056>       retcode-item    "cn=success"                            0x00
1057>
1058>       retcode-item    "cn=success w/ delay"                   0x00    sleeptime=2
1059>
1060>       retcode-item    "cn=operationsError"                    0x01
1061>       retcode-item    "cn=protocolError"                      0x02
1062>       retcode-item    "cn=timeLimitExceeded"                  0x03    op=search
1063>       retcode-item    "cn=sizeLimitExceeded"                  0x04    op=search
1064>       retcode-item    "cn=compareFalse"                       0x05    op=compare
1065>       retcode-item    "cn=compareTrue"                        0x06    op=compare
1066>       retcode-item    "cn=authMethodNotSupported"             0x07
1067>       retcode-item    "cn=strongAuthNotSupported"             0x07    text="same as authMethodNotSupported"
1068>       retcode-item    "cn=strongAuthRequired"                 0x08
1069>       retcode-item    "cn=strongerAuthRequired"               0x08    text="same as strongAuthRequired"
1070
1071Please see {{F:tests/data/retcode.conf}} for a complete {{F:retcode.conf}}
1072
1073
1074H3: Further Information
1075
1076{{:slapo-retcode(5)}}
1077
1078
1079H2: Rewrite/Remap
1080
1081
1082H3: Overview
1083
1084It performs basic DN/data rewrite and objectClass/attributeType mapping. Its
1085usage is mostly intended to provide virtual views of existing data either
1086remotely, in conjunction with the proxy backend described in {{slapd-ldap(5)}},
1087or locally, in conjunction with the relay backend described in {{slapd-relay(5)}}.
1088
1089This overlay is extremely configurable and advanced, therefore recommended
1090reading is the {{slapo-rwm(5)}} man page.
1091
1092
1093H3: Rewrite/Remap Configuration
1094
1095
1096H3: Further Information
1097
1098{{:slapo-rwm(5)}}
1099
1100
1101H2: Sync Provider
1102
1103
1104H3: Overview
1105
1106This overlay implements the provider-side support for the LDAP Content Synchronization
1107({{REF:RFC4533}}) as well as syncrepl replication support, including persistent search functionality.
1108
1109H3: Sync Provider Configuration
1110
1111There is very little configuration needed for this overlay, in fact for many situations merely loading
1112the overlay will suffice.
1113
1114However, because the overlay creates a contextCSN attribute in the root entry of the database which is
1115updated for every write operation performed against the database and only updated in memory, it is
1116recommended to configure a checkpoint so that the contextCSN is written into the underlying database to
1117minimize recovery time after an unclean shutdown:
1118
1119>       overlay syncprov
1120>       syncprov-checkpoint 100 10
1121
1122For every 100 operations or 10 minutes, which ever is sooner, the contextCSN will be checkpointed.
1123
1124The four configuration directives available are {{B:syncprov-checkpoint}}, {{B:syncprov-sessionlog}},
1125{{B:syncprov-nopresent}} and {{B:syncprov-reloadhint}} which are covered in the man page discussing
1126various other scenarios where this overlay can be used.
1127
1128H3: Further Information
1129
1130The {{:slapo-syncprov(5)}} man page and the {{SECT:Configuring the different replication types}} section
1131
1132
1133H2: Translucent Proxy
1134
1135
1136H3: Overview
1137
1138This overlay can be used with a backend database such as {{:slapd-bdb}}(5)
1139to create a "translucent proxy".
1140
1141Entries retrieved from a remote LDAP server may have some or all attributes
1142overridden, or new attributes added, by entries in the local database before
1143being presented to the client.
1144
1145A search operation is first populated with entries from the remote LDAP server,
1146the attributes of which are then overridden with any attributes defined in the
1147local database. Local overrides may be populated with the add, modify, and
1148modrdn operations, the use of which is restricted to the root user of the
1149translucent local database.
1150
1151A compare operation will perform a comparison with attributes defined in the
1152local database record (if any) before any comparison is made with data in the
1153remote database.
1154
1155
1156H3: Translucent Proxy Configuration
1157
1158There are various options available with this overlay, but for this example we
1159will demonstrate adding new attributes to a remote entry and also searching
1160against these newly added local attributes. For more information about overriding remote
1161entries and search configuration, please see {{:slapo-translucent(5)}}
1162
1163Note: The Translucent Proxy overlay will disable schema checking in the local
1164database, so that an entry consisting of overlay attributes need not adhere
1165 to the complete schema.
1166
1167First we configure the overlay in the normal manner:
1168
1169>       include     /usr/local/etc/openldap/schema/core.schema
1170>       include     /usr/local/etc/openldap/schema/cosine.schema
1171>       include     /usr/local/etc/openldap/schema/nis.schema
1172>       include     /usr/local/etc/openldap/schema/inetorgperson.schema
1173>
1174>       pidfile     ./slapd.pid
1175>       argsfile    ./slapd.args
1176>
1177>       database    bdb
1178>       suffix      "dc=suretecsystems,dc=com"
1179>       rootdn      "cn=trans,dc=suretecsystems,dc=com"
1180>       rootpw      secret
1181>       directory   ./openldap-data
1182>
1183>       index       objectClass eq
1184>
1185>       overlay     translucent
1186>       translucent_local carLicense
1187>
1188>       uri         ldap://192.168.X.X:389
1189>       lastmod     off
1190>       acl-bind    binddn="cn=admin,dc=suretecsystems,dc=com" credentials="blahblah"
1191
1192You will notice the overlay directive and a directive to say what attribute we
1193want to be able to search against in the local database. We must also load the
1194ldap backend which will connect to the remote directory server.
1195
1196Now we take an example LDAP group:
1197
1198>       # itsupport, Groups, suretecsystems.com
1199>       dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com
1200>       objectClass: posixGroup
1201>       objectClass: sambaGroupMapping
1202>       cn: itsupport
1203>       gidNumber: 1000
1204>       sambaSID: S-1-5-21-XXX
1205>       sambaGroupType: 2
1206>       displayName: itsupport
1207>       memberUid: ghenry
1208>       memberUid: joebloggs
1209
1210and create an LDIF file we can use to add our data to the local database, using
1211 some pretty strange choices of new attributes for demonstration purposes:
1212
1213>       [ghenry@suretec test_configs]$ cat test-translucent-add.ldif
1214>       dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com
1215>       businessCategory: frontend-override
1216>       carLicense: LIVID
1217>       employeeType: special
1218>       departmentNumber: 9999999
1219>       roomNumber: 41L-535
1220
1221Searching against the proxy gives:
1222
1223>       [ghenry@suretec test_configs]$ ldapsearch -x -H ldap://127.0.0.1:9001 "(cn=itsupport)"
1224>       # itsupport, Groups, OxObjects, suretecsystems.com
1225>       dn: cn=itsupport,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com
1226>       objectClass: posixGroup
1227>       objectClass: sambaGroupMapping
1228>       cn: itsupport
1229>       gidNumber: 1003
1230>       SAMBASID: S-1-5-21-XXX
1231>       SAMBAGROUPTYPE: 2
1232>       displayName: itsupport
1233>       memberUid: ghenry
1234>       memberUid: joebloggs
1235>       roomNumber: 41L-535
1236>       departmentNumber: 9999999
1237>       employeeType: special
1238>       carLicense: LIVID
1239>       businessCategory: frontend-override
1240
1241Here we can see that the 5 new attributes are added to the remote entry before
1242being returned to the our client.
1243
1244Because we have configured a local attribute to search against:
1245
1246>       overlay     translucent
1247>       translucent_local carLicense
1248
1249we can also search for that to return the completely fabricated entry:
1250
1251>       ldapsearch -x -H ldap://127.0.0.1:9001 (carLicense=LIVID)
1252
1253This is an extremely feature because you can then extend a remote directory server
1254locally and also search against the local entries.
1255
1256Note: Because the translucent overlay does not perform any DN rewrites, the local
1257 and remote database instances must have the same suffix. Other configurations
1258will probably fail with No Such Object and other errors
1259
1260H3: Further Information
1261
1262{{:slapo-translucent(5)}}
1263
1264
1265H2: Attribute Uniqueness
1266
1267
1268H3: Overview
1269
1270This overlay can be used with a backend database such as {{slapd-bdb(5)}}
1271to enforce the uniqueness of some or all attributes within a subtree.
1272
1273
1274H3: Attribute Uniqueness Configuration
1275
1276This overlay is only effective on new data from the point the overlay is enabled. To
1277check uniqueness for existing data, you can export and import your data again via the
1278LDAP Add operation, which will not be suitable for large amounts of data, unlike {{B:slapcat}}.
1279
1280For the following example, if uniqueness were enforced for the {{B:mail}} attribute,
1281the subtree would be searched for any other records which also have a {{B:mail}} attribute
1282containing the same value presented with an {{B:add}}, {{B:modify}} or {{B:modrdn}} operation
1283which are unique within the configured scope. If any are found, the request is rejected.
1284
1285Note:  If no attributes are specified, for example {{B:ldap:///??sub?}}, then the URI applies to all non-operational attributes. However,
1286the keyword {{B:ignore}} can be specified to exclude certain non-operational attributes.
1287
1288To search at the base dn of the current backend database ensuring uniqueness of the {{B:mail}}
1289attribute, we simply add the following configuration:
1290
1291>       overlay unique
1292>       unique_uri ldap:///?mail?sub?
1293
1294For an existing entry of:
1295
1296>       dn: cn=gavin,dc=suretecsystems,dc=com
1297>       objectClass: top
1298>       objectClass: inetorgperson
1299>       cn: gavin
1300>       sn: henry
1301>       mail: ghenry@suretecsystems.com
1302
1303and we then try to add a new entry of:
1304
1305>       dn: cn=robert,dc=suretecsystems,dc=com
1306>       objectClass: top
1307>       objectClass: inetorgperson
1308>       cn: robert
1309>       sn: jones
1310>       mail: ghenry@suretecsystems.com
1311
1312would result in an error like so:
1313
1314>       adding new entry "cn=robert,dc=example,dc=com"
1315>       ldap_add: Constraint violation (19)
1316>               additional info: some attributes not unique
1317
1318The overlay can have multiple URIs specified within a domain, allowing complex
1319selections of objects and also have multiple {{B:unique_uri}} statements or
1320{{B:olcUniqueURI}} attributes which will create independent domains.
1321
1322For more information and details about the {{B:strict}} and {{B:ignore}} keywords,
1323please see the {{:slapo-unique(5)}} man page.
1324
1325H3: Further Information
1326
1327{{:slapo-unique(5)}}
1328
1329
1330H2: Value Sorting
1331
1332
1333H3: Overview
1334
1335The Value Sorting overlay can be used with a backend database to sort the
1336values of specific multi-valued attributes within a subtree. The sorting occurs
1337whenever the attributes are returned in a search response.
1338
1339H3: Value Sorting Configuration
1340
1341Sorting can be specified in ascending or descending order, using either numeric
1342or alphanumeric sort methods. Additionally, a "weighted" sort can be specified,
1343 which uses a numeric weight prepended to the attribute values.
1344
1345The weighted sort is always performed in ascending order, but may be combined
1346with the other methods for values that all have equal weights. The weight is
1347specified by prepending an integer weight {<weight>} in front of each value
1348of the attribute for which weighted sorting is desired. This weighting factor
1349is stripped off and never returned in search results.
1350
1351Here are a few examples:
1352
1353>       loglevel    sync stats
1354>
1355>       database    hdb
1356>       suffix      "dc=suretecsystems,dc=com"
1357>       directory   /usr/local/var/openldap-data
1358>
1359>       ......
1360>
1361>       overlay valsort
1362>       valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com alpha-ascend
1363
1364For example, ascend:
1365
1366>       # sharedemail, Groups, suretecsystems.com
1367>       dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com
1368>       objectClass: posixGroup
1369>       objectClass: top
1370>       cn: sharedemail
1371>       gidNumber: 517
1372>       memberUid: admin
1373>       memberUid: dovecot
1374>       memberUid: laura
1375>       memberUid: suretec
1376
1377For weighted, we change our data to:
1378
1379>       # sharedemail, Groups, suretecsystems.com
1380>       dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com
1381>       objectClass: posixGroup
1382>       objectClass: top
1383>       cn: sharedemail
1384>       gidNumber: 517
1385>       memberUid: {4}admin
1386>       memberUid: {2}dovecot
1387>       memberUid: {1}laura
1388>       memberUid: {3}suretec
1389
1390and change the config to:
1391
1392>       overlay valsort
1393>       valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com weighted
1394
1395Searching now results in:
1396
1397>       # sharedemail, Groups, OxObjects, suretecsystems.com
1398>       dn: cn=sharedemail,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com
1399>       objectClass: posixGroup
1400>       objectClass: top
1401>       cn: sharedemail
1402>       gidNumber: 517
1403>       memberUid: laura
1404>       memberUid: dovecot
1405>       memberUid: suretec
1406>       memberUid: admin
1407
1408
1409H3: Further Information
1410
1411{{:slapo-valsort(5)}}
1412
1413
1414H2: Overlay Stacking
1415
1416
1417H3: Overview
1418
1419Overlays can be stacked, which means that more than one overlay
1420can be instantiated for each database, or for the {{EX:frontend}}.
1421As a consequence, each overlays function is called, if defined,
1422when overlay execution is invoked.
1423Multiple overlays are executed in reverse order (as a stack)
1424with respect to their definition in slapd.conf (5), or with respect
1425to their ordering in the config database, as documented in slapd-config (5).
1426
1427
1428H3: Example Scenarios
1429
1430
1431H4: Samba
1432