3.5. 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 may refer 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.5.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.
Whenever a user or group entry is deleted or renamed in the directory, the operation is logged to the referential integrity log file (/var/log/dirsrv/slapd-instance_name). After a specified time, known as the update interval, the server performs a search on all attributes for which referential integrity is enabled and matches the entries resulting from that search with the DNs of deleted or modified entries present in the log file. If the log file shows that the entry was deleted, the corresponding attribute is deleted. If the log file shows that the entry was changed, the corresponding attribute value is modified accordingly.
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 and equality; not indexing those attributes results poor server performance for modify and delete operations. See Section 11.2, “Creating Standard Indexes” for more information about checking and creating indexes.

3.5.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.5.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.5.3. Enabling and Disabling Referential Integrity

3.5.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 checkbox 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/lib/dirsrv/plugins.
  5. Restart the Directory Server to apply the changes. In the Tasks tab, select Restart the Directory Server.

3.5.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: [7]
    /usr/lib/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389 -h server.example.com
    
    dn: cn=ACL Plugin,cn=plugins,cn=config
    changetype: modify
    replace: nsslapd-pluginEnabled
    nsslapd-pluginEnabled: on
  2. Then restart the server.
    service dirsrv restart

3.5.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.5.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.5.4.2. Modifying the Update Interval from the Command Line

  1. Use ldapmodify[7] 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.
    /usr/lib/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389
    
    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.5.5. Modifying the Attribute List

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

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 11.2, “Creating Standard Indexes” for more information about checking and creating indexes.

3.5.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.
nsslapd-pluginarg3: member
nsslapd-pluginarg4: uniqueMember
nsslapd-pluginarg5: owner
nsslapd-pluginarg6: seeAlso
To add another attribute to the list:
  1. Use ldapmodify[7] to add another attribute to the list by adding another nsslapd-pluginarg attribute.
    /usr/lib/mozldap/ldapmodify -D "cn=directory manager" -w secret -p 389
    
    dn: cn=referential integrity postoperation,cn=plugins,cn=config
    changetype: modify
    add: nsslapd-pluginarg7
    nsslapd-pluginarg7: nsroledn
  2. Then restart the server.
    service dirsrv restart

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


[7] The LDAP tools referenced in this guide are Mozilla LDAP, installed with Directory Server in the /usr/lib/mozldap directory on Red Hat Enterprise Linux 5 (32-bit); directories for other platforms are listed in Section 1.2, “LDAP Tool Locations”. However, Red Hat Enterprise Linux systems also include LDAP tools from OpenLDAP. It is possible to use the OpenLDAP commands as shown in the examples, but you must use the -x argument to disable SASL and allow simple authentication.