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.
refreshed, they are automatically {{deleted}}. There is no guarantee of immediate
deletion, so clients should not count on it.
-Dynamic objects can have subordinates, provided these also are dynamic objects.
-RFC 2589 does not specify what the behavior of a dynamic directory service
-should be when a dynamic object with (dynamic) subordinates expires.
-In this implementation, the lifetime of dynamic objects with subordinates is prolonged
-until all the dynamic subordinates expire.
-
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 provides a variety of password control mechanisms,
-e.g. password aging, password reuse and duplication control, mandatory
-password resets, etc.
+This overlay follows the specifications contained in the draft RFC titled
+draft-behera-ldap-password-policy-09. While the draft itself is expired, it has
+been implemented in several directory servers, including slapd. Nonetheless,
+it is important to note that it is a draft, meaning that it is subject to change
+and is a work-in-progress.
+
+The key abilities of the password policy overlay are as follows:
+
+* Enforce a minimum length for new passwords
+* Make sure passwords are not changed too frequently
+* Cause passwords to expire, provide warnings before they need to be changed, and allow a fixed number of 'grace' logins to allow them to be changed after they have expired
+* Maintain a history of passwords to prevent password re-use
+* Prevent password guessing by locking a password for a specified period of time after repeated authentication failures
+* Force a password to be changed at the next authentication
+* Set an administrative lock on an account
+* Support multiple password policies on a default or a per-object basis.
+* Perform arbitrary quality checks using an external loadable module. This is a non-standard extension of the draft RFC.
H3: Password Policy Configuration
+Instantiate the module in the database where it will be used, after adding the
+new ppolicy schema and loading the ppolicy module. The following example shows
+the ppolicy module being added to the database that handles the naming
+context "dc=example,dc=com". In this example we are also specifying the DN of
+a policy object to use if none other is specified in a user's object.
+
+> database bdb
+> suffix "dc=example,dc=com"
+> [...additional database configuration directives go here...]
+>
+> overlay ppolicy
+> ppolicy_default "cn=default,ou=policies,dc=example,dc=com"
+
+
+Now we need a container for the policy objects. In our example the password
+policy objects are going to be placed in a section of the tree called
+"ou=policies,dc=example,dc=com":
+
+> dn: ou=policies,dc=example,dc=com
+> objectClass: organizationalUnit
+> objectClass: top
+> ou: policies
+
+
+The default policy object that we are creating defines the following policies:
+
+* The user is allowed to change his own password. Note that the directory ACLs for this attribute can also affect this ability (pwdAllowUserChange: TRUE).
+* The name of the password attribute is "userPassword" (pwdAttribute: userPassword). Note that this is the only value that is accepted by OpenLDAP for this attribute.
+* The server will check the syntax of the password. If the server is unable to check the syntax (i.e., it was hashed or otherwise encoded by the client) it will return an error refusing the password (pwdCheckQuality: 2).
+* When a client includes the Password Policy Request control with a bind request, the server will respond with a password expiration warning if it is going to expire in ten minutes or less (pwdExpireWarning: 600). The warnings themselves are returned in a Password Policy Response control.
+* When the password for a DN has expired, the server will allow five additional "grace" logins (pwdGraceAuthNLimit: 5).
+* The server will maintain a history of the last five passwords that were used for a DN (pwdInHistory: 5).
+* The server will lock the account after the maximum number of failed bind attempts has been exceeded (pwdLockout: TRUE).
+* When the server has locked an account, the server will keep it locked until an administrator unlocks it (pwdLockoutDuration: 0)
+* The server will reset its failed bind count after a period of 30 seconds.
+* Passwords will not expire (pwdMaxAge: 0).
+* Passwords can be changed as often as desired (pwdMinAge: 0).
+* Passwords must be at least 5 characters in length (pwdMinLength: 5).
+* The password does not need to be changed at the first bind or when the administrator has reset the password (pwdMustChange: FALSE)
+* The current password does not need to be included with password change requests (pwdSafeModify: FALSE)
+* The server will only allow five failed binds in a row for a particular DN (pwdMaxFailure: 5).
+
+
+The actual policy would be:
+
+> dn: cn=default,ou=policies,dc=example,dc=com
+> cn: default
+> objectClass: pwdPolicy
+> objectClass: person
+> objectClass: top
+> pwdAllowUserChange: TRUE
+> pwdAttribute: userPassword
+> pwdCheckQuality: 2
+> pwdExpireWarning: 600
+> pwdFailureCountInterval: 30
+> pwdGraceAuthNLimit: 5
+> pwdInHistory: 5
+> pwdLockout: TRUE
+> pwdLockoutDuration: 0
+> pwdMaxAge: 0
+> pwdMaxFailure: 5
+> pwdMinAge: 0
+> pwdMinLength: 5
+> pwdMustChange: FALSE
+> pwdSafeModify: FALSE
+> sn: dummy value
+
+You can create additional policy objects as needed.
+
+
+There are two ways password policy can be applied to individual objects:
+
+1. Default password policy - If, as in the example above, the password policy
+module was configured with the DN of a default policy object and if that object
+exists, then the policy defined in that object is applied.
+
+2. The pwdPolicySubentry in a user's object - If a user's object contains a
+value for the pwdPolicySubEntry attribute, and if that object exists, then
+the policy defined by that object is applied. Remember that we need to add
+object class pwdPolicy to the user's object as well.
+
+Please see {{slapo-ppolicy(5)}} for complete explanations of features and discussion of
+ "Password Management Issues" at {{URL:http://www.connexitor.com/forums/viewtopic.php?f=6&t=25}}
+
+
H2: Referential Integrity
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 overlay's function is called, if defined,
+can be instantiated for each database, or for the {{EX: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)
+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