Chapter 4. Tracking Modifications to Directory Entries

In certain situations it is 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 update sequence number (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.3.7, “Searching for Operational Attributes”.

4.1. Tracking Modifications to the Database through Update Sequence Numbers

The USN Plug-in enables LDAP clients and servers to identify if entries have been 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 further details about operational attributes, see Section 14.3.7, “Searching for Operational Attributes”.

Example 4.1. Example Entry USN

To display the entryusn attribute of the uid=example,ou=People,dc=example,dc=com user entry:
# ldapsearch -D "cn=Directory Manager" -W -H ldap://server.example.com:389 -x -b "uid=example,ou=People,dc=example,dc=com" -s base -x entryusn

dn: uid=example,ou=People,dc=example,dc=com
entryusn: 17653
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. Enabling the USN Plug-in

This section describes how to enable the USN plug-in to record USNs on entries.

4.1.2.1. Enabling the USN Plug-in Using the Command Line

To enable the USN plug-in using the command line:
  1. Use the dsconf utility to enable the plug-in:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn enable
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

4.1.2.2. Enabling the USN Plug-in Using the Web Console

To enable the USN plug-in using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select the Plugins menu.
  4. Select the USN plug-in.
  5. Change the status to ON to enable the plug-in.
  6. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

4.1.3. Global USNs

With the default settings, Directory Server uses unique update sequence numbers (USN) for each back end database. Alternatively, you can enable unique USNs across all back end databases.

Note

The USN plug-in must be enabled to use this feature. See Section 4.1.2, “Enabling the USN Plug-in”.

4.1.3.1. Identifying Whether Global USNs are Enabled

This section describes how to identify whether USNs are enabled across all back end databases.
4.1.3.1.1. Identifying Whether Global USNs are Enabled Using the Command Line
To display the current status of the global USN feature using the command line:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn global
USN global mode is disabled
4.1.3.1.2. Identifying Whether Global USNs are Enabled Using the Web Console
To display the current status of the global USN feature using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Select the Plugins menu.
  4. Select the USN plug-in.
  5. Verify that the USN Global switch is set to On.

4.1.3.2. Enabling Global USNs

4.1.3.2.1. Enabling Global USNs Using the Command Line
To enable global USNs using the command line:
  1. Enable global USNs:
    # dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn global on
  2. Restart the instance:
    # dsctl instance_name restart
    If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.
4.1.3.2.2. Enabling Global USNs Using the Web Console
To enable global USNs using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the USN plug-in.
  5. Change the status of the plug-in to On.
  6. Change the USN Global status to On.
  7. If you enable the dynamic plug-in as described in Section 1.10.2, “Enabling Plug-ins Dynamically”, restarting the instance is not required.

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
  • to free memory for the server

4.1.4.1. Cleaning up USN Tombstone Entries Using the Command Line

To remove all USN tombstone entries from the dc=example,dc=com suffix using the command line:
# dsconf -D "cn=Directory Manager" ldap://server.example.com plugin usn cleanup -s "dc=example,dc=com"
Optionally, pass the -o max_USN option to the command to delete USN tombstone entries up to the specified value.

4.1.4.2. Cleaning up USN Tombstone Entries Using the Web Console

To remove all USN tombstone entries from the dc=example,dc=com suffix using the web console:
  1. Open the Directory Server user interface in the web console. See Section 1.4, “Logging Into Directory Server Using the Web Console”.
  2. Select the instance.
  3. Open the Plugins menu.
  4. Select the USN plug-in.
  5. Press the Run Fixup Task button.
  6. Fill the fields, and press Run.