Sun Java System Directory Server Enterprise Edition 6.0 Administration Guide

Chapter 13 Directory Server Attribute Value Uniqueness

The UID uniqueness plug-in ensures that the value of a given attribute is unique among all entries of the directory or of a subtree. The plug-in stops any operation that tries to add an entry that contains an existing value for the given attribute. The plug-in also stops any operation that adds or modifies the attribute to a value that already exists in the directory.

The UID uniqueness plug-in is disabled by default. When the plug-in is enabled, it ensures the uniqueness of the uid attribute by default. You can create new instances of the plug-in to enforce unique values on other attributes. The UID uniqueness plug-in ensures attribute value uniqueness on a single server.

This chapter covers the following topics:

Overview of Attribute Value Uniqueness

The UID uniqueness plug-in is a pre-operation plug-in. It checks LDAP add, modify, and modify DN operations before the server performs an update of the directory. The plug-in determines whether the operation will cause two entries to have the same attribute value. If so, the server terminates the operation and returns error 19 LDAP_CONSTRAINT_VIOLATION to the client.

You can configure the plug-in to enforce uniqueness in one or more subtrees in the directory or among entries of a specific object class. This configuration determines the set of entries for which unique attribute values is enforced.

You can define several instances of the UID uniqueness plug-in if you want to enforce the uniqueness of other attributes. Define one plug-in instance for each attribute whose value must be unique. You can also have several plug-in instances for the same attribute to enforce “separate” uniqueness in several sets of entries. A given attribute value is allowed only once in each set of subtrees.

When you enable attribute uniqueness on an existing directory, the server does not check for uniqueness among existing entries. Uniqueness is only enforced when an entry is added or when the attribute is added or modified.

By default, the UID uniqueness plug-in is disabled because the plug-in affects multimaster replication. You can enable the UID uniqueness plug-in when using replication, but you should be aware of the behavior described in Using the Uniqueness Plug-In With Replication.

Enforcing Uniqueness of the `uid` and Other Attributes

This section explains how to enable and configure the default uniqueness plug-in for the uid attribute and how to enforce uniqueness of any other attribute.

To Enforce Uniqueness of the `uid` Attribute

This procedure describes how to enable and configure the UID uniqueness plug-in by using the dsconf command. The DN of the plug-in configuration entry is cn=uid uniqueness,cn=plugins,cn=config.

You can use DSCC to perform this task. For information, see Directory Service Control Center Interface and the DSCC online help.

When using DSCC, you must not modify the default UID uniqueness plug-in to enforce uniqueness of another attribute. If you do not want to have a UID uniqueness plug-in, leave the plug-in disabled and create a new plug-in instance for another attribute, as described in To Enforce Uniqueness of Another Attribute.

Enable the plug-in.

$ dsconf enable-plugin -h host -p port "uid uniqueness"

Modify the plug-in arguments according to how you want to specify the subtrees where uniqueness is enforced.
- To specify the base DN of a single subtree, type:
  $ dsconf set-plugin-prop -h host -p port "uid uniqueness" argument:uid argument:subtreeBaseDN
  For example:
  $ dsconf set-plugin-prop -h host1 -p 1389 "uid uniqueness" argument:uid \ argument:dc=People,dc=example,dc=com
- To specify more than one subtree, add more arguments with the full base DN of a subtree as the value of each argument.
  $ dsconf set-plugin-prop -h host -p port "uid uniqueness" argument:uid \ argument:subtreeBaseDN argument:subtreeBaseDN
- To specify subtrees according to the object class of their base entries, set the arguments to the following values. Uniqueness of the uid attribute is enforced in the subtree below every entry with the baseObjectClass. Optionally, you can specify the entryObjectClass in the third argument so that the plug-in only enforces uniqueness in operations that target entries with this object class.
  $ dsconf set-plugin-prop -h host -p port "uid uniqueness" argument:attribute=uid \ argument:markerObjectClass=baseObjectClass argument:entryObjectClass=baseObjectClass

Restart the server for your changes to take effect.

To Enforce Uniqueness of Another Attribute

The UID uniqueness plug-in can be used to enforce the uniqueness of any attribute. You must create a new instance of the plug-in by creating a new entry under cn=plugins,cn=config in the directory.

You cannot use DSCC to perform this task. Use the command line, as described in this procedure.

Create a new plug-in.

$ dsconf create-plugin -h host -p port -H lib-path -F init-func \
 -Y type plugin-name

plugin-name should be a short and descriptive name that includes the name of the attribute. For example, to create a plug-in for the uniqueness of the mail ID attribute, use this command:

$ dsconf create-plugin -h host1 -p 1389 -H /opt/SUNWdsee/ds6/lib/uid-plugin.so \
 -F NSUniqueAttr_Init -Y preoperation "mail uniqueness"

Set the plug-in properties.

$ dsconf set-plugin-prop -h host -p port plugin-name property:value

For example, to set the properties for the mail uniqueness plug-in, :

$ dsconf set-plugin-prop -h host1 -p 1389 "mail uniqueness" \
 desc:"Enforce unique attribute values..." version:6.0 \
 vendor:"Sun Microsystems, Inc." depends-on-type:database

Enable the plug-in.

$ dsconf enable-plugin -h host -p port plugin-name

Specify the plug-in arguments.

These arguments depend on how you want to determine the subtrees where uniqueness is enforced.
- To define one or more subtrees according to their base DN, the first argument must be the name of the attribute that should have unique values. Subsequent arguments are the full DNs of the base entries of the subtrees.
  $ dsconf set-plugin-prop -h host -p port plugin-name argument:attribute-name \ argument:subtreeBaseDN argument:subtreeBaseDN...
- To define subtrees according to the object class of their base entries, the first argument must contain attribute=attribute-name which specifies the name of the attribute that should have unique values. The second argument must be the baseObjectClass that determines the base entry of subtrees where uniqueness is enforced. Optionally, you can specify an entryObjectClass in the third argument so that the plug-in enforces uniqueness only in operations that target entries with this object class.
  $ dsconf set-plugin-prop -h host -p port plugin-name argument:attribute=attribute-name \ argument:markerObjectClass=baseObjectClass argument:requiredObjectClass=entryObjectClass
In all plug-in arguments, no space can appear before or after the = sign.

Restart the server for your changes to take effect.

Using the Uniqueness Plug-In With Replication

The UID uniqueness plug-in does not perform any checking on attribute values when an update is performed as part of a replication operation. This does not affect single-master replication, but the plug-in cannot automatically enforce attribute uniqueness for multimaster replication.

Single-Master Replication Scenario

Because all modifications by client applications are performed on the master replica, the UID uniqueness plug-in should be enabled on the master server. The plug-in should be configured to enforce uniqueness in the replicated suffix. Because the master ensures that the values of the desired attribute are unique, you do not need to enable the plug-in on the consumer server.

Enabling the UID uniqueness plug-in on the consumer of a single master does not interfere with replication or normal server operations. However, it might cause slight performance degradation.

Multimaster Replication Scenario

The UID uniqueness plug-in was not designed for use in a multimaster replication scenario. Because multimaster replication uses a loosely consistent replication model, simultaneously adding the same attribute value on both servers will not be detected, even if the plug-in is enabled on both servers.

However, you can use the UID uniqueness plug-in if the attribute on which you are performing the uniqueness check is a naming attribute, and the uniqueness plug-in is enabled for the same attribute in the same subtrees on all masters.

When these conditions are met, uniqueness conflicts are reported as naming conflicts at replication time. Naming conflicts must be resolved manually. For more information, refer to Solving Common Replication Conflicts.