Chapter 5. Managing Attributes and Values

Red Hat Directory Server provides several different mechanisms for dynamically and automatically maintaining some types of attributes on directory entries. These plug-ins and configuration options simplify managing directory data and expressing relationships between entries.
Part of the characteristic of entries are their relationships to each other. Obviously, a manager has an employee, so those two entries are related. Groups are associated with their members. There are less apparent relationships, too, like between entries which share a common physical location.
Red Hat Directory Server provides several different ways that these relationships between entries can be maintained smoothly and consistently. There are several plug-ins can apply or generate attributes automatically as part of the data within the directory, including classes of service, linking attributes, and generating unique numeric attribute values.

5.1. Enforcing Attribute Uniqueness

Attribute uniqueness means that the Directory Server requires that all new or edited attributes always have unique values. Attribute uniqueness is enforced through a plug-in. A new instance of the Attribute Uniqueness Plug-in must be created for every attribute for which values must be unique.

5.1.1. Attribute Uniqueness Plug-in Syntax

Configuration information for the Attribute Uniqueness Plug-in is specified in an entry under cn=plugins,cn=config entry. There are two possible syntaxes for nsslapd-pluginarg attributes.

Note

To enforce uniqueness of another attribute than the ones in these example, copy and paste the default Attribute Uniqueness Plug-in entry, and being care to change only the attributes described here.
Use the following syntax to perform the uniqueness check under a suffix or subtree: 
 dn: cn=descriptive_plugin_name,cn=plugins,cn=config
 ...
 nsslapd-pluginEnabled: state    
 nsslapd-pluginarg0: attribute_name    
 nsslapd-pluginarg1: dn1    
 nsslapd-pluginarg2: dn2   
 ...
  • Any value can be given to the cn attribute to name the plug-in. The name should be descriptive.
  • The cn attribute does not contain the name of the attribute which is checked for uniqueness.
  • Only one attribute can be specified on which the uniqueness check will be performed.
  • It is possible to specify several DNs of suffixes or subtrees in which to perform the uniqueness check by incrementing the nsslapd-pluginarg attribute suffix by one each time.
The variable components of the Attribute Uniqueness Plug-in syntax are described in Table 5.1, “Attribute Uniqueness Plug-in Variables”.
Use the following syntax to specify to perform the uniqueness check below an entry containing a specified object class: 
 dn: cn=descriptive_plugin_name,cn=plugins,cn=config
 ...
 nsslapd-pluginEnabled: state      
 nsslapd-pluginarg0: attribute=attribute_name      
 nsslapd-pluginarg1: markerObjectClass=objectclass1      
 nsslapd-pluginarg2: requiredObjectClass=objectclass2     
 ...
  • Any value can be given to the cn attribute to name the plug-in. The name should be descriptive.
  • The cn attribute does not contain the name of the attribute which is checked for uniqueness.
  • Only one attribute can be specified on which the uniqueness check will be performed.
  • If the nsslapd-pluginarg0 attribute begins with attribute=attribute_name, then the server expects the nsslapd-pluginarg1 attribute to include a markerObjectClass value.
The variable components of the attribute uniqueness plug-in syntax are described in Table 5.1, “Attribute Uniqueness Plug-in Variables”.

Table 5.1. Attribute Uniqueness Plug-in Variables

Variable Definition
descriptive_plugin_name Specifies the name of this instance of the Attribute Uniqueness Plug-in. It is not required that the name of the attribute for which to ensure uniqueness be included, but it is advisable. For example, cn=mail uniqueness,cn=plugins,cn=config.
state Defines whether the plug-in is enabled or disabled. Acceptable values are on or off.
attribute_name The name of the attribute for which to ensure unique values. Only one attribute can be named.
dn The DN of the suffix or subtree in which to ensure attribute uniqueness. To specify several suffixes or subtrees, increment the suffix of the nsslapd-pluginarg attribute by one for each additional suffix or subtree.
attribute= attribute_name The name of the attribute for which to ensure unique values. Only one attribute can be named.
markerObjectClass= objectclass1 Attribute uniqueness will be checked under the entry belonging to the DN of the updated entry that has the object class specified in the markerObjectClass keyword. Do not include a space before or after the equals sign.
requiredObjectClass= objectclass2 Optional. When using the markerObjectClass keyword to specify the scope of the uniqueness check instead of a DN, it is also possible to specify to perform the check only if the updated entry contains the objectclass specified in the requiredObjectClass keyword. Do not include a space before or after the equals sign.

5.1.2. Creating an Instance of the Attribute Uniqueness Plug-in

To ensure that a particular attribute in the directory always has unique values, create an instance of the Attribute Uniqueness Plug-in for the attribute to check. For example, to ensure that every entry in the directory that includes a mail attribute has a unique value for that attribute, create a mail uniqueness plug-in.
To create an instance of the Attribute Uniqueness Plug-in, modify the Directory Server configuration to add an entry for the new plug-in under the cn=plugins,cn=config entry. The format of the new entry must conform to the syntax described in Section 5.1.1, “Attribute Uniqueness Plug-in Syntax”.

Note

Red Hat strongly encourages you to copy and paste an existing Attribute Uniqueness Plug-in entry and only modify the attributes listed below.
For example, to create an instance the Attribute Uniqueness Plug-in for the mail attribute:
  1. Stop the Directory Server. Changes to the dse.ldif file are not saved if it is edited while the server is running. 
    service dirsrv stop instance_name
  2. In the dse.ldif file, locate the entry for the Attribute Uniqueness Plug-in, cn=attribute uniqueness,cn=plugins,cn=config.
  3. Copy the entire entry. The entry ends in an empty line; copy the empty line, too.
  4. Paste the copied Attribute Uniqueness Plug-in entry at the end of the file.
  5. Modify the Attribute Uniqueness Plug-in entry attributes for the new attribute information: 
    dn: cn=mail uniqueness,cn=plugins,cn=config
...
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: mail
nsslapd-pluginarg1: dc=example,dc=com
...
  6. Restart the Directory Server. 
    service dirsrv start instance_name
In this example, the uniqueness check will be performed on every entry in the dc=example,dc=com entry that includes the mail attribute.

5.1.3. Configuring Attribute Uniqueness

This section explains how to use Directory Server Console to view the plug-ins configured for the directory and how to modify the configuration of the Attribute Uniqueness Plug-ins.

5.1.3.1. Configuring Attribute Uniqueness Plug-ins from the Directory Server Console

  1. In the Directory Server Console, select the Configuration tab; then, in the navigation tree, expand the Plug-ins folder, and select the Attribute Uniqueness Plug-in to modify.
    The configuration parameters for the plug-in are displayed in the right pane.
  2. To add a suffix or subtree, click Add, and type a DN in the blank text field.
    To delete a suffix from the list, place the cursor in the text field to delete, and click Delete.
    To avoid using a DN, enter the markerObjectClass keyword. With this syntax, it is possible to click Add again to specify a requiredObjectClass, as described in Section 5.1.1, “Attribute Uniqueness Plug-in Syntax”.

    Note

    Do not add an attribute name to the list. To check the uniqueness of other attributes, create a new instance of the Attribute Uniqueness Plug-in for the attribute to check. For information, see Section 5.1.2, “Creating an Instance of the Attribute Uniqueness Plug-in”.
  3. Click Save.

5.1.3.2. Configuring Attribute Uniqueness Plug-ins from the Command Line

This section provides information about configuring the plug-in from the command line.
5.1.3.2.1. Specifying a Suffix or Subtree
The suffix or subtrees which the plug-in checks to ensure attribute uniqueness are defined using the nsslapd-pluginarg attribute in the entry defining the plug-in.
To specify the subtree or subtrees, use ldapmodify to send LDIF update statements. For example: 
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=mail uniqueness,cn=plugins,cn=config
changetype: modify
add: nsslapd-pluginarg2 nsslapd-pluginarg3
nsslapd-pluginarg2: ou=Engineering,dc=example,dc=com
nsslapd-pluginarg3: ou=Sales,dc=example,dc=com
This example LDIF statement modified the Attribute Uniqueness Plug-in to check the uniqueness of the mail attribute under the subtrees dc=example,dc=com, ou=Engineering,dc=example,dc=com, and ou=Sales,dc=example,dc=com.
Whenever this type of configuration change is made, restart the server. 
service dirsrv restart instance_name
For information on restarting the server, see Section 1.3, “Starting and Stopping Servers”.
5.1.3.2.2. Using the markerObjectClass and requiredObjectClass Keywords
Instead of specifying a suffix or subtree in the configuration of an Attribute Uniqueness Plug-in, perform the check under the entry belonging to the DN of the updated entry that has the object class given in the markerObjectClass keyword.
To specify to perform the uniqueness check under the entry in the DN of the updated entry that contains the organizational unit (ou) object class, copy and paste an existing Attribute Uniqueness Plug-in entry, and change the following attributes: 
ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=mail uniqueness,cn=plugins,cn=config
...
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: attribute=mail
nsslapd-pluginarg1: markerObjectClass=organizationalUnit
...
If the server should not check every entry in the organization unit, limit the scope by setting the check to be performed only if the updated entry contains a specified object class.
For example, if the uniqueness of the mail attribute is checked, it is probably only necessary to perform the check when adding or modifying entries with the person or inetorgperson object class.
Restrict the scope of the check by using the requiredObjectClass keyword, as shown in the following example: 
dn: cn=mail uniqueness,cn=plugins,cn=config
...
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: attribute=mail
nsslapd-pluginarg1: markerObjectClass=organizationalUnit
nsslapd-pluginarg2: requiredObjectClass=person
...
The markerObjectClass or requiredObjectClass keywords cannot be repeated by incrementing the counter in the nsslapd-pluginarg attribute suffix. These keywords can only be used once per Attribute Uniqueness Plug-in instance.

Note

The nsslapd-pluginarg0 attribute always contains the name of the attribute for which to ensure uniqueness.

5.1.4. Attribute Uniqueness Plug-in Syntax Examples

This section contains examples of Attribute Uniqueness Plug-in syntax in the dse.ldif file.

5.1.4.1. Specifying One Attribute and One Subtree

This example configures the plug-in to ensure the uniqueness of the mail attribute under the dc=example,dc=com subtree. 
dn: cn=mail uniqueness,cn=plugins,cn=config
...
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: mail
nsslapd-pluginarg1: dc=example,dc=com
...

5.1.4.2. Specifying One Attribute and Multiple Subtrees

It is possible use a single plug-in instance to check for the uniqueness of an attribute within multiple subtrees, which means that the attribute value must be unique within each subtree but not unique across all subtrees. This example configures the Attribute Uniqueness Plug-in to ensure the uniqueness of the mail attribute for separate subtrees, l=Chicago,dc=example,dc=com and l=Boston,dc=example,dc=com. 
dn: cn=mail uniqueness,cn=plugins,cn=config
...
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: mail
nsslapd-pluginarg1: l=Chicago,dc=example,dc=com
nsslapd-pluginarg2: l=Boston,dc=example,dc=com 
...

Note

The nsslapd-pluginarg0 attribute always contains the name of the attribute for which to ensure uniqueness. All other occurrences of the nsslapd-pluginarg, such as nsslapd-pluginarg1, contain DNs.
With this configuration, the plug-in allows an instance of a value for the mail attribute to exist once under the l=Chicago,dc=example,dc=com subtree and once under the l=Boston,dc=example,dc=com subtree. For example, the following two attribute-value settings are allowed: 
mail=bjensen,l=Chicago,dc=example,dc=com
mail=bjensen,l=Boston,dc=example,dc=com
To ensure that only one instance of a value exists under both subtrees, configure the plug-in to ensure uniqueness for the entire dc=example,dc=com subtree.