overlays.sdf 54.6 KB
Newer Older
1
# $OpenLDAP$
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
2
# Copyright 2007-2020 The OpenLDAP Foundation, All Rights Reserved.
3
4
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.

5
6
H1: Overlays

7
8
9
10
Overlays are software components that provide hooks to functions analogous to 
those provided by backends, which can be stacked on top of the backend calls 
and as callbacks on top of backend responses to alter their behavior. 

11
Overlays may be compiled statically into {{slapd}}, or when module support
12
is enabled, they may be dynamically loaded. Most of the overlays
Howard Chu's avatar
Howard Chu committed
13
are only allowed to be configured on individual databases.
14

Howard Chu's avatar
Howard Chu committed
15
16
17
18
19
20
21
Some can be stacked on the {{EX:frontend}} as well, for global use. This means that
they can be executed after a request is parsed and validated, but right before the 
appropriate database is selected. The main purpose is to affect operations 
regardless of the database they will be handled by, and, in some cases, 
to influence the selection of the database by massaging the request DN. 

Essentially, overlays represent a means to:
22

Gavin Henry's avatar
Gavin Henry committed
23
    * customize the behavior of existing backends without changing the backend 
24
25
26
27
28
      code and without requiring one to write a new custom backend with 
      complete functionality
    * write functionality of general usefulness that can be applied to 
      different backend types

Howard Chu's avatar
Howard Chu committed
29
30
31
32
33
34
35
36
When using {{slapd.conf}}(5), overlays that are configured before any other
databases are considered global, as mentioned above. In fact they are implicitly
stacked on top of the {{EX:frontend}} database. They can also be explicitly
configured as such:

>        database frontend
>        overlay <overlay name>

37
38
39
Overlays are usually documented by separate specific man pages in section 5; 
the naming convention is

Gavin Henry's avatar
Gavin Henry committed
40
>        slapo-<overlay name>
41

42
43
44
All distributed core overlays have a man page. Feel free to contribute to any, 
if you think there is anything missing in describing the behavior of the component 
and the implications of all the related configuration directives.
45
46
47

Official overlays are located in

Gavin Henry's avatar
Gavin Henry committed
48
>        servers/slapd/overlays/
49
50

That directory also contains the file slapover.txt, which describes the 
Howard Chu's avatar
Howard Chu committed
51
rationale of the overlay implementation, and may serve as a guideline for the 
52
53
54
55
development of custom overlays.

Contribware overlays are located in

Gavin Henry's avatar
Gavin Henry committed
56
>        contrib/slapd-modules/<overlay name>/
57
58
59
60

along with other types of run-time loadable components; they are officially 
distributed, but not maintained by the project.

Howard Chu's avatar
Howard Chu committed
61
All the current overlays in OpenLDAP are listed and described in detail in the 
62
63
following sections.

64
65
66
67
68
69

H2: Access Logging


H3: Overview

70
71
72
This overlay can record accesses to a given backend database on another
database.

Gavin Henry's avatar
Gavin Henry committed
73
74
75
76
77
78
79
80
This allows all of the activity on a given database to be reviewed using arbitrary 
LDAP queries, instead of just logging to local flat text files. Configuration 
options are available for selecting a subset of operation types to log, and to 
automatically prune older log records from the logging database. Log records 
are stored with audit schema to assure their readability whether viewed as LDIF 
or in raw form.

It is also used for {{SECT:delta-syncrepl replication}}
81

82
83
84
Note: An accesslog database is unique to a given master. It should
never be replicated.

85
86
H3: Access Logging Configuration

Gavin Henry's avatar
Gavin Henry committed
87
88
The following is a basic example that implements Access Logging:

89
>        database mdb
Gavin Henry's avatar
Gavin Henry committed
90
91
92
93
94
95
96
>        suffix dc=example,dc=com
>        ...
>        overlay accesslog
>        logdb cn=log
>        logops writes reads
>        logold (objectclass=person)
>        
97
>        database mdb
Gavin Henry's avatar
Gavin Henry committed
98
99
100
101
102
103
104
105
>        suffix cn=log
>        ...
>        index reqStart eq
>        access to *
>          by dn.base="cn=admin,dc=example,dc=com" read

The following is an example used for {{SECT:delta-syncrepl replication}}:

106
>        database mdb
Gavin Henry's avatar
Gavin Henry committed
107
108
109
110
>        suffix cn=accesslog
>        directory /usr/local/var/openldap-accesslog
>        rootdn cn=accesslog
>        index default eq
111
>        index entryCSN,objectClass,reqEnd,reqResult,reqStart,reqDN
Gavin Henry's avatar
Gavin Henry committed
112
113
114

Accesslog overlay definitions for the primary db

115
>        database mdb
Gavin Henry's avatar
Gavin Henry committed
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
>        suffix dc=example,dc=com
>        ...
>        overlay accesslog
>        logdb cn=accesslog
>        logops writes
>        logsuccess TRUE
>        # scan the accesslog DB every day, and purge entries older than 7 days
>        logpurge 07+00:00 01+00:00

An example search result against {{B:cn=accesslog}} might look like:

>        [ghenry@suretec ghenry]# ldapsearch -x -b cn=accesslog
>        # extended LDIF
>        #
>        # LDAPv3
>        # base <cn=accesslog> with scope subtree
>        # filter: (objectclass=*)
>        # requesting: ALL
>        #
>        
>        # accesslog
>        dn: cn=accesslog
>        objectClass: auditContainer
>        cn: accesslog
>        
>        # 20080110163829.000004Z, accesslog
>        dn: reqStart=20080110163829.000004Z,cn=accesslog
>        objectClass: auditModify
>        reqStart: 20080110163829.000004Z
>        reqEnd: 20080110163829.000005Z
>        reqType: modify
>        reqSession: 196696
>        reqAuthzID: cn=admin,dc=suretecsystems,dc=com
>        reqDN: uid=suretec-46022f8$,ou=Users,dc=suretecsystems,dc=com
>        reqResult: 0
>        reqMod: sambaPwdCanChange:- ###CENSORED###
>        reqMod: sambaPwdCanChange:+ ###CENSORED###
>        reqMod: sambaNTPassword:- ###CENSORED###
>        reqMod: sambaNTPassword:+ ###CENSORED###
>        reqMod: sambaPwdLastSet:- ###CENSORED###
>        reqMod: sambaPwdLastSet:+ ###CENSORED###
>        reqMod: entryCSN:= 20080110163829.095157Z#000000#000#000000
>        reqMod: modifiersName:= cn=admin,dc=suretecsystems,dc=com
>        reqMod: modifyTimestamp:= 20080110163829Z
>        
>        # search result
>        search: 2
>        result: 0 Success
>        
>        # numResponses: 3
>        # numEntries: 2

168
169
170
171

H3: Further Information

{{slapo-accesslog(5)}} and the {{SECT:delta-syncrepl replication}} section.
Gavin Henry's avatar
Gavin Henry committed
172

173
174

H2: Audit Logging
175

176
177
The Audit Logging overlay can be used to record all changes on a given backend database to a specified log file.

178
179
H3: Overview

180
181
If the need arises whereby changes need to be logged as standard LDIF, then the auditlog overlay {{B:slapo-auditlog (5)}}
can be used. Full examples are available in the man page {{B:slapo-auditlog (5)}}
182
183
184

H3: Audit Logging Configuration

185
186
187
If the directory is running vi {{F:slapd.d}}, then the following LDIF could be used to add the overlay to the overlay list 
in {{B:cn=config}} and set what file the {{TERM:LDIF}} gets logged to (adjust to suit)

188
>       dn: olcOverlay=auditlog,olcDatabase={1}mdb,cn=config
189
190
191
192
193
194
195
196
197
>       changetype: add
>       objectClass: olcOverlayConfig
>       objectClass: olcAuditLogConfig
>       olcOverlay: auditlog
>       olcAuditlogFile: /tmp/auditlog.ldif


In this example for testing, we are logging changes to {{F:/tmp/auditlog.ldif}}

198
A typical {{TERM:LDIF}} file created by {{B:slapo-auditlog(5)}} would look like:
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231

>       # add 1196797576 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com
>       dn: dc=suretecsystems,dc=com
>       changetype: add
>       objectClass: dcObject
>       objectClass: organization
>       dc: suretecsystems
>       o: Suretec Systems Ltd.
>       structuralObjectClass: organization
>       entryUUID: 1606f8f8-f06e-1029-8289-f0cc9d81e81a
>       creatorsName: cn=admin,dc=suretecsystems,dc=com
>       modifiersName: cn=admin,dc=suretecsystems,dc=com
>       createTimestamp: 20051123130912Z
>       modifyTimestamp: 20051123130912Z
>       entryCSN: 20051123130912.000000Z#000001#000#000000
>       auditContext: cn=accesslog
>       # end add 1196797576
>       
>       # add 1196797577 dc=suretecsystems,dc=com cn=admin,dc=suretecsystems,dc=com
>       dn: ou=Groups,dc=suretecsystems,dc=com
>       changetype: add
>       objectClass: top
>       objectClass: organizationalUnit
>       ou: Groups
>       structuralObjectClass: organizationalUnit
>       entryUUID: 160aaa2a-f06e-1029-828a-f0cc9d81e81a
>       creatorsName: cn=admin,dc=suretecsystems,dc=com
>       modifiersName: cn=admin,dc=suretecsystems,dc=com
>       createTimestamp: 20051123130912Z
>       modifyTimestamp: 20051123130912Z
>       entryCSN: 20051123130912.000000Z#000002#000#000000
>       # end add 1196797577

232

233
234
235
236
237
H3: Further Information

{{:slapo-auditlog(5)}}


238
239
240
H2: Chaining


Gavin Henry's avatar
Gavin Henry committed
241
H3: Overview
242
243
244
245
246
247
248
249
250
251

The chain overlay provides basic chaining capability to the underlying 
database.

What is chaining? It indicates the capability of a DSA to follow referrals on 
behalf of the client, so that distributed systems are viewed as a single 
virtual DSA by clients that are otherwise unable to "chase" (i.e. follow) 
referrals by themselves.

The chain overlay is built on top of the ldap backend; it is compiled by 
Gavin Henry's avatar
Gavin Henry committed
252
default when {{B:--enable-ldap}}.
253
254


Gavin Henry's avatar
Gavin Henry committed
255
H3: Chaining Configuration
256

Gavin Henry's avatar
Gavin Henry committed
257
258
259
In order to demonstrate how this overlay works, we shall discuss a typical 
scenario which might be one master server and three Syncrepl slaves. 

Howard Chu's avatar
Howard Chu committed
260
261
On each replica, add this near the top of the {{slapd.conf}}(5) file
(global), before any database definitions:
Gavin Henry's avatar
Gavin Henry committed
262
263
264
265
266
267
268
269

>        overlay                    chain
>        chain-uri                  "ldap://ldapmaster.example.com"
>        chain-idassert-bind        bindmethod="simple"
>                                   binddn="cn=Manager,dc=example,dc=com"
>                                   credentials="<secret>" 
>                                   mode="self"
>        chain-tls                  start
Gavin Henry's avatar
Gavin Henry committed
270
>        chain-return-error         TRUE 
Gavin Henry's avatar
Gavin Henry committed
271
272
273

Add this below your {{syncrepl}} statement:

Gavin Henry's avatar
Gavin Henry committed
274
275
276
>        updateref                  "ldap://ldapmaster.example.com/"

The {{B:chain-tls}} statement enables TLS from the slave to the ldap master. 
Gavin Henry's avatar
Gavin Henry committed
277
278
279
The DITs are exactly the same between these machines, therefore whatever user 
bound to the slave will also exist on the master. If that DN does not have 
update privileges on the master, nothing will happen.
Gavin Henry's avatar
Gavin Henry committed
280

Howard Chu's avatar
Howard Chu committed
281
282
283
284
You will need to restart the slave after these {{slapd.conf}} changes.
Then, if you are using {{loglevel stats}} (256), you can monitor an
{{ldapmodify}} on the slave and the master. (If you're using {{cn=config}}
no restart is required.)
Gavin Henry's avatar
Gavin Henry committed
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316

Now start an {{ldapmodify}} on the slave and watch the logs. You should expect 
something like:

>        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)
>        Sep  6 09:27:25 slave1 slapd[29274]: conn=11 op=0 STARTTLS
>        Sep  6 09:27:25 slave1 slapd[29274]: conn=11 op=0 RESULT oid= err=0 text=
>        Sep  6 09:27:25 slave1 slapd[29274]: conn=11 fd=31 TLS established tls_ssf=256 ssf=256
>        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=1 BIND dn="uid=user1,ou=people,dc=example,dc=com" method=128
>        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
>        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=1 RESULT tag=97 err=0 text=
>        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD dn="uid=user1,ou=People,dc=example,dc=com"
>        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=2 MOD attr=mail
>        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=2 RESULT tag=103 err=0 text=
>        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 op=3 UNBIND
>        Sep  6 09:27:28 slave1 slapd[29274]: conn=11 fd=31 closed
>        Sep  6 09:27:28 slave1 slapd[29274]: syncrepl_entry: LDAP_RES_SEARCH_ENTRY(LDAP_SYNC_MODIFY)
>        Sep  6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_search (0)
>        Sep  6 09:27:28 slave1 slapd[29274]: syncrepl_entry: uid=user1,ou=People,dc=example,dc=com
>        Sep  6 09:27:28 slave1 slapd[29274]: syncrepl_entry: be_modify (0)

And on the master you will see this:

>        Sep  6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 PROXYAUTHZ dn="uid=user1,ou=people,dc=example,dc=com"
>        Sep  6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD dn="uid=user1,ou=People,dc=example,dc=com"
>        Sep  6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 MOD attr=mail
>        Sep  6 09:23:57 ldapmaster slapd[2961]: conn=55902 op=3 RESULT tag=103 err=0 text=

Note: You can clearly see the PROXYAUTHZ line on the master, indicating the 
proper identity assertion for the update on the master. Also note the slave 
immediately receiving the Syncrepl update from the master.

Gavin Henry's avatar
Gavin Henry committed
317
318
319
320
321
322
323
324
325
326
H3: Handling Chaining Errors

By default, if chaining fails, the original referral is returned to the client
under the assumption that the client might want to try and follow the referral.

With the following directive however, if the chaining fails at the provider 
side, the actual error is returned to the client.

>        chain-return-error TRUE

327

328
329
330
331
H3: Read-Back of Chained Modifications

Occasionally, applications want to read back the data that they just wrote.
If a modification requested to a shadow server was silently chained to its 
332
provider, an immediate read could result in receiving data not yet synchronized.  
333
334
335
336
337
338
339
340
341
In those cases, clients should use the {{B:dontusecopy}} control to ensure 
they are directed to the authoritative source for that piece of data.

This control usually causes a referral to the actual source of the data
to be returned.  However, when the {{slapo-chain(5)}} overlay is used,
it intercepts the referral being returned in response to the
{{B:dontusecopy}} control, and tries to fetch the requested data.


342
343
344
345
346
H3: Further Information

{{:slapo-chain(5)}}


347
H2: Constraints
348
349


350
351
H3: Overview

352
This overlay enforces a regular expression constraint on all values
353
354
355
of specified attributes during an LDAP modify request that contains add or modify
commands. It is used to enforce a more rigorous syntax when the underlying attribute 
syntax is too general.
356

357
358

H3: Constraint Configuration
359
360
361
362

Configuration via {{slapd.conf}}(5) would look like:

>        overlay constraint
363
>        constraint_attribute mail regex ^[[:alnum:]]+@mydomain.com$
364
365
366
367
368
369
370
371
372
373
374
>        constraint_attribute title uri
>        ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)

A specification like the above would reject any {{mail}} attribute which did not
look like {{<alpha-numeric string>@mydomain.com}}.

It would also reject any title attribute whose values were not listed in the 
title attribute of any {{titleCatalog}} entries in the given scope.   

An example for use with {{cn=config}}:

375
>       dn: olcOverlay=constraint,olcDatabase={1}mdb,cn=config
376
377
378
379
>       changetype: add
>       objectClass: olcOverlayConfig
>       objectClass: olcConstraintConfig
>       olcOverlay: constraint
380
>       olcConstraintAttribute: mail regex ^[[:alnum:]]+@mydomain.com$
381
382
>       olcConstraintAttribute: title uri ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)

383
384
385
386
387

H3: Further Information

{{:slapo-constraint(5)}}

388
389
390
391
392
   
H2: Dynamic Directory Services


H3: Overview
393

Gavin Henry's avatar
Gavin Henry committed
394
The {{dds}} overlay to {{slapd}}(8) implements dynamic objects as per {{REF:RFC2589}}.
Gavin Henry's avatar
Gavin Henry committed
395
396
397
398
399
400
401
402
403
404
405
406
The name {{dds}} stands for Dynamic Directory Services. It allows to define 
dynamic objects, characterized by the {{dynamicObject}} objectClass.

Dynamic objects have a limited lifetime, determined by a time-to-live (TTL) 
that can be refreshed by means of a specific refresh extended operation. This 
operation allows to set the Client Refresh Period (CRP), namely the period 
between refreshes that is required to preserve the dynamic object from expiration. 
The expiration time is computed by adding the requested TTL to the current time.
When dynamic objects reach the end of their lifetime without being further 
refreshed, they are automatically {{deleted}}. There is no guarantee of immediate 
deletion, so clients should not count on it.

407
408
H3: Dynamic Directory Service Configuration

Gavin Henry's avatar
Gavin Henry committed
409
A usage of dynamic objects might be to implement dynamic meetings; in this case, 
410
411
412
413
414
all the participants to the meeting are allowed to refresh the meeting object, 
but only the creator can delete it (otherwise it will be deleted when the TTL expires).

If we add the overlay to an example database, specifying a Max TTL of 1 day, a 
min of 10 seconds, with a default TTL of 1 hour. We'll also specify an interval
Gavin Henry's avatar
Gavin Henry committed
415
416
of 120 (less than 60s might be too small) seconds between expiration checks and a 
tolerance of 5 second (lifetime of a dynamic object will be {{entryTtl + tolerance}}).
417
418
419
420
421

>       overlay dds
>       dds-max-ttl     1d
>       dds-min-ttl     10s
>       dds-default-ttl 1h
Gavin Henry's avatar
Gavin Henry committed
422
423
>       dds-interval    120s
>       dds-tolerance   5s
424

Gavin Henry's avatar
Gavin Henry committed
425
and add an index:
426

Gavin Henry's avatar
Gavin Henry committed
427
>       entryExpireTimestamp
428

Gavin Henry's avatar
grammar    
Gavin Henry committed
429
Creating a meeting is as simple as adding the following:
430

Gavin Henry's avatar
Gavin Henry committed
431
432
433
434
435
436
>       dn: cn=OpenLDAP Documentation Meeting,ou=Meetings,dc=example,dc=com
>       objectClass: groupOfNames
>       objectClass: dynamicObject
>       cn: OpenLDAP Documentation Meeting
>       member: uid=ghenry,ou=People,dc=example,dc=com
>       member: uid=hyc,ou=People,dc=example,dc=com
437
438
439

H4: Dynamic Directory Service ACLs

Gavin Henry's avatar
Gavin Henry committed
440
Allow users to start a meeting and to join it; restrict refresh to the {{member}}; 
441
442
443
444
445
446
restrict delete to the creator:

>       access to attrs=userPassword
>          by self write
>          by * read
>       
Gavin Henry's avatar
Gavin Henry committed
447
>       access to dn.base="ou=Meetings,dc=example,dc=com"
448
449
450
>                 attrs=children
>            by users write
>       
Gavin Henry's avatar
Gavin Henry committed
451
>       access to dn.onelevel="ou=Meetings,dc=example,dc=com"
452
453
454
455
>                 attrs=entry
>            by dnattr=creatorsName write
>            by * read
>       
Gavin Henry's avatar
Gavin Henry committed
456
>       access to dn.onelevel="ou=Meetings,dc=example,dc=com"
457
458
459
460
461
>                 attrs=participant
>            by dnattr=creatorsName write
>            by users selfwrite
>            by * read
>       
Gavin Henry's avatar
Gavin Henry committed
462
>       access to dn.onelevel="ou=Meetings,dc=example,dc=com"
463
464
465
466
>                 attrs=entryTtl
>            by dnattr=member manage
>            by * read

Gavin Henry's avatar
Gavin Henry committed
467
468
469
470
471
472
In simple terms, the user who created the {{OpenLDAP Documentation Meeting}} can add new attendees, 
refresh the meeting using (basically complete control):

>       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

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.
473

474
475
476
477
478
479

H3: Further Information

{{:slapo-dds(5)}}


480
481
482
483
484
H2: Dynamic Groups


H3: Overview

485
This overlay extends the Compare operation to detect
486
487
488
members of a dynamic group. This overlay is now deprecated
as all of its functions are available using the
{{SECT:Dynamic Lists}} overlay.
489

490
491
492
493
494
495
496
497
498

H3: Dynamic Group Configuration


H2: Dynamic Lists
   
   
H3: Overview

Gavin Henry's avatar
Gavin Henry committed
499
500
501
This overlay allows expansion of dynamic groups and lists. Instead of having the
group members or list attributes hard coded, this overlay allows us to define
an LDAP search whose results will make up the group or list.
502
503
504

H3: Dynamic List Configuration

Gavin Henry's avatar
Gavin Henry committed
505
506
507
508
509
510
511
512
513
514
515
516
517
This module can behave both as a dynamic list and dynamic group, depending on
the configuration. The syntax is as follows:

>       overlay dynlist
>       dynlist-attrset <group-oc> <URL-ad> [member-ad]

The parameters to the {{F:dynlist-attrset}} directive have the following meaning:
* {{F:<group-oc>}}: specifies which object class triggers the subsequent LDAP search.
Whenever an entry with this object class is retrieved, the search is performed.
* {{F:<URL-ad>}}: is the name of the attribute which holds the search URI. It
has to be a subtype of {{F:labeledURI}}. The attributes and values present in
the search result are added to the entry unless {{F:member-ad}} is used (see
below).
518
* {{F:member-ad}}: if present, changes the overlay behavior into a dynamic group.
Gavin Henry's avatar
Gavin Henry committed
519
520
521
522
523
524
525
Instead of inserting the results of the search in the entry, the distinguished name
of the results are added as values of this attribute.

Here is an example which will allow us to have an email alias which automatically
expands to all user's emails according to our LDAP filter:

In {{slapd.conf}}(5):
526

Gavin Henry's avatar
Gavin Henry committed
527
528
529
530
531
532
533
>       overlay dynlist
>       dynlist-attrset nisMailAlias labeledURI

This means that whenever an entry which has the {{F:nisMailAlias}} object class is
retrieved, the search specified in the {{F:labeledURI}} attribute is performed.

Let's say we have this entry in our directory:
534

Gavin Henry's avatar
Gavin Henry committed
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
>       cn=all,ou=aliases,dc=example,dc=com
>       cn: all
>       objectClass: nisMailAlias
>       labeledURI: ldap:///ou=People,dc=example,dc=com?mail?one?(objectClass=inetOrgPerson)

If this entry is retrieved, the search specified in {{F:labeledURI}} will be
performed and the results will be added to the entry just as if they have always
been there. In this case, the search filter selects all entries directly
under {{F:ou=People}} that have the {{F:inetOrgPerson}} object class and retrieves
the {{F:mail}} attribute, if it exists.

This is what gets added to the entry when we have two users under {{F:ou=People}}
that match the filter:
!import "allmail-en.png"; align="center"; title="Dynamic list for email aliases"
FT[align="Center"] Figure X.Y: Dynamic List for all emails

The configuration for a dynamic group is similar. Let's see an example which would
automatically populate an {{F:allusers}} group with all the user accounts in the
directory.

In {{F:slapd.conf}}(5):
556

557
558
>       include /path/to/dyngroup.schema
>       ...
Gavin Henry's avatar
Gavin Henry committed
559
>       overlay dynlist
560
>       dynlist-attrset groupOfURLs labeledURI member
561
562
563

Note: We must include the {{F:dyngroup.schema}} file that defines the {{F:groupOfURLs}}
objectClass used in this example.
Gavin Henry's avatar
Gavin Henry committed
564
565

Let's apply it to the following entry:
566

Gavin Henry's avatar
Gavin Henry committed
567
568
>       cn=allusers,ou=group,dc=example,dc=com
>       cn: all
569
>       objectClass: groupOfURLs
Gavin Henry's avatar
Gavin Henry committed
570
571
>       labeledURI: ldap:///ou=people,dc=example,dc=com??one?(objectClass=inetOrgPerson)

572
The behavior is similar to the dynamic list configuration we had before:
573
whenever an entry with the {{F:groupOfURLs}} object class is retrieved, the
Gavin Henry's avatar
Gavin Henry committed
574
575
576
577
578
579
580
581
search specified in the {{F:labeledURI}} attribute is performed. But this time,
only the distinguished names of the results are added, and as values of the
{{F:member}} attribute.

This is what we get:
!import "allusersgroup-en.png"; align="center"; title="Dynamic group for all users"
FT[align="Center"] Figure X.Y: Dynamic Group for all users

582
Note that a side effect of this scheme of dynamic groups is that the members
Gavin Henry's avatar
Gavin Henry committed
583
584
585
586
587
need to be specified as full DNs. So, if you are planning in using this for
{{F:posixGroup}}s, be sure to use RFC2307bis and some attribute which can hold
distinguished names. The {{F:memberUid}} attribute used in the {{F:posixGroup}}
object class can hold only names, not DNs, and is therefore not suitable for
dynamic groups.
588

589
590
591
592
593
594

H3: Further Information

{{:slapo-dynlist(5)}}


595
596
H2: Reverse Group Membership Maintenance

597
598
599
600
601
602
603
604
605
606
607
608
609
610
H3: Overview

In some scenarios, it may be desirable for a client to be able to determine
which groups an entry is a member of, without performing an additional search.
Examples of this are applications using the {{TERM:DIT}} for access control
based on group authorization.

The {{B:memberof}} overlay updates an attribute (by default {{B:memberOf}}) whenever
changes occur to the membership attribute (by default {{B:member}}) of entries of the
objectclass (by default {{B:groupOfNames}}) configured to trigger updates.

Thus, it provides maintenance of the list of groups an entry is a member of,
when usual maintenance of groups is done by modifying the members on the group
entry.
611
612
613

H3: Member Of Configuration

614
615
616
617
618
The typical use of this overlay requires just enabling the overlay for a
specific database. For example, with the following minimal slapd.conf:

>        include /usr/share/openldap/schema/core.schema
>        include /usr/share/openldap/schema/cosine.schema
619
>
620
621
>        authz-regexp "gidNumber=0\\\+uidNumber=0,cn=peercred,cn=external,cn=auth"
>                "cn=Manager,dc=example,dc=com"
622
>        database        mdb
623
624
625
>        suffix          "dc=example,dc=com"
>        rootdn          "cn=Manager,dc=example,dc=com"
>        rootpw          secret
Quanah Gibson-Mount's avatar
Quanah Gibson-Mount committed
626
>        directory       /var/lib/ldap2.5
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
>        checkpoint 256 5
>        index   objectClass   eq
>        index   uid           eq,sub
>        
>        overlay memberof

adding the following ldif:

>        cat memberof.ldif
>        dn: dc=example,dc=com
>        objectclass: domain
>        dc: example
>        
>        dn: ou=Group,dc=example,dc=com
>        objectclass: organizationalUnit
>        ou: Group
>        
>        dn: ou=People,dc=example,dc=com
>        objectclass: organizationalUnit
>        ou: People
>        
>        dn: uid=test1,ou=People,dc=example,dc=com
>        objectclass: account
>        uid: test1
>        
>        dn: cn=testgroup,ou=Group,dc=example,dc=com
>        objectclass: groupOfNames
>        cn: testgroup
>        member: uid=test1,ou=People,dc=example,dc=com

Results in the following output from a search on the test1 user:

> # ldapsearch -LL -Y EXTERNAL -H ldapi:/// "(uid=test1)" -b dc=example,dc=com memberOf
> SASL/EXTERNAL authentication started
> SASL username: gidNumber=0+uidNumber=0,cn=peercred,cn=external,cn=auth
> SASL SSF: 0
> version: 1
> 
> dn: uid=test1,ou=People,dc=example,dc=com
> memberOf: cn=testgroup,ou=Group,dc=example,dc=com

Note that the {{B:memberOf}} attribute is an operational attribute, so it must be
requested explicitly.

671

672
673
674
675
676
H3: Further Information

{{:slapo-memberof(5)}}


677
H2: The Proxy Cache Engine
678

Kurt Zeilenga's avatar
Kurt Zeilenga committed
679
680
681
682
{{TERM:LDAP}} servers typically hold one or more subtrees of a
{{TERM:DIT}}. Replica (or shadow) servers hold shadow copies of
entries held by one or more master servers.  Changes are propagated
from the master server to replica (slave) servers using LDAP Sync
683
684
replication.  An LDAP cache is a special type of replica which holds
entries corresponding to search filters instead of subtrees.
685

686
H3: Overview
687

Howard Chu's avatar
Howard Chu committed
688
The proxy cache extension of slapd is designed to improve the
Gavin Henry's avatar
Gavin Henry committed
689
responsiveness of the ldap and meta backends. It handles a search
Howard Chu's avatar
Howard Chu committed
690
request (query)
691
692
by first determining whether it is contained in any cached search
filter. Contained requests are answered from the proxy cache's local
Howard Chu's avatar
Howard Chu committed
693
694
database. Other requests are passed on to the underlying ldap or
meta backend and processed as usual.
695
696
697
698
699
700
701
702
703
704
705

E.g. {{EX:(shoesize>=9)}} is contained in {{EX:(shoesize>=8)}} and
{{EX:(sn=Richardson)}} is contained in {{EX:(sn=Richards*)}}

Correct matching rules and syntaxes are used while comparing
assertions for query containment. To simplify the query containment
problem, a list of cacheable "templates" (defined below) is specified
at configuration time. A query is cached or answered only if it
belongs to one of these templates. The entries corresponding to
cached queries are stored in the proxy cache local database while
its associated meta information (filter, scope, base, attributes)
Howard Chu's avatar
Howard Chu committed
706
is stored in main memory. 
707
708
709
710

A template is a prototype for generating LDAP search requests.
Templates are described by a prototype search filter and a list of
attributes which are required in queries generated from the template.
Kurt Zeilenga's avatar
Kurt Zeilenga committed
711
The representation for prototype filter is similar to {{REF:RFC4515}},
712
713
714
715
716
717
718
except that the assertion values are missing. Examples of prototype
filters are: (sn=),(&(sn=)(givenname=)) which are instantiated by
search filters (sn=Doe) and (&(sn=Doe)(givenname=John)) respectively.

The cache replacement policy removes the least recently used (LRU)
query and entries belonging to only that query. Queries are allowed
a maximum time to live (TTL) in the cache thus providing weak
Howard Chu's avatar
Howard Chu committed
719
consistency. A background task periodically checks the cache for
720
721
722
723
expired queries and removes them.

The Proxy Cache paper
({{URL:http://www.openldap.org/pub/kapurva/proxycaching.pdf}}) provides
724
design and implementation details.
725
726


727
H3: Proxy Cache Configuration
728
729

The cache configuration specific directives described below must
730
731
appear after a {{EX:overlay pcache}} directive within a
{{EX:"database meta"}} or {{EX:"database ldap"}} section of
732
the server's {{slapd.conf}}(5) file.
733

734
H4: Setting cache parameters
735

736
> pcache <DB> <maxentries> <nattrsets> <entrylimit> <period>
737

738
739
740
This directive enables proxy caching and sets general cache
parameters.  The <DB> parameter specifies which underlying database
is to be used to hold cached entries.  It should be set to
741
{{EX:mdb}}.  The <maxentries> parameter specifies the
742
total number of entries which may be held in the cache.  The
743
<nattrsets> parameter specifies the total number of attribute sets
744
(as specified by the {{EX:pcacheAttrset}} directive) that may be
745
defined.  The <entrylimit> parameter specifies the maximum number of
Gavin Henry's avatar
Gavin Henry committed
746
entries in a cacheable query.  The <period> specifies the consistency
747
748
check period (in seconds).  In each period, queries with expired
TTLs are removed.
749

750
H4: Defining attribute sets
751

752
> pcacheAttrset <index> <attrs...>
753
754
755

Used to associate a set of attributes to an index. Each attribute
set is associated with an index number from 0 to <numattrsets>-1.
756
These indices are used by the pcacheTemplate directive to define
757
758
cacheable templates.

759
H4: Specifying cacheable templates 
760

761
> pcacheTemplate <prototype_string> <attrset_index> <TTL>
762
763
764
765
766
767

Specifies a cacheable template and the "time to live" (in sec) <TTL>
for queries belonging to the template. A template is described by
its prototype filter string and set of required attributes identified
by <attrset_index>.

768

769
H4: Example for slapd.conf
770

771
772
773
An example {{slapd.conf}}(5) database section for a caching server
which proxies for the {{EX:"dc=example,dc=com"}} subtree held
at server {{EX:ldap.example.com}}.
774
 
775
>	database 	ldap
776
>	suffix 		"dc=example,dc=com" 
Howard Chu's avatar
Howard Chu committed
777
>	rootdn 		"dc=example,dc=com" 
Gavin Henry's avatar
Gavin Henry committed
778
>	uri    		ldap://ldap.example.com/
779
>	overlay pcache
780
>	pcache         mdb 100000 1 1000 100
781
782
783
784
>	pcacheAttrset  0 mail postaladdress telephonenumber 
>	pcacheTemplate (sn=) 0 3600
>	pcacheTemplate (&(sn=)(givenName=)) 0 3600
>	pcacheTemplate (&(departmentNumber=)(secretary=*)) 0 3600
785
786
787
788
789
>
>	cachesize 20
>	directory ./testrun/db.2.a
>	index       objectClass eq
>	index       cn,sn,uid,mail  pres,eq,sub
790

791
792
793
794
795
796
H4: Example for slapd-config

The same example as a LDIF file for back-config for a caching server
which proxies for the {{EX:"dc=example,dc=com"}} subtree held
at server {{EX:ldap.example.com}}.

Howard Chu's avatar
Howard Chu committed
797
>   dn: olcDatabase={2}ldap,cn=config
798
799
800
801
802
803
804
>   objectClass: olcDatabaseConfig
>   objectClass: olcLDAPConfig
>   olcDatabase: {2}ldap
>   olcSuffix: dc=example,dc=com
>   olcRootDN: dc=example,dc=com
>   olcDbURI: "ldap://ldap.example.com"
>   
Howard Chu's avatar
Howard Chu committed
805
>   dn: olcOverlay={0}pcache,olcDatabase={2}ldap,cn=config
806
807
808
>   objectClass: olcOverlayConfig
>   objectClass: olcPcacheConfig
>   olcOverlay: {0}pcache
809
>   olcPcache: mdb 100000 1 1000 100
810
811
812
813
814
>   olcPcacheAttrset: 0 mail postalAddress telephoneNumber
>   olcPcacheTemplate: "(sn=)" 0 3600 0 0 0
>   olcPcacheTemplate: "(&(sn=)(givenName=))" 0 3600 0 0 0
>   olcPcacheTemplate: "(&(departmentNumber=)(secretary=))" 0 3600
>   
815
816
>   dn: olcDatabase={0}mdb,olcOverlay={0}pcache,olcDatabase={2}ldap,cn=config
>   objectClass: olcMdbConfig
817
>   objectClass: olcPcacheDatabase
818
>   olcDatabase: {0}mdb
819
820
821
822
823
>   olcDbDirectory: ./testrun/db.2.a
>   olcDbCacheSize: 20
>   olcDbIndex: objectClass eq
>   olcDbIndex: cn,sn,uid,mail  pres,eq,sub

824

825
H5: Cacheable Queries
826
827

A LDAP search query is cacheable when its filter matches one of the
828
templates as defined in the "pcacheTemplate" statements and when it references
829
830
831
only the attributes specified in the corresponding attribute set. 
In the example above the attribute set number 0 defines that only the
attributes: {{EX:mail postaladdress telephonenumber}} are cached for the following
832
pcacheTemplates.
833

834
H5: Examples:
835
836
837
838
839

>	Filter: (&(sn=Richard*)(givenName=jack)) 
>	Attrs: mail telephoneNumber

    is cacheable, because it matches the template {{EX:(&(sn=)(givenName=))}} and its
840
    attributes are contained in pcacheAttrset 0.
841
842
843
844
845
846
847
848
849
850
851
852

>	Filter: (&(sn=Richard*)(telephoneNumber))
>	Attrs: givenName 

    is not cacheable, because the filter does not match the template,
    nor is the attribute givenName stored in the cache

>	Filter: (|(sn=Richard*)(givenName=jack))
>	Attrs: mail telephoneNumber

    is not cacheable, because the filter does not match the template ( logical
    OR "|" condition instead of logical AND "&" )
853
854
855
856
857


H3: Further Information

{{:slapo-pcache(5)}}
858
859
860
861
862
863
864
                           
                           
H2: Password Policies


H3: Overview

865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
This overlay follows the specifications contained in the draft RFC titled 
draft-behera-ldap-password-policy-09. While the draft itself is expired, it has 
been implemented in several directory servers, including slapd. Nonetheless, 
it is important to note that it is a draft, meaning that it is subject to change 
and is a work-in-progress.

The key abilities of the password policy overlay are as follows:

* Enforce a minimum length for new passwords
* Make sure passwords are not changed too frequently
* 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
* Maintain a history of passwords to prevent password re-use
* Prevent password guessing by locking a password for a specified period of time after repeated authentication failures
* Force a password to be changed at the next authentication
* Set an administrative lock on an account
* Support multiple password policies on a default or a per-object basis.
* Perform arbitrary quality checks using an external loadable module. This is a non-standard extension of the draft RFC.
882

883
884
885

H3: Password Policy Configuration

886
887
888
889
890
891
Instantiate the module in the database where it will be used, after adding the 
new ppolicy schema and loading the ppolicy module. The following example shows 
the ppolicy module being added to the database that handles the naming 
context "dc=example,dc=com". In this example we are also specifying the DN of 
a policy object to use if none other is specified in a user's object.

892
>       database mdb
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
>       suffix "dc=example,dc=com"
>       [...additional database configuration directives go here...]
>       
>       overlay ppolicy
>       ppolicy_default "cn=default,ou=policies,dc=example,dc=com"


Now we need a container for the policy objects. In our example the password 
policy objects are going to be placed in a section of the tree called 
"ou=policies,dc=example,dc=com":

>       dn: ou=policies,dc=example,dc=com
>       objectClass: organizationalUnit
>       objectClass: top
>       ou: policies


The default policy object that we are creating defines the following policies:

* The user is allowed to change his own password. Note that the directory ACLs for this attribute can also affect this ability (pwdAllowUserChange: TRUE).
* 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.
* 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).
* 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.
* When the password for a DN has expired, the server will allow five additional "grace" logins (pwdGraceAuthNLimit: 5).
* The server will maintain a history of the last five passwords that were used for a DN (pwdInHistory: 5).
* The server will lock the account after the maximum number of failed bind attempts has been exceeded (pwdLockout: TRUE).
* When the server has locked an account, the server will keep it locked until an administrator unlocks it (pwdLockoutDuration: 0)
* The server will reset its failed bind count after a period of 30 seconds.
* Passwords will not expire (pwdMaxAge: 0).
* Passwords can be changed as often as desired (pwdMinAge: 0).
* Passwords must be at least 5 characters in length (pwdMinLength: 5).
* The password does not need to be changed at the first bind or when the administrator has reset the password (pwdMustChange: FALSE)
* The current password does not need to be included with password change requests (pwdSafeModify: FALSE)
* The server will only allow five failed binds in a row for a particular DN (pwdMaxFailure: 5).


The actual policy would be:

>       dn: cn=default,ou=policies,dc=example,dc=com
>       cn: default
>       objectClass: pwdPolicy
>       objectClass: person
>       objectClass: top
>       pwdAllowUserChange: TRUE
>       pwdAttribute: userPassword
>       pwdCheckQuality: 2
>       pwdExpireWarning: 600
>       pwdFailureCountInterval: 30
>       pwdGraceAuthNLimit: 5
>       pwdInHistory: 5
>       pwdLockout: TRUE
>       pwdLockoutDuration: 0
>       pwdMaxAge: 0
>       pwdMaxFailure: 5
>       pwdMinAge: 0
>       pwdMinLength: 5
>       pwdMustChange: FALSE
>       pwdSafeModify: FALSE
>       sn: dummy value

You can create additional policy objects as needed. 


There are two ways password policy can be applied to individual objects:

Howard Chu's avatar
Howard Chu committed
958
959
960
961
962
963
964
965
1. The pwdPolicySubentry in a user's object - If a user's object has a
pwdPolicySubEntry attribute specifying the DN of a policy object, then 
the policy defined by that object is applied.

2. Default password policy - If there is no specific pwdPolicySubentry set
for an object, and the password policy module was configured with the DN of a
default policy object and if that object exists, then the policy defined in
that object is applied.
966
967

Please see {{slapo-ppolicy(5)}} for complete explanations of features and discussion of
Howard Chu's avatar
Howard Chu committed
968
 "Password Management Issues" at {{URL:http://www.symas.com/blog/?page_id=66}}
969
970


971
972
973
974
H3: Further Information

{{:slapo-ppolicy(5)}}

975
976
977
978
979
980

H2: Referential Integrity


H3: Overview

981
This overlay can be used with a backend database such as slapd-mdb(5)
Gavin Henry's avatar
Gavin Henry committed
982
to maintain the cohesiveness of a schema which utilizes reference
983
984
attributes.

Gavin Henry's avatar
Gavin Henry committed
985
986
987
988
989
990
991
992
993
994
995
996
997
Whenever a {{modrdn}} or {{delete}} is performed, that is, when an entry's DN
is renamed or an entry is removed, the server will search the directory for
references to this DN (in selected attributes: see below) and update them
accordingly. If it was a {{delete}} operation, the reference is deleted. If it
was a {{modrdn}} operation, then the reference is updated with the new DN.

For example, a very common administration task is to maintain group membership
lists, specially when users are removed from the directory. When an
user account is deleted or renamed, all groups this user is a member of have to be
updated. LDAP administrators usually have scripts for that. But we can use the
{{F:refint}} overlay to automate this task. In this example, if the user is
removed from the directory, the overlay will take care to remove the user from
all the groups he/she was a member of. No more scripting for this.
998
999
1000

H3: Referential Integrity Configuration

Gavin Henry's avatar
Gavin Henry committed
1001
The configuration for this overlay is as follows:
1002

Gavin Henry's avatar
Gavin Henry committed
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
>       overlay refint
>       refint_attributes <attribute [attribute ...]>
>       refint_nothing <string>

* {{F:refint_attributes}}: this parameter specifies a space separated list of
attributes which will have the referential integrity maintained. When an entry is
removed or has its DN renamed, the server will do an internal search for any of the
{{F:refint_attributes}} that point to the affected DN and update them accordingly. IMPORTANT:
the attributes listed here must have the {{F:distinguishedName}} syntax, that is,
hold DNs as values.
* {{F:refint_nothing}}: some times, while trying to maintain the referential
integrity, the server has to remove the last attribute of its kind from an
entry. This may be prohibited by the schema: for example, the
{{F:groupOfNames}} object class requires at least one member. In these cases,
the server will add the attribute value specified in {{F:refint_nothing}}
to the entry.

To illustrate this overlay, we will use the group membership scenario.

In {{F:slapd.conf}}:
1023

Gavin Henry's avatar
Gavin Henry committed
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
>       overlay refint
>       refint_attributes member
>       refint_nothing "cn=admin,dc=example,dc=com"

This configuration tells the overlay to maintain the referential integrity of the {{F:member}}
attribute. This attribute is used in the {{F:groupOfNames}} object class which always needs
a member, so we add the {{F:refint_nothing}} directive to fill in the group with a standard
member should all the members vanish.

If we have the following group membership, the refint overlay will
automatically remove {{F:john}} from the group if his entry is removed from the
directory:

!import "refint.png"; align="center"; title="Group membership"
FT[align="Center"] Figure X.Y: Maintaining referential integrity in groups

Notice that if we rename ({{F:modrdn}}) the {{F:john}} entry to, say, {{F:jsmith}}, the refint
overlay will also rename the reference in the {{F:member}} attribute, so the group membership
stays correct.

If we removed all users from the directory who are a member of this group, then the end result
would be a single member in the group: {{F:cn=admin,dc=example,dc=com}}. This is the
{{F:refint_nothing}} parameter kicking into action so that the schema is not violated.
1047

1048
1049
The {{rootdn}} must be set for the database as refint runs as the {{rootdn}} to gain access to
make its updates.  The {{rootpw}} does not need to be set.
1050
1051
1052
1053
1054
1055

H3: Further Information

{{:slapo-refint(5)}}


1056
1057
1058
1059
1060
H2: Return Code


H3: Overview

1061
This overlay is useful to test the behavior of clients when
1062
1063
1064
1065
1066
1067
1068
server-generated erroneous and/or unusual responses occur,
for example; error codes, referrals, excessive response times and so on.

This would be classed as a debugging tool whilst developing client software
or additional Overlays.

For detailed information, please see the {{slapo-retcode(5)}} man page.
1069

1070
1071
1072

H3: Return Code Configuration

1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
The retcode overlay utilizes the "return code" schema described in the man page.  
This schema is specifically designed for use with this overlay and is not intended 
to be used otherwise. 

Note: The necessary schema is loaded automatically by the overlay.

An example configuration might be:

>       overlay         retcode
>       retcode-parent  "ou=RetCodes,dc=example,dc=com"
>       include         ./retcode.conf
>       
>       retcode-item    "cn=Unsolicited"                0x00 unsolicited="0"
>       retcode-item    "cn=Notice of Disconnect"       0x00 unsolicited="1.3.6.1.4.1.1466.20036"
>       retcode-item    "cn=Pre-disconnect"             0x34 flags="pre-disconnect"
>       retcode-item    "cn=Post-disconnect"            0x34 flags="post-disconnect"

Note: {{retcode.conf}} can be found in the openldap source at: {{F:tests/data/retcode.conf}}

An excerpt of a {{F:retcode.conf}} would be something like:

>       retcode-item    "cn=success"                            0x00
>       
>       retcode-item    "cn=success w/ delay"                   0x00    sleeptime=2
>       
>       retcode-item    "cn=operationsError"                    0x01
>       retcode-item    "cn=protocolError"                      0x02
>       retcode-item    "cn=timeLimitExceeded"                  0x03    op=search
>       retcode-item    "cn=sizeLimitExceeded"                  0x04    op=search
>       retcode-item    "cn=compareFalse"                       0x05    op=compare
>       retcode-item    "cn=compareTrue"                        0x06    op=compare
>       retcode-item    "cn=authMethodNotSupported"             0x07
>       retcode-item    "cn=strongAuthNotSupported"             0x07    text="same as authMethodNotSupported"
>       retcode-item    "cn=strongAuthRequired"                 0x08
>       retcode-item    "cn=strongerAuthRequired"               0x08    text="same as strongAuthRequired"

Please see {{F:tests/data/retcode.conf}} for a complete {{F:retcode.conf}}

1111

1112
1113
1114
1115
1116
H3: Further Information

{{:slapo-retcode(5)}}


1117
1118
1119
1120
1121
H2: Rewrite/Remap
            
            
H3: Overview

1122
1123
1124
1125
1126
1127
1128
It performs basic DN/data rewrite and objectClass/attributeType mapping. Its 
usage is mostly intended to provide virtual views of existing data either 
remotely, in conjunction with the proxy backend described in {{slapd-ldap(5)}}, 
or locally, in conjunction with the relay backend described in {{slapd-relay(5)}}.

This overlay is extremely configurable and advanced, therefore recommended 
reading is the {{slapo-rwm(5)}} man page.
1129

1130
1131
1132
1133

H3: Rewrite/Remap Configuration


1134
1135
1136
1137
1138
H3: Further Information

{{:slapo-rwm(5)}}


1139
1140
1141
1142
1143
H2: Sync Provider


H3: Overview

Gavin Henry's avatar
Gavin Henry committed
1144
1145
This overlay implements the provider-side support for the LDAP Content Synchronization 
({{REF:RFC4533}}) as well as syncrepl replication support, including persistent search functionality.
1146
1147
1148

H3: Sync Provider Configuration

Gavin Henry's avatar
Gavin Henry committed
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
There is very little configuration needed for this overlay, in fact for many situations merely loading 
the overlay will suffice.

However, because the overlay creates a contextCSN attribute in the root entry of the database which is
updated for every write operation performed against the database and only updated in memory, it is 
recommended to configure a checkpoint so that the contextCSN is written into the underlying database to 
minimize recovery time after an unclean shutdown:

>       overlay syncprov
>       syncprov-checkpoint 100 10

For every 100 operations or 10 minutes, which ever is sooner, the contextCSN will be checkpointed.

The four configuration directives available are {{B:syncprov-checkpoint}}, {{B:syncprov-sessionlog}},
{{B:syncprov-nopresent}} and {{B:syncprov-reloadhint}} which are covered in the man page discussing
various other scenarios where this overlay can be used. 
1165

1166
1167
H3: Further Information

Gavin Henry's avatar
Gavin Henry committed
1168
The {{:slapo-syncprov(5)}} man page and the {{SECT:Configuring the different replication types}} section
1169
1170


1171
1172
1173
1174
1175
H2: Translucent Proxy


H3: Overview

1176
This overlay can be used with a backend database such as {{:slapd-mdb}}(5)
1177
1178
to create a "translucent proxy".

Gavin Henry's avatar
Gavin Henry committed
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
Entries retrieved from a remote LDAP server may have some or all attributes 
overridden, or new attributes added, by entries in the local database before 
being presented to the client.

A search operation is first populated with entries from the remote LDAP server, 
the attributes of which are then overridden with any attributes defined in the
local database. Local overrides may be populated with the add, modify, and 
modrdn operations, the use of which is restricted to the root user of the 
translucent local database.

A compare operation will perform a comparison with attributes defined in the
local database record (if any) before any comparison is made with data in the 
remote database.
1192

1193
1194
1195

H3: Translucent Proxy Configuration

Gavin Henry's avatar
Gavin Henry committed
1196
1197
1198
1199
There are various options available with this overlay, but for this example we
will demonstrate adding new attributes to a remote entry and also searching 
against these newly added local attributes. For more information about overriding remote
entries and search configuration, please see {{:slapo-translucent(5)}}
1200

Gavin Henry's avatar
Gavin Henry committed
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
Note: The Translucent Proxy overlay will disable schema checking in the local
database, so that an entry consisting of overlay attributes need not adhere
 to the complete schema.

First we configure the overlay in the normal manner:

>       include     /usr/local/etc/openldap/schema/core.schema
>       include     /usr/local/etc/openldap/schema/cosine.schema
>       include     /usr/local/etc/openldap/schema/nis.schema
>       include     /usr/local/etc/openldap/schema/inetorgperson.schema
>       
>       pidfile     ./slapd.pid
>       argsfile    ./slapd.args
>       
1215
>       database    mdb
Gavin Henry's avatar
Gavin Henry committed
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
>       suffix      "dc=suretecsystems,dc=com"
>       rootdn      "cn=trans,dc=suretecsystems,dc=com"
>       rootpw      secret
>       directory   ./openldap-data
>       
>       index       objectClass eq
>       
>       overlay     translucent
>       translucent_local carLicense
>       
>       uri         ldap://192.168.X.X:389
>       lastmod     off
>       acl-bind    binddn="cn=admin,dc=suretecsystems,dc=com" credentials="blahblah"

You will notice the overlay directive and a directive to say what attribute we 
want to be able to search against in the local database. We must also load the 
ldap backend which will connect to the remote directory server.

Now we take an example LDAP group:

>       # itsupport, Groups, suretecsystems.com
>       dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com
>       objectClass: posixGroup
>       objectClass: sambaGroupMapping
>       cn: itsupport
>       gidNumber: 1000
>       sambaSID: S-1-5-21-XXX
>       sambaGroupType: 2
>       displayName: itsupport
>       memberUid: ghenry
>       memberUid: joebloggs

and create an LDIF file we can use to add our data to the local database, using
 some pretty strange choices of new attributes for demonstration purposes:

>       [ghenry@suretec test_configs]$ cat test-translucent-add.ldif 
>       dn: cn=itsupport,ou=Groups,dc=suretecsystems,dc=com
>       businessCategory: frontend-override
>       carLicense: LIVID
>       employeeType: special
>       departmentNumber: 9999999
>       roomNumber: 41L-535

Searching against the proxy gives:

>       [ghenry@suretec test_configs]$ ldapsearch -x -H ldap://127.0.0.1:9001 "(cn=itsupport)"
>       # itsupport, Groups, OxObjects, suretecsystems.com
>       dn: cn=itsupport,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com
>       objectClass: posixGroup
>       objectClass: sambaGroupMapping
>       cn: itsupport
>       gidNumber: 1003
>       SAMBASID: S-1-5-21-XXX
>       SAMBAGROUPTYPE: 2
>       displayName: itsupport
>       memberUid: ghenry
>       memberUid: joebloggs
>       roomNumber: 41L-535
>       departmentNumber: 9999999
>       employeeType: special
>       carLicense: LIVID
>       businessCategory: frontend-override

Here we can see that the 5 new attributes are added to the remote entry before 
being returned to the our client.

Because we have configured a local attribute to search against:

>       overlay     translucent
>       translucent_local carLicense

we can also search for that to return the completely fabricated entry:

>       ldapsearch -x -H ldap://127.0.0.1:9001 (carLicense=LIVID)

This is an extremely feature because you can then extend a remote directory server
locally and also search against the local entries.

Note: Because the translucent overlay does not perform any DN rewrites, the local
 and remote database instances must have the same suffix. Other configurations 
will probably fail with No Such Object and other errors
1297
1298
1299
1300
1301
1302

H3: Further Information

{{:slapo-translucent(5)}}


1303
1304
1305
1306
1307
H2: Attribute Uniqueness


H3: Overview

1308
This overlay can be used with a backend database such as {{slapd-mdb(5)}}
1309
1310
to enforce the uniqueness of some or all attributes within a subtree.

1311
1312
1313

H3: Attribute Uniqueness Configuration

1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
This overlay is only effective on new data from the point the overlay is enabled. To
check uniqueness for existing data, you can export and import your data again via the
LDAP Add operation, which will not be suitable for large amounts of data, unlike {{B:slapcat}}.

For the following example, if uniqueness were enforced for the {{B:mail}} attribute, 
the subtree would be searched for any other records which also have a {{B:mail}} attribute 
containing the same value presented with an {{B:add}}, {{B:modify}} or {{B:modrdn}} operation 
which are unique within the configured scope. If any are found, the request is rejected.

Note:  If no attributes are specified, for example {{B:ldap:///??sub?}}, then the URI applies to all non-operational attributes. However,
the keyword {{B:ignore}} can be specified to exclude certain non-operational attributes. 

To search at the base dn of the current backend database ensuring uniqueness of the {{B:mail}}
Gavin Henry's avatar
Gavin Henry committed
1327
attribute, we simply add the following configuration:
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361

>       overlay unique
>       unique_uri ldap:///?mail?sub?

For an existing entry of:

>       dn: cn=gavin,dc=suretecsystems,dc=com
>       objectClass: top
>       objectClass: inetorgperson
>       cn: gavin
>       sn: henry
>       mail: ghenry@suretecsystems.com

and we then try to add a new entry of:

>       dn: cn=robert,dc=suretecsystems,dc=com
>       objectClass: top
>       objectClass: inetorgperson
>       cn: robert
>       sn: jones
>       mail: ghenry@suretecsystems.com

would result in an error like so:

>       adding new entry "cn=robert,dc=example,dc=com"
>       ldap_add: Constraint violation (19)
>               additional info: some attributes not unique

The overlay can have multiple URIs specified within a domain, allowing complex
selections of objects and also have multiple {{B:unique_uri}} statements or 
{{B:olcUniqueURI}} attributes which will create independent domains.

For more information and details about the {{B:strict}} and {{B:ignore}} keywords,
please see the {{:slapo-unique(5)}} man page.
1362

1363
1364
1365
1366
1367
H3: Further Information

{{:slapo-unique(5)}}


1368
1369
1370
1371
1372
H2: Value Sorting


H3: Overview

Gavin Henry's avatar
Gavin Henry committed
1373
1374
1375
The Value Sorting overlay can be used with a backend database to sort the 
values of specific multi-valued attributes within a subtree. The sorting occurs 
whenever the attributes are returned in a search response.
1376
1377
1378

H3: Value Sorting Configuration

Gavin Henry's avatar
Gavin Henry committed
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
Sorting can be specified in ascending or descending order, using either numeric 
or alphanumeric sort methods. Additionally, a "weighted" sort can be specified,
 which uses a numeric weight prepended to the attribute values. 

The weighted sort is always performed in ascending order, but may be combined 
with the other methods for values that all have equal weights. The weight is 
specified by prepending an integer weight {<weight>} in front of each value 
of the attribute for which weighted sorting is desired. This weighting factor 
is stripped off and never returned in search results.

Here are a few examples:

>       loglevel    sync stats
>       
1393
>       database    mdb
Gavin Henry's avatar
Gavin Henry committed
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
>       suffix      "dc=suretecsystems,dc=com"
>       directory   /usr/local/var/openldap-data
>       
>       ......
>       
>       overlay valsort
>       valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com alpha-ascend

For example, ascend:

>       # sharedemail, Groups, suretecsystems.com
>       dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com
>       objectClass: posixGroup
>       objectClass: top
>       cn: sharedemail
>       gidNumber: 517
>       memberUid: admin
>       memberUid: dovecot
>       memberUid: laura
>       memberUid: suretec

For weighted, we change our data to:

>       # sharedemail, Groups, suretecsystems.com
>       dn: cn=sharedemail,ou=Groups,dc=suretecsystems,dc=com
>       objectClass: posixGroup
>       objectClass: top
>       cn: sharedemail
>       gidNumber: 517
>       memberUid: {4}admin
>       memberUid: {2}dovecot
>       memberUid: {1}laura
>       memberUid: {3}suretec

and change the config to:

>       overlay valsort
>       valsort-attr memberUid ou=Groups,dc=suretecsystems,dc=com weighted

Searching now results in:

>       # sharedemail, Groups, OxObjects, suretecsystems.com
>       dn: cn=sharedemail,ou=Groups,ou=OxObjects,dc=suretecsystems,dc=com
>       objectClass: posixGroup
>       objectClass: top
>       cn: sharedemail
>       gidNumber: 517
>       memberUid: laura
>       memberUid: dovecot
>       memberUid: suretec
>       memberUid: admin

1446

1447
1448
1449
1450
1451
H3: Further Information

{{:slapo-valsort(5)}}


1452
1453
1454
1455
1456
H2: Overlay Stacking


H3: Overview

1457
Overlays can be stacked, which means that more than one overlay
Howard Chu's avatar
Howard Chu committed
1458
can be instantiated for each database, or for the {{EX:frontend}}.
1459
As a consequence, each overlays function is called, if defined,
1460
when overlay execution is invoked.
Howard Chu's avatar
Howard Chu committed
1461
Multiple overlays are executed in reverse order (as a stack)
1462
1463
1464
with respect to their definition in slapd.conf (5), or with respect
to their ordering in the config database, as documented in slapd-config (5).

1465

Gavin Henry's avatar
Gavin Henry committed
1466
H3: Example Scenarios
1467

1468

1469
H4: Samba