Sun ONE logo     Previous     Contents     Index     Next    
Sun ONE Directory Server Administration Guide



Chapter 15   Using the UID Uniqueness Plug-In

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 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.

By default, the plug-in ensures the uniqueness of the uid attribute, however the plug-in is not enabled by default. You may 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:

Overview

The UID uniqueness plug-in is a preoperation plug-in. It will check 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 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 may define several instances of the UID uniqueness plug-in if you wish to enforce the uniqueness of other attributes. Define one plug-in instance for each attribute and set of entries where you want its value to be unique. You may 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 the 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 Attribute

This section explains how to enable and configure the default uniqueness plug-in for the uid attribute in your directory. 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".

  1. On the top-level Configuration tab of the Directory Server console, expand the Plug-Ins node and select the uid uniqueness plug-in.
  2. In the right-hand panel, select the checkbox to enable the plug-in.
  3. Do not modify the fields for the initialization function or the plug-in module path.

  4. Modify the plug-in arguments according to how you wish to specify the subtrees where uniqueness is enforced:
  5. 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.
  6. 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=baseObjectClass

The 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 may further restrict the enforcement of attribute uniqueness to certain entries according on 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 are done 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.

    1. Enable or disable the plug-in by setting the nsslapd-pluginEnabled attribute to on or off, respectively:
    2. 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

    3. Modify the plug-in arguments according to how you wish to specify the subtrees where uniqueness is enforced:
    4. To specify the base DN of a single subtree, modify the value of nsslapd-pluginarg1:
    5. 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
      ^D

      To 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

    6. 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.
    7. 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

    8. Restart the server for your changes to take effect.

    Enforcing Uniqueness of Another Attribute

    The 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.

    1. 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.
    2. 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.extension
      nsslapd-pluginVersion: 5.2
      nsslapd-pluginVendor: Sun Microsystems, Inc.
      nsslapd-pluginId: NSUniqueAttr
      nsslapd-pluginInitfunc: NSUniqueAttr_Init
      nsslapd-pluginEnabled: on or off
      ...

      In 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. Finally, specify the enabled state of your new instance as either on or off when the server is restarted.

    3. If you verify plug-in signatures in your server, you must include the signature in the new uniqueness plug-in configuration. Because your uniqueness plug-in is a new instance of the UID uniqueness plug-in, you must use the same signature information, which is located in the following file:
    4. ServerRoot/plugins/signatures/plugin.signatures

      This file is readable only to the user identity that was used when installing the server, for example root. In this file, locate the information under the entry dn: cn=uid uniqueness,cn=plugins,cn=config. Use the same values given in the file to add the following attributes to your new plug-in instance. You must also include the ds-signedPlugin objectclass:

      objectClass: ds-signedPlugin
      ds-pluginDigest:: 02Q7yVLYsC8FInPrvbAKYq7Rj0o=
      ds-pluginSignature:: MIIBjwYJKoZIhvcNAQcCoIIBgDCCAXwCAQExCzAJBg
       UrDgMCGgUAMAsGCSqGSIb3DQEHATGCAVswggFXAgEBMFYwTTELMAkGA1UEBhMC
       VVMxGTAXBgNVBAoTEFN1biBNaWNyb3N5c3RlbXMxIzAhBgNVBAMTGlBsdWdpbi
       BTaWduaW5nIENlcnRpZmljYXRlAgUA5X1ATjAJBgUrDgMCGgUAoF0wGAYJKoZI
       A2WjAjBgkqhkiG9w0BCQQxFgQU77mUWWJWttkH89eLwTr/fQtz+BswDQYJKoZI
       hvcNAQEBBQAEgYAzZwvgwo+OdKNkXWxlP+pUNpHesL6UQcvXcm37mEQyikRvLs
       hy3X0JutFhEXaCfU4UX76A3Zzedr2Iy0YEGkiPCu3g8jnkFEG/ux0ZMeOPiulF
       f9PUfqpnz6phq19eBZxZ/MBFLxtlzJHG42Ext/un4ZzQIg==
      ...

      For more information about plug-in signatures, see "Verifying Plug-In Signatures". If you do not verify plug-in signatures, you do not need these attributes. The configuration will show that your new plug-in instance is not signed, but the plug-in will still function normally.

    5. The rest of the command specifies the plug-in arguments that depend on how you wish to determine the subtrees where uniqueness is enforced:
    6. To define one or more subtrees according to their base DN, the first argument must be the name of attribute that should have unique values, and the subsequent arguments are the full DNs of the base entries of the subtrees:
    7. nsslapd-pluginarg0: attribute_name
      nsslapd-pluginarg1: subtreeBaseDN
      nsslapd-pluginarg2: subtreeBaseDN
      ...
      ^D

    8. 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.
    9. nsslapd-pluginarg0: attribute=attribute_name
      nsslapd-pluginarg1: markerObjectClass=baseObjectClass
      nsslapd-pluginarg2: requiredObjectClass=entryObjectClass
      ^D

      In all plug-in arguments, there must be no white space before or after the = sign.

    10. Restart the server to load this new instance of the uniqueness plug-in into the server.

    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 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:

    • The attribute on which you are performing the uniqueness check is a naming attribute.
    • 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 require manual resolution. For information on resolving replication conflicts, refer to "Solving Common Replication Conflicts".


    Previous     Contents     Index     Next    
    Copyright 2003 Sun Microsystems, Inc. All rights reserved.