Chapter 11. Using Referential Integrity to maintain relationships between entries
Referential Integrity is a database mechanism that ensures that Directory Server maintains relationship between related entries. You can use this feature to ensure that an update to one entry in the directory is correctly reflected in other entries that reference the updated entry.
For example, if you remove a user from the directory and the Referential Integrity plug-in is enabled, the server also removes the user from any group in which the user is a member. If the plug-in is not enabled, the user remains a member of the group until an administrator manually removes it.
Referential Integrity is an important feature if you integrate Directory Server with other products that rely on Directory Server for user and group management.
11.1. How the Referential Integrity plug-in works
When you enable the Referential Integrity plug-in, it performs integrity updates on the member
, uniqueMember
, owner
, and seeAlso
attributes, by default, immediately after an operation.
For example, if an administrator deletes, updates, renames, or moves a group or user within the directory, Directory Server logs the operation in the Referential Integrity log file. Directory Server then uses the distinguished name (DN) from this log file and searches entries matching the attribute specified in the plug-in’s configuration, and then updates the matching entries. For example, after deleting the cn=demo,dc=example,dc=com
entry the plug-in searches for entries with the member
attribute set to cn=demo,dc=example,dc=com
and removes these member
attributes. Afterwards, the plug-in does the same for the uniqueMember
, owner
, and seeAlso
attributes.
By default, Directory Server does searches and updates in the same transaction as the original operation. Because search and update operations can take a lot of time, it is possible to delay them after the completion of the original operation. You can use the --update-delay
option of the dsconf plugin referential-integrity set
command to separate the original operations from integrity updates.
To avoid poor performance of modify and delete operations, index the attributes you specify in the Referential Integrity plug-in configuration.
Additional resources
11.2. Configuring the Referential Integrity plug-in using the command line
You can use the command line to configure the Referential Integrity plug-in.
Perform this procedure on every supplier in a replication topology.
Procedure
Enable the Referential Integrity plug-in:
#
dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity enable
Set the subtree in which the plug-in searches for delete or rename operations of user entries:
#
dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --entry-scope "ou=People,dc=example,dc=com"
Optional: Exclude a subtree under the entry scope:
#
dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --exclude-entry-scope "ou=Special Users,ou=People,dc=example,dc=com"
This command configures the plug-in to ignore delete or rename operations performed in the
ou=Special Users,ou=People,dc=example,dc=com
subtree.Configure the subtree in which the plug-in updates group entries:
#
dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --container-scope "ou=Groups,dc=example,dc=com"
By default, the plug-in performs integrity updates on the
member
,uniqueMember
,owner
, andseeAlso
attributes. To specify other attributes, enter:#
dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --membership-attr attribute_1 attribute_2
Note that this command overrides the list of attributes in the plug-in’s configuration. If you want to add an attribute, pass the current list of attributes and the additional one to the
--membership-attr
option.Optional: By default, Directory Server performs referential integrity checks immediately. If you want to set a delay, enter:
#
dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity set --update-delay=5
This command delays the referential integrity checks by
5
seconds. Note that, if you enabled the Referential Integrity on multiple suppliers, setting a delay can cause replication loops and directory inconsistencies. To avoid such problems, enable the plug-in only on one supplier in the topology.Restart the instance:
#
dsctl instance_name restart
Verification
Display the Referential Integrity plug-in configuration:
#
dsconf -D "cn=Directory Manager" ldap://server.example.com plugin referential-integrity show
... nsslapd-plugincontainerscope: ou=Groups,dc=example,dc=com nsslapd-pluginentryscope: ou=People,dc=example,dc=com ... referint-membership-attr: member referint-membership-attr: uniquemember referint-membership-attr: owner referint-membership-attr: seeAlso referint-update-delay: 0 ...List the members of a group by displaying the
member
attributes of the groups:#
ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -b "cn=demoGroup,ou=Groups,dc=example,dc=com" member
... member: uid=demoUser,ou=People,dc=example,dc=comDelete the
uid=demoUser,ou=People,dc=example,dc=com
user:#
dsidm -D "cn=Directory manager" ldap://server.example.com -b "dc=example,dc=com" user delete "uid=demoUser,ou=People,dc=example,dc=com"
Display the members of the group again:
#
ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -b "cn=demoGroup,ou=People,dc=example,dc=com" member
If
uid=demoUser,ou=People,dc=example,dc=com
is no longer listed as a member of the group, the Referential Integrity plug-in works.
11.3. Configuring the Referential Integrity plug-in using the web console
You can use the Directory Server web console to configure the Referential Integrity plug-in.
Perform this procedure on every supplier in a replication topology.
Prerequisites
- You are logged in to the instance in the web console.
Procedure
-
Navigate to
. - Enable the plug-in.
-
Click
. -
Navigate again to
. -
By default, the plug-in performs integrity updates on the
member
,uniqueMember
,owner
, andseeAlso
attributes. To specify other attributes, update the list in theMembership Attribute
field. -
Set the
Entry Scope
field to the DN of the subtree in which the plug-in should search for delete or rename operations of user entries. -
Optional: To exclude a subtree under the entry scope, enter the DN of the subtree in the
Exclude Entry Scope
field. -
Set the
Container Scope
field to the DN of the subtree in which the plug-in should update group entries. -
Optional: Update the path to the Referential Integrity log file. Directory Server uses this file to track changes in the directory. Note that the
dirsrv
user must have write permissions to this location. Optional: By default, Directory Server performs referential integrity checks immediately. If you want to set a delay, set it in the
Update Delay
field.Note that, if you enabled the Referential Integrity on multiple suppliers, setting a delay can cause replication loops and directory inconsistencies. To avoid such problems, enable the plug-in only on one supplier in the topology.
- Click .
Verification
List the members of a group by displaying the
member
attributes of the groups:#
ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -b "cn=demoGroup,ou=Groups,dc=example,dc=com" member
... member: uid=demoUser,ou=People,dc=example,dc=comDelete the
uid=demoUser,ou=People,dc=example,dc=com
user:#
dsidm -D "cn=Directory manager" ldap://server.example.com -b "dc=example,dc=com" user delete "uid=demoUser,ou=People,dc=example,dc=com"
Display the members of the group again:
#
ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com -b "cn=demoGroup,ou=People,dc=example,dc=com" member
If
uid=demoUser,ou=People,dc=example,dc=com
is no longer listed as a member of the group, the Referential Integrity plug-in works.