# $OpenLDAP$
-# Copyright 2007 The OpenLDAP Foundation, All Rights Reserved.
+# Copyright 2007-2008 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Overlays
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.
-Overlays may be compiled statically into slapd, or when module support
+Overlays may be compiled statically into {{slapd}}, or when module support
is enabled, they may be dynamically loaded. Most of the overlays
are only allowed to be configured on individual databases, but some
may also be configured globally.
-Essentially they represent a means to:
+Essentially, they represent a means to:
* customize the behavior of existing backends without changing the backend
code and without requiring one to write a new custom backend with
Overlays are usually documented by separate specific man pages in section 5;
the naming convention is
- slapo-<overlay name>
+> slapo-<overlay name>
-Not all distributed overlays have a man page yet. Feel free to contribute one,
-if you think you well understood the behavior of the component and the
-implications of all the related configuration directives.
+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.
Official overlays are located in
- servers/slapd/overlays/
+> servers/slapd/overlays/
That directory also contains the file slapover.txt, which describes the
rationale of the overlay implementation, and may serve as guideline for the
Contribware overlays are located in
- contrib/slapd-modules/<overlay name>/
+> contrib/slapd-modules/<overlay name>/
along with other types of run-time loadable components; they are officially
distributed, but not maintained by the project.
This overlay can record accesses to a given backend database on another
database.
+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}}
H3: Access Logging Configuration
+The following is a basic example that implements Access Logging:
+
+> database bdb
+> suffix dc=example,dc=com
+> ...
+> overlay accesslog
+> logdb cn=log
+> logops writes reads
+> logold (objectclass=person)
+>
+> database bdb
+> 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}}:
+
+> database hdb
+> suffix cn=accesslog
+> directory /usr/local/var/openldap-accesslog
+> rootdn cn=accesslog
+> index default eq
+> index entryCSN,objectClass,reqEnd,reqResult,reqStart
+
+Accesslog overlay definitions for the primary db
+
+> database bdb
+> 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
+
+For more information, please see {{slapo-accesslog(5)}} and the {{SECT:delta-syncrepl replication}} section.
+
H2: Audit Logging
-This overlay records changes on a given backend database to an LDIF log
-file.
-
-
+The Audit Logging overlay can be used to record all changes on a given backend database to a specified log file.
+
H3: Overview
+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)}}
H3: Audit Logging Configuration
+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)
+
+> dn: olcOverlay=auditlog,olcDatabase={1}hdb,cn=config
+> 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}}
+
+A typical {{TERM:LDIF}} file created by {{B:slapo-auditlog (5)}} would look like:
+
+> # 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
+
H2: Chaining
referrals by themselves.
The chain overlay is built on top of the ldap backend; it is compiled by
-default when --enable-ldap.
+default when {{B:--enable-ldap}}.
H3: Chaining Configuration
+In order to demonstrate how this overlay works, we shall discuss a typical
+scenario which might be one master server and three Syncrepl slaves.
+
+On each replica, add this near the top of the file (global), before any database
+definitions:
+
+> 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
+> chain-return-error TRUE
+
+Add this below your {{syncrepl}} statement:
+
+> updateref "ldap://ldapmaster.example.com/"
+
+The {{B:chain-tls}} statement enables TLS from the slave to the ldap master.
+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.
+
+You will need to restart the slave after these changes. Then, if you are using
+{{loglevel stats}} (256), you can monitor an {{ldapmodify}} on the slave and the master.
+
+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.
+
+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
+
H2: Constraints
H3: Overview
This overlay enforces a regular expression constraint on all values
-of specified attributes. It is used to enforce a more rigorous
-syntax when the underlying attribute syntax is too general.
+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.
H3: Constraint Configuration
-
+
+Configuration via {{slapd.conf}}(5) would look like:
+
+> overlay constraint
+> constraint_attribute mail regex ^[:alnum:]+@mydomain.com$
+> 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}}:
+
+> dn: olcOverlay=constraint,olcDatabase={1}hdb,cn=config
+> changetype: add
+> objectClass: olcOverlayConfig
+> objectClass: olcConstraintConfig
+> olcOverlay: constraint
+> olcConstraintAttribute: mail regex ^[:alnum:]+@mydomain.com$
+> olcConstraintAttribute: title uri ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
+
H2: Dynamic Directory Services
H3: Overview
-This overlay supports dynamic objects, which have a limited life after
-which they expire and are automatically deleted.
-
-
+The {{dds}} overlay to {{slapd}}(8) implements dynamic objects as per {{REF:RFC2589}}.
+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.
+
H3: Dynamic Directory Service Configuration
+A usage of dynamic objects might be to implement dynamic meetings; in this case,
+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
+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}}).
+
+> overlay dds
+> dds-max-ttl 1d
+> dds-min-ttl 10s
+> dds-default-ttl 1h
+> dds-interval 120s
+> dds-tolerance 5s
+
+and add an index:
+
+> entryExpireTimestamp
+
+Creating a meeting is as simple as adding the following:
+
+> 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
+
+H4: Dynamic Directory Service ACLs
+
+Allow users to start a meeting and to join it; restrict refresh to the {{member}};
+restrict delete to the creator:
+
+> access to attrs=userPassword
+> by self write
+> by * read
+>
+> access to dn.base="ou=Meetings,dc=example,dc=com"
+> attrs=children
+> by users write
+>
+> access to dn.onelevel="ou=Meetings,dc=example,dc=com"
+> attrs=entry
+> by dnattr=creatorsName write
+> by * read
+>
+> access to dn.onelevel="ou=Meetings,dc=example,dc=com"
+> attrs=participant
+> by dnattr=creatorsName write
+> by users selfwrite
+> by * read
+>
+> access to dn.onelevel="ou=Meetings,dc=example,dc=com"
+> attrs=entryTtl
+> by dnattr=member manage
+> by * read
+
+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.
H2: Dynamic Groups
H3: Overview
This overlay extends the Compare operation to detect
-members of a dynamic group.
+members of a dynamic group. This overlay is now deprecated
+as all of its functions are available using the
+{{SECT:Dynamic Lists}} overlay.
H3: Dynamic Group Configuration
H3: Overview
-This overlay allows expansion of dynamic groups and more.
-
+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.
H3: Dynamic List Configuration
+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).
+* {{F:member-ad}}: if present, changes the overlay behavior into a dynamic group.
+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):
+> 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:
+> 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):
+> overlay dynlist
+> dynlist-attrset groupOfNames labeledURI member
+
+Let's apply it to the following entry:
+> cn=allusers,ou=group,dc=example,dc=com
+> cn: all
+> objectClass: groupOfNames
+> labeledURI: ldap:///ou=people,dc=example,dc=com??one?(objectClass=inetOrgPerson)
+
+The behavior is similar to the dynamic list configuration we had before:
+whenever an entry with the {{F:groupOfNames}} object class is retrieved, the
+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
+
+Note that a side effect of this scheme of dynamic groups is that the members
+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.
+
+H2: Reverse Group Membership Maintenance
+
+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.
+
+H3: Member Of Configuration
+
+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
+> modulepath /usr/lib/openldap
+> moduleload memberof.la
+> authz-regexp "gidNumber=0\\\+uidNumber=0,cn=peercred,cn=external,cn=auth"
+> "cn=Manager,dc=example,dc=com"
+> database bdb
+> suffix "dc=example,dc=com"
+> rootdn "cn=Manager,dc=example,dc=com"
+> rootpw secret
+> directory /var/lib/ldap2.4
+> 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.
+
H2: The Proxy Cache Engine
> database ldap
> suffix "dc=example,dc=com"
> rootdn "dc=example,dc=com"
-> uri ldap://ldap.example.com/dc=example%2cdc=com
+> uri ldap://ldap.example.com/
> overlay proxycache
> proxycache bdb 100000 1 1000 100
> proxyAttrset 0 mail postaladdress telephonenumber
H3: Overview
-This overlay can be used with a backend database such as slapd-bdb (5)
+This overlay can be used with a backend database such as slapd-bdb(5)
to maintain the cohesiveness of a schema which utilizes reference
attributes.
+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.
H3: Referential Integrity Configuration
+The configuration for this overlay is as follows:
+> 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}}:
+> 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.
H2: Return Code
H3: Overview
+Overlays can be stacked, which means that more than one overlay
+can be instantiated for each database, or for the frontend.
+As a consequence, each overlays function is called, if defined,
+when overlay execution is invoked.
+Multiple overlays are executed in reverse order (it's a stack, all in all)
+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).
+
H3: Example Scenarios
projects / openldap / blobdiff