Netscape Directory Server Administrator's Guide: Chapter 17Using the Attribute Uniqueness Plug-In

Administrator's Guide
Netscape Directory Server

Chapter 17 Using the Attribute Uniqueness Plug-In

The attribute uniqueness plug-in can be used to ensure that the attributes you specify always have unique values in the directory. You must create a new instance of the plug-in for every attribute for which you want to ensure unique values.

Netscape Directory Server (Directory Server), provides a uid uniqueness plug-in that can be used to manage the uniqueness of the uid attribute.

This chapter describes the attribute uniqueness plug-in and the uid uniqueness plug-in in the following sections:

Overview of the Attribute Uniqueness Plug-In

Overview of the UID Uniqueness Plug-in

Attribute Uniqueness Plug-In Syntax

Creating an Instance of the Attribute Uniqueness Plug-In

Configuring Attribute Uniqueness Plug-Ins

Attribute Uniqueness Plug-In Syntax Examples

Replication and the Attribute Uniqueness Plug-In

Overview of the Attribute Uniqueness Plug-In

The attribute uniqueness plug-in is a preoperation plug-in. This means that the plug-in checks all update operations before the server performs an LDAP operation. The plug-in determines whether the operation applies to an attribute and a suffix that you have configured it to monitor.

If an update operation applies to an attribute and suffix monitored by the plug-in, and it would cause two entries to have the same attribute value, then the server terminates the operation and returns an LDAP_CONSTRAINT_VIOLATION error to the client.

The attribute uniqueness plug-in performs a check on:

A single attribute

One or several subtrees

If you want to check uniqueness of several attributes, you must create a separate instance of the plug-in for each attribute you want to check.

You can also configure how the attribute uniqueness plug-in operates:

It can check every entry in the subtrees you specify.

For example, if your company, example.com, hosts the directories for example_a.com and example_b.com, when you add an entry such as uid=jdoe,ou=people,o=example_a,dc=example,dc=com, you need to enforce uniqueness only in the o=example_a,dc=example,dc=com subtree. You can do this by listing the DN of the subtree explicitly in the uid uniqueness plug-in configuration.

This configuration option is explained in more detail in "Specifying a Suffix or Subtree".

You can specify an object class pertaining to an entry in the DN of the updated entry, and perform the uniqueness check on all the entries beneath it.

This option is useful in hosted environments. For example, when you add an entry such as uid=jdoe,ou=people,o=example_a,dc=example,dc=com, you can enforce uniqueness under the o=example_a,dc=example,dc=com subtree without listing this subtree explicitly in the configuration, but instead, by indicating a marker object class. If you specify that the marker object class is organization, the uniqueness check algorithm locates the entry in the DN that has this object class (o=example_a) and performs the check on all entries beneath it.

Additionally, you can specify to check uniqueness only if the updated entry includes a specified object class. For example, you could specify to perform the check only if the updated entry includes objectclass=inetorgperson.

This configuration option is explained in more detail in "Using the markerObjectClass and requiredObjectClass Keywords".

If you intend to use the attribute uniqueness plug-in in a replicated environment, refer to "Replication and the Attribute Uniqueness Plug-In".

Overview of the UID Uniqueness Plug-in

Directory Server provides an instance of the attribute uniqueness plug-in, the Uid Uniqueness plug-in. By default, the plug-in ensures that values given to the uid attribute are unique in the suffix you configured when installing the directory (the suffix corresponding to the userRoot database).

You can change the configuration to specify additional suffixes or subtrees, or by specifying to only perform the check under entries that contain a specified object class. The syntax and configuration of the uid uniqueness plug-in is the same as for any other attribute. For more information on the configuration changes you can make, see "Configuring Attribute Uniqueness Plug-Ins".

By default, the Uid Uniqueness plug-in is disabled because it affects the operation of multi-master replication. For information on using the attribute uniqueness plug-in in a replicated environment, refer to "Replication and the Attribute Uniqueness Plug-In".

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. The differences are highlighted in the sections below.

Use the following syntax to perform the uniqueness check under a suffix or subtree:

dn: cn=descriptive_plugin_name,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: descriptive_plugin_namee
nsslapd-pluginPath: /usr/netscape/servers/lib/uid-plugin.extension
nsslapd-pluginInitfunc: NSUniqueAttr_Init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: state
nsslapd-pluginarg0: attribute_name
nsslapd-pluginarg1: dn1
[ nsslapd-pluginarg2: dn2 ]
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: NSUniqueAttr
nsslapd-pluginVersion: 6.1
nsslapd-pluginVendor: Netscape Communications Corporation
nsslapd-pluginDescription: Enforce unique attribute values
Notes:

You can specify any name you like in the cn attribute to name the plug-in. The name should be descriptive. This attribute does not contain the name of the attribute which is checked for uniqueness.

You can specify only one attribute on which the uniqueness check will be performed.

You can specify several DNs of suffixes or subtrees in which you want to perform the uniqueness check by incrementing the nsslapd-pluginarg attribute suffix by 1 each time.

The variable components of the attribute uniqueness plug-in syntax are described in Table 17-1.

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
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: descriptive_plugin_name
nsslapd-pluginPath: /usr/netscape/servers/lib/uid-plugin.extension
nsslapd-pluginInitfunc: NSUniqueAttr_Init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: state
nsslapd-pluginarg0: attribute=attribute_name
nsslapd-pluginarg1: markerObjectClass=objectclass1
[ nsslapd-pluginarg2: requiredObjectClass=objectclass2 ]
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: NSUniqueAttr
nsslapd-pluginVersion: 6.1
nsslapd-pluginVendor: Netscape Communications Corporation
nsslapd-pluginDescription: Enforce unique attribute values
Notes:

You can specify any name you like in the cn attribute to name the plug-in. The name should be descriptive. This attribute does not contain the name of the attribute which is checked for uniqueness.

You can specify only one attribute on which the uniqueness check will be performed.

If the nsslapd-pluginarg0 attribute begins with attribute= attribute_name, then the server expects that the nsslapd-pluginarg1 attribute will include a markerObjectClass.

The variable components of the attribute uniqueness plug-in syntax are described in Table 17-1.

Table 17-1    Attribute Uniqueness Plug-In Variables

Variable

Definition

descriptive_plugin_name

Specifies the name of this instance of the attribute uniqueness plug-in. You do not have to include the name of the attribute for which you want to ensure uniqueness, but it is advisable. For example cn=mail uniqueness,cn=plugins,cn=config.

extension

File extension for the plug-in. The extension is always .sl on HP-UX, .so on all other UNIX platforms, and .dll on Windows.

state

Defines whether the plug-in is enabled or disabled. Acceptable values are on or off . See "Turning the Plug-in On or Off" for more information.

attribute_name

The name of the attribute for which you want to ensure unique values. You can specify one attribute name only.

dn

The DN of the suffix or subtree in which you want to ensure attribute uniqueness. You can specify several suffixes or subtrees by incrementing the suffix of the nsslapd-pluginarg attribute by 1 for each additional suffix or subtree.

attribute=attribute_name

The name of the attribute for which you want to ensure unique values. You can specify one attribute name only.

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 you use the markerObjectClass keyword to specify the scope of the uniqueness check instead of a DN, you can optionally 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.

Creating an Instance of the Attribute Uniqueness Plug-In

If you want to ensure that a particular attribute in your directory always has unique values, you must create an instance of the attribute uniqueness plug-in for the attribute you want to check. For example, if you want to ensure that every entry in your directory that includes a mail attribute has a unique value for that attribute, you must create a mail uniqueness plug-in.

To create an instance of the attribute uniqueness plug-in, you must modify the dse.ldif file 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 "Attribute Uniqueness Plug-In Syntax".

For example, to instantiate the attribute uniqueness plug-in for the mail attribute, you would perform the following steps:

In the dse.ldif file, locate the entry for the uid uniqueness plug-in, cn=uid uniqueness,cn=plugins,cn=config.

Add the following lines for the mail uniqueness plug-in entry before or after the uid uniqueness plug-in entry:

dn: cn=mail uniqueness,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: mail uniqueness
nsslapd-pluginPath: /usr/netscape/servers/lib/uid-plugin.extension
nsslapd-pluginInitfunc: NSUniqueAttr_Init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: mail
nsslapd-pluginarg1: dc=example,dc=com
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: NSUniqueAttr
nsslapd-pluginVersion: 6.1
nsslapd-pluginVendor: Netscape Communications Corporation
nsslapd-pluginDescription: Enforce unique attribute values

Restart Directory Server.

In this example, the uniqueness check will be performed on every entry in the dc=example,dc=com entry that includes the mail attribute.

Configuring Attribute Uniqueness Plug-Ins

This section explains how to use Directory Server Console to view the plug-ins configured for your directory, and how to modify the configuration of the attribute uniqueness plug-ins.

Viewing Plug-In Configuration Information

From the Directory Server Console, you can display the configuration entry for attribute uniqueness plug-ins as follows:

On the Directory Server Console, click the Directory tab.

In the left navigation tree, expand the config folder, then the plugins folder.

The list of plug-ins is displayed in the right navigation window. You should see the uid uniqueness plug-in and any other attribute uniqueness plug-ins that you created following the example given in "Creating an Instance of the Attribute Uniqueness Plug-In".

In the right navigation window, double-click the plug-in entry you want to look at.

The Property Editor is displayed. It contains a list of all the attributes and values for the plug-in.

Configuring Attribute Uniqueness Plug-Ins From the Directory Server Console

You can update plug-in configuration from Directory Server Console in several ways:

From the Property Editor

Display the Property Editor as explained in "Viewing Plug-In Configuration Information", and edit the attribute value fields.

From the Configuration tab

To modify an attribute uniqueness plug-in configuration from the Directory Server Console Configuration tab:

On the Directory Server Console, select the Configuration tab, then in the navigation tree, expand the Plugins folder, and select the attribute uniqueness plug-in that you want to modify.

The configuration parameters for the plug-in are displayed in the right pane.

To turn the plug-in on or off, check or clear the Enable Plugin checkbox.

To add a suffix or subtree, click Add, and type a DN in the blank text field.

If you do not want to add a DN, you can use the markerObjectClass keyword. If you use this syntax, you can click Add again to specify a requiredObjectClass as described in "Attribute Uniqueness Plug-In Syntax".

Note

You must not add an attribute name to the list. If you want to check the uniqueness of other attributes, you must create a new instance of the attribute uniqueness plug-in for the attribute you want to check. For information, refer to "Creating an Instance of the Attribute Uniqueness Plug-In".

To delete an item from the list, place the cursor in the text field that you want to delete, and click Delete.

Click Save to save your changes.

Configuring Attribute Uniqueness Plug-Ins from the Command Line

This section provides information about configuring the plug-in from the command line. It covers the following tasks:

Turning the Plug-in On or Off

Specifying a Suffix or Subtree

Using the markerObjectClass and requiredObjectClass Keywords

Turning the Plug-in On or Off

To turn the plug-in on from the command line, you must create an LDIF file that contains the following LDIF update statements:

dn: cn=descriptive_plugin_name,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginenabled
nsslapd-pluginenabled: on
Use the ldapmodify command to import the LDIF file into the directory. For detailed information on the ldapmodify command, refer to Netscape Directory Server Configuration, Command, and File Reference.

To disable the plug-in, change the LDIF update statements to replace the nsslapd-pluginenabled: on statement, by the nsslapd-pluginenabled: off statement.

Whenever you enable or disable the plug-in, you must restart the server. For information on restarting the server, refer to "Starting and Stopping the Directory Server".

Specifying a Suffix or Subtree

You specify the suffix or subtrees under which you want the plug-in to ensure attribute uniqueness by using the nsslapd-pluginarg attribute in the entry defining the plug-in.

You can specify the subtree or subtrees by creating and LDIF file that contains update statements similar to those shown in the following example:

dn: cn=mail uniqueness,cn=plugins,cn=config
changetype: add
nsslapd-pluginarg2: ou=Engineering,dc=example,dc=com
nsslapd-pluginarg3: ou=Sales,dc=example,dc=com
This example LDIF file will check 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.

Use the ldapmodify command to import the LDIF file into the directory. For detailed information on the ldapmodify command, refer to Netscape Directory Server Configuration, Command, and File Reference.

Whenever you make this type of configuration change, you must restart the server. For information on restarting the server, refer to "Starting and Stopping the Directory Server".

Using the markerObjectClass and requiredObjectClass Keywords

Instead of specifying a suffix or subtree in the configuration of an attribute uniqueness plug-in, you can specify to perform the check under the entry belonging to the DN of the updated entry that has the object class specified 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, you can create an LDIF file such as the one shown in the following example:

dn: cn=mail uniqueness,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: mail uniqueness
nsslapd-pluginPath: /usr/netscape/servers/lib/uid-plugin.so
nsslapd-pluginInitfunc: NSUniqueAttr_Init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: attribute=mail
nsslapd-pluginarg1: markerObjectClass=ou
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: NSUniqueAttr
nsslapd-pluginVersion: 6.1
nsslapd-pluginVendor: Netscape Communications Corporation
nsslapd-pluginDescription: Enforce unique attribute values
If you do not want the server to check every entry under the organizational unit entry, you can limit the scope by specifying to perform the check only if the updated entry contains a specified object class.

For example, if you check the uniqueness of the mail attribute, it is probably necessary to perform the check only when you add or modify entries that contain the person or inetorgperson object class.

You can 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
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: mail uniqueness
nsslapd-pluginPath: /usr/netscape/servers/lib/uid-plugin.so
nsslapd-pluginInitfunc: NSUniqueAttr_Init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: attribute=mail
nsslapd-pluginarg1: markerObjectClass=ou
nsslapd-pluginarg2: requiredObjectClass=person
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: NSUniqueAttr
nsslapd-pluginVersion: 6.1
nsslapd-pluginVendor: Netscape Communications Corporation
nsslapd-pluginDescription: Enforce unique attribute values
You cannot repeat the markerObjectClass or requiredObjectClass keywords by incrementing the counter in the nsslapd-pluginarg attribute suffix.

Note

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

Attribute Uniqueness Plug-In Syntax Examples

This section contains examples of attribute uniqueness plug-in syntax in the dse.ldif file. All examples show the plug-in syntax as it appears on UNIX machines.

Specifying One Attribute and One Subtree

Specifying One Attribute and Multiple Subtrees

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
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: mail uniqueness
nsslapd-pluginPath: /usr/netscape/servers/lib/uid-plugin.so
nsslapd-pluginInitfunc: NSUniqueAttr_Init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: mail
nsslapd-pluginarg1: dc=example,dc=com
nsslapd-plugin-depends-on-type: database
nsslapd-pluginId: NSUniqueAttr
nsslapd-pluginVersion: 6.1
nsslapd-pluginVendor: Netscape Communications Corporation
nsslapd-pluginDescription: Enforce unique attribute values
Specifying One Attribute and Multiple Subtrees

This example configures the plug-in to ensure the uniqueness of the mail attribute under the l=Chicago,dc=example,dc=com and l=Boston,dc=example,dc=com subtrees.

dn: cn=mail uniqueness,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: mail uniqueness
nsslapd-pluginPath: /usr/netscape/servers/lib/uid-plugin.so
nsslapd-pluginInitfunc: NSUniqueAttr_Init
nsslapd-pluginType: preoperation
nsslapd-pluginEnabled: on
nsslapd-pluginarg0: mail
nsslapd-pluginarg1: l=Chicago,dc=example,dc=comnsslapd-pluginarg2: l=Boston,dc=example,dc=comnsslapd-plugin-depends-on-type: database
nsslapd-pluginId: NSUniqueAttr
nsslapd-pluginVersion: 6.1
nsslapd-pluginVendor: Netscape Communications Corporation
nsslapd-pluginDescription: Enforce unique attribute values

Note

The nsslapd-pluginarg0 attribute always contains the name of the attribute for which you want to ensure uniqueness. All other occurrences of the nsslapd-pluginarg (nsslapd-pluginarg1 to nsslapd-pluginargx) 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 would be allowed:

mail=bjensen,l=Chicago,dc=example,dc=com
mail=bjensen,l=Boston,dc=example,dc=com
If you want to ensure that only one instance of a value exists under both subtrees, you need to configure the plug-in to ensure uniqueness for the entire dc=example,dc=com subtree.

Replication and the Attribute Uniqueness Plug-In

When you use the attribute uniqueness plug-ins on Directory Servers involved in a replication agreement, you must think carefully about how to configure the plug-in on each server.

Consider the following cases:

Simple replication with one supplier and one or several consumers

Complex replication with multiple masters

Attribute uniqueness plug-ins do not perform any checking on attribute values when an update is performed as part of a replication operation.

Simple Replication Scenario

Because all modifications by client applications are performed on the supplier server, the attribute uniqueness plug-in should be enabled on the supplier. It is unnecessary to enable it on the consumer server.

Enabling the attribute uniqueness plug-in on the consumer will not prevent Directory Server from operating correctly, but is likely to cause a performance degradation.

Multi-Master Replication Scenario

In a multi-master replication scenario, the two masters act both as suppliers and consumers of the same replica. Because multi-master replication uses a loosely consistent replication model, enabling an attribute uniqueness plug-in on one of the servers is not sufficient to ensure that attribute values will be unique across both masters at any given time. Therefore, enabling an attribute uniqueness plug-in on one server can cause inconsistencies in the data held on each replica.

However, you can use an attribute uniqueness plug-in, providing all of the following conditions are met:

The attribute on which you are performing the uniqueness check is a naming attribute

The attribute uniqueness plug-in is enabled on both masters

When these conditions are met, attribute uniqueness conflicts are reported as naming conflicts at replication time. Naming conflicts require manual resolution. For information on how to resolve replication conflicts, refer to "Solving Common Replication Conflicts".

Variable	Definition
descriptive_plugin_name	Specifies the name of this instance of the attribute uniqueness plug-in. You do not have to include the name of the attribute for which you want to ensure uniqueness, but it is advisable. For example `cn=mail uniqueness,cn=plugins,cn=config`.
extension	File extension for the plug-in. The extension is always `.sl` on HP-UX, `.so` on all other UNIX platforms, and `.dll` on Windows.
state	Defines whether the plug-in is enabled or disabled. Acceptable values are `on` or `off` . See "Turning the Plug-in On or Off" for more information.
attribute_name	The name of the attribute for which you want to ensure unique values. You can specify one attribute name only.
dn	The DN of the suffix or subtree in which you want to ensure attribute uniqueness. You can specify several suffixes or subtrees by incrementing the suffix of the `nsslapd-pluginarg` attribute by 1 for each additional suffix or subtree.
attribute=attribute_name	The name of the attribute for which you want to ensure unique values. You can specify one attribute name only.
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 you use the `markerObjectClass` keyword to specify the scope of the uniqueness check instead of a DN, you can optionally 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.

Last Updated August 15, 2002


Note	You must not add an attribute name to the list. If you want to check the uniqueness of other attributes, you must create a new instance of the attribute uniqueness plug-in for the attribute you want to check. For information, refer to "Creating an Instance of the Attribute Uniqueness Plug-In".


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