Chapter 36 Attribute Value Uniqueness Plug-In

The attribute value uniqueness plug-in is an experimental feature that requires Sun™ ONE Directory Server Resource Kit (DSRK) 5.2. This server plug-in enforces the uniqueness of attribute values in replicas that participate in a multi-master replication scenario. This chapter provides information on the plug-in. It contains the following sections:

Overview

The attribute value uniqueness plug-in verifies and enforces the uniqueness of any number of attributes. To do this, it communicates with attribute value uniqueness plug-ins on other servers. An operation that modifies an attribute being monitored will receive an error if the new value already exists in any of the master replicas. This guarantees that all attributes being verified will have unique values in all the servers, even in the delay between replication updates.

This plug-in is designed to be used only in a multi-master replication environment. Consumer and hub replicas do not accept write operations, and therefore they do not need the attribute uniqueness plug-in to be enabled. Masters in a multi-master configuration contain the same data, but may hold updates that have not yet been replicated. The attribute value uniqueness plug-in must be enabled and configured identically on all replicating master servers as it will contact all masters to verify the latest values for an attribute on any server.

The attribute value uniqueness plug-in verifies uniqueness for any number of attributes. Each attribute may be associated with a list of suffixes where uniqueness will be enforced collectively. The plug-in does not allow “separate” uniqueness within different sets of entries. It ensures that the attribute’s value will be unique in all suffixes in the list and in all master replicas of those suffixes.

Networking Plug-Ins


Caution	The attribute value uniqueness plug-in is classified as an Unstable interface according to the definition provided in attributes(5) on Solaris^™ systems. It is provided to give you early access to a new technology as an interim solution to multi-master attribute uniqueness. Deployment of this plug-in is not recommended in production environments and will not be supported. Deployment solutions based on this interface may not work with future minor releases of Directory Server. For more information, see Limitations.

In order to verify uniqueness on all servers, the attribute value uniqueness plug-in establishes a network of connections, so that all servers can inquire about values on all other servers. The configuration of the plug-in on a server includes a list of Lightweight Directory Access Protocol (LDAP) URLs for nearby servers, called directly connected servers or DCS. If one server is configured with the URL of another, the second server will participate without needing the URL of the first. The second server is called a dcsleaf. Figure 36-1 illustrates an example of connections between plug-ins.

The directly connected servers and leaves are defined in the configuration of the attribute value uniqueness plug-ins. The connections are independent of the replication agreements. The difference between nodes and leaves of a connection diagram is that at startup, nodes initiate the connection to leaves. A node will retry connections for a minute, whereas leaves will listen for 5 minutes for any expected messages.

Connections between the plug-ins are used to determine whether all servers are reachable. By default, the node plug-ins will regularly send keepalive messages to the directly connected server every 60 seconds to determine if all master servers are reachable. If a server does not respond to a uniqueness check or a keepalive message within a given delay (by default, 30 seconds) it is considered unreachable.

When there are two masters, set the DCS on the primary or more robust master server, and make the other a dcsleaf. This configuration will allow the keepalive messages to detect connection problems sooner. With three or four masters, you should avoid having sequences of directly connected servers where one node connects to another node. Instead, make one server a leaf and have all others connect to it, as shown in Figure 36-1. Parameters for configuring communication between plug-ins are described in Deploying the Plug-In.

Distributed Hash Tables

The plug-in architecture optimizes network usage by maintaining tables of attribute values in use. For each attribute being monitored, the network of plug-ins maintains a single table of attribute values in use on all masters. Uniqueness can then be determined by reading a single table instead of performing a search operation on every master.

Attribute values are hashed using the SHA1 hash algorithm. Subsets of the hash space are distributed to the servers in the topology and stored as part of the database containing the suffix. Hashing the values makes the plug-in more secure because copies of attribute values are not sent in clear but avoids the heavier overheads of encryption methods.

Because of the hashing, each plug-in is responsible for a certain subset of the hashed attribute value data. Hashing also ensures that the tables of attribute values are evenly distributed between all master servers. For example, in a topology with 3 masters and 2 attributes configured for uniqueness, the plug-in on each server will manage approximately one third of the values of each attribute. As a result, one third of all uniqueness checks can be performed by the local plug-in and do not require further connections. Another benefit of distribution is that connections between attribute value uniqueness plug-ins are evenly distributed and do not overload any one of the servers.

Limitations

You should also be aware of the performance considerations and potential single points of failure that are inherent when enforcing attribute uniqueness in a multi-master environment. These issues are explained in the following sections.

Using UID Uniqueness Plug-In

The attribute value uniqueness plug-in does not adequately replace the UID uniqueness plug-in provided with Sun™ ONE Directory Server. For example, the attribute value uniqueness plug-in cannot be configured to enforce uniqueness on a single server nor on a single master replica. For more information about the supported plug-in, see Chapter 15, “Using the UID Uniqueness Plug-In,” in the Sun ONE Directory Server Administration Guide.

No Signature File

No signature file is provided with the attribute value uniqueness plug-in because it is not a supported feature of the DSRK. In order to use this plug-in, you must configure your server to accept unsigned plug-ins.

Multi-Master Replication Topology

The attribute value uniqueness plug-in is designed only to enforce attribute value uniqueness in multi-master replication scenarios. You must configure your multi-master replication topology before enabling the plug-in. Attribute uniqueness is enforced in the entire replicated suffix, not in arbitrary subtrees of the directory. Subsuffixes must be explicitly specified in the plug-in configuration.

The deployment of attribute value uniqueness also requires a stable topology. You must not add, remove, promote or demote a master server into or out of the multi-master replication topology while the plug-in is enabled. Instead, you must stop all servers, reconfigure your topology, reconfigure the plug-ins and their connections, and then restart all servers.

Unavailability at Startup

When the attribute value uniqueness plug-in is first enabled, the network of plug-ins must create the table of values for each monitored attribute. Hashing all values of all attributes being monitored for uniqueness and distributing those values requires some time at initialization. First, the plug-in must scan all attribute values and build the hash tables. During this scan, all masters will be entirely read-only because the plug-in must ensure uniqueness in the existing attribute values. The time for which the servers will refuse modify operations depends on the number of attributes and the number of entries containing these attributes, but it is typically several minutes.

When the scan of attribute values is complete, modification operations are allowed again. However, server and network activity may be high for a certain period while the tables of hashed values are distributed to all servers. Again, the duration of this activity depends on the number of attribute values being hashed and distributed, but it is typically on the order of several minutes, more for communication over a wide area network (WAN). To reduce startup time to a minimum, we recommend that you enable the plug-in before populating your suffixes. Then populate your suffixes by importing them through LDAP operations.

Performance Considerations

Enforcing attribute value uniqueness in a multi-master topology involves additional communication between servers. Before any update operation can be allowed to proceed, the network of plug-ins must determine if the new value of a given attribute is already used on any of the other masters. The plug-in architecture optimizes this verification procedure, but it may still lead to measurable overhead on update operations.

When using the attribute value uniqueness plug-in, all update operations will require communication between plug-ins over the network. Distributed tables of hashed attribute values optimize this process but every update operation still requires one or more network connections to check for uniqueness and to update the tables. This will both induce delays in the completion of the operation and increase network traffic.

For example, using the attribute value uniqueness plug-in in a multi-master environment over a WAN may significantly increase update operation times. Multi-master replication over WAN uses delayed and grouped operations for efficient network usage. The nature of attribute uniqueness requires immediate network communication between plug-ins, during which time the client operation is blocked. The delay in operations depends on the bandwidth, latency, and network traffic on the WAN.

Single Point of Failure

An unavoidable side-effect of multi-master uniqueness in general is that every server is a single point of failure. If a server is down or unreachable, it is impossible to check the uniqueness of attribute values stored on that server. The hashing mechanism alleviates this problem but does not eliminate it. Without hashing, every uniqueness check would fail if one server is down. With hashing and distribution, a uniqueness check will fail only if the value being checked happens to be stored on the unavailable server. For example, if one of 3 master servers is offline, roughly one third of all uniqueness checks will fail.

The attribute value uniqueness plug-in allows you to configure whether uniqueness is critical or non-critical for a given attribute. When uniqueness of an attribute is critical and a uniqueness check fails because a server is unreachable, the modification operation is refused. Examples of critical attribute values might be user ID, telephone number, credit card number, or e-mail address. The default behavior of the plug-in, is to consider all attributes as critical, and it will not authorize write operations to proceed unless an attribute value can be verified. (When an attribute being checked for uniqueness is configured as non-critical and a uniqueness check fails, the plug-in will report a warning in the error log but allow the modification operation to proceed.)


Caution	The attribute value uniqueness plug-in will conflict with instances of the UID uniqueness plug-in. The two plug-ins must not be enabled simultaneously.


Note	For security, you should still verify plug-in signatures and monitor plug-ins that have an invalid signature. For more information, see “Verifying Plug-In Signatures” in Chapter 1 of the Sun ONE Directory Server Administration Guide.


Caution	When you have configured attribute values to be non-critical, you should monitor the error logs for these warnings and manually determine uniqueness of attributes that were added or modified while a server was unreachable.

Deploying the Plug-In

Before you deploy the attribute value uniqueness plug-in, you must fully configure your replication topology. All masters must have replication enabled and their replication agreements configured. All replicas should be initialized and active. Then you must create a new instance of the plug-in in every master server. The configuration of attributes and suffixes where uniqueness is enforced must be identical in every plug-in. This implies that all of the suffixes and subsuffixes listed for all of the attributes must be replicated between every one of the masters. You must create the plug-in configuration entry on all masters before restarting all servers simultaneously.

After you create the plug-in instance, you may use either the Console or the command-line to modify its configuration. If you change the attributes or suffixes where uniqueness is enforced, or if you add or remove a master server from the topology, you must modify all plug-ins and restart all servers simultaneously.

Creating the Plug-In Instance

To create a new plug-in instance, you must create a new entry under cn=plugins,cn=config in the directory. The following procedure shows how to do this from the command-line.

Use the ldapmodify command to add the configuration entry of the new attribute value uniqueness plug-in instance.



Note	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=Attribute Value Uniqueness,cn=plugins,cn=config
objectClass: top
objectClass: nsSlapdPlugin
objectClass: extensibleObject
cn: Attribute Value Uniqueness
nsslapd-pluginDescription: Unique attribute values across
multiple servers
nsslapd-pluginType: preoperation
nsslapd-plugin-depends-on-type: database
nsslapd-pluginVersion: 5.2
nsslapd-pluginVendor: Sun Microsystems, Inc.
nsslapd-pluginId: UniqueValue
nsslapd-pluginPath: DSRK_base/lib/valueunique-plugin.extension
nsslapd-pluginInitfunc: valueunique_init
nsslapd-pluginEnabled: on
...

Where:

The DSRK_base is the location where you installed the DSRK and the library extension depends on your platform.

Alternatively, you may copy the valueunique-plugin.extension file from the DSRK into serverRoot/lib and specify that as the plug-in path. If you run your server in 64-bit mode, you must instead copy the DSRKpath/lib/64/valueunique-plugin.extension file into serverRoot/lib/64 where the server will find it automatically. In both 32- and 64-bit modes, the plug-in using the copied library must be configured as follows:

nsslapd-pluginPath: serverRoot/lib/valueunique-plugin.extension

For more information, see “64-bit Plug-In Locations” in Chapter 3 of the Sun ONE Directory Server Plug-In Programming Guide.

The rest of the command specifies the arguments that configure the plug-in. The arguments must be named sequentially starting with 0 (zero).

nsslapd-pluginarg0: first_argument
nsslapd-pluginarg1: second_argument
nsslapd-pluginarg2: third_argument
...
nsslapd-pluginargN: last_argument
^D

The plug-in arguments are described in the following substeps. Whenever an equals sign (=) appears in an argument, there must be no white space before or after the sign.

Define every attribute whose values you wish to be checked for uniqueness. After each attribute, list the base DN of the replicated suffixes where uniqueness of that attribute will be enforced collectively. A given attribute value may occur only once in all listed suffixes.

You must list subsuffixes explicitly, even if their parent suffix is listed. Optionally, specify whether the attribute is critical or not. These plug-in arguments have the following format:

nsslapd-pluginargn: attribute=attributeTypeName
[nsslapd-pluginargn+1: onerror=fail or onerror=continue]
nsslapd-pluginargn+2: suffix=suffix1BaseDN
nsslapd-pluginargn+3: suffix=suffix2BaseDN
...

When you specify onerror=fail, the attribute is considered critical and any inability to determine uniqueness because of an unavailable server will cause the operation to fail. By default, all attributes are considered critical if the onerror argument is omitted. Specify onerror=continue to make an attribute non-critical. In this case, the inability to determine uniqueness will not cause an operation to fail, but the plug-in will log a warning in the error log.

You must configure the plug-in on all master servers to check uniqueness for all of the same attributes. Also, the onerror setting and the suffix DNs of a given attribute configuration must be the same on all servers.

After all attributes and their suffixes have been specified, add the following arguments to define the connections between plug-ins:

nsslapd-pluginargn: dcsleaf
or
nsslapd-pluginargn: dcs=ldap://host1:port1/
nsslapd-pluginargn+1: dcs=ldap://host2:port2/
...

The directly connected server (DCS) definitions should be different on every master so that all masters are connected. For more information, see Networking Plug-Ins. You may specify secure ports if SSL is enabled on the local server and the target host. When using secure ports, all communication between the two plug-ins will be encrypted.

Optionally, specify the either or both of the following attributes to define how communications between connected servers are handled. These parameters are specific to each server, depending upon your network conditions:

nsslapd-pluginargn: alivecheck=seconds
nsslapd-pluginargn+1: optimeout=seconds
...

If the local plug-in has not received a message from a connected server within the delay specified by the alivecheck parameter, the plug-in will send a keepalive message to the server. After sending either a uniqueness check or a keepalive message to a server, the optimeout parameter determines the delay that the plug-in will wait for an answer. If the server does not respond within this delay the server is assumed to be unreachable and the uniqueness check will fail.

The alivecheck parameter has no effect if dcsleaf is specified, because leaf plug-ins do not send keepalive messages. The default alivecheck is 60 seconds, and the default optimeout is 30 seconds. When using the plug-in with master servers connected over a WAN, you should set the alivecheck and optimeout arguments to values that allow for both the average and exceptional delays that occur over your WAN.

If you verify plug-in signatures in your server, you must change the configuration to only flag plug-ins with invalid signatures. For details of this procedure, see “Verifying Plug-In Signatures” in Chapter 1 of the Sun ONE Directory Server Administration Guide.

Before restarting the server, repeat this procedure to configure the attribute value uniqueness plug-in on every master server in your multi-master replication topology.

Restart all master servers in your multi-master replication topology. Begin with servers that are a dcsleaf in the plug-in connection diagram, and then restart the ones connected to those leaves.

The master servers will restart in read-only mode until the plug-ins have initialized and then automatically switch to allow normal write operation. However, network traffic between the plug-ins will still be high while the plug-ins distribute the hashed attribute values. For more information, see Unavailability at Startup.

Configuring the Plug-In Using the Console

After the new instance of the attribute value uniqueness plug-in has been created, you can modify its configuration at any time using the Console. For example, if you add or remove a master server from the replication topology, you must modify the connections between plug-ins to account for this change. You may also modify the attributes or suffixes where uniqueness is enforced by identically reconfiguring all plug-ins in the multi-master topology. (In both of these cases, you must restart all master servers after all modifications have been made.) You may also modify the communication arguments of a plug-in. These are specific to each server and do not require restarting all master servers.

On the top-level Configuration tab of the Directory Server console, expand the Plug-Ins node and select the attribute value uniqueness plug-in.

In the right-hand panel, select or deselect the checkbox to enable or disable the plug-in.

If you have changed the installation path of the DSRK, modify the field for the the plug-in module path accordingly. Do not modify the name of the initialization function.

Use the text fields and the Add and Delete buttons to modify the plug-in arguments that configure the plug-in. The syntax for the order of the arguments is the following:

Specify the attributes for which uniqueness is enforced, each one followed by the optional onerror argument and one or more suffixes or subsuffixes given by their base DN.

attribute=attributeTypeName
[onerror=fail or onerror=continue]
suffix=suffixBaseDN
...

When onerror=fail and uniqueness cannot be checked because a server is unreachable, the modify operation will fail. When onerror=continue in the same condition, an error will be logged, the modify operations will succeed, but you must then verify manually on all servers that attribute values are still unique. When this argument is omitted, the default behavior is the same as onerror=fail.

Use the following directly connected server (DCS) arguments to specify the connections between attribute value uniqueness plug-ins. Specify that a server is either a leaf or give the LDAP URL of another server. For more information, see Networking Plug-Ins.

dcsleaf or
dcs=ldap://host:port/
...

You may specify secure ports if SSL is enabled on the local server and the target host. When using secure ports, all communication between the two plug-ins will be encrypted.

Optionally, specify the either or both of the following attributes to define how communications between connected servers are handled.

[alivecheck=seconds]
[optimeout=seconds]

The alivecheck parameter determines how often the plug-in will contact its directly connected servers to see if they are still reachable. The default is every 60 seconds. This parameter has no effect if defined on a leaf server. The optimeout parameter defines how long the plug-in will wait for a reply to either a uniqueness check or a “keepalive” check before assuming a server is unreachable. The default is 30 seconds.

Click Save when you are done editing the plug-in configuration. You will be reminded that you must restart the server for the changes to take effect.

If you modified the attribute arguments, including the onerror or suffix configuration you must modify the plug-in configuration on all other master servers in exactly the same way. If you modified the directly connected server arguments, modify other plug-in configurations to reestablish a connection between all plug-ins.

If you modified the attribute arguments or the directly connected server arguments, you must restart all master servers in the replication topology. If you modified only the connection arguments, you need only to restart this server.

If you restart all masters, begin with servers that are a dcsleaf in the plug-in connection diagram, and then restart the ones connected to those leaves. See also Unavailability at Startup.

Configuring the Plug-In From the Command-Line

The following procedure describes how to enable and configure the attribute value uniqueness plug-in using the ldapmodify command. By convention, the DN of the plug-in entry is cn=Attribute Value Uniqueness,cn=plugins,cn=config.

Enable or disable the plug-in by setting the nsslapd-pluginEnabled attribute to on or off, respectively:

Modify the plug-in arguments to set the new configuration of the plug-in. The order of the plug-in arguments is important, therefore you may need to modify many arguments that occur after one that is modified. For example, given the following configuration entry:

dn: cn=Attribute Value Uniqueness,cn=plugins,cn=config
...
nsslapd-pluginarg0: attribute=mail
nsslapd-pluginarg1: suffix=dc=example,dc=com
nsslapd-pluginarg2: attribute=uid
nsslapd-pluginarg3: suffix=dc=example,dc=com
nsslapd-pluginarg4: dcs=ldap://host:port/

the following command sets the onerror parameter for the mail attribute and defines the optimeout parameter to increase it from the default of 30 seconds:

ldapmodify -h host -p port -D "cn=Directory Manager" -w password
dn: cn=Attribute Value Uniqueness,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginarg2
nsslapd-pluginarg2: onerror=continue
-
replace: nsslapd-pluginarg3
nsslapd-pluginarg3: attribute=uid
-
replace: nsslapd-pluginarg4
nsslapd-pluginarg4: suffix=dc=example,dc=com
-
add: nsslapd-pluginarg5
nsslapd-pluginarg5: dcs=ldap://host:port/
-
add: nsslapd-pluginarg6
nsslapd-pluginarg6: optimeout=60
^D

See Step 4 of Configuring the Plug-In Using the Console, for a description of the possible argument values and the order of the arguments.

If you restart all masters, begin with servers that are a dcsleaf in the plug-in connection diagram, and then restart the ones connected to those leaves. See also Unavailability at Startup.

Previous Contents Index Next
Sun ONE Directory Server Resource Kit 5.2 Tools Reference