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.

During password update, an identity with manage access to the userPassword attribute is considered a password administrator where relevant to the IETF Password Policy proposal.

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 supports the SunDS Account Usability control (1.3.6.1.4.1.42.2.27.9.5.8) on search requests and 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.

ppolicy_check_module <path>

Specify the path of a loadable module containing a check_password() function for additional password quality checks. The use of this module is described further below in the description of the pwdPolicyChecker objectclass. Note: The user-defined loadable module must be in slapd's standard executable search PATH, or an absolute path must be provided.

Note: Use of a ppolicy_check_module is a non-standard extension to the LDAP password policy proposal.

## 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 $ pwdMaxLength $

pwdExpireWarning $ pwdGraceAuthnLimit $

pwdGraceExpiry $ pwdLockout $ pwdLockoutDuration $

pwdMaxFailure $ pwdFailureCountInterval $

pwdMustChange $ pwdAllowUserChange $

pwdSafeModify $ pwdMaxRecordedFailure $

pwdMinDelay $ pwdMaxDelay $ pwdMaxIdle ) )

The pwdPolicy class is not structural, and so entries using it require another, structural, object class. The namedPolicy object class is a good choice. namedPolicy requires a cn attribute, suitable as the policy entry's rDN.

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 $ pwdCheckModuleArg $ pwdUseCheckModule ) )

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 length in bytes 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)). If the number of characters should be enforced with regards to a particular encoding, the use of an appropriate ppolicy_check_module is required.

( 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 )

pwdMaxLength

When syntax checking is enabled (see also the pwdCheckQuality attribute), this attribute contains the maximum length in bytes that will be accepted in a password. If this attribute is not present, maximum 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)). If the number of characters should be enforced with regards to a particular encoding, the use of an appropriate ppolicy_check_module is required.

( 1.3.6.1.4.1.42.2.27.8.1.31

NAME 'pwdMaxLength'

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 )

pwdGraceExpiry

This attribute specifies the number of seconds the grace authentications are valid. If this attribute is not present or if the value is zero (0), there is no time limit on the grace authentications.

( 1.3.6.1.4.1.42.2.27.8.1.30

NAME 'pwdGraceExpiry'

EQUALITY integerMatch

ORDERING integerOrderingMatch

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

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 )

pwdMinDelay

This attribute specifies the number of seconds to delay responding to the first failed authentication attempt. If this attribute is not set or is zero (0), no delays will be used. pwdMaxDelay must also be specified if pwdMinDelay is set.

Note that this implementation uses a variable lockout instead of delaying the bind response.

( 1.3.6.1.4.1.42.2.27.8.1.24

NAME 'pwdMinDelay'

EQUALITY integerMatch

ORDERING integerOrderingMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdMaxDelay

This attribute specifies the maximum number of seconds to delay when responding to a failed authentication attempt. The time specified in pwdMinDelay is used as the starting time and is then doubled on each failure until the delay time is greater than or equal to pwdMaxDelay (or a successful authentication occurs, which resets the failure counter). pwdMinDelay must also be specified if pwdMaxDelay is set.

Note that this implementation uses a variable lockout instead of delaying the bind response.

( 1.3.6.1.4.1.42.2.27.8.1.25

NAME 'pwdMaxDelay'

EQUALITY integerMatch

ORDERING integerOrderingMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdMaxIdle

This attribute specifies the number of seconds an account may remain unused before it becomes locked. If this attribute is not set or is zero (0), no check is performed. For this to be enforced, lastbind functionality needs to be enabled on the database, that is olcLastBind is set to TRUE.

( 1.3.6.1.4.1.42.2.27.8.1.26

NAME 'pwdMaxIdle'

EQUALITY integerMatch

ORDERING integerOrderingMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.27

SINGLE-VALUE )

pwdUseCheckModule/pwdCheckModuleArg

The pwdUseCheckModule attribute enables use of a loadable module previously configured with ppolicy_check_module for the current policy. The module 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, struct berval *pErrmsg, Entry *pEntry, struct berval *pArg);

The pPasswd parameter contains the clear-text user password, the pErrmsg parameter points to a struct berval containing space to return human-readable details about any error it encounters. The bv_len field must contain the size of the space provided by the bv_val field. The pEntry parameter is optional, if non-NULL, carries a pointer to the entry whose password is being checked.

The optional pArg parameter points to a struct berval containing the value of pwdCheckModuleArg in the effective password policy, if set, otherwise NULL.

If pErrmsg is NULL, then funcName must NOT attempt to use it. 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 pErrmsg may be used to return a human-readable textual explanation of the error. If the space passed in by the caller is too small, the function may replace it with a dynamically allocated buffer, which will be free()'d by slapd.

The pwdCheckModule attribute is now obsolete and is ignored.

( 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

OBSOLETE

SINGLE-VALUE ) ( 1.3.6.1.4.1.4754.1.99.2

NAME 'pwdCheckModuleArg'

EQUALITY octetStringMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.40

DESC 'Argument to pass to check_password() function'

SINGLE-VALUE )

( 1.3.6.1.4.1.4754.1.99.3

NAME 'pwdUseCheckModule'

EQUALITY booleanMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.7

SINGLE-VALUE )

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

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

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)

pwdStartTime

This attribute specifies the time the entry's password becomes valid for authentication. Authentication attempts made before this time will fail. If this attribute does not exist, then no restriction applies.

( 1.3.6.1.4.1.42.2.27.8.1.27

NAME 'pwdStartTime'

DESC 'The time the password becomes enabled'

EQUALITY generalizedTimeMatch

ORDERING generalizedTimeOrderingMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.24

SINGLE-VALUE

USAGE directoryOperation )

pwdEndTime

This attribute specifies the time the entry's password becomes invalid for authentication. Authentication attempts made after this time will fail, regardless of expiration or grace settings. If this attribute does not exist, then this restriction does not apply.

( 1.3.6.1.4.1.42.2.27.8.1.28

NAME 'pwdEndTime'

DESC 'The time the password becomes disabled'

EQUALITY generalizedTimeMatch

ORDERING generalizedTimeOrderingMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.24

SINGLE-VALUE

USAGE directoryOperation )

Note that pwdStartTime may be set to a time greater than or equal to pwdEndTime; this simply disables the account.

pwdAccountTmpLockoutEnd

This attribute that the user's password has been locked out temporarily according to the pwdMinDelay policy option and when the lockout ends.

( 1.3.6.1.4.1.42.2.27.8.1.33

NAME 'pwdAccountTmpLockoutEnd'

DESC 'Temporary lockout end'

EQUALITY generalizedTimeMatch

ORDERING generalizedTimeOrderingMatch

SYNTAX 1.3.6.1.4.1.1466.115.121.1.24

SINGLE-VALUE

NO-USER-MODIFICATION

USAGE directoryOperation )

## SUNDS ACCOUNT USABILITY CONTROL
If the SunDS Account Usability control is used with a search request, the overlay will attach validity information to each entry provided all of the following are met:

•

There is a password policy that applies to the entry

•

The user has compare access to the entry's password attribute.

•

The configured password attribute is present in the entry

## EXAMPLES

```
database mdb
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-10.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-10.txt, written in August of 2009.

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

package: openldap-servers

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-mdb(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-remoteauth

title: slapo-remoteauth(5)

text:
# slapo-remoteauth(5)

## NAME
slapo-remoteauth - Delegate authentication requests to remote directories, e.g. Active Directory

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The remoteauth overlay to slapd(8) provides passthrough authentication to remote directory servers, e.g. Active Directory, for LDAP simple bind operations. The local LDAP entry referenced in the bind operation is mapped to its counterpart in the remote directory. An LDAP bind operation is performed against the remote directory and results are returned based on those of the remote operation.

A slapd server configured with the remoteauth overlay handles an authentication request based on the presence of userPassword in the local entry. If the userPassword is present, authentication is performed locally, otherwise the remoteauth overlay performs the authentication request to the configured remote directory server.

## CONFIGURATION
The following options can be applied to the remoteauth overlay within the slapd.conf file. All options should follow the overlay remoteauth directive.

overlay remoteauth

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

remoteauth_dn_attribute <dnattr>

Attribute in the local entry that is used to store the bind DN to a remote directory server.

remoteauth_mapping <domain> <hostname|LDAP URI|file:///path/to/list_of_hostnames>

For a non-Windows deployment, a domain can be considered as a collection of one or more hosts to which slapd server authentcates against on behalf of authenticating users. For a given domain name, the mapping specifies the target server(s), e.g., Active Directory domain controller(s), to connect to via LDAP. The second argument can be given either as a hostname, an LDAP URI, or a file containing a list of hostnames/URIs, one per line. The hostnames are tried in sequence until the connection succeeds. This option can be provided more than once to provide mapping information for different domains. For example:

```
    remoteauth_mapping americas file:///path/to/americas.domain.hosts

    remoteauth_mapping asiapacific file:///path/to/asiapacific.domain.hosts

    remoteauth_mapping emea emeadc1.emea.example.com
```

remoteauth_domain_attribute <attr>

Attribute in the local entry that specifies the domain name, any text after "\" or ":" is ignored.

remoteauth_default_domain <default domain>

Default domain.

remoteauth_default_realm <server>

Fallback server to connect to for domains not specified in remoteauth_mapping.

remoteauth_retry_count <num>

Number of connection retries attempted. Default is 3.

remoteauth_store <on|off>

Whether to store the password in the local entry on successful bind. Default is off.

remoteauth_tls [starttls=yes] [tls_cert=<file>] [tls_key=<file>] [tls_cacert=<file>] [tls_cacertdir=<path>] [tls_reqcert=never|allow|try|demand] [tls_reqsan=never|allow|try|demand] [tls_cipher_suite=<ciphers>] [tls_ecname=<names>] [tls_crlcheck=none|peer|all]

Remoteauth specific TLS configuration, see slapd.conf(5) for more details on each of the parameters and defaults.

remoteauth_tls_peerkey_hash <hostname> <hashname>:<base64 of public key hash>

Mapping between remote server hostnames and their public key hashes. Only one mapping per hostname is supported and if any pins are specified, all hosts need to be pinned. If set, pinning is in effect regardless of whether or not certificate name validation is enabled by tls_reqcert.

## EXAMPLE
A typical example configuration of remoteauth overlay for AD is shown below (as a slapd.conf(5) snippet):

```
   database <database>

   #...

   overlay remoteauth

   remoteauth_dn_attribute seeAlso

   remoteauth_domain_attribute associatedDomain

   remoteauth_default_realm americas.example.com

   remoteauth_mapping americas file:///home/ldap/etc/remoteauth.americas

   remoteauth_mapping emea emeadc1.emea.example.com

   remoteauth_tls starttls=yes tls_reqcert=demand tls_cacert=/home/ldap/etc/example-ca.pem

   remoteauth_tls_peerkey_hash ldap.americas.tld sha256:Bxv3MkLoDm6gt/iDfeGNdNNqa5TTpPDdIwvZM/cIgeo=
```

Where seeAlso contains the AD bind DN for the user, associatedDomain contains the Windows Domain Id in the form of <NT-domain-name>:<NT-username> in which anything following, including ":", is ignored.

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

## Copyrights
Copyright 2004-2026 The OpenLDAP Foundation. Portions Copyright 2004-2017 Howard Chu, Symas Corporation. Portions Copyright 2017-2021 Ondřej Kuzník, Symas Corporation. Portions Copyright 2004 Hewlett-Packard Company


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.


slapo-rwm

title: slapo-rwm(5)

summary: rewrite/remap overlay to slapd

text:
# slapo-rwm(5)

## NAME
slapo-rwm - rewrite/remap overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The rwm overlay to slapd(8) performs basic DN/data rewrite and objectClass/attributeType mapping. Its usage is mostly intended to provide virtual views of existing data either remotely, in conjunction with the proxy backend described in slapd-ldap(5), or locally, in conjunction with the relay backend described in slapd-relay(5).

This overlay is experimental.

## MAPPING
An important feature of the rwm overlay is the capability to map objectClasses and attributeTypes from the local set (or a subset of it) to a foreign set, and vice versa. This is accomplished by means of the rwm-map directive.

rwm-map {attribute | objectclass} [<local name> | *] {<foreign name> | *}

Map attributeTypes and objectClasses from the foreign server to different values on the local slapd. The reason is that some attributes might not be part of the local slapd's schema, some attribute names might be different but serve the same purpose, etc. If local or foreign name is `*', the name is preserved. If local name is omitted, the foreign name is removed. Unmapped names are preserved if both local and foreign name are `*', and removed if local name is omitted and foreign name is `*'.

The local objectClasses and attributeTypes must be defined in the local schema; the foreign ones do not have to, but users are encouraged to explicitly define the remote attributeTypes and the objectClasses they intend to map. All in all, when remapping a remote server via back-ldap (slapd-ldap(5)) or back-meta (slapd-meta(5)) their definition can be easily obtained by querying the subschemaSubentry of the remote server; the problem should not exist when remapping a local database. Note, however, that the decision whether to rewrite or not attributeTypes with distinguishedName syntax, requires the knowledge of the attributeType syntax. See the REWRITING section for details.

Note that when mapping DN-valued attributes from local to remote, first the DN is rewritten, and then the attributeType is mapped; while mapping from remote to local, first the attributeType is mapped, and then the DN is rewritten. As such, it is important that the local attributeType is appropriately defined as using the distinguishedName syntax. Also, note that there are DN-related syntaxes (i.e. compound types with a portion that is DN-valued), like nameAndOptionalUID, whose values are currently not rewritten.

If the foreign type of an attribute mapping is not defined on the local server, it might be desirable to have the attribute values normalized after the mapping process. Not normalizing the values can lead to wrong results, when the rwm overlay is used together with e.g. the pcache overlay. This normalization can be enabled by means of the rwm-normalize-mapped-attrs directive.

rwm-normalize-mapped-attrs {yes|no}

Set this to "yes", if the rwm overlay should try to normalize the values of attributes that are mapped from an attribute type that is unknown to the local server. The default value of this setting is "no".

rwm-drop-unrequested-attrs {yes|no}

Set this to "yes", if the rwm overlay should drop attributes that are not explicitly requested by a search operation. When this is set to "no", the rwm overlay will leave all attributes in place, so that subsequent modules can further manipulate them. In any case, unrequested attributes will be omitted from search results by the frontend, when the search entry response package is encoded. The default value of this setting is "yes".

## SUFFIX MASSAGING
A basic feature of the rwm overlay is the capability to perform suffix massaging between a virtual and a real naming context by means of the rwm-suffixmassage directive. This, in conjunction with proxy backends, slapd-ldap(5) and slapd-meta(5), or with the relay backend, slapd-relay(5), allows one to create virtual views of databases. A distinguishing feature of this overlay is that, when instantiated before any database, it can modify the DN of requests before database selection. For this reason, rules that rewrite the empty DN ("") or the subschemaSubentry DN (usually "cn=subschema"), would prevent clients from reading the root DSE or the DSA's schema.

rwm-suffixmassage [<virtual naming context>] <real naming context>

Shortcut to implement naming context rewriting; the trailing part of the DN is rewritten from the virtual to the real naming context in the bindDN, searchDN, searchFilterAttrDN, compareDN, compareAttrDN, addDN, addAttrDN, modifyDN, modifyAttrDN, modrDN, newSuperiorDN, deleteDN, exopPasswdDN, and from the real to the virtual naming context in the searchEntryDN, searchAttrDN and matchedDN rewrite contexts. By default no rewriting occurs for the searchFilter and for the referralAttrDN and referralDN rewrite contexts. If no <virtual naming context> is given, the first suffix of the database is used; this requires the rwm-suffixmassage directive be defined after the database suffix directive. The rwm-suffixmassage directive automatically sets the rwm-rewriteEngine to ON.

See the REWRITING section for details.

## REWRITING
A string is rewritten according to a set of rules, called a `rewrite context'. The rules are based on POSIX (''extended'') regular expressions with substring matching; basic variable substitution and map resolution of substrings is allowed by specific mechanisms detailed in the following. The behavior of pattern matching/substitution can be altered by a set of flags.

```
<rewrite context> ::= <rewrite rule> [...]
<rewrite rule> ::= <pattern> <action> [<flags>]
```

The underlying concept is to build a lightweight rewrite module for the slapd server (initially dedicated to the LDAP backend):

## Passes
An incoming string is matched against a set of rewriteRules. Rules are made of a regex match pattern, a substitution pattern and a set of actions, described by a set of optional flags. In case of match, string rewriting is performed according to the substitution pattern that allows one to refer to substrings matched in the incoming string. The actions, if any, are finally performed. Each rule is executed recursively, unless altered by specific action flags; see "Action Flags" for details. A default limit on the recursion level is set, and can be altered by the rwm-rewriteMaxPasses directive, as detailed in the "Additional Configuration Syntax" section. The substitution pattern allows map resolution of substrings. A map is a generic object that maps a substitution pattern to a value. The flags are divided in "Pattern Matching Flags" and "Action Flags"; the former alter the regex match pattern behavior, while the latter alter the actions that are taken after substitution.

## Pattern Matching Flags
`C'

honors case in matching (default is case insensitive)

`R'

use POSIX ''basic'' regular expressions (default is ''extended'')

`M{n}'

allow no more than n recursive passes for a specific rule; does not alter the max total count of passes, so it can only enforce a stricter limit for a specific rule.

## Action Flags
`:'

apply the rule once only (default is recursive)

`@'

stop applying rules in case of match; the current rule is still applied recursively; combine with `:' to apply the current rule only once and then stop.

`#'

stop current operation if the rule matches, and issue an `unwilling to perform' error.

`G{n}'

jump n rules back and forth (watch for loops!). Note that `G{1}' is implicit in every rule.

`I'

ignores errors in rule; this means, in case of error, e.g. issued by a map, the error is treated as a missed match. The `unwilling to perform' is not overridden.

`U{n}'

uses n as return code if the rule matches; the flag does not alter the recursive behavior of the rule, so, to have it performed only once, it must be used in combination with `:', e.g. `:U{32}' returns the value `32' (indicating noSuchObject) after exactly one execution of the rule, if the pattern matches. As a consequence, its behavior is equivalent to `@', with the return code set to n; or, in other words, `@' is equivalent to `U{0}'. Positive errors are allowed, indicating the related LDAP error codes as specified in RFC4511.

The ordering of the flags can be significant. For instance: `IG{2}' means ignore errors and jump two lines ahead both in case of match and in case of error, while `G{2}I' means ignore errors, but jump two lines ahead only in case of match.

More flags (mainly Action Flags) will be added as needed.

## Pattern Matching
See regex(7) and/or re_format(7).

## Substitution Pattern Syntax
Everything starting with `$' requires substitution;

the only obvious exception is `$$', which is turned into a single `$';

the basic substitution is `$<d>', where `<d>' is a digit; 0 means the whole string, while 1-9 is a submatch, as discussed in regex(7) and/or re_format(7).

a `$' followed by a `{' invokes an advanced substitution. The pattern is:

`$' `{' [ <operator> ] <name> `(' <substitution> `)' `}'

where <name> must be a legal name for the map, i.e.

```
<name> ::= [a-z][a-z0-9]* (case insensitive)
<operator> ::= `>' `|' `&' `&&' `*' `**' `$'
```

and <substitution> must be a legal substitution pattern, with no limits on the nesting level.

The operators are:

>

sub-context invocation; <name> must be a legal, already defined rewrite context name

|

external command invocation; <name> must refer to a legal, already defined command name (NOT IMPLEMENTED YET)

&

variable assignment; <name> defines a variable in the running operation structure which can be dereferenced later; operator & assigns a variable in the rewrite context scope; operator && assigns a variable that scopes the entire session, e.g. its value can be dereferenced later by other rewrite contexts

*

variable dereferencing; <name> must refer to a variable that is defined and assigned for the running operation; operator * dereferences a variable scoping the rewrite context; operator ** dereferences a variable scoping the whole session, e.g. the value is passed across rewrite contexts

$

parameter dereferencing; <name> must refer to an existing parameter; the idea is to make some run-time parameters set by the system available to the rewrite engine, as the client host name, the bind DN if any, constant parameters initialized at config time, and so on; no parameter is currently set by either back-ldap or back-meta, but constant parameters can be defined in the configuration file by using the rewriteParam directive.

Substitution escaping has been delegated to the `$' symbol, which is used instead of `\' in string substitution patterns because `\' is already escaped by slapd's low level parsing routines; as a consequence, regex escaping requires two `\' symbols, e.g. `.*\.foo\.bar' must be written as `.*\\.foo\\.bar'.

## Rewrite Context
A rewrite context is a set of rules which are applied in sequence. The basic idea is to have an application initialize a rewrite engine (think of Apache's mod_rewrite ...) with a set of rewrite contexts; when string rewriting is required, one invokes the appropriate rewrite context with the input string and obtains the newly rewritten one if no errors occur.

Each basic server operation is associated to a rewrite context; they are divided in two main groups: client -> server and server -> client rewriting.

client -> server:

```
(default)            if defined and no specific context

                     is available
bindDN               bind
searchDN             search
searchFilter         search
searchFilterAttrDN   search
compareDN            compare
compareAttrDN        compare AVA
addDN                add
addAttrDN            add AVA (DN portion of "ref" excluded)
modifyDN             modify
modifyAttrDN         modify AVA (DN portion of "ref" excluded)
referralAttrDN       add/modify DN portion of referrals

                     (default to none)
renameDN             modrdn (the old DN)
newSuperiorDN        modrdn (the new parent DN, if any)
newRDN               modrdn (the new relative DN)
deleteDN             delete
exopPasswdDN         password modify extended operation DN
```

server -> client:

```
searchEntryDN        search (only if defined; no default;

                     acts on DN of search entries)
searchAttrDN         search AVA (only if defined; defaults

                     to searchEntryDN; acts on DN-syntax

                     attributes of search results)
matchedDN            all ops (only if applicable; defaults

                     to searchEntryDN)
referralDN           all ops (only if applicable; defaults

                     to none)
```

## Basic Configuration Syntax
All rewrite/remap directives start with the prefix rwm-

rwm-rewriteEngine { on | off }

If `on', the requested rewriting is performed; if `off', no rewriting takes place (an easy way to stop rewriting without altering too much the configuration file).

rwm-rewriteContext <context name> [ alias <aliased context name> ]

<Context name> is the name that identifies the context, i.e. the name used by the application to refer to the set of rules it contains. It is used also to reference sub contexts in string rewriting. A context may alias another one. In this case the alias context contains no rule, and any reference to it will result in accessing the aliased one.

rwm-rewriteRule <regex match pattern> <substitution pattern> [ <flags> ]

Determines how a string can be rewritten if a pattern is matched. Examples are reported below.

## Additional Configuration Syntax
rwm-rewriteMap <map type> <map name> [ <map attrs> ]

Allows one to define a map that transforms substring rewriting into something else. The map is referenced inside the substitution pattern of a rule.

rwm-rewriteParam <param name> <param value>

Sets a value with global scope, that can be dereferenced by the command `${$paramName}'.

rwm-rewriteMaxPasses <number of passes> [<number of passes per rule>]

Sets the maximum number of total rewriting passes that can be performed in a single rewrite operation (to avoid loops). A safe default is set to 100; note that reaching this limit is still treated as a success; recursive invocation of rules is simply interrupted. The count applies to the rewriting operation as a whole, not to any single rule; an optional per-rule limit can be set. This limit is overridden by setting specific per-rule limits with the `M{n}' flag.

## MAPS
Currently, few maps are builtin but additional map types may be registered at runtime.

Supported maps are:

LDAP <URI> [bindwhen=<when>] [version=<version>] [binddn=<DN>] [credentials=<cred>]

The LDAP map expands a value by performing a simple LDAP search. Its configuration is based on a mandatory URI, whose attrs portion must contain exactly one attribute (use entryDN to fetch the DN of an entry). If a multi-valued attribute is used, only the first value is considered. The parameter bindwhen determines when the connection is established. It can take the values now, later, and everytime, respectively indicating that the connection should be created at startup, when required, or any time it is used. In the former two cases, the connection is cached, while in the latter a fresh new one is used all times. This is the default.

The parameters binddn and credentials represent the DN and the password that is used to perform an authenticated simple bind before performing the search operation; if not given, an anonymous connection is used.

The parameter version can be 2 or 3 to indicate the protocol version that must be used. The default is 3.

slapd <URI>

The slapd map expands a value by performing an internal LDAP search. Its configuration is based on a mandatory URI, which must begin with ldap:/// (i.e., it must be an LDAP URI and it must not specify a host). As with the LDAP map, the attrs portion must contain exactly one attribute, and if a multi-valued attribute is used, only the first value is considered.

escape [escape2dn|escape2filter|unescapedn|unescapefilter]...

The escape map makes it possible use DNs or their parts in filter strings and vice versa. It processes a value according to the operations listed in order. Supported operations include:

escape2dn

takes a string and escapes it so it can safely be pasted in a DN

escape2filter

takes a string and escapes it so it can safely be pasted in a filter

unescapedn

takes a string and undoes DN escaping

unescapefilter

takes a string and undoes filter escaping

It is advised that each escape map ends with an escape operation as that is the only safe way to handle arbitrary strings.

## REWRITE CONFIGURATION EXAMPLES

```
# set to `off' to disable rewriting
rwm-rewriteEngine on
# the rules the "suffixmassage" directive implies
rwm-rewriteEngine on
# all dataflow from client to server referring to DNs
rwm-rewriteContext default
rwm-rewriteRule "(.+,)?<virtualnamingcontext>$" "$1<realnamingcontext>" ":"
# empty filter rule
rwm-rewriteContext searchFilter
# all dataflow from server to client
rwm-rewriteContext searchEntryDN
rwm-rewriteRule "(.+,)?<realnamingcontext>$" "$1<virtualnamingcontext>" ":"
rwm-rewriteContext searchAttrDN alias searchEntryDN
rwm-rewriteContext matchedDN alias searchEntryDN
# misc empty rules
rwm-rewriteContext referralAttrDN
rwm-rewriteContext referralDN
# Everything defined here goes into the `default' context.
# This rule changes the naming context of anything sent
# to `dc=home,dc=net' to `dc=OpenLDAP, dc=org'
rwm-rewriteRule "(.+,)?dc=home,[ ]?dc=net$"

            "$1dc=OpenLDAP, dc=org"  ":"
# since a pretty/normalized DN does not include spaces
# after rdn separators, e.g. `,', this rule suffices:
rwm-rewriteRule "(.+,)?dc=home,dc=net$"

            "$1dc=OpenLDAP,dc=org"  ":"
# Start a new context (ends input of the previous one).
# This rule adds blanks between DN parts if not present.
rwm-rewriteContext  addBlanks
rwm-rewriteRule     "(.*),([^ ].*)" "$1, $2"
# This one eats blanks
rwm-rewriteContext  eatBlanks
rwm-rewriteRule     "(.*), (.*)" "$1,$2"
# Here control goes back to the default rewrite
# context; rules are appended to the existing ones.
# anything that gets here is piped into rule `addBlanks'
rwm-rewriteContext  default
rwm-rewriteRule     ".*" "${>addBlanks($0)}" ":"
# Rewrite the search base according to `default' rules.
rwm-rewriteContext  searchDN alias default
# Search results with OpenLDAP DN are rewritten back with
# `dc=home,dc=net' naming context, with spaces eaten.
rwm-rewriteContext  searchEntryDN
rwm-rewriteRule     "(.*[^ ],)?[ ]?dc=OpenLDAP,[ ]?dc=org$"

                "${>eatBlanks($1)}dc=home,dc=net"    ":"
# Transform a DN value such that it can be used in a filter
rwm-rewriteMap escape dn2filter unescapedn escape2filter
# Bind with email instead of full DN: we first need
# an ldap map that turns attributes into a DN (the
# argument used when invoking the map is appended to
# the URI and acts as the filter portion)
rwm-rewriteMap ldap attr2dn "ldap://host/dc=my,dc=org?dn?sub"
# Then we need to detect DN made up of a single email,
# e.g. `mail=someone@example.com'; note that the rule
# in case of match stops rewriting; in case of error,
# it is ignored.  In case we are mapping virtual
# to real naming contexts, we also need to rewrite
# regular DNs, because the definition of a bindDN
# rewrite context overrides the default definition.
#
# While actual email addresses tend not to contain filter
# special characters, the provided Bind DN has no such
# restrictions.
rwm-rewriteContext bindDN
rwm-rewriteRule "^(mail=)([^,]+@[^,]+)$"

                "${attr2dn($1${dn2filter($2)})}" ":@I"
# This is a rather sophisticated example. It massages a
# search filter in case who performs the search has
# administrative privileges.  First we need to keep
# track of the bind DN of the incoming request, which is
# stored in a variable called `binddn' with session scope,
# and left in place to allow regular binding:
rwm-rewriteContext  bindDN
rwm-rewriteRule     ".+" "${&&binddn($0)}$0" ":"
# A search filter containing `uid=' is rewritten only
# if an appropriate DN is bound.
# To do this, in the first rule the bound DN is
# dereferenced, while the filter is decomposed in a
# prefix, in the value of the `uid=<arg>' AVA, and
# in a suffix. A tag `<>' is appended to the DN.
# If the DN refers to an entry in the `ou=admin' subtree,
# the filter is rewritten OR-ing the `uid=<arg>' with
# `cn=<arg>'; otherwise it is left as is. This could be
# useful, for instance, to allow apache's auth_ldap-1.4
# module to authenticate users with both `uid' and
# `cn', but only if the request comes from a possible
# `cn=Web auth,ou=admin,dc=home,dc=net' user.
rwm-rewriteContext searchFilter
rwm-rewriteRule "(.*\\()uid=([a-z0-9_]+)(\\).*)"

  "${**binddn}<>${&prefix($1)}${&arg($2)}${&suffix($3)}"

  ":I"
rwm-rewriteRule "^[^,]+,ou=admin,dc=home,dc=net$"

  "${*prefix}|(uid=${*arg})(cn=${*arg})${*suffix}" ":@I"
rwm-rewriteRule ".*<>$" "${*prefix}uid=${*arg}${*suffix}" ":"
# This example shows how to strip unwanted DN-valued
# attribute values from a search result; the first rule
# matches DN values below "ou=People,dc=example,dc=com";
# in case of match the rewriting exits successfully.
# The second rule matches everything else and causes
# the value to be rejected.
rwm-rewriteContext searchEntryDN
rwm-rewriteRule ".+,ou=People,dc=example,dc=com$" "$0" ":@"
rwm-rewriteRule ".*" "" "#"
```

## MAPPING EXAMPLES
The following directives map the object class `groupOfNames' to the object class `groupOfUniqueNames' and the attribute type `member' to the attribute type `uniqueMember':

```
map objectclass groupOfNames groupOfUniqueNames
map attribute uniqueMember member
```

This presents a limited attribute set from the foreign server:

```
map attribute cn *
map attribute sn *
map attribute manager *
map attribute description *
map attribute *
```

These lines map cn, sn, manager, and description to themselves, and any other attribute gets "removed" from the object before it is sent to the client (or sent up to the LDAP server). This is obviously a simplistic example, but you get the point.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5), slapd-ldap(5), slapd-meta(5), slapd-relay(5), slapd(8), regex(7), re_format(7).

## AUTHOR
Pierangelo Masarati; based on back-ldap rewrite/remap features by Howard Chu, Pierangelo Masarati.


title: slapo-smbk5pwd(5)

text:
# slapo-smbk5pwd(5)

## NAME
slapo-smbk5pwd - Samba & Kerberos password sync overlay to slapd

## SYNOPSIS
ETCDIR/slapd.conf

include <path to>/krb5-kdc.schema

include <path to>/samba.schema

moduleload smbk5pwd.so

...

database mdb

...

overlay smbk5pwd

## DESCRIPTION
The smbk5pwd overlay to slapd(8) overloads the Password Modify Extended Operation (RFC 3062) to update Kerberos keys and Samba password hashes for an LDAP user, as well as updating password change related attributes for Kerberos, Samba and/or UNIX user accounts.

The Samba support is written using the Samba 3.0 LDAP schema; Kerberos support is written for Heimdal using its hdb-ldap backend.

Additionally, a new {K5KEY} password hash mechanism is provided. For krb5KDCEntry objects that have this scheme specifier in their userPassword attribute, Simple Binds will be checked against the Kerberos keys of the entry. No data is needed after the {K5KEY} scheme specifier in the userPassword, it is looked up from the entry directly.

## CONFIGURATION
The smbk5pwd overlay supports the following slapd.conf configuration options, which should appear after the overlay directive:

smbk5pwd-enable <module>

can be used to enable only the desired modules. Legal values for <module> are

krb5

If the user has the krb5KDCEntry objectclass, update the krb5Key and krb5KeyVersionNumber attributes using the new password in the Password Modify operation, provided the Kerberos account is not expired. Exiration is determined by evaluating the krb5ValidEnd attribute.

samba

If the user is a sambaSamAccount object, synchronize the sambaNTPassword to the password entered in the Password Modify operation, and update sambaPwdLastSet accordingly.

shadow

Update the attribute shadowLastChange, if the entry has the objectclass shadowAccount.

By default all modules compiled in are enabled. Setting the config statement restricts the enabled modules to the ones explicitly mentioned.

smbk5pwd-can-change <seconds>

If the samba module is enabled and the user is a sambaSamAccount, update the attribute sambaPwdCanChange to point <seconds> into the future, essentially denying any Samba password change until then. A value of 0 disables this feature.

smbk5pwd-must-change <seconds>

If the samba module is enabled and the user is a sambaSamAccount, update the attribute sambaPwdMustChange to point <seconds> into the future, essentially setting the Samba password expiration time. A value of 0 disables this feature.

Alternatively, the overlay supports table-driven configuration, and thus can be run-time loaded and configured via back-config.

## EXAMPLE
The layout of a slapd.d based, table-driven configuration entry looks like:

```
        # {0}smbk5pwd, {1}mdb, config

        dn: olcOverlay={0}smbk5pwd,olcDatabase={1}mdb,cn=config

        objectClass: olcOverlayConfig

        objectClass: olcSmbK5PwdConfig

        olcOverlay: {0}smbk5pwd

        olcSmbK5PwdEnable: krb5

        olcSmbK5PwdEnable: samba

        olcSmbK5PwdMustChange: 2592000
```

which enables both krb5 and samba modules with a Samba password expiration time of 30 days (= 2592000 seconds).

## SEE ALSO
slapd.conf(5), ldappasswd(1), ldap(3),

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

## ACKNOWLEDGEMENTS
This manual page has been written by Peter Marschall based on the module's README file written by Howard Chu.

OpenLDAP is developed and maintained by The OpenLDAP Project (http://www.openldap.org/). OpenLDAP is derived from University of Michigan LDAP 3.3 Release.


slapo-sssvlv

title: slapo-sssvlv(5)

text:
# slapo-sssvlv(5)

## NAME
slapo-sssvlv - Server Side Sorting and Virtual List View overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
This overlay implements the LDAP Server Side Sorting (RFC2891) control as well as the Virtual List View control. It also replaces the default implementation of the LDAP PagedResults (RFC2696) control, to ensure that it works with Sorting. The overlay can be used with any backend or globally for all backends.

Since a complete result set must be generated in memory before sorting can be performed, processing sort requests can have a large impact on the server's memory use. As such, any connection is limited to having only a limited number of sort requests active at a time. Additional limits may be configured as described below.

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

sssvlv-max <num>

Set the maximum number of concurrent sort requests allowed across all connections. The default is one half of the number of server threads.

sssvlv-maxkeys <num>

Set the maximum number of keys allowed in a sort request. The default is 5.

sssvlv-maxperconn <num>

Set the maximum number of concurrent paged search requests per connection. The default is 5. The number of concurrent requests remains limited by sssvlv-max.

## 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 Virtual List View proposal by D. Boreham, J. Sermersheim, and A. Kashi in IETF document "draft-ietf-ldapext-ldapv3-vlv-09.txt".

## AUTHOR
Howard Chu


slapo-syncprov

title: slapo-syncprov(5)

summary: Sync Provider overlay to slapd

text:
# slapo-syncprov(5)

## NAME
slapo-syncprov - Sync Provider overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The Sync Provider overlay implements the provider-side support for the LDAP Content Synchronization (RFC4533) as well as syncrepl replication support. The overlay can be used with any backend that maintains entryCSN and entryUUID attributes for its entries. It also creates a contextCSN attribute in the root entry of the database.

The contextCSN is updated for every write operation performed against the database. To reduce database contention, the contextCSN is only updated in memory. The value is written to the database on server shutdown and read into memory on startup, and maintained in memory thereafter. Checkpoints may be configured to write the contextCSN into the underlying database to minimize recovery time after an unclean shutdown.

On databases that support inequality indexing, it is highly recommended to set an eq index on the entryCSN attribute when using this overlay.

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

syncprov-checkpoint <ops> <minutes>

After a write operation has succeeded, write the contextCSN to the underlying database if <ops> write operations or more than <minutes> time have passed since the last checkpoint. Checkpointing is disabled by default.

syncprov-sessionlog <ops>

Configures an in-memory session log for recording information about write operations made on the database. The <ops> specifies the number of operations that are recorded in the log. All write operations (except Adds) are recorded in the log. When using the session log, it is helpful to set an eq index on the entryUUID attribute in the underlying database.

syncprov-sessionlog-source <dn>

Should not be set when syncprov-sessionlog is set and vice versa. When accesslog for this database is configured and is logging at this suffix, it can be used as the session log source instead of the in-memory session log mentioned above. This log has the advantage of not starting afresh every time the server is restarted.

syncprov-nopresent TRUE | FALSE

Specify that the Present phase of refreshing should be skipped. This value should only be set TRUE for a syncprov instance on top of a log database (such as one managed by the accesslog overlay). The default is FALSE.

syncprov-reloadhint TRUE | FALSE

Specify that the overlay should honor the reloadHint flag in the Sync Control. It must be set TRUE when using the accesslog overlay for delta-based syncrepl replication support. The default is FALSE.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

## SEE ALSO
slapd.conf(5), slapd-config(5), slapo-accesslog(5). OpenLDAP Administrator's Guide.

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

title: slapo-translucent(5)

summary: Translucent Proxy overlay to slapd

text:
# slapo-translucent(5)

## NAME
slapo-translucent - Translucent Proxy overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The Translucent Proxy overlay can be used with a backend database such as slapd-mdb(5) to create a "translucent proxy". Entries retrieved from a remote LDAP server may have some or all attributes overridden, or new attributes added, by entries in the local database before being presented to the client.

A search operation is first populated with entries from the remote LDAP server, the attributes of which are then overridden with any attributes defined in the local database. Local overrides may be populated with the add, modify , and modrdn operations, the use of which is restricted to the root user.

A compare operation will perform a comparison with attributes defined in the local database record (if any) before any comparison is made with data in the remote database.

## CONFIGURATION
The Translucent Proxy overlay uses a proxied database, typically a (set of) remote LDAP server(s), which is configured with the options shown in slapd-ldap(5), slapd-meta(5) or similar. These slapd.conf options are specific to the Translucent Proxy overlay; they must appear after the overlay directive that instantiates the translucent overlay.

translucent_strict

By default, attempts to delete attributes in either the local or remote databases will be silently ignored. The translucent_strict directive causes these modifications to fail with a Constraint Violation.

translucent_no_glue

This configuration option disables the automatic creation of "glue" records for an add or modrdn operation, such that all parents of an entry added to the local database must be created by hand. Glue records are always created for a modify operation.

translucent_local <attr[,attr...]>

Specify a list of attributes that should be searched for in the local database when used in a search filter. By default, search filters are only handled by the remote database. With this directive, search filters will be split into a local and remote portion, and local attributes will be searched locally.

translucent_remote <attr[,attr...]>

Specify a list of attributes that should be searched for in the remote database when used in a search filter. This directive complements the translucent_local directive. Attributes may be specified as both local and remote if desired.

If neither translucent_local nor translucent_remote are specified, the default behavior is to search the remote database with the complete search filter. If only translucent_local is specified, searches will only be run on the local database. Likewise, if only translucent_remote is specified, searches will only be run on the remote database. In any case, both the local and remote entries corresponding to a search result will be merged before being returned to the client.

translucent_bind_local

Enable looking for locally stored credentials for simple bind when binding to the remote database fails. Disabled by default.

translucent_pwmod_local

Enable RFC 3062 Password Modification extended operation on locally stored credentials. The operation only applies to entries that exist in the remote database. Disabled by default.

## ACCESS CONTROL
Access control is delegated to either the remote DSA(s) or to the local database backend for auth and write operations. It is delegated to the remote DSA(s) and to the frontend for read operations. Local access rules involving data returned by the remote DSA(s) should be designed with care. In fact, entries are returned by the remote DSA(s) only based on the remote fraction of the data, based on the identity the operation is performed as. As a consequence, local rules might only be allowed to see a portion of the remote data.

## CAVEATS
The Translucent Proxy overlay will disable schema checking in the local database, so that an entry consisting of overlay attributes need not adhere to the complete schema.

Because the translucent overlay does not perform any DN rewrites, the local and remote database instances must have the same suffix. Other configurations will probably fail with No Such Object and other errors.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

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


slapo-unique

title: slapo-unique(5)

summary: Attribute Uniqueness overlay to slapd

text:
# slapo-unique(5)

## NAME
slapo-unique - Attribute Uniqueness overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The Attribute Uniqueness overlay can be used with a backend database such as slapd-mdb(5) to enforce the uniqueness of some or all attributes within a scope. This subtree defaults to all objects within the subtree of the database for which the Uniqueness overlay is configured.

Uniqueness is enforced by searching the subtree to ensure that the values of all attributes presented with an add, modify or modrdn operation are unique within the scope. For example, if uniqueness were enforced for the uid attribute, the subtree would be searched for any other records which also have a uid attribute containing the same value. If any are found, the request is rejected.

The search is performed using the rootdn of the database, to avoid issues with ACLs preventing the overlay from seeing all of the relevant data. As such, the database must have a rootdn configured.

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

unique_uri <[strict ][ignore ][serialize ]URI[[ URI...]...]>

Configure the base, attributes, scope, and filter for uniqueness checking. Multiple URIs may be specified within a domain, allowing complex selections of objects. Multiple unique_uri statements or olcUniqueURI attribute values will create independent domains, each with their own independent lists of URIs and ignore/strict settings. Keywords strict, ignore, and serialize have to be enclosed in quotes (") together with the URI when using deprecated slapd.conf configurations.

The LDAP URI syntax is a subset of RFC-4516, and takes the form:

ldap:///[base dn]?[attributes...]?scope[?filter]

The base dn defaults to that of the back-end database. Specified base dns must be within the subtree of the back-end database.

If no attributes are specified, the URI applies to all non-operational attributes.

The scope component is effectively mandatory, because LDAP URIs default to base scope, which is not valid for uniqueness, because groups of one object are always unique. Scopes of sub (for subtree) and one for one-level are valid.

The filter component causes the domain to apply uniqueness constraints only to matching objects. e.g. ldap:///?cn?sub?(sn=e*) would require unique cn attributes for all objects in the subtree of the back-end database whose sn starts with an e.

It is possible to assert uniqueness upon all non-operational attributes except those listed by prepending the keyword ignore If not configured, all non-operational (e.g., system) attributes must be unique. Note that the attributes list of an ignore URI should generally contain the objectClass, dc, ou and o attributes, as these will generally not be unique, nor are they operational attributes.

It is possible to set strict checking for the uniqueness domain by prepending the keyword strict. By default, uniqueness is not enforced for null values. Enabling strict mode extends the concept of uniqueness to include null values, such that only one attribute within a subtree will be allowed to have a null value. Strictness applies to all URIs within a uniqueness domain, but some domains may be strict while others are not.

It is possible to enforce strict serialization of modifications by prepending the keyword serialize. By default, no serialization is performed, so multiple modifications occurring nearly simultaneously may see incomplete uniqueness results. Using serialize will force individual write operations to fully complete before allowing any others to proceed, to ensure that each operation's uniqueness checks are consistent.

It is not possible to set both URIs and legacy slapo-unique configuration parameters simultaneously. In general, the legacy configuration options control pieces of a single unfiltered subtree domain.

unique_base <basedn>

This legacy configuration parameter should be converted to the base dn component of the above unique_uri style of parameter.

unique_ignore <attribute...>

This legacy configuration parameter should be converted to a unique_uri parameter with ignore keyword as described above.

unique_attributes <attribute...>

This legacy configuration parameter should be converted to a unique_uri parameter, as described above.

unique_strict <attribute...>

This legacy configuration parameter should be converted to a strict keyword prepended to a unique_uri parameter, as described above.

## CAVEATS
unique_uri cannot be used with the old-style of configuration, and vice versa. unique_uri can implement everything the older system can do, however.

Typical attributes for the ignore ldap:///... URIs are intentionally not hardcoded into the overlay to allow for maximum flexibility in meeting site-specific requirements.

Replication and operations with the relax control are allowed to bypass this enforcement. It is therefore important that all servers accepting writes have this overlay configured in order to maintain uniqueness in a replicated DIT.

## FILES
/etc/openldap/slapd.conf

default slapd configuration file

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


slapo-valsort

title: slapo-valsort(5)

summary: Value Sorting overlay to slapd

text:
# slapo-valsort(5)

## NAME
slapo-valsort - Value Sorting overlay to slapd

## SYNOPSIS
/etc/openldap/slapd.conf

## DESCRIPTION
The Value Sorting overlay can be used with a backend database to sort the values of specific multi-valued attributes within a subtree. The sorting occurs whenever the attributes are returned in a search response.

Sorting can be specified in ascending or descending order, using either numeric or alphanumeric sort methods. Additionally, a "weighted" sort can be specified, which uses a numeric weight prepended to the attribute values. The weighted sort is always performed in ascending order, but may be combined with the other methods for values that all have equal weights. The weight is specified by prepending an integer weight {<weight>} in front of each value of the attribute for which weighted sorting is desired. This weighting factor is stripped off and not returned in search results unless the valsort control is specified (1.3.6.1.4.1.4203.666.5.14).

The valsort control requires a value consisting of a Sequence that contains a boolean flag. The weighting factor is only returned if the boolean value is TRUE. In lber-encode(3) format, the required value must conform to "{b}" syntax.

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

valsort-attr <attribute> <baseDN> (<sort-method> | weighted [<sort-method>])

Configure a sorting method for the specified attribute in the subtree rooted at baseDN. The sort-method may be one of alpha-ascend, alpha-descend, numeric-ascend, or numeric-descend. If the special weighted method is specified, a secondary sort-method may also be specified. It is an error to specify an alphanumeric sort-method for an attribute with Integer or NumericString syntax, and it is an error to specify a numeric sort-method for an attribute with a syntax other than Integer or NumericString.

## EXAMPLES

```
	database mdb
	suffix dc=example,dc=com
	...
	overlay valsort
	valsort-attr member ou=groups,dc=example,dc=com alpha-ascend
```

To invoke ldapsearch(1) with the valsort control, the control value must be set appropriately. The following octets represent the desired "{b}" encoding:

```
	0x30 0x03 0x01 0x01 0xff
```

The control can be sent from the command-line using the base64 encoding of the value:

```
	ldapsearch -E 1.3.6.1.4.1.4203.666.5.14=::MAMBAf8=
```

## 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. The work was sponsored by Stanford University.


slapo-variant

title: slapo-variant(5)

summary: share values between entries

text:
# slapo-variant(5)

## NAME
slapo-variant - share values between entries

## SYNOPSIS
olcOverlay=variant

## DESCRIPTION
The variant overlay to slapd(8) allows attributes/values to be shared between several entries. In some ways this is similar to slapo-collect(5) with the exception that the source and target attributes can be different.

The overlay operates on configured variant entries which can have several attributes each configured to borrow values from an attribute in the alternate entry.

Two types of variant entries can be configured, regular and regex, where the latter are configured with a regular expression and patterns to locate each alternate entry, with access to the variant DN and first nine submatches captured by the regular expression.

For most purposes (see LIMITATIONS, especially for regex variants), the resulting entry is completely transparent to the operations performed on it, e.g. a modify operation on the variant attribute gets transformed into an operation on the alternate entry+attribute. As such, the usual ACL rules apply, appropriate access to both the variant and alternate entry is checked.

As a special case, Add and Delete operations will not affect the alternate entries. Should an attempt be made to add a configured variant entry with the variant attributes already populated, the operation will be rejected with a Constraint Violation.

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

The overlay configuration subtree consists of the following levels:

objectClass=olcVariantConfig

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

objectClass=olcVariantVariant

Specifies a regular variant entry and must be a child of an entry with objectClass=olcVariantConfig. There may be as many such entries as necessary provided they all specify a different DN in the olcVariantEntry attribute.

objectClass=olcVariantAttribute

Specifies a regular variant attribute together with information where the alternate attribute is stored. Must be a child of an entry with objectClass=olcVariantVariant. There may be as many such entries as necessary provided they all specify a different attribute in olcVariantVariantAttribute.

objectClass=olcVariantRegex

Specifies a regex variant entry and must be a child of an entry with objectClass=olcVariantConfig. There may be as many such entries as necessary provided they all specify a different DN in the olcVariantEntryRegex attribute.

objectClass=olcVariantAttributePattern

Specifies a regex variant attribute together with information where the alternate attribute is stored. Must be a child of an entry with objectClass=olcVariantRegex. There may be as many such entries as necessary provided they all specify a different attribute in olcVariantVariantAttribute.

In the case of slapd.conf(5), the variant definition is delimited by the keyword variantDN followed by an arbitrary number of variantSpec providing the attribute definitions following it. Each new variantDN line starts configuring a new variant.

## OVERLAY CONFIGURATION ENTRY
The top entry (olcVariantConfig) has the following options available:

olcVariantPassReplication: TRUE | FALSE

If set to TRUE, search operations with the SyncReplication control will be passed unchanged so that replication can be unaffected. Defaults to FALSE while unset. The slapd.conf(5) equivalent is passReplication.

## VARIANT CONFIGURATION ENTRY
The regular variant entry configuration (olcVariantVariant) has the following options available:

olcVariantEntry: <dn>

Mandatory attribute, indicates that the named entry is to be treated as a variant entry. The slapd.conf(5) equivalent is variantDN.

name: <reference>

Name of the entry for reference, usually the attribute present in the configuration entry's RDN. There is no slapd.conf(5) equivalent as this has no effect on the overlay operation.

Similarly, the regex variant entry configuration (olcVariantRegex) has these options available:

olcVariantRegex: <regex>

Mandatory attribute, indicates that the entries whose normalised DN matches is to be treated as a regex variant entry. The (POSIX.2) regex can use submatches to capture parts of the DN for later use in locating the alternative entry. The slapd.conf(5) equivalent is variantRegex.

name: <reference>

Name of the entry for reference, usually the attribute present in the configuration entry's RDN. There is no slapd.conf(5) equivalent as this has no effect on the overlay operation.

## CONFIGURATION PRECEDENCE
While several regex variants can match the same entry, only one can apply at a time. The list of the regular variants is checked first. Should none match, the list of regex variants is checked in the order they have been configured using only the first one that matches.

## VARIANT ATTRIBUTE CONFIGURATION ENTRY
The regular variant attribute configuration (olcVariantAttribute) and regex variant attribute configuration (olcVariantAttributePattern) have the following options available:

name: <reference>

Name of the attribute configuration for reference and/or documentation, if present, usually found in the configuration entry's RDN. There is no slapd.conf(5) equivalent as this has no effect on the overlay operation.

olcVariantVariantAttribute: <attr>

Mandatory attribute, indicates that the named attribute is not present in the variant entry but is to be retrieved from the alternate entry.

olcVariantAlternativeAttribute: <attr>

Mandatory attribute, indicates that the values of the named attribute is to be retrieved from the alternate entry for use as the values of the variant attribute. The syntaxes of the corresponding variant and alternate attributes have to match or the configuration will be rejected.

olcVariantAlternativeEntry: <dn>

Attribute mandatory for regular variants, indicates the alternate entry to use when retrieving the attribute from.

olcVariantAlternativeEntryPattern: <pattern>

Attribute mandatory for regex variants, indicates the alternate entry to use when retrieving the attribute from. Substitution patterns ($n) can be used to insert parts of the variant entry's DN. $0 will place the entire variant DN, $1 to $9 can be used to place respective capture patterns from the variant entry.

variantSpec <attr> <attr2> <dn>

slapd.conf(5) only. The equivalent to options above, where <attr> represents the olcVariantVariantAttribute, <attr2> represents the olcVariantAlternativeAttribute and <dn> has the same meaning as the content of olcVariantAlternativeEntry. Has to follow a variantDN line in the overlay's configuration.

variantRegexSpec <attr> <attr2> <pattern>

slapd.conf(5) only. The equivalent to options above, where <attr> represents the olcVariantVariantAttribute, <attr2> represents the olcVariantAlternativeAttribute and <pattern> has the same meaning as the content of olcVariantAlternativeEntryPattern. Has to follow a variantRegex line in the overlay's configuration.

## 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}variant,$DATABASE
objectClass: olcVariantConfig
olcOverlay: variant
# Let replication requests pass through unmodified
olcVariantPassReplication: TRUE
# when an operation considers dc=example,dc=com
dn: name=example,olcOverlay={x}variant,$DATABASE
objectClass: olcVariantVariant
olcVariantEntry: dc=example,dc=com
# share the Headquarters' address as the company address
dn: olcVariantVariantAttribute=postaladdress,name={0}example,olcOverlay={x}variant,$DATABASE
objectClass: olcVariantAttribute
olcVariantVariantAttribute: postaladdress
olcVariantAlternativeAttribute: postaladdress
olcVariantAlternativeEntry: ou=Headquarters,dc=example,dc=com
# populate telephonenumber from CEO's home phone
dn: name=Take phone from CEO entry,name={0}example,olcOverlay={x}variant,$DATABASE
objectClass: olcVariantAttribute
olcVariantVariantAttribute: telephonenumber
olcVariantAlternativeAttribute: homephone
olcVariantAlternativeEntry: cn=John Doe,ou=People,dc=example,dc=com
# Match all entries with example in the DN
#
# It will not match dc=example,dc=com as that's already configured as a regular
# variant
dn: name=example 2,olcOverlay={x}variant,$DATABASE
objectClass: olcVariantRegex
olcVariantEntryRegex: .*example[^,]*,(.*)
dn: olcVariantVariantAttribute=location,name={1}example 2,olcOverlay={x}variant,$DATABASE
objectClass: olcVariantAttributePattern
olcVariantVariantAttribute: location
olcVariantAlternativeAttribute: location
olcVariantAlternativeEntryPattern: ou=object with location,$1
```

The slapd.conf(5) equivalent of the above follows (note that the converted cn=config will differ in the first variant attribute configuration entry):

```
overlay variant
passReplication TRUE
variantDN dc=example,dc=com
variantSpec telephonenumber homephone "cn=John Doe,ou=People,dc=example,dc=com"
variantSpec postaladdress postaladdress ou=Headquarters,dc=example,dc=com
variantRegex .*example[^,]*,(.*)
variantRegexSpec location location "ou=object with location,$1"
```

## REPLICATION
There are two ways that a database with slapo-variant(5) might be replicated, either replicating the data as stored in the database, or as seen by the clients interacting with the server.

The former can be achieved by setting the overlay option olcVariantPassReplication on the provider and configuring slapo-syncprov(5) to appear before (with a lower index than) slapo-variant(5). This is the preferred way and the only to work with regex variants or support multi-provider replication, but care must be taken to configure slapo-variant(5) correctly on each replica.

The latter is mostly possible by keeping the option olcVariantPassReplication set to FALSE on the provider and configuring slapo-syncprov(5) to appear after (with a higher index than) slapo-variant(5). However, it will only really work for replication set-ups that do not utilise regex variants, delta-replication nor the refresh and persist mode and is therefore discouraged.

## LIMITATIONS
For regex variants, the Search operation will only apply if the search scope is set to base.

The ModRDN operation is not currently handled and will always modify only the entry in question, not the configured alternate entry.

The Modify operation is not atomic with respect to the alternate entries. Currently, the overlay processes the operations on the entry, sends the result message and, if successful, starts modifying the alternate entries accordingly. There is currently no support to indicate whether modifications to the alternate entries have been successful or whether they have finished.

The only control explicitly handled is the SyncReplication control if enabled through the olcVariantPassReplication setting, adding any controls to an operation that is handled by the overlay might lead to unexpected behaviour and is therefore discouraged.

## 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), regex(7), slapd(8)

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