|
| |
| Sun Java(TM) System Directory Server 5.2 2005Q1 Administration Guide | |
Chapter 15
Enforcing Attribute Value UniquenessThe 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 will stop any operation that tries to add an entry which contains an existing value for the given attribute, or 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 it 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 is limited to ensuring attribute value uniqueness on a single server.
This chapter contains the following sections:
OverviewThe UID uniqueness plug-in is a pre-operation plug-in. It checks all LDAP 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, in which case the server terminates the operation and returns an 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 will be enforced. An operation may be terminated only if it targets an entry of this set and if the attribute value is not unique among all entries of this set.
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 set of entries and 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 will be allowed only once in each set.
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 it affects the operation of multi-master replication. You may 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 AttributeThis section explains how to enable and configure the default uniqueness plug-in for the uid attribute. To enforce uniqueness for another attribute, see Enforcing Uniqueness of Another Attribute.
Configuring the Plug-In Using the Console
When using the console, you must not modify the default uid uniqueness plug-in to enforce uniqueness of another attribute. If you do not wish to have a uid uniqueness plug-in, leave it disabled and create a new plug-in instance for another attribute, as described in Enforcing Uniqueness of Another Attribute.
- On the top-level Configuration tab of Directory Server Console, expand the Plug-Ins node and select the uid uniqueness plug-in.
- In the right-hand panel, select the checkbox to enable the plug-in.
Do not modify the fields for the initialization function or the plug-in module path.
- Modify the plug-in arguments according to how you wish to specify the subtrees where uniqueness is enforced:
- To specify the base DN of a single subtree, edit the value of Argument 2. To specify more than one subtree, click Add to add more arguments and enter the base DN of a subtree in each new text field.
- To specify subtrees by the object class of their base entries, set the arguments to the following values:
Argument 1: attribute=uid
Argument 2: markerObjectClass=baseObjectClassThe plug-in will enforce uid uniqueness in the subtree below every entry in the directory with the given baseObjectClass. For example, if you have user entries in many branches such as ou=Employees and ou=Contractors, specify markerObjectClass=organizationalUnit.
Because the scope of branches under the marker object classes may be quite large, you can further restrict the enforcement of attribute uniqueness to certain entries, according to their object class. Click on Add to add a third plug-in argument and set it to the following value:
Argument 3: requiredObjectClass=entryObjectClass
Within the subtree of entries with the baseObjectClass, the plug-in will enforce uniqueness only in operations that target entries with the entryObjectClass. For example, if you have traditional user entries, specify requiredObjectClass=inetorgperson.
- Click Save when you have finished editing the uid uniqueness plug-in. You will be reminded that you must restart the server for the changes to take effect.
- Restart the server to begin enforcing unique values for the uid attribute.
Configuring the Plug-In From the Command Line
The following procedure describes how to enable and configure the uid uniqueness plug-in using the ldapmodify command. The DN of the plug-in configuration entry is cn=uid uniqueness,cn=plugins,cn=config.
- Enable or disable the plug-in by setting the nsslapd-pluginEnabled attribute to on or off, respectively:
ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=uid uniqueness,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on or off
^D- Modify the plug-in arguments according to how you wish to specify the subtrees where uniqueness is enforced:
- To specify the base DN of a single subtree, modify the value of nsslapd-pluginarg1:
ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=uid uniqueness,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginArg1
nsslapd-pluginArg1: subtreeBaseDN
^DTo specify more than one subtree, add more arguments with the full base DN of a subtree as the value of each argument:
ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=uid uniqueness,cn=plugins,cn=config
changetype: modify
add: nsslapd-pluginArg2
nsslapd-pluginArg2: subtreeBaseDN
-
add: nsslapd-pluginArg3
nsslapd-pluginArg3: subtreeBaseDN
-
...
^D- To specify subtrees according to the object class of their base entries, set the arguments to the following values. Uniqueness of the uid attribute will be enforced in the subtree below every entry with the baseObjectClass. Optionally, you may specify the entryObjectClass in the third argument so that the plug-in enforces uniqueness only in operations that target entries with this object class.
ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=uid uniqueness,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginArg0
nsslapd-pluginArg0: attribute=uid
-
replace: nsslapd-pluginArg1
nsslapd-pluginArg1: markerObjectClass=baseObjectClass
-
replace: nsslapd-pluginArg2
nsslapd-pluginArg2: requiredObjectClass=entryObjectClass
^D- Restart the server for your changes to take effect.
Enforcing Uniqueness of Another AttributeThe UID uniqueness plug-in may 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.
- Use the ldapmodify command to add the configuration entry of the new plug-in instance. The first part of the command is shown below. The rest of the command is shown in the following steps.
ldapmodify -a -h host -p port -D "cn=Directory Manager" -w password
dn: cn=plug-in_name,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: plug-in_name
nsslapd-pluginDescription: Enforce unique attribute values
nsslapd-pluginType: preoperation
nsslapd-plugin-depends-on-type: database
nsslapd-pluginPath: ServerRoot/lib/uid-plugin.soextension
nsslapd-pluginVersion: 5.2
nsslapd-pluginVendor: Sun Microsystems, Inc.
nsslapd-pluginId: NSUniqueAttr
nsslapd-pluginInitfunc: NSUniqueAttr_Init
nsslapd-pluginEnabled: on or off
...
^DIn this first part of the command, plug-in_name should be a short and descriptive name that includes the name of the attribute, for example cn=mail uniqueness. The ServerRoot and library extension depend on your platform. Specify the enabled state of your new instance as either on or off when the server is restarted.
- The rest of the command specifies the plug-in arguments that depend on how you wish 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, and the subsequent arguments are the full DNs of the base entries of the subtrees:
nsslapd-pluginarg0: attribute_name
nsslapd-pluginarg1: subtreeBaseDN
nsslapd-pluginarg2: subtreeBaseDN
...
^D- To define subtrees according to the objectclass of their base entries, the first argument must contain attribute=attribute_name to specify 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 may specify an entryObjectClass in the third argument so that the plug-in enforces uniqueness only in operations that target entries with this object class.
nsslapd-pluginarg0: attribute=attribute_name
nsslapd-pluginarg1: markerObjectClass=baseObjectClass
nsslapd-pluginarg2: requiredObjectClass=entryObjectClass
^DIn all plug-in arguments, there must be no white space before or after the = sign.
- Restart the server to load this new instance of the uniqueness plug-in into the server.
Using the Uniqueness Plug-In With ReplicationThe 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 multi-master 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, it is unnecessary to enable the plug-in on the consumer server.
Enabling the UID uniqueness plug-in on the consumer of a single master will not interfere with replication or normal server operations, but it may cause a slight performance degradation.
Multi-Master Replication Scenario
The UID uniqueness plug-in was not designed for use in a multi-master replication scenario. Because multi-master 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 under the following conditions:
When these conditions are met, uniqueness conflicts are reported as naming conflicts at replication time. Naming conflicts require manual resolution. For information on resolving replication conflicts, refer to Solving Common Replication Conflicts.