3.5. Tracking Modifications to Directory Entries

It can be useful to track when changes are made to entries. There are two aspects of entry modifications that the Directory Server tracks:
  • Using change sequence numbers to track changes to the database. This is similar to change sequence numbers used in replication and synchronization. Every normal directory operation triggers a sequence number.
  • Assigning creation and modification information. These attributes record the names of the user who created and most recently modified an entry, as well as the timestamps of when it was created and modified.

Note

The entry USN, modify time and name, and create time and name are all operational attributes and are not returned in a regular ldapsearch. For details on running a search for operational attributes, see Section 10.5.7, “Searching for Operational Attributes”.

3.5.1. Tracking Modifications to the Database through Update Sequence Numbers

The USN Plug-in provides a way for LDAP clients to know that something — anything — in the database has changed.

3.5.1.1. An Overview of the Entry Sequence Numbers

When the USN Plug-in is enabled, update sequence numbers (USNs) are sequential numbers that are assigned to an entry whenever a write operation is performed against the entry. (Write operations include add, modify, modrdn, and delete operations. Internal database operations, like export operations, are not counted in the update sequence.) A USN counter keeps track of the most recently assigned USN.
3.5.1.1.1. Local and Global USNs
The USN is evaluated globally, for the entire database, not for the single entry. The USN is similar to the change sequence number for replication and synchronization, in that it simply ticks upward to track any changes in the database or directory. However, the entry USN is maintained separately from the CSNs, and USNs are not replicated.
The entry shows the change number for the last modification to that entry in the entryUSN operational attribute. (For details on running a search for operational attributes, see Section 10.5.7, “Searching for Operational Attributes”.)

Example 3.2. Example Entry USN

 dn: uid=jsmith,ou=People,dc=example,dc=com
 mail: jsmith@example.com
 uid: jsmith
 givenName: John
 objectClass: top
 objectClass: person
 objectClass: organizationalPerson
 objectClass: inetorgperson
 sn: Smith
 cn: John Smith
 userPassword: {SSHA}EfhKCI4iKl/ipZMsWlITQatz7v2lUnptxwZ/pw==
 entryusn: 1122
The USN Plug-in has two modes, local mode and global mode:
  • In local mode, each back end database has an instance of the USN Plug-in with a USN counter specific to that back end database. This is the default setting.
  • In global mode, there is a global instance of the USN Plug-in with a global USN counter that applies to changes made to the entire directory.
When the USN Plug-in is set to local mode, results are limited to the local back end database. When the USN Plug-in is set to global mode, the returned results are for the entire directory.
The root DSE shows the most recent USN assigned to any entry in the database in the lastusn attribute. When the USN Plug-in is set to local mode, so each database has its own local USN counter, the lastUSN shows both the database which assigned the USN and the USN: 
lastusn;database_name:USN
For example: 
lastusn;example1: 2130
lastusn;example2: 2070
In global mode, when the database uses a shared USN counter, the lastUSN attribute shows the latest USN only: 
lastusn: 4200
3.5.1.1.2. Importing USN Entries
When entries are imported, the USN Plug-in uses the nsslapd-entryusn-import-initval attribute to check if the entry has an assigned USN. If the value of nsslapd-entryusn-import-initval is numerical, the imported entry will use this numerical value as the entry's USN. If the value of nsslapd-entryusn-import-initval is not numerical, the USN Plug-in will use the value of the lastUSN attribute and increment it by one as the USN for the imported entry.

3.5.1.2. Configuring the USN Plug-in

The USN Plug-in must be enabled for USNs to be recorded on entries, as described in Section 1.8.1, “Enabling Plug-ins in the Directory Server Console”. The plug-in can be enabled through the Directory Server Console or through the command line. For example: 
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x
dn: cn=USN,cn=plugins,cn=config
changetype: modify
replace: nsslapd-pluginEnabled
nsslapd-pluginEnabled: on
Then restart the server to apply the changes.

3.5.1.3. Enabling Global USN

The nsslapd-entryusn-global configuration parameter controls whether the USN Plug-in runs in local mode or global mode. The default is set to use a local USN counter, and the nsslapd-entryusn-global attribute value is off. To change whether the USN counter is in local or global mode, modify the nsslapd-entryusn-global attribute. For example: 
[root@server ~]# ldapmodify -D "cn=directory manager" -W -x
dn: cn=USN,cn=plugins,cn=config
changetype: modify
replace: nsslapd-entryusn-global
nsslapd-entryusn-global: on
The USN Plug-in must be enabled before the nsslapd-entryusn-global configuration parameter is turned on.

3.5.1.4. Cleaning up USN Tombstone Entries

The USN Plug-in moves entries to tombstone entries when the entry is deleted. If replication is enabled, then separate tombstone entries are kept by both the USN and Replication Plug-ins. Both tombstone entries are deleted by the replication process, but for server performance, it can be beneficial to delete the USN tombstones before converting a server to a replica or to free memory for the server.
The usn-tombstone-cleanup.pl command deletes USN tombstone entries for a specific database back end or specific suffix. Optionally, it can delete all of tombstone entries up to a certain USN. For example: 
/usr/lib64/dirsrv/instance_name/usn-tombstone-cleanup.pl -D "cn=directory manager" -w secret -s "ou=people,dc=example,dc=com" -m 1100
Either the back end must be specified using the -n option or the suffix, using the -s option. If both are given, then the suffix in the -s option is used.
The options for usn-tombstone-cleanup.pl command are listed in Table 3.5, “usn-tombstone-cleanup.pl Options”. More details for this tool are in the Configuration and Command-Line Tool Reference.

Table 3.5. usn-tombstone-cleanup.pl Options

Option Description
-D rootdn Gives the user DN with root permissions, such as Directory Manager. The default is the DN of the Directory Manager, which is read from the nsslapd-root attribute under cn=config.
-m maximum_USN Sets the upper bound for entries to delete. All tombstone entries with an entryUSN value up to the specified maximum (inclusive) are deleted, but not past that USN value. If no maximum USN value is set, then all back end tombstone entries are deleted.
-n backendInstance Gives the name of the database containing the entries to clean (delete).
-s suffix Gives the name of the suffix containing the entries to clean (delete).
-w password The password associated with the user DN.

3.5.2. Tracking Entry Modifications through Operational Attributes

The Directory Server can maintain some special operational attributes for every directory entry, showing basic creation and modification information:
  • creatorsName. The distinguished name of the person who initially created the entry.
  • createTimestamp. The timestamp for when the entry was created in GMT (Greenwich Mean Time) format.
  • modifiersName. The distinguished name of the person who last modified the entry.
  • modifyTimestamp. The timestamp for when the entry was last modified in GMT format.
Operational attributes are not returned in default directory searches and must be explicitly requested, as described in Section 10.5.7, “Searching for Operational Attributes”.

Note

When a database link is used by a client application to create or modify entries, the creatorsName and modifiersName attributes do not reflect the real creator or modifier of the entries. These attributes contain the name of the administrator who is granted proxy authorization rights on the remote server.
The access logs, however, will show both the proxy user (as dn) and the real user (as the authzid entity). For example: 
[23/May/2011:18:13:56 +051800] conn=1175 op=0 BIND dn="cn=proxy admin,ou=people,dc=example,dc=com" method=128 version=3
[23/May/2011:18:13:56 +051800] conn=1175 op=0 RESULT err=0 tag=97 nentries=0 etime=0 dn="cn=proxy admin,ou=people,dc=example,dc=com"
[23/May/2011:18:13:56 +051800] conn=1175 op=1 SRCH base="dc=example,dc=com" scope=2 filter="(objectClass=*)" attrs=ALL authzid="uid=jsmith,ou=people,dc=example,dc=com"
For information on proxy authorization, see Section 2.3.1.2.2, “Providing Bind Credentials”.
To enable the Directory Server to track when entries are created or modified:
  1. In the Directory Server Console, select the Configuration tab, and then select the top entry in the navigation tree in the left pane.
  2. Select the Settings tab in the right pane.
  3. Select the Track Entry Modification Times check box.
    The server adds the creatorsName, createTimestamp, modifiersName, and modifyTimestamp attributes to every newly created or modified entry.
  4. Open the Tasks tab, and click Restart Directory Server.

    Note

    The Directory Server must be restarted for the changes to take effect.

3.5.3. Tracking the Bind DN for Plug-in Initiated Updates

One change to an entry can trigger other, automatic changes across the directory tree. When a user is deleted, for example, that user is automatically removed from any groups it belonged to by the Referential Integrity Plug-in.
The initial action is shown in the entry as being performed by whatever user account is bound to the server, but all related updates (by default) are shown as being performed by the plug-in, with no information about which user initiated that update. For example, using the MemberOf Plug-in to update user entries with group membership, the update to the group account is shown as being performed by the bound user, while the edit to the user entry is shown as being performed by the MemberOf Plug-in: 
dn: cn=my_group,ou=groups,dc=example,dc=com
modifiersname: uid=jsmith,ou=people,dc=example,dc=com

dn: uid=bjensen,ou=people,dc=example,dc=com
modifiersname: cn=memberOf plugin,cn=plugins,cn=config
The nsslapd-plugin-binddn-tracking attribute allows the server to track which user originated an update operation, as well as the internal plug-in which actually performed it. The bound user is shown in the modifiersname and creatorsname operational attributes, while the plug-in which performed it is shown in the internalModifiersname and internalCreatorsname operational attributes. For example: 
dn: uid=bjensen,ou=people,dc=example,dc=com
modifiersname: uid=jsmith,ou=people,dc=example,dc=com
internalModifiersname: cn=memberOf plugin,cn=plugins,cn=config
The nsslapd-plugin-binddn-tracking attribute tracks and maintains the relationship between the bound user and any updates performed for that connection.

Note

The internalModifiersname and internalCreatorsname attributes always show a plug-in as the identity. This plug-in could be an additional plug-in, such as the MemberOf Plug-in. If the change is made by the core Directory Server, then the plug-in is the database plug-in, cn=ldbm database,cn=plugins,cn=config.
The nsslapd-plugin-binddn-tracking attribute is disabled by default. To allow the server to track operations based on bind DN, enable that attribute using ldapmodify: 
[jsmith@server ~]$ ldapmodify -D "cn=directory manager" -W -p 389 -h server.example.com -x

dn: cn=config
changetype: modify
replace: nsslapd-plugin-binddn-tracking
nsslapd-plugin-binddn-tracking: on

3.5.4. Tracking Password Change Times

Password change operations are normally treated as any other modification to an entry, so the update time is recorded in the lastModified operational attrobite. However, there can be times when the time of the last password change needs to be recorded separately, to make it easier to update passwords in Active Directory synchronization or to connect with other LDAP clients.
The passwordTrackUpdateTime attribute within the password policy tells the server to record a timestamp for the last time that the password was updated for an entry. The password change time itself is stored as an operational attribute on the user entry, pwdUpdateTime (which is separate from the modifyTimestamp or lastModified operational attributes).
The passwordTrackUpdateTime attribute can be set as part of the global password policy or on a subtree or user-level policy, depending on what clients need to access the password change time. Setting password policies is described in Section 14.1, “Managing the Password Policy”.