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.