Symas OpenLDAP Knowledge Base

OpenLDAP Change Sequence Numbers (CSNs)

Note: For brevity, the $SETTINGS variable in command line examples is assumed to contain following: “-x -D cn=manager,dc=example,dc=com -w secret -LLL”

Change Serial Numbers (CSNs)

OpenLDAP replication relies on CSNs (defined here.) Two different CSNs are used, the entryCSN and the contextCSN. 

Both CSNs are stored as operational attributes and share the same syntax:

<CSN>            ::= <timestamp> # <changeCount> # <replicaId> # <modifierNumber>
<timestamp>      ::= A GMT based time, YYYYmmddHHMMSS.uuuuuuZ
<changeCount>    ::= [000000-ffffff] (Change number within a millisecond)
<serverID>       ::= [000-fff] (This is the serverID of the provider that processed the update)
<modifierNumber> ::= [000000-ffffff] Order of modification within an LDAP Modify operation (always 000000)

Breaking down an example CSN: 20161109223238.357222Z#000000#000#000000

  1. The change was written at 20161109223238.357222
  2. The change is the first of any changes written within the microsecond
  3. The serverID of the replication provider is 0
  4. No order of modification within the MOD operation

Note: In #3 above, serverID of 0 indicates that there is only one Master taking updates from client applications (single master replication or SMR). Symas recommends that even in SMR clusters, the Master have a non-zero serverID to ease converstion to multi-master replication (MMR).

The entryCSN

The entryCSN represents the time and provider source of the last change to an object.  Every entry in the database has an entryCSN.   The entryCSN is a single-valued attribute.

The contextCSN

The contextCSN is the entryCSN of the most recently updated entry in a directory and is stored in the directory root entry. Every time an entry is updated, the contextCSN is updated to the entryCSN.  contextCSNs are unique to each LDAP provider, as designated by the serverID setting.  With single-master environments, the serverID defaults to 0 and does not need to be set.  In multi-master environments, the serverID must be unique across all servers.

Accessing CSNs

CSNs are operational attributes that may be accessed through regular LDAP searches via command line or in an LDAP browser. The examples below use the ldapsearch command line command form.

Example contextCSN search and result:

user@host# ldapsearch $SETTINGS -H ldap://localhost -s base -b dc=example,dc=com contextCSN

dn: dc=example,dc=com
contextCSN: 20161109223238.357222Z#000000#000#000000

Q: What if my contextCSN search returns no contextCSNs?

A:  First make sure the server you are querying is set up to provide replication to other servers! If not, this is normal.

Otherwise, if no contextCSNs are returned, first make sure that the search base of the ldapsearch is set to the root database entry.  If the search base is correct, this usually means that the provider is new and hasn’t updated any entries as a synchronization provider, or the consumers are new and no entries have been replicated by the consumer.  First, make sure your syncprov and syncrepl configurations are correct.  Then add or modify an entry on the provider.  Finally, search for the contextCSN on your providers and consumers, each provider and consumer should return a contextCSN.

Q: What if my contextCSN search returns more than one contextCSN?

A: This is normal in multi-master environments.  When an LDAP replica server (replication consumer) uses multiple providers, a contextCSN for each provider is returned.

Example entryCSN search and result:

user@host# ldapsearch $SETTINGS -H ldap://localhost -s base -b ou=Accounting,dc=example,dc=com contextCSN

dn: ou=Accounting,dc=example,dc=com
entryCSN: 20161018201640.414299Z#000000#000#000000