+# $OpenLDAP$
# Copyright 2007 The OpenLDAP Foundation, All Rights Reserved.
# COPYING RESTRICTIONS APPLY, see COPYRIGHT.
H1: Overlays
+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.
+
+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:
+
+ * customize the behavior of existing backends without changing the backend
+ 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
+
+Overlays are usually documented by separate specific man pages in section 5;
+the naming convention is
+
+> 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.
+
+Official overlays are located in
+
+> 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
+development of custom overlays.
+
+Contribware overlays are located in
+
+> contrib/slapd-modules/<overlay name>/
+
+along with other types of run-time loadable components; they are officially
+distributed, but not maintained by the project.
+
+They can be stacked on the frontend as well; 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.
+
+All the current overlays in 2.4 are listed and described in detail in the
+following sections.
+
H2: Access Logging
H3: Overview
+This overlay can record accesses to a given backend database on another
+database.
+
H3: Access Logging Configuration
H2: Audit Logging
+
+This overlay records changes on a given backend database to an LDIF log
+file.
H3: Overview
H3: Audit Logging Configuration
+H2: Chaining
+
+
+H3: Overview
+
+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
+default when --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 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.
+
H3: Constraint Configuration
H3: Overview
+
+This overlay supports dynamic objects, which have a limited life after
+which they expire and are automatically deleted.
H3: Dynamic Directory Service Configuration
H3: Overview
+This overlay extends the Compare operation to detect
+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.
+
H3: Dynamic List Configuration
+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
{{TERM:LDAP}} servers typically hold one or more subtrees of a
H3: Overview
The proxy cache extension of slapd is designed to improve the
-responseiveness of the ldap and meta backends. It handles a search
+responsiveness of the ldap and meta backends. It handles a search
request (query)
by first determining whether it is contained in any cached search
filter. Contained requests are answered from the proxy cache's local
<nattrsets> parameter specifies the total number of attribute sets
(as specified by the {{EX:proxyAttrSet}} directive) that may be
defined. The <entrylimit> parameter specifies the maximum number of
-entries in a cachable query. The <period> specifies the consistency
+entries in a cacheable query. The <period> specifies the consistency
check period (in seconds). In each period, queries with expired
TTLs are removed.
H3: Overview
+This overlay provides a variety of password control mechanisms,
+e.g. password aging, password reuse and duplication control, mandatory
+password resets, etc.
+
H3: Password Policy Configuration
H3: Overview
+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.
+
H3: Referential Integrity Configuration
H3: Overview
+This overlay is useful to test the behavior of clients when
+server-generated erroneous and/or unusual responses occur.
+
H3: Return Code Configuration
H3: Overview
+It performs basic DN/data rewrite and
+objectClass/attributeType mapping.
+
H3: Rewrite/Remap Configuration
H3: Overview
+This overlay implements the provider-side support for syncrepl
+replication, including persistent search functionality
+
H3: Sync Provider Configuration
H3: Overview
+This overlay can be used with a backend database such as slapd-bdb (5)
+to create a "translucent proxy".
+
+Content of entries retrieved from a remote LDAP server can be partially
+overridden by the database.
+
H3: Translucent Proxy Configuration
H3: Overview
+This overlay can be used with a backend database such as slapd-bdb (5)
+to enforce the uniqueness of some or all attributes within a subtree.
+
H3: Attribute Uniqueness Configuration
H3: Overview
+This overlay can be used to enforce a specific order for the values
+of an attribute when it is returned in a search.
+
H3: Value Sorting Configuration
H3: Overview
-H3: Example Senarios
+H3: Example Scenarios
H4: Samba