3.6. Maintaining Referential Integrity

Referential Integrity is a database mechanism that ensures relationships between related entries are maintained. In the Directory Server, the Referential Integrity can be used to ensure that an update to one entry in the directory is correctly reflected in any other entries that reference to the updated entry.
For example, if a user's entry is removed from the directory and referential integrity is enabled, the server also removes the user from any groups of which the user is a member. If referential integrity is not enabled, the user remains a member of the group until manually removed by the administrator. This is an important feature if you are integrating the Directory Server with other products that rely on the directory for user and group management.

3.6.1. How Referential Integrity Works

When the Referential Integrity Plug-in is enabled, it performs integrity updates on specified attributes immediately after a delete or rename operation. By default, the Referential Integrity Plug-in is disabled.

Note

The Referential Integrity Plug-in should only be enabled on one supplier replica in a multi-master replication environment to avoid conflict resolution loops. When enabling the plug-in on servers issuing chaining requests, be sure to analyze performance resource and time needs, as well as your integrity needs. Integrity checks can be time-consuming and draining on memory and CPU.
When a user or group entry is deleted, updated, renamed, or moved within the directory, the operation is logged to the Referential Integrity log file. For the distinguished names (DN) in the log file, Directory Server searches and updates in intervals the attributes set in the plug-in configuration:
  • For entries, marked in the log file as deleted, the corresponding attribute in the directory is deleted.
  • For entries, marked in the log file as updated, the corresponding attribute in the directory is updated.
  • For entries, marked in the log file as renamed or moved, the value of the corresponding attribute in the directory is renamed.
By default, when the Referential Integrity Plug-in is enabled, it performs integrity updates on the member, uniquemember, owner, and seeAlso attributes immediately after a delete or rename operation. However, the behavior of the Referential Integrity Plug-in can be configured to suit the needs of the directory in several different ways:
  • Record referential integrity updates in the replication changelog.
  • Modify the update interval.
  • Select the attributes to which to apply referential integrity.
  • Disable referential integrity.
All attributes used in referential integrity must be indexed for presence, equality, and subtring; not indexing those attributes results poor server performance for modify and delete operations. 
nsIndexType: pres
nsIndexType: eq
nsIndexType: sub
See Section 9.2, “Creating Standard Indexes” for more information about checking and creating indexes.

3.6.2. Using Referential Integrity with Replication

There are certain limitations when using the Referential Integrity Plug-in in a replication environment:
  • Never enable it on a dedicated consumer server (a server that contains only read-only replicas).
  • Never enable it on a server that contains a combination of read-write and read-only replicas.
  • It is possible to enable it on a supplier server that contains only read-write replicas.
  • With multi-master replication, enable the plug-in on just one supplier.
If the replication environment satisfies the all of those condition, you can enable the Referential Integrity Plug-in.
  1. Enable the Referential Integrity Plug-in as described in Section 3.6.3, “Enabling and Disabling Referential Integrity”.
  2. Configure the plug-in to record any integrity updates in the changelog.
  3. Ensure that the Referential Integrity Plug-in is disabled on all consumer servers.

    Note

    Because the supplier server sends any changes made by the Referential Integrity Plug-in to consumer servers, it is unnecessary to run the Referential Integrity Plug-in on consumer servers.

3.6.3. Enabling and Disabling Referential Integrity

3.6.3.1. Enabling and Disabling Referential Integrity in the Console

  1. Select the Configuration tab, and expand the Plugins folder.
  2. Select Referential Integrity Postoperation Plug-in from the list.
  3. Check the Enable plugin check box to enable the plug-in; clear it to disable it.
  4. Fill in the correct path to the plug-in by default; plug-ins are located in /usr/lib64/dirsrv/plugins.
  5. Restart the Directory Server to apply the changes. In the Tasks tab, select Restart the Directory Server.

3.6.3.2. Enabling and Disabling Referential Integrity from the Command Line

To disable or enable the Referential Integrity Plug-in:
  1. Use ldapmodify to edit the value of the nsslapd-pluginEnabled attribute. For example: 
    ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=referential integrity postoperation,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on
  2. Then restart the server. 
    service dirsrv restart

3.6.4. Modifying the Update Interval

By default, the server makes referential integrity updates immediately after a delete or a modrdn operation. To reduce the impact this operation has on your system, increase the amount of time between updates. Although there is no maximum update interval, the following intervals are commonly used:
  • Update immediately
  • 90 seconds
  • 3600 seconds (updates occur every hour)
  • 10,800 seconds (updates occur every 3 hours)
  • 28,800 seconds (updates occur every 8 hours)
  • 86,400 seconds (updates occur once a day)
  • 604,800 seconds (updates occur once a week)

3.6.4.1. Modifying the Update Interval from the Console

  1. Select the Configuration tab, and expand the Plugins folder. Select the Referential Integrity Postoperation Plug-in.
  2. In the arguments list, replace the value in the first text box with the appropriate time interval.
  3. Restart the Directory Server to apply the changes. In the Tasks tab, select Restart the Directory Server.

3.6.4.2. Modifying the Update Interval from the Command Line

  1. Use ldapmodify to edit the value of the nsslapd-pluginarg attribute. For example:
    The first argument listed sets the update interval for referential integrity checks. To change the interval, replace the nsslapd-pluginarg0 attribute. 
    [root@server ~]# ldapmodify -D "cn=directory manager" -W -x
dn: cn=referential integrity postoperation,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginarg0
nsslapd-pluginarg0: 600
  2. Then restart the server. 
    service dirsrv restart

3.6.5. Modifying the Attribute List

3.6.5.1. Modifying the Attribute List from the Console

By default, the Referential Integrity Plug-in is set up to check for and update the member, uniquemember, owner, and seeAlso attributes. You can add or delete attributes to be updated through the Directory Server Console, such as adding the nsroledn attribute if roles are being used.

Note

Keep in mind that any attribute specified in the Referential Integrity Plug-in parameter list must have equality indexing on all databases. Otherwise, the plug-in scans every entry of the databases for matching the deleted or modified DN, degrading performance severely. If you add an attribute, ensure that it is indexed in all the back ends.

Note

Improve the performance by removing any unused attributes from the list.
  1. Select the Configuration tab, and expand the Plugins folder. Select the Referential Integrity Postoperation Plug-in.
  2. In the Arguments section, use the Add and Delete buttons to modify the attributes in the list.
  3. Restart the Directory Server to apply the changes. In the Tasks tab, select Restart the Directory Server.

Note

All attributes used in referential integrity must be indexed for presence and equality; not indexing those attributes results poor server performance for modify and delete operations. See Section 9.2, “Creating Standard Indexes” for more information about checking and creating indexes.

3.6.5.2. Modifying the Attribute List from the Command Line

By default, the Referential Integrity plug-in is set up to check for and update the member, uniquemember, owner, and seeAlso attributes.
To enable shared configuration entries, set the nsslapd-pluginConfigArea attribute: 
nsslapd-pluginConfigArea:entry_DN
All the configuration attribute settings, for example adding or removing a shared entry, are dynamic and do not require a server restart to take effect.
The following example uses the pluginarg* attributes: 
nsslapd-pluginarg0: 0
nsslapd-pluginarg1: /var/log/dirsrv/slapd-localhost/referint
nsslapd-pluginarg2: 0
nsslapd-pluginarg3: member
nsslapd-pluginarg4: uniquemember
nsslapd-pluginarg5: owner
nsslapd-pluginarg6: seeAlso
Referential Integrity plug-in parameter descriptions:
Legacy-style parameter Description
nsslapd-pluginarg0
Sets the update delay:
  • -1: No check for referential integrity is performed.
  • 0: The check for referential integrity is performed immediately.
  • Positive integer value: Represents the interval in seconds for performing the referential integrity check.
nsslapd-pluginarg1 Sets the path to the log file.
nsslapd-pluginarg2
nsslapd-pluginarg[3-10] Sets the attributes on which the plug-in performs integrity updates.

Note

Keep in mind that any attribute specified in the Referential Integrity Plug-in parameter list must have equality indexing on all databases. Otherwise, the plug-in scans every entry of the databases for matching the deleted or modified DN, degrading performance severely. If you add an attribute, ensure that it is indexed in all the back ends.