xref: /netbsd-src/external/bsd/openldap/dist/contrib/slapd-modules/variant/slapo-variant.5 (revision e670fd5c413e99c2f6a37901bb21c537fcd322d2) 
 SLAPO-VARIANT 5 "RELEASEDATE" "OpenLDAP"
 Copyright 2016-2017 Symas Corp. All Rights Reserved.
 Copying restrictions apply. See LICENSE.
 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: olcVariantVariantAttribute
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: olcVariantVariantAttribute
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.