15.10. Managing Attributes Within Fractional Replication

As Section 15.1.7, “Replicating a Subset of Attributes with Fractional Replication” describes, fractional replication allows administrators to set attributes that are excluded from replication updates. Administrators can do this for a variety of performance reasons — to limit the number of large attributes that are sent over a network or to reduce the number of times that fixup tasks (like memberOf calculations) are run.
The list of attributes to exclude from replication are defined in the nsDS5ReplicatedAttributeList attribute. This attribute is part of the replication agreement and it can be configured in the replication agreement wizard in the Directory Server Console (or through the command line) when the replication agreement is created.
nsDS5ReplicatedAttributeList: (objectclass=*) $ EXCLUDE memberof authorityRevocationList accountUnlockTime

Important

Directory Server requires the (objectclass=*) $ EXCLUDE part in the value of the nsDS5ReplicatedAttributeList attribute. If you edit the attribute directly, for example using the ldapmodify utility, you must specify this part together with the list of attributes as displayed in the example above.

15.10.1. Setting Different Fractional Replication Attributes for Total and Incremental Updates

When fractional replication is first configured, the list of excluded attributes applies to every update operation. Meaning, this list of attributes is excluded for a total update as well as regular incremental updates. However, there can be times when attributes should be excluded from incremental updates for performance but should be included in a total update to ensure the directory data sets are complete. In this case, it is possible to add a second attribute that defines a separate list of attributes to exclude from total updates, nsDS5ReplicatedAttributeListTotal.

Note

nsDS5ReplicatedAttributeList is the primary fractional replication attribute. If only nsDS5ReplicatedAttributeList is set, then it applies to both incremental updates and total updates. If both nsDS5ReplicatedAttributeList and nsDS5ReplicatedAttributeListTotal are set, then nsDS5ReplicatedAttributeList only applies to incremental updates.
For example, every time a memberOf attribute is added to an entry, a memberOf fixup task is run to resolve the group membership. This can cause overhead on the server if that task is run every time replication occurs. Since a total update only occurs for a database which is newly-added to replication or that has been offline for a long time, running a memberOf fixup task after a total update is an acceptable option. In this case, the nsDS5ReplicatedAttributeList attribute lists memberOf so it is excluded from incremental updates, but nsDS5ReplicatedAttributeListTotal does not list memberOf so that it is included in total updates.
The exclusion list for incremental updates is set in the nsDS5ReplicatedAttributeList attribute for the replication agreement.
nsds5replicatedattributelist: (objectclass=*) $ EXCLUDE authorityRevocationList accountUnlockTime memberof
If nsDS5ReplicatedAttributeList is the only attribute set, then that list applies to both incremental and total updates. To set a separate list for total updates, add the nsDS5ReplicatedAttributeListTotal attribute to the replication agreement.
# ldapmodify -D "cn=Directory Manager" -W -x -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=ExampleAgreement,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config
changetype: modify
add: nsDS5ReplicatedAttributeListTotal
nsDS5ReplicatedAttributeListTotal: (objectclass=*) $ EXCLUDE accountUnlockTime

Note

The nsDS5ReplicatedAttributeList attribute must be set for incremental updates before nsDS5ReplicatedAttributeListTotal can be set for total updates.

15.10.2. Preventing "Empty" Updates from Fractional Replication

Fractional replication allows a list of attributes which are removed from replication updates (nsDS5ReplicatedAttributeList). However, a changed to an excluded attribute still triggers a modify event and generates an empty replication update.
The nsds5ReplicaStripAttrs attribute adds a list of attributes which cannot be sent in an empty replication event and are stripped from the update sequence. This logically includes operational attribtes like modifiersName.
For example, let's say that the accountUnlockTime attribute is excluded. John Smith's user account is locked and then the time period expires and it is automatically unlocked. Only the accountUnlockTime attribute has changed, and that attribute is excluded from replication. However, the operational attribute internalmodifytimestamp also changed. A replication event is triggered because John Smith's user account was modified — but the only data to send is the new modify time stamp and the update is otherwise emtpy. If there are a large number of attributes related to login times or password expiration times (for example), this could create a flood of empty replication updates that negatively affect server performance or that interfere with associated applications.
To prevent this, add the nsds5ReplicaStripAttrs attribute to the replication agreement to help tune the fractional replication behavior:
# ldapmodify -D "cn=Directory Manager" -W -x -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=ExampleAgreement,cn=replica,cn=dc\=example\,dc\=com,cn=mapping tree,cn=config
changetype: modify
add: nsds5ReplicaStripAttrs
nsds5ReplicaStripAttrs: modifiersname modifytimestamp internalmodifiersname internalmodifytimestamp
If a replication event is not empty, the stripped attributes are still replicated with the other changes. These attributes are removed from updates only if the event would otherwise be emtpy.