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
> 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
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: cn=module{0},cn=config
+> changetype: modify
+> add: olcModuleLoad
+> olcModuleLoad: {2}auditlog.la
+>
+> 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
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: cn=module{0},cn=config
+> changetype: modify
+> add: olcModuleLoad
+> olcModuleLoad: {1}constraint.la
+>
+> 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
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 behaviour into a dynamic group.
+* {{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.
> objectClass: groupOfNames
> labeledURI: ldap:///ou=people,dc=example,dc=com??one?(objectClass=inetOrgPerson)
-The behaviour is similar to the dynamic list configuration we had before:
+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
!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 dymamic groups is that the members
+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}}
> 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