xref: /netbsd-src/external/bsd/openldap/dist/contrib/slapd-modules/datamorph/slapo-datamorph.5 (revision e670fd5c413e99c2f6a37901bb21c537fcd322d2) 
 SLAPO-DATAMORPH 5 "RELEASEDATE" "OpenLDAP"
 Copyright 2016-2017 Symas Corp. All Rights Reserved.
 Copying restrictions apply. See LICENSE.
 NAME
slapo-datamorph - store enumerated values and fixed size integers

 SYNOPSIS
olcOverlay=datamorph

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



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



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





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

 Compare Request returns
 Compare  False . 

 Add, Modify Requests are rejected with a
 Constraint  Violation . 


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





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


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


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


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



 CONFIGURATION LAYOUT

The overlay has to be instantiated under a database adding an entry of
 olcOverlay=datamorph with objectClass of
 olcDatamorphConfig. 
The overlay configuration subtree consists of the following levels:




 objectClass=olcDatamorphConfig Main overlay configuration. Created directly under the database
configuration entry.


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


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


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



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


 ENUMERATED ATTRIBUTE CONFIGURATION ENTRY

The enumerated attribute entry configuration
 ( olcDatamorphEnum ) only has the following option available:





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


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





 olcDatamorphValue: <value> A permitted value for the attribute being configured.


 olcDatamorphIndex: <0-255> The corresponding database value.



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

 FIXED-WIDTH INTEGER CONFIGURATION ENTRY

The fixed-width integer configuration entry
 ( olcDatamorphInteger ) has the following options available:





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

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

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

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

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



 EXAMPLE

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


dn: olcOverlay={x}datamorph,$DATABASE
objectClass: olcDatamorphConfig
olcOverlay: datamorph

# to handle attribute 'enumeratedAttribute'
dn: olcDatamorphAttribute=enumeratedAttribute,olcOverlay={x}datamorph,$DATABASE
objectClass: olcDatamorphEnum

# value 'value1' corresponds to 'AQ==' (0x01)
dn: olcDatamorphValue=value1,olcDatamorphAttribute={0}enumeratedAttribute,olcOv
 erlay={x}datamorph,$DATABASE
objectclass: olcDatamorphEnumValue
olcDatamorphIndex: 1

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

# handle attribute 'signedInteger' as a 2-byte signed integer with values
# between -20000 and 30000 (inclusive on both sides)
dn: olcDatamorphAttribute=signedInteger,olcOverlay={x}datamorph,$DATABASE
objectclass: olcDatamorphInteger
olcDatamorphIntegerBytes: 2
olcDatamorphIntegerSigned: TRUE
olcDatamorphIntegerLowerBound: -20000
olcDatamorphIntegerUpperBound: 30000

# handle attribute 'shortInteger' as a 1-byte unsigned integer with only values
# 0 and 1 allowed (effectively a true/false)
dn: olcDatamorphAttribute=shortInteger,olcOverlay={x}datamorph,$DATABASE
objectclass: olcDatamorphInteger
olcDatamorphIntegerBytes: 1
olcDatamorphIntegerUpperBound: 1
olcDatamorphIntegerSigned: FALSE



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


overlay datamorph

datamorph enum enumeratedAttribute
datamorph_value 1 value1
datamorph_value 11 value11

datamorph int signedInteger
datamorph_size 2
datamorph_signed TRUE
datamorph_lower_bound -20000
datamorph_upper_bound 30000

datamorph int shortInteger
datamorph_size 1
datamorph_signed no
datamorph_upper_bound 1




 REPLICATION

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


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

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

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

Increment modification of the configured attributes is not supported either.

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


 FILES

ETCDIR/slapd.conf
default slapd configuration file


ETCDIR/slapd.d
default slapd configuration directory

 SEE ALSO
 slapd-config (5),  slapd.conf (5),  slapd.overlays (5),  slapd (8),  slapcat (8),  slapadd (8) 
 ACKNOWLEDGEMENTS
This module was developed in 2016 by Ondřej Kuzník for Symas Corp.