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-cloak

package: openldap-servers

title: slapo-cloak(5)

summary: Attribute cloak overlay to slapd

text:
# slapo-cloak(5)

## NAME
slapo-cloak - Attribute cloak overlay to slapd

## SYNOPSIS
ETCDIR/slapd.conf

## DESCRIPTION
The cloak overlay to slapd(8) allows the server to hide specific attributes, unless explicitly requested by the client. This improve performance when a client requests all attributes and get a huge binary attribute that is of no interest for it. This behavior is disabled when the manageDSAit control (RFC 3296) is used.

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

overlay cloak

This directive adds the cloak 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 cloak overlay. It may have multiple occurrences, and it must appear after the overlay directive:

cloak-attr <attribute> [<class>]

The value <attribute> is the name of the attribute that will be cloaked. The optional <class> restricts cloaking only to entries of the named <class>.

## EXAMPLE
This example hide the jpegPhoto attribute. Add the following to slapd.conf:

```
    database <database>

    # ...

    overlay cloak

    cloak-attr jpegPhoto
```

and that slapd loads cloak.la, if compiled as a run-time module;

## FILES
ETCDIR/slapd.conf

default slapd configuration file

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

## ACKNOWLEDGEMENTS
This module was originally written in 2008 by Emmanuel Dreyfus.


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. Six types of constraint are currently supported - regex, negregex, size, count, uri, and set. The parameter following the regex or negregex 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 mail negregex ^[[:alnum:]]+@notallowed.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 <alphanumeric string>@mydomain.com or that looks like <alphanumeric string>@notallowed.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-datamorph

title: slapo-datamorph(5)

text:
# slapo-datamorph(5)

## NAME
slapo-datamorph - store enumerated values and fixed size integers

## SYNOPSIS
olcOverlay=datamorph

## DESCRIPTION
The datamorph overlay to slapd(8) allows attributes with a few pre-defined values to be saved more space-efficiently as well as signed or unsigned integer attributes.

The overlay operates on configured attributes that must have their syntax compatible with 1.3.6.1.4.1.4203.666.11.12.1.1, there are three such syntaxes defined by the overlay: 1.3.6.1.4.1.4203.666.11.12.1.2 (Enumerated value), 1.3.6.1.4.1.4203.666.11.12.1.3 (Fixed-size integer), and 1.3.6.1.4.1.4203.666.11.12.1.4 (Fixed-size signed integer).

While transforming the request, if a value for an attribute is not permitted by the configuration, the behaviour depends on the operation:

Search

The affected value assertions in a Search request filter are replaced by a filter returning Undefined .

Compare

Request returns Compare False.

Add, Modify

Requests are rejected with a Constraint Violation.

The supported allowed matching rules for the attribute types above are:

EQUALITY fixedSizeIntegerMatch

Appropriate for syntaxes 1.3.6.1.4.1.4203.666.11.12.1.2 (Enumerated value), and 1.3.6.1.4.1.4203.666.11.12.1.3 (Fixed-size integer).

EQUALITY fixedSizeSignedIntegerMatch

Appropriate for syntax 1.3.6.1.4.1.4203.666.11.12.1.4 (Fixed-size signed integer) only.

ORDERING fixedSizeIntegerOrderingMatch

Appropriate for syntaxes 1.3.6.1.4.1.4203.666.11.12.1.2 (Enumerated value), and 1.3.6.1.4.1.4203.666.11.12.1.3 (Fixed-size integer). Enumerated value attributes are compared according to their stored database value.

ORDERING fixedSizeSignedIntegerOrderingMatch

Appropriate for syntax 1.3.6.1.4.1.4203.666.11.12.1.4 (Fixed-size signed integer) only.

## CONFIGURATION LAYOUT
The overlay has to be instantiated under a database adding an entry of olcOverlay=datamorph with objectClass of olcDatamorphConfig.

The overlay configuration subtree consists of the following levels:

objectClass=olcDatamorphConfig

Main overlay configuration. Created directly under the database configuration entry.

objectClass=olcDatamorphInteger

Specifies a fixed-size integer attribute and must be a child of an entry with objectClass=olcDatamorphConfig. There may be as many such entries as necessary provided they all specify a different attribute in the olcDatamorphAttribute attribute.

objectClass=olcDatamorphEnum

Specifies an enumerated attribute and must be a child of an entry with objectClass=olcDatamorphConfig. There may be as many such entries as necessary provided they all specify a different attribute in the olcDatamorphAttribute attribute.

objectClass=olcDatamorphEnumValue

Specifies a permitted value for the enumerated attribute and its database representation. Must be a child of an entry with objectClass=olcDatamorphEnum. There may be as many such entries as necessary provided they all specify a different value and index in the corresponding fields.

In the case of slapd.conf(5), the attribute definition is delimited by the keyword datamorph to define an integer or enumerated attribute followed by an arbitrary number of datamorph_value lines in the case of an enumerated one. Each new datamorph line starts configuring a new attribute.

## ENUMERATED ATTRIBUTE CONFIGURATION ENTRY
The enumerated attribute entry configuration (olcDatamorphEnum) only has the following option available:

olcDatamorphAttribute: <attribute>

Mandatory attribute, indicates that the named attribute is to be handled by the overlay. The slapd.conf(5) equivalent is datamorph int <attribute>.

The children of this entry then define how the string values map to the database values. They use the objectclass olcDatamorphEnumValue, which asks for the following attributes:

olcDatamorphValue: <value>

A permitted value for the attribute being configured.

olcDatamorphIndex: <0-255>

The corresponding database value.

The slapd.conf(5) equivalent of the above two is datamorph_value <0-255> <value> .

## FIXED-WIDTH INTEGER CONFIGURATION ENTRY
The fixed-width integer configuration entry (olcDatamorphInteger) has the following options available:

olcDatamorphAttribute: <attribute>

Mandatory attribute, indicates that the named attribute is to be handled by the overlay. The slapd.conf(5) equivalent is datamorph int <attribute>.

olcDatamorphIntegerBytes: <1|2|4|8>

Size of the integer as stored in the backend. The slapd.conf(5) equivalent is datamorph_size <1|2|4|8>.

olcDatamorphIntegerSigned: <TRUE|FALSE>

Whether the integer is to be treated as signed. Note that the overlay will not enforce consistency between this option and the attribute's syntax. The slapd.conf(5) equivalent is datamorph_signed <TRUE|FALSE>.

olcDatamorphIntegerLowerBound: <number>

The lowest value that the configured attribute will be allowed to have. This affects all operations where values are mentioned. The slapd.conf(5) equivalent is datamorph_lower_bound <number>.

olcDatamorphIntegerUpperBound: <number>

The highest value that the configured attribute will be allowed to have. This affects all operations where values are mentioned. The slapd.conf(5) equivalent is datamorph_upper_bound <number>.

## EXAMPLE
The following is an example of a configured overlay, substitute $DATABASE for the DN of the database it is attached to and {x} with the desired position of the overlay in the overlay stack.

```
dn: olcOverlay={x}datamorph,$DATABASE
objectClass: olcDatamorphConfig
olcOverlay: datamorph
# to handle attribute 'enumeratedAttribute'
dn: olcDatamorphAttribute=enumeratedAttribute,olcOverlay={x}datamorph,$DATABASE
objectClass: olcDatamorphEnum
# value 'value1' corresponds to 'AQ==' (0x01)
dn: olcDatamorphValue=value1,olcDatamorphAttribute={0}enumeratedAttribute,olcOv

 erlay={x}datamorph,$DATABASE
objectclass: olcDatamorphEnumValue
olcDatamorphIndex: 1
# value 'value11' corresponds to 'Cw==' (0x0B)
dn: olcDatamorphValue=value11,olcDatamorphAttribute={0}enumeratedAttribute,olcO

 verlay={x}datamorph,$DATABASE
objectclass: olcDatamorphEnumValue
olcDatamorphIndex: 11
# handle attribute 'signedInteger' as a 2-byte signed integer with values
# between -20000 and 30000 (inclusive on both sides)
dn: olcDatamorphAttribute=signedInteger,olcOverlay={x}datamorph,$DATABASE
objectclass: olcDatamorphInteger
olcDatamorphIntegerBytes: 2
olcDatamorphIntegerSigned: TRUE
olcDatamorphIntegerLowerBound: -20000
olcDatamorphIntegerUpperBound: 30000
# handle attribute 'shortInteger' as a 1-byte unsigned integer with only values
# 0 and 1 allowed (effectively a true/false)
dn: olcDatamorphAttribute=shortInteger,olcOverlay={x}datamorph,$DATABASE
objectclass: olcDatamorphInteger
olcDatamorphIntegerBytes: 1
olcDatamorphIntegerUpperBound: 1
olcDatamorphIntegerSigned: FALSE
```

The slapd.conf(5) equivalent of the above follows:

```
overlay datamorph
datamorph enum enumeratedAttribute
datamorph_value 1 value1
datamorph_value 11 value11
datamorph int signedInteger
datamorph_size 2
datamorph_signed TRUE
datamorph_lower_bound -20000
datamorph_upper_bound 30000
datamorph int shortInteger
datamorph_size 1
datamorph_signed no
datamorph_upper_bound 1
```

## REPLICATION
Given that there are syntaxes and matching rules provided by the overlay, it should be configured on each replica to guarantee consistency.

## BUGS AND LIMITATIONS
Due to the fact that overlays are not active in the slapcat(8) nor slapadd(8) processes, backups of the database will be made exactly as stored. This means that backups made using ldapsearch(1) cannot be used by slapadd(8) nor can backups made using slapcat(8) be loaded using ldapadd(8).

Value based ACLs that involve values of the transformed attributes are not supported.

The overlay will refuse operations that add or rename entries with any of the configured attributes in their RDN.

No controls are explicitly handled in the overlay, attaching any controls that reference configured attributes might lead to unexpected behaviour and is therefore discouraged.

Increment modification of the configured attributes is not supported either.

If a transformation is configured to be signed yet the attribute's schema uses the unsigned syntax and matching rules, inequality matching will not work as intended and will treat negative numbers as higher than positive numbers.

## FILES
ETCDIR/slapd.conf

default slapd configuration file

ETCDIR/slapd.d

default slapd configuration directory

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

## ACKNOWLEDGEMENTS
This module was developed in 2016 by Ondřej Kuzník for Symas Corp.


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 <time>

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 <time>

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 <time>

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 <time>

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

dds-tolerance <time>

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-deref

title: slapo-deref(5)

summary: Dereference Control overlay to slapd

text:
# slapo-deref(5)

## NAME
slapo-deref - Dereference Control overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

/etc/openldap/slapd.d

## DESCRIPTION
This overlay implements the draft Dereference control. The overlay can be used with any backend or globally for all backends.

## EXAMPLES

```
  database mdb

  ...

  overlay deref
```

Given these entries:

```
  dn: cn=Howard Chu,ou=people,dc=example,dc=org

  objectClass: inetOrgPerson

  cn: Howard Chu

  sn: Chu

  uid: hyc

  dn: cn=Pierangelo Masarati,ou=people,dc=example,dc=org

  objectClass: inetOrgPerson

  cn: Pierangelo Masarati

  sn: Masarati

  uid: ando

  dn: cn=Test Group,ou=groups,dc=example,dc=org

  objectClass: groupOfNames

  cn: Test Group

  member: cn=Howard Chu,ou=people,dc=example,dc=org

  member: cn=Pierangelo Masarati,ou=people,dc=example,dc=org
```

A search could be performed with a Dereference request control value specified as

```
  { member, uid }
```

I.e.,

```
  ldapsearch -x -b dc=example,dc=org -E 'deref=member:uid'
```

and the "cn=Test Group" entry would be returned with the response control value

```
  { { member, cn=Howard Chu,ou=people,dc=example,dc=org,

      { { uid, [hyc] } } },

    { member, cn=Pierangelo Masarati,ou=people,dc=example,dc=org,

      { { uid, [ando] } } } }
```

## 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).

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

IETF LDAP Dereference Control proposal by P. Masarati, H. Chu, in IETF document "draft-masarati-ldap-deref-00.txt".

## AUTHOR
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 mdb

  ...

  overlay dyngroup

  attrpair member memberURL
```

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## BACKWARD COMPATIBILITY
The dyngroup overlay has been reworked with the 2.5 release to use a consistent namespace as with other overlays. As a side-effect the following cn=config parameters are deprecated and will be removed in a future release: olcDGAttrPair is replaced with olcDynGroupAttrPair olcDGConfig is replaced with olcDynGroupConfig

## 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 lists and groups. 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.

For a dynamic list, the values of the attributes listed in the URI are added from the matching entries to the original entry. No recursion is allowed, to avoid potential infinite loops. 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.

For a dynamic group, the DNs of the matching entries are added to a member attribute in the original entry.

All dynamic behavior is disabled when the manageDSAit control (RFC 3296) is used. In that case, the contents of the original 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> [options]

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 remaining options depend on whether a dynamic list or a dynamic group is being configured.

For a dynamic list, the allowed options have the form

[<mapped-ad>:<list-ad> ...]

The mapped-ad can be used to remap attributes obtained through expansion. The list-ad must be one of the attributes returned in the expansion of the URIs in the URL-ad attribute of the dynamic entry. Multiple mapping statements can be used. Note that in order for dynamic lists to be usable in a search filter, the dynamic attributes to be filtered must be explicitly mapped. They can be mapped to themselves if no transformation is required.

For a dynamic group, the allowed options are

<member-ad>[+<memberOf-ad>[@<static-oc>[*]]]

The member-ad is required; 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. If the optional memberOf-ad attribute is also specified, then it will be populated with the DNs of the dynamic groups that an entry is a member of. If the optional static-oc objectClass is also specified, then the memberOf attribute will also be populated with the DNs of the static groups that an entry is a member of. Note that using the same static-oc objectClass in more than one dynamic group configuration is not supported. If the optional * character is also specified, then the member and memberOf values will be populated recursively, for nested groups. Note that currently nesting is only supported for Search operations, not Compares.

dynlist-simple TRUE | FALSE

This option downgrades to the behavior of the OpenLDAP 2.4 dynlist overlay. It disables memberOf processing, nested group support, and filter evaluation of dynamically generated values. The default is FALSE.

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. When using dynamic memberOf in search filters, search access to the entryDN pseudo-attribute is required.

## 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.

The values of the above list can not be evaluated in a search filter. To enable filter evaluation on the dynamic list, the configuration must be changed to explicitly map the dynamic attributes to be filtered. In this case mail is just mapped to itself.

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

    # ...

    database <database>

    # ...

    overlay dynlist

    dynlist-attrset groupOfURLs memberURL mail:mail
```

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
```

This example extends the dynamic group feature to add a dynamic dgMemberOf attribute to all the members of a dynamic group:

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

    # ...

    database <database>

    # ...

    overlay dynlist

    dynlist-attrset groupOfURLs memberURL member+dgMemberOf
```

This example extends the dynamic memberOf feature to add the memberOf attribute to all the members of both static and dynamic groups:

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

    # ...

    database <database>

    # ...

    overlay dynlist

    dynlist-attrset groupOfURLs memberURL member+memberOf@groupOfNames
```

This dynamic memberOf feature can fully replace the functionality of the slapo-memberof(5) overlay.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## BACKWARD COMPATIBILITY
The dynlist overlay has been reworked with the 2.5 release to use a consistent namespace as with other overlays. As a side-effect the following cn=config parameters are deprecated and will be removed in a future release: olcDlAttrSet is replaced with olcDynListAttrSet olcDynamicList is replaced with olcDynListConfig

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

## BUGS
Filtering on dynamic groups may return incomplete results if the search operation uses the pagedResults control.

## 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-homedir

title: slapo-homedir(5)

summary: Home directory provisioning overlay

text:
# slapo-homedir(5)

## NAME
slapo-homedir - Home directory provisioning overlay

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The homedir overlay causes slapd(8) to notice changes involving RFC-2307bis style user-objects and make appropriate changes to the local filesystem. This can be performed on both master and replica systems, so it is possible to perform remote home directory provisioning.

## CONFIGURATION
Both slapd.conf and back-config style configuration is supported.

overlay homedir

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

homedir-skeleton-path <pathname>

olcSkeletonPath: pathname

These options set the path to the skeleton account directory. (Generally, /etc/skel) Files in this directory will be copied into newly created home directories. Copying is recursive and handles symlinks and fifos, but will skip most specials.

homedir-min-uidnumber <user id number>

olcMinimumUidNumber: number

These options configure the minimum userid to use in any home directory attempt. This is a basic safety measure to prevent accidentally using system accounts. See REPLICATION for more flexible options for selecting accounts.

homedir-regexp <regexp> <path>

olcHomedirRegexp: regexp path

These options configure a set of regular expressions to use for matching and optionally remapping incoming homeDirectory attribute values to pathnames on the local filesystem. $number expansion is supported to access values captured in parentheses. For example, to accept any directory starting with home and use it verbatim on the local filesystem:

homedir-regexp ^(/home/[-_/a-z0-9]+)$ $1

To match the same set of directories, but create them instead under exporthome, as is popular on Solaris NFS servers:

homedir-regexp ^(/home/[-_/a-z0-9]+)$ /export$1

homedir-delete-style style

olcHomedirDeleteStyle: style

These options configure how deletes of posixAccount entries or their attributes are handled; valid styles are IGNORE, which does nothing, and DELETE, which immediately performs a recursive delete on the home directory, and ARCHIVE, which archives the home directory contents in a TAR file for later examination. The default is IGNORE. Use with caution. ARCHIVE requires homedir-archive-path to be set, or it functions similar to IGNORE.

homedir-archive-path <pathname>

olcHomedirArchivePath: pathname

These options specify the destination path for TAR files created by the ARCHIVE delete style.

## REPLICATION
The homedir overlay can operate on either master or replica systems with no changes. See slapd.conf(5) or slapd-config(5) for more information on configure syncrepl.

Partial replication (e.g. with filters) is especially useful for providing different provisioning options to different sets of users.

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

```
dn: cn=module{0},cn=config
changetype: modify
add: olcModuleLoad
olcModuleLoad: homedir
dn: olcOverlay=homedir,olcDatabase={1}mdb,cn=config
changetype: add
objectClass: olcOverlayConfig
objectClass: olcHomedirConfig
olcOverlay: homedir
olcSkeletonPath: /etc/skel
olcMinimumUidNumber: 1000
olcHomedirRegexp: ^(/home/[-_/a-z0-9]+)$ /export/$1
olcHomedirDeleteStyle: ARCHIVE
olcHomedirArchivePath: /archive
```

## BUGS
DELETE, MOD, and MODRDN operations that remove the unix attributes when delete style is set to DELETE will recursively delete the (regex modified) home directory from the disk. Please be careful when deleting or changing values.

MOD and MODRDN will correctly respond to homeDirectory changes and perform a non-destructive rename() operation on the filesystem, but this does not correctly retry with a recursive copy when moving between filesystems.

The recursive copy/delete/chown/tar functions are not aware of ACLs, extended attributes, forks, sparse files, or hard links. Block and character device archival is non-portable, but should not be an issue in home directories, hopefully.

Copying and archiving may not support files larger than 2GiB on some architectures. Bare POSIX UStar archives cannot support internal files larger than 8GiB. The current tar generator does not attempt to resolve uid/gid into symbolic names.

No attempt is made to try to mkdir() the parent directories needed for a given home directory or archive path.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

/etc/skel (or similar)

source of new homedir files.

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

## ACKNOWLEDGEMENTS
This module was written in 2009 by Emily Backes for Symas Corporation.


slapo-lastbind

title: slapo-lastbind(5)

summary: lastbind overlay to slapd

text:
# slapo-lastbind(5)

## NAME
slapo-lastbind - lastbind overlay to slapd

## SYNOPSIS
ETCDIR/slapd.conf

## DESCRIPTION
The lastbind overlay to slapd(8) allows recording the timestamp of the last successful bind to entries in the directory, in the authTimestamp attribute. The overlay can be configured to update this timestamp only if it is older than a given value, thus avoiding large numbers of write operations penalizing performance. One sample use for this overlay would be to detect unused accounts.

Now that OpenLDAP has native support for most of this functionality, you should consider storing the value in pwdLastSuccess to better interact with the Behera Password Policy draft 10.

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

overlay lastbind

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

This slapd.conf configuration option is defined for the lastbind overlay. It must appear after the overlay directive:

lastbind-precision <seconds>

The value <seconds> is the number of seconds after which to update the authTimestamp attribute in an entry. If the existing value of authTimestamp is less than <seconds> old, it will not be changed. If this configuration option is omitted, the authTimestamp attribute is updated on each successful bind operation.

lastbind_forward_updates

Specify that updates of the authTimestamp attribute 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.

## EXAMPLE
This example configures the lastbind overlay to store authTimestamp in all entries in a database, with a 1 week precision. Add the following to slapd.conf(5):

```
    database <database>

    # ...

    overlay lastbind

    lastbind-precision 604800
```

slapd must also load lastbind.la, if compiled as a run-time module;

## FILES
ETCDIR/slapd.conf

default slapd configuration file

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

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

The slapo-lastbind(5) overlay supports dynamic configuration via back-config.

## ACKNOWLEDGEMENTS
This module was written in 2009 by Jonathan Clarke. It is loosely derived from the password policy overlay.


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.

Note that the dynlist overlay can also provide this functionality and may be suitable for less demanding environments.

## 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. Note that while this overlay handles renames of individual groups and members, it doesn't handle changes due to subtree renames. For referential integrity on subtree renames the slapo-refint(5) overlay should also be used.

memberof-addcheck {true|FALSE}

This option determines whether the overlay will check newly added entries for membership in any existing groups. This check is useful if populated groups are created in the directory before the entries they reference. The situation often occurs during replication, which may replicate entries in random order. If set to TRUE, every Add operation will search for groups referencing the added entry and populate its memberof attribute with the group DNs. Note that memberof-dangling must be left on its default setting of ignore for this option to work.

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. Consumers must also be configured to exclude the memberof attribute from replication. (See the exattrs option in the consumer configuration.)

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## BACKWARD COMPATIBILITY
The memberof overlay has been reworked with the 2.5 release to use a consistent namespace as with other overlays. As a side-effect the following cn=config parameters are deprecated and will be removed in a future release: olcMemberOf is replaced with olcMemberOfConfig

## SEE ALSO
slapo-dynlist(5), slapo-refint(5), 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-nestgroup

title: slapo-nestgroup(5)

summary: Nested Group overlay to slapd

text:
# slapo-nestgroup(5)

## NAME
slapo-nestgroup - Nested Group overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The nestgroup overlay to slapd(8) supports evaluation of nested groups in Search operations. Support consists of four possible features: inclusion of parent groups when searching with (member=) filters, inclusion of child groups when searching with (memberOf=) filters, expansion of child groups when returning member attributes, and expansion of parent groups when returning memberOf attributes. Each of these features may be enabled independently. By default, no features are enabled, so this overlay does nothing unless explicitly enabled.

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

overlay nestgroup

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

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

nestgroup-member <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.

nestgroup-memberof <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. It defaults to memberOf.

nestgroup-base <dn>

The value <dn> specifies a subtree that contains group entries in the DIT. This may be specified multiple times for multiple distinct subtrees. It has no default and the overlay does no processing unless it is explicitly configured.

nestgroup-flags {member-filter, memberof-filter, member-values, memberof-values}

This option specifies which features to enable in the overlay. By default, nothing is enabled and the overlay is a no-op.

The nestgroup overlay may be used with any backend that provides standard search functionality.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

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

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


slapo-otp

title: slapo-otp(5)

summary: OATH One-Time Password module

text:
# slapo-otp(5)

## NAME
slapo-otp - OATH One-Time Password module

## SYNOPSIS
moduleload otp.la

## DESCRIPTION
The otp module allows time-based one-time password, AKA "authenticator-style", and HMAC-based one-time password authentication to be used in conjunction with a standard LDAP password for two-factor authentication.

With this module, users would use their password, followed with the one-time password in the password prompt to authenticate.

The password needed for a user to authenticate is calculated based on a counter (current time in case of TOTP) and a key that is referenced in the user's LDAP entry. Since the password is based on the time or number of uses, it changes periodically. Once used, it cannot be used again so keyloggers and shoulder-surfers are thwarted. A mobile phone application, such as the Google Authenticator or YubiKey (a prover), can be used to calculate the user's current one-time password, which is expressed as a (usually six-digit) number.

Alternatively, the value can be calculated by some other application with access to the user's key and delivered to the user through SMS or some other channel. When prompted to authenticate, the user merely appends the code provided by the prover at the end of their password when authenticating.

This implementation complies with RFC 4226 HOTP HMAC-Based One Time Passwords and RFC 6238 TOTP Time-based One Time Passwords and includes support for the SHA-1, SHA-256, and SHA-512 HMAC algorithms.

The HMAC key used in the OTP computation is stored in the oathOTPToken entry referenced in the user's LDAP entry and the parameters are stored in the oathOTPParams LDAP entry referenced in the token.

## CONFIGURATION
Once the module is configured on the database, it will intercept LDAP simple binds for users whose LDAP entry has any of the oathOTPUser derived objectlasses attached to it. The attributes linking the user and the shared secret are:

oathTOTPToken: <dn>

Mandatory for oathTOTPUser, indicates that the named entry is designated to hold the time-based one-time password shared secret and the last password used.

oathHOTPToken: <dn>

Mandatory for oathHOTPUser, indicates that the named entry is designated to hold the one-time password shared secret and the last password used.

oathTOTPParams: <dn>

Mandatory for oathTOTPToken, indicates that the named entry is designated to hold the parameters to generate time-based one-time password shared secret: its length and algorithm to use as well as the length of each time step and the grace period.

oathHOTPParams: <dn>

Mandatory for oathHOTPToken, indicates that the named entry is designated to hold the parameters to generate one-time password shared secret: its length and algorithm to use as well as the permitted number of passwords to skip.

The following parts of the OATH-LDAP schema are implemented.

General attributes:

oathSecret: <data>

The shared secret is stored here as raw bytes.

oathOTPLength: <length>

The password length, usually 6.

oathHMACAlgorithm: <OID>

The OID of the hash algorithm to use as defined in RFC 8018. Supported algorithms include SHA1, SHA224, SHA256, SHA384 and SHA512.

The HOTP attributes:

oathHOTPLookAhead: <number>

The number of successive HOTP tokens that can be skipped.

oathHOTPCounter: <number>

The order of the last HOTP token successfully redeemed by the user.

The TOTP attributes:

oathTOTPTimeStepPeriod: <seconds>

The length of the time-step period for TOTP calculation.

oathTOTPLastTimeStep: <number>

The order of the last TOTP token successfully redeemed by the user.

oathTOTPTimeStepWindow: <number>

The number of time periods around the current time to try when checking the password provided by the user.

oathTOTPTimeStepDrift: <number>

If the client didn't provide the correct token but it still fit with oathTOTPTimeStepWindow above, this attribute records the current offset to provide for slow clock drift of the client device.

## SEE ALSO
slapd-config(5).

## ACKNOWLEDGEMENT
This work was developed by Ondřej Kuzník and Howard Chu of Symas Corporation for inclusion in OpenLDAP Software.

This work reuses the OATH-LDAP schema developed by Michael Ströder.


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. The "undef" keyword cannot be used with the slapd-mdb(5) backend as it requires all schema elements be fully defined.

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
maxsize   1073741824
```

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 proxy cache overlay requires a full result set of data to properly function. Therefore it will strip out the paged results control if it is requested by the client.

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.