slapd.plugin

title: slapd.plugin(5)

text:
# slapd.plugin(5)

## NAME
slapd.plugin - plugin configuration for slapd, the stand-alone LDAP daemon

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The slapd.conf(5) file contains configuration information for the slapd(8) daemon. This configuration file is also used by the SLAPD tools slapadd(8), slapcat(8), and slapindex(8).

The slapd.conf file consists of a series of global configuration options that apply to slapd as a whole (including all backends), followed by zero or more database backend definitions that contain information specific to a backend instance.

The general format of slapd.conf is as follows:

```
    # comment - these options apply to every database

    <global configuration options>

    # first database definition & configuration options

    database    <backend 1 type>

    <configuration options specific to backend 1>

    # subsequent database definitions & configuration options

    ...
```

If slapd is compiled with --enable-slapi, support for plugins according to Netscape's Directory Server Plug-Ins. Version 4 of the API is currently implemented, with some extensions from version 5.

Both global and database specific data may contain plugin information. Plugins associated with a specific database are called before global plugins. This manpage details the slapd(8) configuration statements that affect the loading of SLAPI plugins.

Arguments that should be replaced by actual text are shown in brackets <>.

The structure of the plugin directives is

plugin <type> <lib_path> <init_function> [<arguments>]

Load a plugin of the specified type for the current database.

The <type> can be one of preoperation, that is executed before processing the operation for the specified database, postoperation, that is executed after the operation for the specified database has been processed, extendedop, that is used when executing an extended operation, or object. The latter is used for miscellaneous types such as ACL, computed attribute and search filter rewriter plugins.

The <libpath> argument specifies the path to the plugin loadable object; if a relative path is given, the object is looked for according to the underlying dynamic loading package (libtool's ltdl is used).

The <init_function> argument specifies what symbol must be called when the plugin is first loaded. This function should register the functions provided by the plugin for the desired operations. It should be noted that it is this init function, not the plugin type specified as the first argument, that determines when and for what operations the plugin will be invoked. The optional <arguments> list is passed to the init function.

pluginlog <file>

Specify an alternative path for the plugin log file (default is /var/lib/errors).

modulepath <pathspec>

This statement sets the module load path for dynamically loadable backends, as described in slapd.conf(5); however, since both the dynamically loadable backends and the SLAPI plugins use the same underlying library (libtool's ltdl) its value also affects the plugin search path. In general the search path is made of colon-separated paths; usually the user-defined path is searched first; then the value of the LTDL_LIBRARY_PATH environment variable, if defined, is used; finally, the system-specific dynamic load path is attempted (e.g. on Linux the value of the environment variable LD_LIBRARY_PATH). Please carefully read the documentation of ltdl because its behavior is very platform dependent.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

/var/lib/errors

default plugin log file

## SEE ALSO
slapd(8),

"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)

## ACKNOWLEDGEMENTS
OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from the University of Michigan LDAP 3.3 Release.


slapo-accesslog

package: openldap-servers

title: slapo-accesslog(5)

summary: Access Logging overlay to slapd

text:
# slapo-accesslog(5)

## NAME
slapo-accesslog - Access Logging overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The Access Logging overlay can be used to record all 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 (see below) to assure their readability whether viewed as LDIF or in raw form.

## CONFIGURATION
These slapd.conf options apply to the Access Logging overlay. They should appear after the overlay directive.

logdb <suffix>

Specify the suffix of a database to be used for storing the log records. The specified database must be defined elsewhere in the configuration. The access controls on the log database should prevent general access. The suffix entry of the log database will be created automatically by this overlay. The log entries will be generated as the immediate children of the suffix entry.

logops <operations>

Specify which types of operations to log. The valid operation types are abandon, add, bind, compare, delete, extended, modify, modrdn, search, and unbind. Aliases for common sets of operations are also available:

writes

add, delete, modify, modrdn

reads

compare, search

session

abandon, bind, unbind

all

all operations

logbase <operations> <baseDN>

Specify a set of operations that will only be logged if they occur under a specific subtree of the database. The operation types are as above for the logops setting, and delimited by a '|' character.

logold <filter>

Specify a filter for matching against Deleted and Modified entries. If the entry matches the filter, the old contents of the entry will be logged along with the current request.

logoldattr <attr> ...

Specify a list of attributes whose old contents are always logged in Modify and ModRDN requests. Usually only the contents of attributes that were actually modified will be logged; by default no old attributes are logged for ModRDN requests.

logpurge <age> <interval>

Specify the maximum age for log entries to be retained in the database, and how often to scan the database for old entries. Both the age and interval are specified as a time span in days, hours, minutes, and seconds. The time format is [ddd+]hh:mm[:ss] i.e., the days and seconds components are optional but hours and minutes are required. Except for days, which can be up to 5 digits, each numeric field must be exactly two digits. For example

logpurge 2+00:00 1+00:00

would specify that the log database should be scanned every day for old entries, and entries older than two days should be deleted. When using a log database that supports ordered indexing on generalizedTime attributes, specifying an eq index on the reqStart attribute will greatly benefit the performance of the purge operation.

logsuccess TRUE | FALSE

If set to TRUE then log records will only be generated for successful requests, i.e., requests that produce a result code of 0 (LDAP_SUCCESS). If FALSE, log records are generated for all requests whether they succeed or not. The default is FALSE.

## EXAMPLES

```
	database bdb
	suffix dc=example,dc=com
	...
	overlay accesslog
	logdb cn=log
	logops writes reads
	logbase search|compare ou=testing,dc=example,dc=com
	logold (objectclass=person)
	database bdb
	suffix cn=log
	...
	index reqStart eq
	access to *
	  by dn.base="cn=admin,dc=example,dc=com" read
```

## SCHEMA
The accesslog overlay utilizes the "audit" schema described herein. This schema is specifically designed for accesslog auditing and is not intended to be used otherwise. It is also noted that the schema described here is a work in progress, and hence subject to change without notice. The schema is loaded automatically by the overlay.

The schema includes a number of object classes and associated attribute types as described below.

There is a basic auditObject class from which two additional classes, auditReadObject and auditWriteObject are derived. Object classes for each type of LDAP operation are further derived from these classes. This object class hierarchy is designed to allow flexible yet efficient searches of the log based on either a specific operation type's class, or on more general classifications. The definition of the auditObject class is as follows:

( 1.3.6.1.4.1.4203.666.11.5.2.1

NAME 'auditObject'

DESC 'OpenLDAP request auditing'

SUP top STRUCTURAL

MUST ( reqStart $ reqType $ reqSession )

MAY ( reqDN $ reqAuthzID $ reqControls $ reqRespControls $

reqEnd $ reqResult $ reqMessage $ reqReferral ) )

Note that all of the OIDs used in the logging schema currently reside under the OpenLDAP Experimental branch. It is anticipated that they will migrate to a Standard branch in the future.

An overview of the attributes follows: reqStart and reqEnd provide the start and end time of the operation, respectively. They use generalizedTime syntax. The reqStart attribute is also used as the RDN for each log entry.

The reqType attribute is a simple string containing the type of operation being logged, e.g. add, delete, search, etc. For extended operations, the type also includes the OID of the extended operation, e.g. extended(1.1.1.1)

The reqSession attribute is an implementation-specific identifier that is common to all the operations associated with the same LDAP session. Currently this is slapd's internal connection ID, stored in decimal.

The reqDN attribute is the distinguishedName of the target of the operation. E.g., for a Bind request, this is the Bind DN. For an Add request, this is the DN of the entry being added. For a Search request, this is the base DN of the search.

The reqAuthzID attribute is the distinguishedName of the user that performed the operation. This will usually be the same name as was established at the start of a session by a Bind request (if any) but may be altered in various circumstances.

The reqControls and reqRespControls attributes carry any controls sent by the client on the request and returned by the server in the response, respectively. The attribute values are just uninterpreted octet strings.

The reqResult attribute is the numeric LDAP result code of the operation, indicating either success or a particular LDAP error code. An error code may be accompanied by a text error message which will be recorded in the reqMessage attribute.

The reqReferral attribute carries any referrals that were returned with the result of the request.

Operation-specific classes are defined with additional attributes to carry all of the relevant parameters associated with the operation:

( 1.3.6.1.4.1.4203.666.11.5.2.4

NAME 'auditAbandon'

DESC 'Abandon operation'

SUP auditObject STRUCTURAL

MUST reqId )

For the Abandon operation the reqId attribute contains the message ID of the request that was abandoned.

( 1.3.6.1.4.1.4203.666.11.5.2.5

NAME 'auditAdd'

DESC 'Add operation'

SUP auditWriteObject STRUCTURAL

MUST reqMod )

The Add class inherits from the auditWriteObject class. The Add and Modify classes are very similar. The reqMod attribute carries all of the attributes of the original entry being added. (Or in the case of a Modify operation, all of the modifications being performed.) The values are formatted as

attribute:<+|-|=|#> [ value]

Where '+' indicates an Add of a value, '-' for Delete, '=' for Replace, and '#' for Increment. In an Add operation, all of the reqMod values will have the '+' designator.

( 1.3.6.1.4.1.4203.666.11.5.2.6

NAME 'auditBind'

DESC 'Bind operation'

SUP auditObject STRUCTURAL

MUST ( reqVersion $ reqMethod ) )

The Bind class includes the reqVersion attribute which contains the LDAP protocol version specified in the Bind as well as the reqMethod attribute which contains the Bind Method used in the Bind. This will be the string SIMPLE for LDAP Simple Binds or SASL(<mech>) for SASL Binds. Note that unless configured as a global overlay, only Simple Binds using DNs that reside in the current database will be logged.

( 1.3.6.1.4.1.4203.666.11.5.2.7

NAME 'auditCompare'

DESC 'Compare operation'

SUP auditObject STRUCTURAL

MUST reqAssertion )

For the Compare operation the reqAssertion attribute carries the Attribute Value Assertion used in the compare request.

( 1.3.6.1.4.1.4203.666.11.5.2.8

NAME 'auditDelete'

DESC 'Delete operation'

SUP auditWriteObject STRUCTURAL

MAY reqOld )

The Delete operation needs no further parameters. However, the reqOld attribute may optionally be used to record the contents of the entry prior to its deletion. The values are formatted as

attribute: value

The reqOld attribute is only populated if the entry being deleted matches the configured logold filter.

( 1.3.6.1.4.1.4203.666.11.5.2.9

NAME 'auditModify'

DESC 'Modify operation'

SUP auditWriteObject STRUCTURAL

MAY reqOld MUST reqMod )

The Modify operation contains a description of modifications in the reqMod attribute, which was already described above in the Add operation. It may optionally contain the previous contents of any modified attributes in the reqOld attribute, using the same format as described above for the Delete operation. The reqOld attribute is only populated if the entry being modified matches the configured logold filter.

( 1.3.6.1.4.1.4203.666.11.5.2.10

NAME 'auditModRDN'

DESC 'ModRDN operation'

SUP auditWriteObject STRUCTURAL

MUST ( reqNewRDN $ reqDeleteOldRDN )

MAY ( reqNewSuperior $ reqOld ) )

The ModRDN class uses the reqNewRDN attribute to carry the new RDN of the request. The reqDeleteOldRDN attribute is a Boolean value showing TRUE if the old RDN was deleted from the entry, or FALSE if the old RDN was preserved. The reqNewSuperior attribute carries the DN of the new parent entry if the request specified the new parent. The reqOld attribute is only populated if the entry being modified matches the configured logold filter and contains attributes in the logoldattr list.

( 1.3.6.1.4.1.4203.666.11.5.2.11

NAME 'auditSearch'

DESC 'Search operation'

SUP auditReadObject STRUCTURAL

MUST ( reqScope $ reqDerefAliases $ reqAttrsOnly )

MAY ( reqFilter $ reqAttr $ reqEntries $ reqSizeLimit $

reqTimeLimit ) )

For the Search class the reqScope attribute contains the scope of the original search request, using the values specified for the LDAP URL format. I.e. base, one, sub, or subord. The reqDerefAliases attribute is one of never, finding, searching, or always, denoting how aliases will be processed during the search. The reqAttrsOnly attribute is a Boolean value showing TRUE if only attribute names were requested, or FALSE if attributes and their values were requested. The reqFilter attribute carries the filter used in the search request. The reqAttr attribute lists the requested attributes if specific attributes were requested. The reqEntries attribute is the integer count of how many entries were returned by this search request. The reqSizeLimit and reqTimeLimit attributes indicate what limits were requested on the search operation.

( 1.3.6.1.4.1.4203.666.11.5.2.12

NAME 'auditExtended'

DESC 'Extended operation'

SUP auditObject STRUCTURAL

MAY reqData )

The Extended class represents an LDAP Extended Operation. As noted above, the actual OID of the operation is included in the reqType attribute of the parent class. If any optional data was provided with the request, it will be contained in the reqData attribute as an uninterpreted octet string.

## NOTES
The Access Log implemented by this overlay may be used for a variety of other tasks, e.g. as a ChangeLog for a replication mechanism, as well as for security/audit logging purposes.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5).

## ACKNOWLEDGEMENTS
This module was written in 2005 by Howard Chu of Symas Corporation.


slapo-auditlog

title: slapo-auditlog(5)

summary: Audit Logging overlay to slapd

text:
# slapo-auditlog(5)

## NAME
slapo-auditlog - Audit Logging overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

/etc/openldap/slapd.d

## DESCRIPTION
The Audit Logging overlay can be used to record all changes on a given backend database to a specified log file. Changes are logged as standard LDIF, with an additional comment header giving the timestamp of the change and the identity of the user making the change.

For Add and Modify operations the identity comes from the modifiersName associated with the operation. This is usually the same as the requestor's identity, but may be set by other overlays to reflect other values.

## CONFIGURATION
This slapd.conf option applies to the Audit Logging overlay. It should appear after the overlay directive.

auditlog <filename>

Specify the fully qualified path for the log file.

olcAuditlogFile <filename>

For use with cn=config

## EXAMPLE
The following LDIF could be used to add this overlay to cn=config (adjust to suit)

```
dn: olcOverlay=auditlog,olcDatabase={1}mdb,cn=config
changetype: add
objectClass: olcOverlayConfig
objectClass: olcAuditLogConfig
olcOverlay: auditlog
olcAuditlogFile: /tmp/auditlog.ldif
```

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

/etc/openldap/slapd.d

default slapd configuration directory

## SEE ALSO
slapd.conf(5), slapd-config(5).


slapo-chain

title: slapo-chain(5)

summary: chain overlay to slapd

text:
# slapo-chain(5)

## NAME
slapo-chain - chain overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The chain overlay to slapd(8) allows automatic referral chasing. Any time a referral is returned (except for bind operations), it is chased by using an instance of the ldap backend. If operations are performed with an identity (i.e. after a bind), that identity can be asserted while chasing the referrals by means of the identity assertion feature of back-ldap (see slapd-ldap(5) for details), which is essentially based on the proxied authorization control [RFC 4370]. Referral chasing can be controlled by the client by issuing the chaining control (see draft-sermersheim-ldap-chaining for details.)

The config directives that are specific to the chain overlay are prefixed by chain-, to avoid potential conflicts with directives specific to the underlying database or to other stacked overlays.

There are very few chain overlay specific directives; however, directives related to the instances of the ldap backend that may be implicitly instantiated by the overlay may assume a special meaning when used in conjunction with this overlay. They are described in slapd-ldap(5), and they also need to be prefixed by chain-.

Note: this overlay is built into the ldap backend; it is not a separate module.

overlay chain

This directive adds the chain overlay to the current backend. The chain overlay may be used with any backend, but it is mainly intended for use with local storage backends that may return referrals. It is useless in conjunction with the slapd-ldap and slapd-meta backends because they already exploit the libldap specific referral chase feature. [Note: this may change in the future, as the ldap(5) and meta(5) backends might no longer chase referrals on their own.]

chain-cache-uri {FALSE|true}

This directive instructs the chain overlay to cache connections to URIs parsed out of referrals that are not predefined, to be reused for later chaining. These URIs inherit the properties configured for the underlying slapd-ldap(5) before any occurrence of the chain-uri directive; basically, they are chained anonymously.

chain-chaining [resolve=<r>] [continuation=<c>] [critical]

This directive enables the chaining control (see draft-sermersheim-ldap-chaining for details) with the desired resolve and continuation behaviors and criticality. The resolve parameter refers to the behavior while discovering a resource, namely when accessing the object indicated by the request DN; the continuation parameter refers to the behavior while handling intermediate responses, which is mostly significant for the search operation, but may affect extended operations that return intermediate responses. The values r and c can be any of chainingPreferred, chainingRequired, referralsPreferred, referralsRequired. If the critical flag affects the control criticality if provided. [This control is experimental and its support may change in the future.]

chain-max-depth <n>

In case a referral is returned during referral chasing, further chasing occurs at most <n> levels deep. Set to 1 (the default) to disable further referral chasing.

chain-return-error {FALSE|true}

In case referral chasing fails, the real error is returned instead of the original referral. In case multiple referral URIs are present, only the first error is returned. This behavior may not be always appropriate nor desirable, since failures in referral chasing might be better resolved by the client (e.g. when caused by distributed authentication issues).

chain-uri <ldapuri>

This directive instantiates a new underlying ldap database and instructs it about which URI to contact to chase referrals. As opposed to what stated in slapd-ldap(5), only one URI can appear after this directive; all subsequent slapd-ldap(5) directives prefixed by chain- refer to this specific instance of a remote server.

Directives for configuring the underlying ldap database may also be required, as shown in this example:

```
overlay                 chain
chain-rebind-as-user    FALSE
chain-uri               "ldap://ldap1.example.com"
chain-rebind-as-user    TRUE
chain-idassert-bind     bindmethod="simple"

                        binddn="cn=Auth,dc=example,dc=com"

                        credentials="secret"

                        mode="self"
chain-uri               "ldap://ldap2.example.com"
chain-idassert-bind     bindmethod="simple"

                        binddn="cn=Auth,dc=example,dc=com"

                        credentials="secret"

                        mode="none"
```

Any valid directives for the ldap database may be used; see slapd-ldap(5) for details. Multiple occurrences of the chain-uri directive may appear, to define multiple "trusted" URIs where operations with identity assertion are chained. All URIs not listed in the configuration are chained anonymously. All slapd-ldap(5) directives appearing before the first occurrence of chain-uri are inherited by all URIs, unless specifically overridden inside each URI configuration.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5), slapd-ldap(5), slapd(8).

## AUTHOR
Originally implemented by Howard Chu; extended by Pierangelo Masarati.


slapo-collect

title: slapo-collect(5)

summary: Collective attributes overlay to slapd

text:
# slapo-collect(5)

## NAME
slapo-collect - Collective attributes overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The collect overlay is used to provide a relatively coarse implementation of RFC 3671 collective attributes. In X.500, a collective attribute is "a user attribute whose values are the same for each member of an entry collection".

Collective attributes are added to entries returned by a search operation when the entry is within the scope of the related ancestor. Collective attributes can only be modified when the modification affects the related ancestor.

## CONFIGURATION
This slapd.conf option applies to the collect overlay. It should appear after the overlay directive.

collectinfo <DN> <attrlist>

Specify the DN of the ancestor entry and the set of related collective attributes, where attrlist is a comma-separated list of attributes. The DN should be within the naming context of the database.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5), The slapo-collect(5) overlay supports dynamic configuration via back-config.

## ACKNOWLEDGEMENTS
This module was written in 2003 by Howard Chu. This man page was written in 2008 by Pierangelo Masarati. OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from the University of Michigan LDAP 3.3 Release.


slapo-constraint

title: slapo-constraint(5)

summary: Attribute Constraint Overlay to slapd

text:
# slapo-constraint(5)

## NAME
slapo-constraint - Attribute Constraint Overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The constraint overlay is used to ensure that attribute values match some constraints beyond basic LDAP syntax. Attributes can have multiple constraints placed upon them, and all must be satisfied when modifying an attribute value under constraint.

This overlay is intended to be used to force syntactic regularity upon certain string represented data which have well known canonical forms, like telephone numbers, post codes, FQDNs, etc.

It constrains only LDAP add, modify and rename commands and only seeks to control the add and replace values of modify and rename requests.

No constraints are applied for operations performed with the relax control set.

## CONFIGURATION
This slapd.conf option applies to the constraint overlay. It should appear after the overlay directive.

constraint_attribute <attribute_name>[,...] <type> <value> [<extra> [...]]

Specifies the constraint which should apply to the comma-separated attribute list named as the first parameter. Five types of constraint are currently supported - regex, size, count, uri, and set. The parameter following the regex type is a Unix style regular expression (See regex(7) ). The parameter following the uri type is an LDAP URI. The URI will be evaluated using an internal search. It must not include a hostname, and it must include a list of attributes to evaluate.

The parameter following the set type is a string that is interpreted according to the syntax in use for ACL sets. This allows one to construct constraints based on the contents of the entry.

The size type can be used to enforce a limit on an attribute length, and the count type limits the number of values of an attribute.

Extra parameters can occur in any order after those described above.

<extra> : restrict=<uri>

This extra parameter allows one to restrict the application of the corresponding constraint only to entries that match the base, scope and filter portions of the LDAP URI. The base, if present, must be within the naming context of the database. The scope is only used when the base is present; it defaults to base. The other parameters of the URI are not allowed.

Any attempt to add or modify an attribute named as part of the constraint overlay specification which does not fit the constraint listed will fail with a LDAP_CONSTRAINT_VIOLATION error.

## EXAMPLES

```
overlay constraint
constraint_attribute jpegPhoto size 131072
constraint_attribute userPassword count 3
constraint_attribute mail regex ^[[:alnum:]]+@mydomain.com$
constraint_attribute title uri

  ldap:///dc=catalog,dc=example,dc=com?title?sub?(objectClass=titleCatalog)
constraint_attribute cn,sn,givenName set

  "(this/givenName + [ ] + this/sn) & this/cn"

  restrict="ldap:///ou=People,dc=example,dc=com??sub?(objectClass=inetOrgPerson)"
```

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. (Note that the "dc=catalog,dc=example,dc=com" subtree ought to reside in a separate database, otherwise the initial set of titleCatalog entries could not be populated while the constraint is in effect.) Finally, it requires the values of the attribute cn to be constructed by pairing values of the attributes sn and givenName, separated by a space, but only for entries derived from the objectClass inetOrgPerson.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5),

## ACKNOWLEDGEMENTS
This module was written in 2005 by Neil Dunbar of Hewlett-Packard and subsequently extended by Howard Chu and Emmanuel Dreyfus. OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from the University of Michigan LDAP 3.3 Release.


slapo-dds

title: slapo-dds(5)

text:
# slapo-dds(5)

## NAME
slapo-dds - Dynamic Directory Services overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The dds overlay to slapd(8) implements dynamic objects as per RFC 2589. The name dds stands for Dynamic Directory Services. It allows one 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 one 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.

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.

This slapd.conf(5) directive adds the dds overlay to the current database:

overlay dds

The database must have a rootdn specified, otherwise, the dds overlay will not be able to delete expired objects. The dds overlay may be used with any backend that implements the add, modify, search, and delete operations. Since its use may result in many internal entry lookups, adds and deletes, it should be best used in conjunction with backends that have reasonably good write performances.

The config directives that are specific to the dds overlay are prefixed by dds-, to avoid potential conflicts with directives specific to the underlying database or to other stacked overlays.

dds-max-ttl <ttl>

Specifies the max TTL value. This is also the default TTL newly created dynamic objects receive, unless dds-default-ttl is set. When the client with a refresh extended operation requests a TTL higher than it, sizeLimitExceeded is returned. This value must be between 86400 (1 day, the default) and 31557600 (1 year plus 6 hours, as per RFC 2589).

dds-min-ttl <ttl>

Specifies the min TTL value; clients requesting a lower TTL by means of the refresh extended operation actually obtain this value as CRP. If set to 0 (the default), no lower limit is set.

dds-default-ttl <ttl>

Specifies the default TTL value that newly created dynamic objects get. If set to 0 (the default), the dds-max-ttl is used.

dds-interval <ttl>

Specifies the interval between expiration checks; defaults to 1 hour.

dds-tolerance <ttl>

Specifies an extra time that is added to the timer that actually wakes up the thread that will delete an expired dynamic object. So the nominal lifetime of the entry is that specified in the entryTtl attribute, but its lifetime will actually be entryTtl + tolerance. Note that there is no guarantee that the lifetime of a dynamic object will be exactly the requested TTL; due to implementation details, it may be longer, which is allowed by RFC 2589. By default, tolerance is 0.

dds-max-dynamicObjects <num>

Specifies the maximum number of dynamic objects that can simultaneously exist within a naming context. This allows one to limit the amount of resources (mostly in terms of run-queue size) that are used by dynamic objects. By default, no limit is set.

dds-state {TRUE|false}

Specifies if the Dynamic Directory Services feature is enabled or not. By default it is; however, a proxy does not need to keep track of dynamic objects itself, it only needs to inform the frontend that support for dynamic objects is available.

## ACCESS CONTROL
The dds overlay restricts the refresh operation by requiring manage access to the entryTtl attribute (see slapd.access(5) for details about the manage access privilege). Since the entryTtl is an operational, NO-USER-MODIFICATION attribute, no direct write access to it is possible. So the dds overlay turns refresh extended operation into an internal modification to the value of the entryTtl attribute with the relax control set.

RFC 2589 recommends that anonymous clients should not be allowed to refresh a dynamic object. This can be implemented by appropriately crafting access control to obtain the desired effect.

Example: restrict refresh to authenticated clients

```
access to attrs=entryTtl
	by users manage
	by * read
```

Example: restrict refresh to the creator of the dynamic object

```
access to attrs=entryTtl
	by dnattr=creatorsName manage
	by * read
```

Another suggested usage of dynamic objects is 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) Example: assuming participant is a valid DN-valued attribute, allow users to start a meeting and to join it; restrict refresh to the participants; restrict delete to the creator

```
access to dn.base="cn=Meetings"
		attrs=children
	by users write
access to dn.onelevel="cn=Meetings"
		attrs=entry
	by dnattr=creatorsName write
	by * read
access to dn.onelevel="cn=Meetings"
		attrs=participant
	by dnattr=creatorsName write
	by users selfwrite
	by * read
access to dn.onelevel="cn=Meetings"
		attrs=entryTtl
	by dnattr=participant manage
	by * read
```

## REPLICATION
This implementation of RFC 2589 provides a restricted interpretation of how dynamic objects replicate. Only the provider takes care of handling dynamic object expiration, while consumers simply see the dynamic object as a plain object.

When replicating these objects, one needs to explicitly exclude the dynamicObject class and the entryTtl attribute. This implementation of RFC 2589 introduces a new operational attribute, entryExpireTimestamp, that contains the expiration timestamp. This must be excluded from replication as well.

The quick and dirty solution is to set schemacheck=off in the syncrepl configuration and, optionally, exclude the operational attributes from replication, using

```
syncrepl ...
	exattrs=entryTtl,entryExpireTimestamp
```

In any case the overlay must be either statically built in or run-time loaded by the consumer, so that it is aware of the entryExpireTimestamp operational attribute; however, it must not be configured in the shadow database. Currently, there is no means to remove the dynamicObject class from the entry; this may be seen as a feature, since it allows one to see the dynamic properties of the object.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5), slapd(8).

## AUTHOR
Implemented by Pierangelo Masarati.


slapo-dyngroup

title: slapo-dyngroup(5)

summary: Dynamic Group overlay to slapd

text:
# slapo-dyngroup(5)

## NAME
slapo-dyngroup - Dynamic Group overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The Dynamic Group overlay allows clients to use LDAP Compare operations to test the membership of a dynamic group the same way they would check against a static group. Compare operations targeting a group's static member attribute will be intercepted and tested against the configured dynamic group's URL attribute.

Note that this intercept only happens if the actual Compare operation does not return a LDAP_COMPARE_TRUE result. So if a group has both static and dynamic members, the static member list will be checked first.

## CONFIGURATION
This slapd.conf option applies to the Dynamic Group overlay. It should appear after the overlay directive.

attrpair <memberAttr> <URLattr>

Specify the attributes to be compared. A compare operation on the memberAttr will cause the URLattr to be evaluated for the result.

## EXAMPLES

```
  database bdb

  ...

  overlay dyngroup

  attrpair member memberURL
```

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5).

## AUTHOR
Howard Chu


slapo-dynlist

title: slapo-dynlist(5)

summary: Dynamic List overlay to slapd

text:
# slapo-dynlist(5)

## NAME
slapo-dynlist - Dynamic List overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The dynlist overlay to slapd(8) allows expansion of dynamic groups and more. Any time an entry with a specific objectClass (defined in the overlay configuration) is being returned, the LDAP URI-valued occurrences of a specific attribute (also defined in the overlay configuration) are expanded into the corresponding entries, and the values of the attributes listed in the URI are added to the original entry. No recursion is allowed, to avoid potential infinite loops.

Since the resulting entry is dynamically constructed, it does not exist until it is constructed while being returned. As a consequence, dynamically added attributes do not participate in the filter matching phase of the search request handling. In other words, filtering for dynamically added attributes always fails.

The resulting entry must comply with the LDAP data model, so constraints are enforced. For example, if a SINGLE-VALUE attribute is listed, only the first value found during the list expansion appears in the final entry. The above described behavior is disabled when the manageDSAit control (RFC 3296) is used. In that case, the contents of the dynamic group entry is returned; namely, the URLs are returned instead of being expanded.

## CONFIGURATION
The config directives that are specific to the dynlist overlay must be prefixed by dynlist-, to avoid potential conflicts with directives specific to the underlying database or to other stacked overlays.

overlay dynlist

This directive adds the dynlist overlay to the current database, or to the frontend, if used before any database instantiation; see slapd.conf(5) for details.

This slapd.conf configuration option is defined for the dynlist overlay. It may have multiple occurrences, and it must appear after the overlay directive.

dynlist-attrset <group-oc> [<URI>] <URL-ad> [[<mapped-ad>:]<member-ad> ...]

The value group-oc is the name of the objectClass that triggers the dynamic expansion of the data. The optional URI restricts expansion only to entries matching the DN, the scope and the filter portions of the URI.

The value URL-ad is the name of the attributeDescription that contains the URI that is expanded by the overlay; if none is present, no expansion occurs. If the intersection of the attributes requested by the search operation (or the asserted attribute for compares) and the attributes listed in the URI is empty, no expansion occurs for that specific URI. It must be a subtype of labeledURI.

The value member-ad is optional; if present, the overlay behaves as a dynamic group: this attribute will list the DN of the entries resulting from the internal search. In this case, the attrs portion of the URIs in the URL-ad attribute must be absent, and the DNs of all the entries resulting from the expansion of the URIs are listed as values of this attribute. Compares that assert the value of the member-ad attribute of entries with group-oc objectClass apply as if the DN of the entries resulting from the expansion of the URI were present in the group-oc entry as values of the member-ad attribute.

Alternatively, mapped-ad can be used to remap attributes obtained through expansion. member-ad attributes are not filled by expanded DN, but are remapped as mapped-ad attributes. Multiple mapping statements can be used.

The dynlist overlay may be used with any backend, but it is mainly intended for use with local storage backends. In case the URI expansion is very resource-intensive and occurs frequently with well-defined patterns, one should consider adding a proxycache later on in the overlay stack.

## AUTHORIZATION
By default the expansions are performed using the identity of the current LDAP user. This identity may be overridden by setting the dgIdentity attribute in the group's entry to the DN of another LDAP user. In that case the dgIdentity will be used when expanding the URIs in the object. Setting the dgIdentity to a zero-length string will cause the expansions to be performed anonymously. Note that the dgIdentity attribute is defined in the dyngroup schema, and this schema must be loaded before the dgIdentity authorization feature may be used. If the dgAuthz attribute is also present in the group's entry, its values are used to determine what identities are authorized to use the dgIdentity to expand the group. Values of the dgAuthz attribute must conform to the (experimental) OpenLDAP authz syntax.

## EXAMPLE
This example collects all the email addresses of a database into a single entry; first of all, make sure that slapd.conf contains the directives:

```
    include /path/to/dyngroup.schema

    # ...

    database <database>

    # ...

    overlay dynlist

    dynlist-attrset groupOfURLs memberURL
```

and that slapd loads dynlist.la, if compiled as a run-time module; then add to the database an entry like

```
    dn: cn=Dynamic List,ou=Groups,dc=example,dc=com

    objectClass: groupOfURLs

    cn: Dynamic List

    memberURL: ldap:///ou=People,dc=example,dc=com?mail?sub?(objectClass=person)
```

If no <attrs> are provided in the URI, all (non-operational) attributes are collected.

This example implements the dynamic group feature on the member attribute:

```
    include /path/to/dyngroup.schema

    # ...

    database <database>

    # ...

    overlay dynlist

    dynlist-attrset groupOfURLs memberURL member
```

A dynamic group with dgIdentity authorization could be created with an entry like

```
    dn: cn=Dynamic Group,ou=Groups,dc=example,dc=com

    objectClass: groupOfURLs

    objectClass: dgIdentityAux

    cn: Dynamic Group

    memberURL: ldap:///ou=People,dc=example,dc=com??sub?(objectClass=person)

    dgIdentity: cn=Group Proxy,ou=Services,dc=example,dc=com
```

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5), slapd(8). The slapo-dynlist(5) overlay supports dynamic configuration via back-config.

## ACKNOWLEDGEMENTS
This module was written in 2004 by Pierangelo Masarati for SysNet s.n.c.

Attribute remapping was contributed in 2008 by Emmanuel Dreyfus.


slapo-memberof

title: slapo-memberof(5)

text:
# slapo-memberof(5)

## NAME
slapo-memberof - Reverse Group Membership overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The memberof overlay to slapd(8) allows automatic reverse group membership maintenance. Any time a group entry is modified, its members are modified as appropriate in order to keep a DN-valued "is member of" attribute updated with the DN of the group.

## CONFIGURATION
The config directives that are specific to the memberof overlay must be prefixed by memberof-, to avoid potential conflicts with directives specific to the underlying database or to other stacked overlays.

overlay memberof

This directive adds the memberof overlay to the current database; see slapd.conf(5) for details.

The following slapd.conf configuration options are defined for the memberof overlay.

memberof-group-oc <group-oc>

The value <group-oc> is the name of the objectClass that triggers the reverse group membership update. It defaults to groupOfNames.

memberof-member-ad <member-ad>

The value <member-ad> is the name of the attribute that contains the names of the members in the group objects; it must be DN-valued. It defaults to member.

memberof-memberof-ad <memberof-ad>

The value <memberof-ad> is the name of the attribute that contains the names of the groups an entry is member of; it must be DN-valued. Its contents are automatically updated by the overlay. It defaults to memberOf.

memberof-dn <dn>

The value <dn> contains the DN that is used as modifiersName for internal modifications performed to update the reverse group membership. It defaults to the rootdn of the underlying database.

memberof-dangling {ignore, drop, error}

This option determines the behavior of the overlay when, during a modification, it encounters dangling references. The default is ignore, which may leave dangling references. Other options are drop, which discards those modifications that would result in dangling references, and error, which causes modifications that would result in dangling references to fail.

memberof-dangling-error <error-code>

If memberof-dangling is set to error, this configuration parameter can be used to modify the response code returned in case of violation. It defaults to "constraint violation", but other implementations are known to return "no such object" instead.

memberof-refint {true|FALSE}

This option determines whether the overlay will try to preserve referential integrity or not. If set to TRUE, when an entry containing values of the "is member of" attribute is modified, the corresponding groups are modified as well.

The memberof overlay may be used with any backend that provides full read-write functionality, but it is mainly intended for use with local storage backends. The maintenance operations it performs are internal to the server on which the overlay is configured and are never replicated. Consumer servers should be configured with their own instances of the memberOf overlay if it is desired to maintain these memberOf attributes on the consumers. Note that slapo-memberOf is not compatible with syncrepl based replication, and should not be used in a replicated environment. An alternative is to use slapo-dynlist to emulate slapo-memberOf behavior.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5), slapd(8). The slapo-memberof(5) overlay supports dynamic configuration via back-config.

## ACKNOWLEDGEMENTS
This module was written in 2005 by Pierangelo Masarati for SysNet s.n.c.


slapo-pbind

title: slapo-pbind(5)

summary: proxy bind overlay to slapd

text:
# slapo-pbind(5)

## NAME
slapo-pbind - proxy bind overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The pbind overlay to slapd(8) forwards Simple Binds on a local database to a remote LDAP server instead of processing them locally. The remote connection is managed using an instance of the ldap backend.

The pbind overlay uses a subset of the ldap backend's config directives. They are described in more detail in slapd-ldap(5).

Note: this overlay is built into the ldap backend; it is not a separate module.

overlay pbind

This directive adds the proxy bind overlay to the current backend. The proxy bind overlay may be used with any backend, but it is mainly intended for use with local storage backends.

uri <ldapurl>

LDAP server to use.

tls <TLS parameters>

Specify the use of TLS.

network-timeout <time>

Set the network timeout.

quarantine <quarantine parameters>

Turns on quarantine of URIs that returned LDAP_UNAVAILABLE.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5), slapd-ldap(5), slapd(8).

## AUTHOR
Howard Chu


slapo-pcache

title: slapo-pcache(5)

summary: proxy cache overlay to slapd

text:
# slapo-pcache(5)

## NAME
slapo-pcache - proxy cache overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The pcache overlay to slapd(8) allows caching of LDAP search requests (queries) in a local database. For an incoming query, the proxy cache determines its corresponding template. If the template was specified as cacheable using the pcacheTemplate directive and the request is contained in a cached request, it is answered from the proxy cache. Otherwise, the search is performed as usual and cacheable search results are saved in the cache for use in future queries.

A template is defined by a filter string and an index identifying a set of attributes. The template string for a query can be obtained by removing assertion values from the RFC 4515 representation of its search filter. A query belongs to a template if its template string and set of projected attributes correspond to a cacheable template. Examples of template strings are (mail=), (|(sn=)(cn=)), (&(sn=)(givenName=)).

The config directives that are specific to the pcache overlay can be prefixed by pcache-, to avoid conflicts with directives specific to the underlying database or to other stacked overlays. This may be particularly useful for those directives that refer to the backend used for local storage. The following cache specific directives can be used to configure the proxy cache:

overlay pcache

This directive adds the proxy cache overlay to the current backend. The proxy cache overlay may be used with any backend but is intended for use with the ldap, meta, and sql backends. Please note that the underlying backend must have a configured rootdn.

pcache <database> <max_entries> <numattrsets> <entry_limit> <cc_period>

The directive enables proxy caching in the current backend and sets general cache parameters. A <database> backend will be used internally to maintain the cached entries. The chosen database will need to be configured as well, as shown below. Cache replacement is invoked when the cache size grows to <max_entries> entries and continues till the cache size drops below this size. <numattrsets> should be equal to the number of following pcacheAttrset directives. Queries are cached only if they correspond to a cacheable template (specified by the pcacheTemplate directive) and the number of entries returned is less than <entry_limit>. Consistency check is performed every <cc_period> duration (specified in secs). In each cycle queries with expired "time to live(TTL)" are removed. A sample cache configuration is:

pcache mdb 10000 1 50 100

pcacheAttrset <index> <attrs...>

Used to associate a set of attributes <attrs..> with an <index>. Each attribute set is associated with an integer from 0 to <numattrsets>-1. These indices are used by the pcacheTemplate directive to define cacheable templates. A set of attributes cannot be empty. A set of attributes can contain the special attributes "*" (all user attributes), "+" (all operational attributes) or both; in the latter case, any other attribute is redundant and should be avoided for clarity. A set of attributes can contain "1.1" as the only attribute; in this case, only the presence of the entries is cached. Attributes prefixed by "undef:" need not be present in the schema.

pcacheMaxQueries <queries>

Specify the maximum number of queries to cache. The default is 10000.

pcacheValidate { TRUE | FALSE }

Check whether the results of a query being cached can actually be returned from the cache by the proxy DSA. When enabled, the entries being returned while caching the results of a query are checked to ensure consistency with the schema known to the proxy DSA. In case of failure, the query is not cached. By default, the check is off.

pcacheOffline { TRUE | FALSE }

Set the cache to offline mode. While offline, the consistency checker will be stopped and no expirations will occur. This allows the cache contents to be used indefinitely while the proxy is cut off from network access to the remote DSA. The default is FALSE, i.e. consistency checks and expirations will be performed.

pcachePersist { TRUE | FALSE }

Specify whether the cached queries should be saved across restarts of the caching proxy, to provide hot startup of the cache. Only non-expired queries are reloaded. The default is FALSE. CAVEAT: of course, the configuration of the proxy cache must not change across restarts; the pcache overlay does not perform any consistency checks in this sense. In detail, this option should be disabled unless the existing pcacheAttrset and pcacheTemplate directives are not changed neither in order nor in contents. If new sets and templates are added, or if other details of the pcache overlay configuration changed, this feature should not be affected.

pcacheTemplate <template_string> <attrset_index> <ttl> [<negttl> [<limitttl> [<ttr>]]]

Specifies a cacheable template and "time to live" <ttl> of queries belonging to the template. An optional <negttl> can be used to specify that negative results (i.e., queries that returned zero entries) should also be cached for the specified amount of time. Negative results are not cached by default (<negttl> set to 0). An optional <limitttl> can be used to specify that results hitting a sizelimit should also be cached for the specified amount of time. Results hitting a sizelimit are not cached by default (<limitttl> set to 0). An optional <ttr> "time to refresh" can be used to specify that cached entries should be automatically refreshed after a certain time. Entries will only be refreshed while they have not expired, so the <ttl> should be larger than the <ttr> for this option to be useful. Entries are not refreshed by default (<ttr> set to 0).

pcacheBind <filter_template> <attrset_index> <ttr> <scope> <base>

Specifies a template for caching Simple Bind credentials based on an already defined pcacheTemplate. The <filter_template> is similar to a <template_string> except that it may have some values present. Its purpose is to allow the overlay to generate filters similar to what other applications do when they do a Search immediately before a Bind. E.g., if a client like nss_ldap is configured to search for a user with the filter "(&(objectClass=posixAccount)(uid=<username>))" then the corresponding template "(&(objectClass=posixAccount)(uid=))" should be used here. When converted to a regular template e.g. "(&(objectClass=)(uid=))" this template and the <attrset_index> must match an already defined pcacheTemplate clause. The "time to refresh" <ttr> determines the time interval after which the cached credentials may be refreshed. The first Bind request that occurs after that time will trigger the refresh attempt. Refreshes are not performed when the overlay is Offline. There is no "time to live" parameter for the Bind credentials; the credentials will expire according to the pcacheTemplate ttl. The <scope> and <base> should match the search scope and base used by the authentication clients. The cached credentials are not stored in cleartext, they are hashed using the default password hash. By default Bind caching is not enabled.

pcachePosition { head | tail }

Specifies whether the response callback should be placed at the tail (the default) or at the head (actually, wherever the stacking sequence would make it appear) of the callback list. This affects how the overlay interacts with other overlays, since the proxycache overlay should be executed as early as possible (and thus configured as late as possible), to get a chance to return the cached results; however, if executed early at response, it would cache entries that may be later "massaged" by other databases and thus returned after massaging the first time, and before massaging when cached.

There are some constraints:

all values must be positive;

<entry_limit> must be less than or equal to <max_entries>;

<numattrsets> attribute sets SHOULD be defined by using the directive pcacheAttrset;

all attribute sets SHOULD be referenced by (at least) one pcacheTemplate directive;

The following adds a template with filter string (&(sn=)(givenName=)) and attributes mail, postaladdress, telephonenumber and a TTL of 1 hour.

```
pcacheAttrset 0 mail postaladdress telephonenumber
pcacheTemplate (&(sn=)(givenName=)) 0 3600
```

Directives for configuring the underlying database must also be given, as shown here:

```
directory /var/tmp/cache
cachesize 100
```

Any valid directives for the chosen database type may be used. Indexing should be used as appropriate for the queries being handled. In addition, an equality index on the pcacheQueryid attribute should be configured, to assist in the removal of expired query data.

## BACKWARD COMPATIBILITY
The configuration keywords have been renamed and the older form is deprecated. These older keywords are still recognized but may disappear in future releases.

proxycache

use pcache

proxyattrset

use pcacheAttrset

proxycachequeries

use pcacheMaxQueries

proxycheckcacheability

use pcacheValidate

proxysavequeries

use pcachePersist

proxytemplate

use pcacheTemplate

response-callback

use pcachePosition

## CAVEATS
Caching data is prone to inconsistencies because updates on the remote server will not be reflected in the response of the cache at least (and at most) for the duration of the pcacheTemplate TTL. These inconsistencies can be minimized by careful use of the TTR.

The remote server should expose the objectClass attribute because the underlying database that actually caches the entries may need it for optimal local processing of the queries.

The proxy server should contain all the schema information required for caching. Significantly, it needs the schema of attributes used in the query templates. If the objectClass attribute is used in a query template, it needs the definition of the objectClasses of the entries it is supposed to cache. It is the responsibility of the proxy administrator to keep the proxy schema lined up with that of the proxied server.

Another potential (and subtle) inconsistency may occur when data is retrieved with different identities and specific per-identity access control is enforced by the remote server. If data was retrieved with an identity that collected only partial results because of access rules enforcement on the remote server, other users with different access privileges on the remote server will get different results from the remote server and from the cache. If those users have higher access privileges on the remote server, they will get from the cache only a subset of the results they would get directly from the remote server; but if they have lower access privileges, they will get from the cache a superset of the results they would get directly from the remote server. Either occurrence may or may not be acceptable, based on the security policy of the cache and of the remote server. It is important to note that in this case the proxy is violating the security of the remote server by disclosing to an identity data that was collected by another identity. For this reason, it is suggested that, when using back-ldap, proxy caching be used in conjunction with the identity assertion feature of slapd-ldap(5) (see the idassert-bind and the idassert-authz statements), so that remote server interrogation occurs with a vanilla identity that has some relatively high search and read access privileges, and the "real" access control is delegated to the proxy's ACLs. Beware that since only the cached fraction of the real datum is available to the cache, it may not be possible to enforce the same access rules that are defined on the remote server. When security is a concern, cached proxy access must be carefully tailored.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5), slapd-ldap(5), slapd-meta(5), slapd-sql(5), slapd(8).

## AUTHOR
Originally implemented by Apurva Kumar as an extension to back-meta; turned into an overlay by Howard Chu.


slapo-ppolicy

title: slapo-ppolicy(5)

summary: Password Policy overlay to slapd

text:
# slapo-ppolicy(5)

## NAME
slapo-ppolicy - Password Policy overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The ppolicy overlay is an implementation of the most recent IETF Password Policy proposal for LDAP. When instantiated, it intercepts, decodes and applies specific password policy controls to overall use of a backend database, changes to user password fields, etc.

The overlay provides a variety of password control mechanisms. They include password aging -- both minimum and maximum ages, password reuse and duplication control, account time-outs, mandatory password resets, acceptable password content, and even grace logins. Different groups of users may be associated with different password policies, and there is no limit to the number of password policies that may be created.

Note that some of the policies do not take effect when the operation is performed with the rootdn identity; all the operations, when performed with any other identity, may be subjected to constraints, like access control. This overlay requires a rootdn to be configured on the database.

Note that the IETF Password Policy proposal for LDAP makes sense when considering a single-valued password attribute, while the userPassword attribute allows multiple values. This implementation enforces a single value for the userPassword attribute, despite its specification.

In addition to supporting the IETF Password Policy, this module can send the Netscape Password validity controls when configured to do so.

## CONFIGURATION
These slapd.conf configuration options apply to the ppolicy overlay. They should appear after the overlay directive.

ppolicy_default <policyDN>

Specify the DN of the pwdPolicy object to use when no specific policy is set on a given user's entry. If there is no specific policy for an entry and no default is given, then no policies will be enforced.

ppolicy_forward_updates

Specify that policy state changes that result from Bind operations (such as recording failures, lockout, etc.) on a consumer should be forwarded to a provider instead of being written directly into the consumer's local database. This setting is only useful on a replication consumer, and also requires the updateref setting and chain overlay to be appropriately configured.

ppolicy_hash_cleartext

Specify that cleartext passwords present in Add and Modify requests should be hashed before being stored in the database. This violates the X.500/LDAP information model, but may be needed to compensate for LDAP clients that don't use the Password Modify extended operation to manage passwords. It is recommended that when this option is used that compare, search, and read access be denied to all directory users.

ppolicy_use_lockout

A client will always receive an LDAP InvalidCredentials response when Binding to a locked account. By default, when a Password Policy control was provided on the Bind request, a Password Policy response will be included with no special error code set. This option changes the Password Policy response to include the AccountLocked error code. Note that sending the AccountLocked error code provides useful information to an attacker; sites that are sensitive to security issues should not enable this option.

ppolicy_send_netscape_controls

If set, ppolicy will send the password policy expired (2.16.840.1.113730.3.4.4) and password policy expiring (2.16.840.1.113730.3.4.5) controls when appropriate. The controls are not sent for bind requests where the Password policy control has already been requested. Default is not to send the controls.

## OBJECT CLASS
The ppolicy overlay depends on the pwdPolicy object class. The definition of that class is as follows:

( 1.3.6.1.4.1.42.2.27.8.2.1

NAME 'pwdPolicy'

AUXILIARY

SUP top

MUST ( pwdAttribute )

MAY (

pwdMinAge $ pwdMaxAge $ pwdInHistory $

pwdCheckQuality $ pwdMinLength $

pwdExpireWarning $ pwdGraceAuthnLimit $

pwdLockout $ pwdLockoutDuration $

pwdMaxFailure $ pwdFailureCountInterval $

pwdMustChange $ pwdAllowUserChange $

pwdSafeModify $ pwdMaxRecordedFailure ) )

This implementation also provides an additional pwdPolicyChecker objectclass, used for password quality checking (see below).

( 1.3.6.1.4.1.4754.2.99.1

NAME 'pwdPolicyChecker'

AUXILIARY

SUP top

MAY ( pwdCheckModule ) )

Every account that should be subject to password policy control should have a pwdPolicySubentry attribute containing the DN of a valid pwdPolicy entry, or they can simply use the configured default. In this way different users may be managed according to different policies.

## OBJECT CLASS ATTRIBUTES
Each one of the sections below details the meaning and use of a particular attribute of this pwdPolicy object class.

pwdAttribute

This attribute contains the name of the attribute to which the password policy is applied. For example, the password policy may be applied to the userPassword attribute.

Note: in this implementation, the only value accepted for pwdAttribute is userPassword .

( 1.3.6.1.4.1.42.2.27.8.1.1

NAME 'pwdAttribute'

EQUALITY objectIdentifierMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.38 )

pwdMinAge

This attribute contains the number of seconds that must elapse between modifications allowed to the password. If this attribute is not present, zero seconds is assumed (i.e. the password may be modified whenever and however often is desired).

( 1.3.6.1.4.1.42.2.27.8.1.2

NAME 'pwdMinAge'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdMaxAge

This attribute contains the number of seconds after which a modified password will expire. If this attribute is not present, or if its value is zero (0), then passwords will not expire.

( 1.3.6.1.4.1.42.2.27.8.1.3

NAME 'pwdMaxAge'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdInHistory

This attribute is used to specify the maximum number of used passwords that will be stored in the pwdHistory attribute. If the pwdInHistory attribute is not present, or if its value is zero (0), used passwords will not be stored in pwdHistory and thus any previously-used password may be reused. No history checking occurs if the password is being modified by the rootdn, although the password is saved in the history.

( 1.3.6.1.4.1.42.2.27.8.1.4

NAME 'pwdInHistory'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdCheckQuality

This attribute indicates if and how password syntax will be checked while a password is being modified or added. If this attribute is not present, or its value is zero (0), no syntax checking will be done. If its value is one (1), the server will check the syntax, and if the server is unable to check the syntax, whether due to a client-side hashed password or some other reason, it will be accepted. If its value is two (2), the server will check the syntax, and if the server is unable to check the syntax it will return an error refusing the password.

( 1.3.6.1.4.1.42.2.27.8.1.5

NAME 'pwdCheckQuality'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdMinLength

When syntax checking is enabled (see also the pwdCheckQuality attribute), this attribute contains the minimum number of characters that will be accepted in a password. If this attribute is not present, minimum password length is not enforced. If the server is unable to check the length of the password, whether due to a client-side hashed password or some other reason, the server will, depending on the value of pwdCheckQuality, either accept the password without checking it (if pwdCheckQuality is zero (0) or one (1)) or refuse it (if pwdCheckQuality is two (2)).

( 1.3.6.1.4.1.42.2.27.8.1.6

NAME 'pwdMinLength'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdExpireWarning

This attribute contains the maximum number of seconds before a password is due to expire that expiration warning messages will be returned to a user who is authenticating to the directory. If this attribute is not present, or if the value is zero (0), no warnings will be sent.

( 1.3.6.1.4.1.42.2.27.8.1.7

NAME 'pwdExpireWarning'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdGraceAuthnLimit

This attribute contains the number of times that an expired password may be used to authenticate a user to the directory. If this attribute is not present or if its value is zero (0), users with expired passwords will not be allowed to authenticate to the directory.

( 1.3.6.1.4.1.42.2.27.8.1.8

NAME 'pwdGraceAuthnLimit'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdLockout

This attribute specifies the action that should be taken by the directory when a user has made a number of failed attempts to authenticate to the directory. If pwdLockout is set (its value is "TRUE"), the user will not be allowed to attempt to authenticate to the directory after there have been a specified number of consecutive failed bind attempts. The maximum number of consecutive failed bind attempts allowed is specified by the pwdMaxFailure attribute. If pwdLockout is not present, or if its value is "FALSE", the password may be used to authenticate no matter how many consecutive failed bind attempts have been made.

( 1.3.6.1.4.1.42.2.27.8.1.9

NAME 'pwdLockout'

EQUALITY booleanMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.7

SINGLE-VALUE )

pwdLockoutDuration

This attribute contains the number of seconds during which the password cannot be used to authenticate the user to the directory due to too many consecutive failed bind attempts. (See also pwdLockout and pwdMaxFailure.) If pwdLockoutDuration is not present, or if its value is zero (0), the password cannot be used to authenticate the user to the directory again until it is reset by an administrator.

( 1.3.6.1.4.1.42.2.27.8.1.10

NAME 'pwdLockoutDuration'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdMaxFailure

This attribute contains the number of consecutive failed bind attempts after which the password may not be used to authenticate a user to the directory. If pwdMaxFailure is not present, or its value is zero (0), then a user will be allowed to continue to attempt to authenticate to the directory, no matter how many consecutive failed bind attempts have occurred with that user's DN. (See also pwdLockout and pwdLockoutDuration.)

( 1.3.6.1.4.1.42.2.27.8.1.11

NAME 'pwdMaxFailure'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdMaxRecordedFailure

This attribute contains the maximum number of failed bind attempts to store in a user's entry. If pwdMaxRecordedFailure is not present, or its value is zero (0), then it defaults to the value of pwdMaxFailure. If that value is also 0, the default is 5.

( 1.3.6.1.4.1.42.2.27.8.1.16

NAME 'pwdMaxRecordedFailure'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdFailureCountInterval

This attribute contains the number of seconds after which old consecutive failed bind attempts are purged from the failure counter, even though no successful authentication has occurred. If pwdFailureCountInterval is not present, or its value is zero (0), the failure counter will only be reset by a successful authentication.

( 1.3.6.1.4.1.42.2.27.8.1.12

NAME 'pwdFailureCountInterval'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdMustChange

This attribute specifies whether users must change their passwords when they first bind to the directory after a password is set or reset by the administrator, or not. If pwdMustChange has a value of "TRUE", users must change their passwords when they first bind to the directory after a password is set or reset by the administrator. If pwdMustChange is not present, or its value is "FALSE", users are not required to change their password upon binding after the administrator sets or resets the password.

( 1.3.6.1.4.1.42.2.27.8.1.13

NAME 'pwdMustChange'

EQUALITY booleanMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.7

SINGLE-VALUE )

pwdAllowUserChange

This attribute specifies whether users are allowed to change their own passwords or not. If pwdAllowUserChange is set to "TRUE", or if the attribute is not present, users will be allowed to change their own passwords. If its value is "FALSE", users will not be allowed to change their own passwords.

Note: this implies that when pwdAllowUserChange is set to "TRUE", users will still be able to change the password of another user, subjected to access control. This restriction only applies to modifications of ones's own password. It should also be noted that pwdAllowUserChange was defined in the specification to provide rough access control to the password attribute in implementations that do not allow fine-grain access control. Since OpenLDAP provides fine-grain access control, the use of this attribute is discouraged; ACLs should be used instead (see slapd.access(5) for details).

( 1.3.6.1.4.1.42.2.27.8.1.14

NAME 'pwdAllowUserChange'

EQUALITY booleanMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.7

SINGLE-VALUE )

pwdSafeModify

This attribute denotes whether the user's existing password must be sent along with their new password when changing a password. If pwdSafeModify is set to "TRUE", the existing password must be sent along with the new password. If the attribute is not present, or its value is "FALSE", the existing password need not be sent along with the new password.

( 1.3.6.1.4.1.42.2.27.8.1.15

NAME 'pwdSafeModify'

EQUALITY booleanMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.7

SINGLE-VALUE )

pwdCheckModule

This attribute names a user-defined loadable module that must instantiate the check_password() function. This function will be called to further check a new password if pwdCheckQuality is set to one (1) or two (2), after all of the built-in password compliance checks have been passed. This function will be called according to this function prototype:

int check_password (char *pPasswd, char **ppErrStr, Entry *pEntry);

The pPasswd parameter contains the clear-text user password, the ppErrStr parameter contains a double pointer that allows the function to return human-readable details about any error it encounters. The optional pEntry parameter, if non-NULL, carries a pointer to the entry whose password is being checked. If ppErrStr is NULL, then funcName must NOT attempt to use it/them. A return value of LDAP_SUCCESS from the called function indicates that the password is ok, any other value indicates that the password is unacceptable. If the password is unacceptable, the server will return an error to the client, and ppErrStr may be used to return a human-readable textual explanation of the error. The error string must be dynamically allocated as it will be free()'d by slapd.

( 1.3.6.1.4.1.4754.1.99.1

NAME 'pwdCheckModule'

EQUALITY caseExactIA5Match

SYNTAX 1.3.6.1.4.1.1466.115.121.1.26

SINGLE-VALUE )

Note: The user-defined loadable module named by pwdCheckModule must be in slapd's standard executable search PATH.

Note: pwdCheckModule is a non-standard extension to the LDAP password policy proposal.

## OPERATIONAL ATTRIBUTES
The operational attributes used by the ppolicy module are stored in the user's entry. Most of these attributes are not intended to be changed directly by users; they are there to track user activity. They have been detailed here so that administrators and users can both understand the workings of the ppolicy module.

Note that the current IETF Password Policy proposal does not define how these operational attributes are expected to behave in a replication environment. In general, authentication attempts on a replica server only affect the copy of the operational attributes on that replica and will not affect any attributes for a user's entry on the provider. Operational attribute changes resulting from authentication attempts on a provider will usually replicate to the replicas (and also overwrite any changes that originated on the replica). These behaviors are not guaranteed and are subject to change when a formal specification emerges.

userPassword

The userPassword attribute is not strictly part of the ppolicy module. It is, however, the attribute that is tracked and controlled by the module. Please refer to the standard OpenLDAP schema for its definition.

pwdPolicySubentry

This attribute refers directly to the pwdPolicy subentry that is to be used for this particular directory user. If pwdPolicySubentry exists, it must contain the DN of a valid pwdPolicy object. If it does not exist, the ppolicy module will enforce the default password policy rules on the user associated with this authenticating DN. If there is no default, or the referenced subentry does not exist, then no policy rules will be enforced.

( 1.3.6.1.4.1.42.2.27.8.1.23

NAME 'pwdPolicySubentry'

DESC 'The pwdPolicy subentry in effect for

this object'

EQUALITY distinguishedNameMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.12

SINGLE-VALUE

NO-USER-MODIFICATION

USAGE directoryOperation)

pwdChangedTime

This attribute denotes the last time that the entry's password was changed. This value is used by the password expiration policy to determine whether the password is too old to be allowed to be used for user authentication. If pwdChangedTime does not exist, the user's password will not expire.

( 1.3.6.1.4.1.42.2.27.8.1.16

NAME 'pwdChangedTime'

DESC 'The time the password was last changed'

SYNTAX 1.3.6.1.4.1.1466.115.121.1.24

EQUALITY generalizedTimeMatch

ORDERING generalizedTimeOrderingMatch

SINGLE-VALUE

NO-USER-MODIFICATION

USAGE directoryOperation)

pwdAccountLockedTime

This attribute contains the time that the user's account was locked. If the account has been locked, the password may no longer be used to authenticate the user to the directory. If pwdAccountLockedTime is set to 000001010000Z, the user's account has been permanently locked and may only be unlocked by an administrator. Note that account locking only takes effect when the pwdLockout password policy attribute is set to "TRUE".

( 1.3.6.1.4.1.42.2.27.8.1.17

NAME 'pwdAccountLockedTime'

DESC 'The time an user account was locked'

SYNTAX 1.3.6.1.4.1.1466.115.121.1.24

EQUALITY generalizedTimeMatch

ORDERING generalizedTimeOrderingMatch

SINGLE-VALUE

NO-USER-MODIFICATION

USAGE directoryOperation)

pwdFailureTime

This attribute contains the timestamps of each of the consecutive authentication failures made upon attempted authentication to this DN (i.e. account). If too many timestamps accumulate here (refer to the pwdMaxFailure password policy attribute for details), and the pwdLockout password policy attribute is set to "TRUE", the account may be locked. (Please also refer to the pwdLockout password policy attribute.) Excess timestamps beyond those allowed by pwdMaxFailure or pwdMaxRecordedFailure may also be purged. If a successful authentication is made to this DN (i.e. to this user account), then pwdFailureTime will be cleansed of entries.

( 1.3.6.1.4.1.42.2.27.8.1.19

NAME 'pwdFailureTime'

DESC 'The timestamps of the last consecutive

authentication failures'

SYNTAX 1.3.6.1.4.1.1466.115.121.1.24

EQUALITY generalizedTimeMatch

ORDERING generalizedTimeOrderingMatch

NO-USER-MODIFICATION

USAGE directoryOperation )

pwdHistory

This attribute contains the history of previously used passwords for this DN (i.e. for this user account). The values of this attribute are stored in string format as follows:

pwdHistory=

time "#" syntaxOID "#" length "#" data

time=

GeneralizedTime as specified in section 3.3.13 of [RFC4517]

syntaxOID = numericoid

This is the string representation of the dotted-decimal OID that defines the syntax used to store the password. numericoid is described in section 1.4 of [RFC4512].

length = NumericString

The number of octets in the data. NumericString is described in section 3.3.23 of [RFC4517].

data =

Octets representing the password in the format specified by syntaxOID.

This format allows the server to store and transmit a history of passwords that have been used. In order for equality matching on the values in this attribute to function properly, the time field is in GMT format.

( 1.3.6.1.4.1.42.2.27.8.1.20

NAME 'pwdHistory'

DESC 'The history of user passwords'

SYNTAX 1.3.6.1.4.1.1466.115.121.1.40

EQUALITY octetStringMatch

NO-USER-MODIFICATION

USAGE directoryOperation)

pwdGraceUseTime This attribute contains the list of timestamps of logins made after the user password in the DN has expired. These post-expiration logins are known as "grace logins". If too many grace logins have been used (please refer to the pwdGraceAuthnLimit password policy attribute), then the DN will no longer be allowed to be used to authenticate the user to the directory until the administrator changes the DN's userPassword attribute.

( 1.3.6.1.4.1.42.2.27.8.1.21

NAME 'pwdGraceUseTime'

DESC 'The timestamps of the grace login once the password has expired'

SYNTAX 1.3.6.1.4.1.1466.115.121.1.24

EQUALITY generalizedTimeMatch

NO-USER-MODIFICATION

USAGE directoryOperation)

pwdReset

This attribute indicates whether the user's password has been reset by the administrator and thus must be changed upon first use of this DN for authentication to the directory. If pwdReset is set to "TRUE", then the password was reset and the user must change it upon first authentication. If the attribute does not exist, or is set to "FALSE", the user need not change their password due to administrative reset.

( 1.3.6.1.4.1.42.2.27.8.1.22

NAME 'pwdReset'

DESC 'The indication that the password has

been reset'

EQUALITY booleanMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.7

SINGLE-VALUE

USAGE directoryOperation)

## EXAMPLES

```
database bdb
suffix dc=example,dc=com
...
overlay ppolicy
ppolicy_default "cn=Standard,ou=Policies,dc=example,dc=com"
```

## SEE ALSO
ldap(3), slapd.conf(5), slapd-config(5), slapo-chain(5).

"OpenLDAP Administrator's Guide" (http://www.OpenLDAP.org/doc/admin/)

IETF LDAP password policy proposal by P. Behera, L. Poitou and J. Sermersheim: documented in IETF document "draft-behera-ldap-password-policy-09.txt".

## BUGS
The LDAP Password Policy specification is not yet an approved standard, and it is still evolving. This code will continue to be in flux until the specification is finalized.

## ACKNOWLEDGEMENTS
This module was written in 2004 by Howard Chu of Symas Corporation with significant input from Neil Dunbar and Kartik Subbarao of Hewlett-Packard.

This manual page borrows heavily and shamelessly from the specification upon which the password policy module it describes is based. This source is the IETF LDAP password policy proposal by P. Behera, L. Poitou and J. Sermersheim. The proposal is fully documented in the IETF document named draft-behera-ldap-password-policy-09.txt, written in July of 2005.

OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from the University of Michigan LDAP 3.3 Release.


slapo-refint

title: slapo-refint(5)

summary: Referential Integrity overlay to slapd

text:
# slapo-refint(5)

## NAME
slapo-refint - Referential Integrity overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The Referential Integrity overlay can be used with a backend database such as slapd-bdb(5) to maintain the cohesiveness of a schema which utilizes reference attributes.

Integrity is maintained by updating database records which contain the named attributes to match the results of a modrdn or delete operation. For example, if the integrity attribute were configured as manager, deletion of the record "uid=robert,ou=people,dc=example,dc=com" would trigger a search for all other records which have a manager attribute containing that DN. Entries matching that search would have their manager attribute removed. Or, renaming the same record into "uid=george,ou=people,dc=example,dc=com" would trigger a search for all other records which have a manager attribute containing that DN. Entries matching that search would have their manager attribute deleted and replaced by the new DN.

rootdn must be set for the database. refint runs as the rootdn to gain access to make its updates. rootpw is not needed.

## CONFIGURATION
These slapd.conf options apply to the Referential Integrity overlay. They should appear after the overlay directive.

refint_attributes <attribute> [...]

Specify one or more attributes for which integrity will be maintained as described above.

refint_nothing <string>

Specify an arbitrary value to be used as a placeholder when the last value would otherwise be deleted from an attribute. This can be useful in cases where the schema requires the existence of an attribute for which referential integrity is enforced. The attempted deletion of a required attribute will otherwise result in an Object Class Violation, causing the request to fail. The string must be a valid DN.

refint_modifiersname <DN>

Specify the DN to be used as the modifiersName of the internal modifications performed by the overlay. It defaults to "cn=Referential Integrity Overlay".

Modifications performed by this overlay are not propagated during replication. This overlay must be configured identically on replication consumers in order to maintain full synchronization with the provider.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5).

## ACKNOWLEDGEMENTS
OpenLDAP Software is developed and maintained by The OpenLDAP Project <http://www.openldap.org/>. OpenLDAP Software is derived from the University of Michigan LDAP 3.3 Release.


slapo-retcode

title: slapo-retcode(5)

summary: return code overlay to slapd

text:
# slapo-retcode(5)

## NAME
slapo-retcode - return code overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The retcode overlay to slapd(8) is useful to test the behavior of clients when server-generated erroneous and/or unusual responses occur, e.g. error codes, referrals, excessive response times and so on.

The error responses are generated according to different strategies.

In the first case, all operations targeted at a specific configurable subtree cause the object related to the request DN to be looked up and checked for return code data: a response code, plus an optional textual message, an optional configurable delay, an optional matched DN field, and, when the response code is "referral", a (list of) referral(s).

Well-known response codes from standard track documents are provided in retcode.conf, which can be included after instantiating the overlay.

In the second case, objects of classes inherited from the errAbsObject, like errObject or errAuxObject, when returned as intermediate responses of a search request, are changed into the response dictated by their content.

A third mode causes objects to be looked up from the underlying database to discover if their class inherits from errABsObject; in that case, their content is used to compute the corresponding response.

The behavior is disabled by using the manageDSAit control (RFC 3296); in that case, the resulting object, either present in the directory or dynamically generated by the overlay, or contained in the request, is handled as usual.

The config directives that are specific to the retcode overlay must be prefixed by retcode-, to avoid conflicts with directives specific to the underlying database or to other stacked overlays. The following specific directives can be used to configure the retcode overlay:

retcode-parent <DN>

This directive defines the parent DN where dynamically generated entries reside. If not defined, the suffix of the database is used.

retcode-item <RDN> <errCode> [op=<oplist>] [text=<message>] [ref=<referral>] [sleeptime=<sec>] [matched=<DN>] [unsolicited=<OID>[:<data>]] [flags=[pre|post-]disconnect[,...]]

A dynamically generated entry, located below retcode-parent. The errCode is the number of the response code; it can be in any format supported by strtol(3). The optional oplist is a list of operations that cause response code generation; if absent, all operations are affected. The matched field is the matched DN that is returned along with the error, while the text field is an optional diagnostics message. The ref field is only allowed for the referral response code. The sleeptime field causes slapd(8) to sleep the specified number of seconds before proceeding with the operation. The unsolicited field can be used to cause the return of an RFC 4511 unsolicited response message; if OID is not "0", an extended response is generated, with the optional data appended. If flags contains disconnect, or pre-disconnect, slapd(8) disconnects abruptly, without notice; post-disconnect causes disconnection right after sending response as appropriate.

retcode-indir

Enables exploitation of in-directory stored errAbsObject. May result in a lot of unnecessary overhead.

retcode-sleep [-]<n>

Defines a sleep time in seconds that is spent before actually handling any operation. If negative, a random time between 0 and the absolute value of the argument is used.

## SCHEMA
The retcode overlay utilizes the "return code" schema described herein. This schema is specifically designed for use with this overlay and is not intended to be used otherwise. It is also noted that the schema described here is a work in progress, and hence subject to change without notice. The schema is loaded automatically by the overlay.

The schema includes a number of object classes and associated attribute types as described below.

The error code:

( 1.3.6.1.4.1.4203.666.11.4.1.1

NAME ( 'errCode' )

DESC 'LDAP error code'

EQUALITY integerMatch

ORDERING integerOrderingMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

The operations that trigger the response code:

( 1.3.6.1.4.1.4203.666.11.4.1.2

NAME ( 'errOp' )

DESC 'Operations the errObject applies to'

EQUALITY caseIgnoreMatch

SUBSTR caseIgnoreSubstringsMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 )

The text message:

( 1.3.6.1.4.1.4203.666.11.4.1.3

NAME ( 'errText' )

DESC 'LDAP error textual description'

EQUALITY caseIgnoreMatch

SUBSTR caseIgnoreSubstringsMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.15

SINGLE-VALUE )

The sleep time before the response is actually returned to the client:

( 1.3.6.1.4.1.4203.666.11.4.1.4

NAME ( 'errSleepTime' )

DESC 'Time to wait before returning the error'

EQUALITY integerMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

The matched DN returned to the client:

( 1.3.6.1.4.1.4203.666.11.4.1.5

NAME ( 'errMatchedDN' )

DESC 'Value to be returned as matched DN'

EQUALITY distinguishedNameMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.12

SINGLE-VALUE )

The OID to be returned as extended response OID in RFC 4511 unsolicited responses ("0" generates a regular response with msgid set to 0):

( 1.3.6.1.4.1.4203.666.11.4.1.6

NAME ( 'errUnsolicitedOID' )

DESC 'OID to be returned within unsolicited response'

EQUALITY objectIdentifierMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.38

SINGLE-VALUE )

The octet string to be returned as extended response data in RFC 4511 unsolicited response:

( 1.3.6.1.4.1.4203.666.11.4.1.7

NAME ( 'errUnsolicitedData' )

DESC 'Data to be returned within unsolicited response'

SYNTAX 1.3.6.1.4.1.1466.115.121.1.40

SINGLE-VALUE )

If TRUE, slapd(8) disconnects abruptly without notice; if FALSE, it disconnects after sending response as appropriate:

( 1.3.6.1.4.1.4203.666.11.4.1.8

NAME ( 'errDisconnect' )

DESC 'Disconnect without notice'

SYNTAX 1.3.6.1.4.1.1466.115.121.1.7

SINGLE-VALUE )

The abstract class that triggers the overlay:

( 1.3.6.1.4.1.4203.666.11.4.3.0

NAME ( 'errAbsObject' )

SUP top ABSTRACT

MUST ( errCode )

MAY ( cn $ description $ errOp $ errText $ errSleepTime

$ errMatchedDN ) )

The standalone structural objectclass for specifically created data:

( 1.3.6.1.4.1.4203.666.11.4.3.1

NAME ( 'errObject' )

SUP errAbsObject STRUCTURAL )

The auxiliary objectclass to alter the behavior of existing objects:

( 1.3.6.1.4.1.4203.666.11.4.3.2

NAME ( 'errAuxObject' )

SUP errAbsObject AUXILIARY )

## EXAMPLE

```
overlay         retcode
retcode-parent  "ou=RetCodes,dc=example,dc=com"
# retcode.conf is found in tests/data/ of the source tree
include         ./retcode.conf
# Wait 10 seconds, then return success (0x00)
retcode-item    "cn=Success after 10 seconds" 0x00 sleeptime=10
# Wait 10 seconds, then return timelimitExceeded (0x03)
retcode-item    "cn=Timelimit after 10 seconds" 0x03 sleeptime=10
```

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5), slapd(8). The slapo-retcode(5) overlay supports dynamic configuration via back-config.

## ACKNOWLEDGEMENTS
This module was written in 2005 by Pierangelo Masarati for SysNet s.n.c.