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.
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
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 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:
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
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
+Overlays can be stacked, which means that more than one overlay
+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 (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).
+
H3: Example Scenarios
projects / openldap / blobdiff