Show Table of Contents
Chapter 4. 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 14.5.7, “Searching for Operational Attributes”.
4.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.
4.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.
4.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 14.5.7, “Searching for Operational Attributes”.)
Example 4.1. 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
4.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.
4.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.9.2.2, “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:
# 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.
4.1.3. Enabling Global USN
With the default settings, Directory Server uses unique update sequence numbers (USN) for each back end database. To enable unique USNs across all back end databases:
- Enable the USN plug-in. See Section 4.1.2, “Configuring the USN Plug-in”.
- Set the
nsslapd-entryusn-global
parameter toon
:# ldapmodify -D "cn=Directory Manager" -W -x dn: cn=config changetype: modify replace: nsslapd-entryusn-global nsslapd-entryusn-global: on
4.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/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 4.1, “usn-tombstone-cleanup.pl Options”. More details for this tool are in the Configuration, Command, and File Reference.
Table 4.1. 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. |