Administrator’s Guide
Red Hat Directory Server                                                            
Previous
 Contents
 Index
 Next

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.

Red Hat 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

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:

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:

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," on page 539.
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," on page 540.

If you intend to use the Attribute Uniqueness Plug-in in a replicated environment, refer to "Replication and the Attribute Uniqueness Plug-in," on page 543.

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 perform the check only 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," on page 537 .

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," on page 543.

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: /opt/redhat-ds/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: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

nsslapd-pluginDescription: Enforce unique attribute values.
Note
  • 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: 
/opt/redhat-ds/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: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

nsslapd-pluginDescription: Enforce unique attribute values.
Note
  • 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 and .so on all other UNIX platforms.
state
Defines whether the plug-in is enabled or disabled. Acceptable values are on or off . See "Turning the Plug-in On or Off," on page 539, 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," on page 533.

For example, to create an instance the Attribute Uniqueness Plug-in for the mail attribute, you would perform the following steps:

  1. In the dse.ldif file, locate the entry for the UID Uniqueness Plug-in, cn=uid uniqueness,cn=plugins,cn=config.
  2. 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: 
/opt/redhat-ds/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: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

nsslapd-pluginDescription: Enforce unique attribute values.
  1. 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:

  1. In the Directory Server Console, click the Directory tab.
  2. 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," on page 536.
  1. 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:

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

To modify an Attribute Uniqueness Plug-in configuration from the Directory Server Console Configuration tab:

  1. In 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.
  1. To turn the plug-in on or off, check or clear the Enable Plugin checkbox.
  2. 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," on page 533.
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," on page 536.


  1. To delete an item from the list, place the cursor in the text field that you want to delete, and click Delete.
  2. 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

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 Red Hat Directory Server Configuration, Command, and File Reference.

To disable the plug-in, change the LDIF update statements to replace the nsslapd-pluginenabled: on statement with 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," on page 37.

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 Red Hat 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," on page 37.

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: /opt/redhat-ds/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: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

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: /opt/redhat-ds/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: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

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.

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: /opt/redhat-ds/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: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

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: /opt/redhat-ds/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=com

nsslapd-pluginarg2: l=Boston,dc=example,dc=com

nsslapd-plugin-depends-on-type: database

nsslapd-pluginId: NSUniqueAttr

nsslapd-pluginVersion: 7.1

nsslapd-pluginVendor: Red Hat, Inc.

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:

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 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 both of the following conditions are met:

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," on page 370.




Previous
 Contents
 Index
 Next
© 2001 Sun Microsystems, Inc. Used by permission. © 2005 Red Hat, Inc. All rights reserved.
Read the Full Copyright and Third-Party Acknowledgments.

 last updated May 20, 2005