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:

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:

VARIANT CONFIGURATION ENTRY¶

The regular variant entry configuration (olcVariantVariant) has the following options available:

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

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:

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.