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.
+are only allowed to be configured on individual databases.
-Essentially, they represent a means to:
+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:
* customize the behavior of existing backends without changing the backend
code and without requiring one to write a new custom backend with
* write functionality of general usefulness that can be applied to
different backend types
+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>
+
Overlays are usually documented by separate specific man pages in section 5;
the naming convention is
> 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
+rationale of the overlay implementation, and may serve as a guideline for the
development of custom overlays.
Contribware overlays are located in
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
+All the current overlays in OpenLDAP are listed and described in detail in the
following sections.
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:
+On each replica, add this near the top of the {{slapd.conf}}(5) file
+(global), before any database definitions:
> overlay chain
> chain-uri "ldap://ldapmaster.example.com"
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.
+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.)
Now start an {{ldapmodify}} on the slave and watch the logs. You should expect
something like:
H3: Overview
-The {{dds}} overlay to {{slapd}}(8) implements dynamic objects as per RFC 2589.
+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.
H3: Dynamic Directory Service Configuration
-A usage of dynamic objects might beto implement dynamic meetings; in this case,
+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 5 seconds between expiration checks and a tolerance of 1 second (lifetime of
-a dynamic object will be {{B:entryTtl + tolerance}}.
+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 5s
-> dds-tolerance 1s
+> dds-interval 120s
+> dds-tolerance 5s
-So let's create an entry using:
+and add an index:
-> dn: cn=Dynamic,dc=example,dc=com
-> objectClass: inetOrgPerson
-> objectClass: dynamicObject
-> cn: Dynamic Object
-> sn: Object
+> entryExpireTimestamp
-MORE coming.
+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 {{B:member}}s;
+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="cn=Meetings,dc=example,dc=com"
+> access to dn.base="ou=Meetings,dc=example,dc=com"
> attrs=children
> by users write
>
-> access to dn.onelevel="cn=Meetings,dc=example,dc=com"
+> access to dn.onelevel="ou=Meetings,dc=example,dc=com"
> attrs=entry
> by dnattr=creatorsName write
> by * read
>
-> access to dn.onelevel="cn=Meetings,dc=example,dc=com"
+> 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="cn=Meetings,dc=example,dc=com"
+> 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
Overlays can be stacked, which means that more than one overlay
-can be instantiated for each database, or for the frontend.
+can be instantiated for each database, or for the {{EX:frontend}}.
As a consequence, each overlay's function is called, if defined,
when overlay execution is invoked.
-Multiple overlays are executed in reverse order (it's a stack, all in all)
+Multiple overlays are executed in reverse order (as a stack)
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).
projects / openldap / blobdiff