Reference15r1:Concept LDAP Replication

Note: The feature has not successfully passed through our quality assurance process yet and will therefore not be included in the 15r1 final release. However, we will release this feature separately at a later date. Up until further notice or until removal of this note, please refer to a pre-15r1 version of this article.

LDAP replication concepts, mainly the differences between full- and incremental replication are going to be covered within this article. The focus is on replication between PBXs.

Glossary

Admin Object

An LDAP DB object named "_ADMIN_".

Config Restore

The act of administratively uploading an old configuration to a box. Can be accomplished via the firmware's maintenance UI or in-part via a PBX UI.

Epoch

A Root DSE value. The current value of the GUID of the object Admin object.

Flashdir, Flashman

Flash Directory, Flash Manager with Flashdir sitting on-top of Flashman. The Flashdir exchange API messages with the Flashman to persistently add, replace, delete LDAP objects.

Full Replication

Every object is going to be queried and or handled by replication partners.

GUID

A unique 16-byte value. Every object contains an attribute GUID.

Incremental Replication

Only objects written since a last-known point in time will be queried and or handled.

Master

The replication partner acting as an LDAP server.

Notify Search

A single LDAP search remaing active until a cancellation. A server responds to it with multiple search responses for all objects being modified after the notify search was received.

Paged Search/Paging

A means to iterate over an entire database in chunks or pages of a fixed maximum size.

Replication Filter

A static LDAP filter supposed to be active during a replication session.

Root DSE

Directory-specific entry. A collection of few properties and capabilities that can be read by any LDAP client. The Root DSE is accessible without authentication and by providing a special search filter.

Slave

The replication partner acting as an LDAP client.

Tombstones, isDeleted

Deleted objects aren't deleted immediately from storage. Instead, such objects are marked with an attribute isDeleted.

USN

Update Sequence Number, a 64-bit value incremented by 1 on every write. It is deemed to never wrap-around and to be unique within an LDAP DB. Every object contains an attribute USN.

Technical concept of replication as client

The replication of a source via LDAP is basically divided into 3 phases that must be passed through when synchronization is started.

1st phase local

The first phase is the "local" phase and ensures a comparison of any delta between the local data stock and the remote data stock. (In other words, objects that need to be deleted locally).

The LDAP client makes an LDAP query per local object (which it knows from its local database) based on the guid to the LDAP server. If the LDAP server knows this object, it returns the entire object so that the client can update the object locally if necessary. If the object does not exist in the LDAP server, it is removed locally.

During this phase, the status shows the following:

remote: Stopped
local: Active

2nd phase remote

The second phase is the "remote" phase and ensures a comparison of any delta between the remote data stock and the local data stock. (In other words, objects that are missing locally are created).

The LDAP client requests a paging version of all objects of the LDAP server. The client then receives back page by page (2 objects) per request. If necessary, objects in the local database are updated accordingly.

During this phase the following is shown in the status:

remote: Active
local: Completed

3rd phase notify

The third phase is the "notify" phase, in which there is no longer an open delta between the two sources, and future changes are synchronised. In this phase, a permanent TCP connection exists between the LDAP client and the LDAP server and is used for the LDAP server to notify the LDAP client when a change has occurred so that the client can create or update the record in the local database.

During this phase, the status will show the following:

remote: Completed
local: Completed

It is important to note that:

• if a problem occurs (e.g. due to the interruption of a phase or e.g. loss of the TCP connection to the LDAP server) the synchronisation starts again from the first phase ("local")
• the local attribute usn will not be replicated. Each ldap node manages its own local usn
• if you use a configured Poll Timer the notify feature will not be used in this ldap session

Algorithmic and Technical Details

This section covers details the incremental replication is based on, enabling the transition from full- to incremental replication and back from incremental- to full replication.

epoch

The master's Root DSE contains or does not contain an attribute epoch, reflecting the GUID attribute of an existing object by the name _admin_. A slave must permanently store the epoch as a persistent VARiable epoch.

• Slave connects and BINDs to master
• Slave requests Root DSE from master
• Slave evalutates epoch
  • epoch is not present
    • =>Full replication
    • Store copy of epoch
  • epoch is present
    • epoch matches slave's copy
      • =>Incremental replication
    • epoch does not match slave's copy
      • Delete copy of epoch
      • =>Full replication
      • Store copy of epoch
• Slave, persistent epoch storage
  • Variable: LREPI/epoc-r/cn=PBX0

USN Processing

Every object features the attribute USN. A slave keeps track of the highest USN seen within all objects rx'ed from a master.

• Slave checks USN for objects rx'ed from master
  • No local record of a highest USN
    • =>Store current USN as highest USN
  • Local copy of highest USN existing
    • RX'ed USN greater than local USN copy
      • =>Store current USN as highest USN
    • RX'ed USN less or equal than local USN copy
      • =>NOP, nothing to be done

• Slave, persistent USN storage
  • Replication completed - at the end of a full or incremental replication. Also, when rx'ing notify search results from a master.
    • =>Persistently storing the volatile memorized highest USN
  • Variable: LREPI/u-r/cn=PBX0

Paging

Incremental paging requires an additional filter term spedifying a USN value.

• 1st Search
  • Slave
    • Filter (&(objectclass=*)(usn>=103)) The USN-Term contains the highest USN rx'ed during last replication run, plus 1.
    • Cookie <empty>
  • Server
    • Evaluate (usn>=103) and set cursor at corresponding item
    • Replies with entries and non-empty(more) or empty(final) cookie

• 2nd Search,..
  • Slave
    • Filter (objectclass=*)
    • Cookie <Last Cookie content rx'ed from server>
  • Server
    • Evaluate cookie and set cursor at corresponding item
    • Replies with entries and non-empty(more) or empty(final) cookie

Root DSE

Because of the Flash Directory also exporting some infos into the Root DSE it probably makes sense to inform there about the current GUID of the _admin_ object. Following excerpt represents this by an attribute epoch. A slave can comfortably compare this to its copy of the epoch last seen.

Getting 1 entries:
>> Dn: 
	1> epoch: 0B1581AF783F67018F170050568214B4; 
..
	1> ldapServiceName: IP6013-50-00-68; 

VARs

Noteable variables for persistent storage of some replication control data within a slave's VARs section.

LDAP Replication, remote highest USN

vars create LREPI/u-r/cn=PBX0 p 102
..
vars create LREPI/u-r/cn=KBX0 p 105

LDAP Replication, remote last seen epoch

vars create LREPI/epoc-r/cn=KPBX0 pb 5238705224c067016fd10090334117be
..
vars create LREPI/epoc-r/cn=PBX0 pb 5238705224c067016fd10090334117be

Restore on Master

A mechanism provides information by a replication master to replication slaves that a full replication run shall take place. That mechanism gets triggered by an upload of a configuration to a master. A restore of an older configuration on a master causes a new GUID for the object with the name _ADMIN_.

• A new configuration is going to be uploaded
• The Flash Directory processes the module command

  mod cmd FLASHDIR0 erase-all

  • The FLASH Directory erases it's entire database, awaiting further commands
• The FLASH Directory processes a module command

  mod cmd FLASHDIR0 add-item 102 (cn=_ADMIN_)..(guid;bin=5238705224C067016FD10090334117BE)

  • This is the Admin object. Before being stored, it will now get assigned a new random GUID
• The Admin object's new GUID gets now promoted as the new epoch for the master's database. Replication slave's are supposed to detect a change of the DB's epoch and to replicate in full.

Detecting Obsolete Objects

Objects with the isDeleted attribute, a.k.a. tombstones, shall persist ideally forever. In practice tombstones get erased after a timeout. Only the most recent tombstone (tombstone with highest USN) remains.

Current tombstone timeout

48 hours

Behaviour during Full Replication

The local phase takes place in full. The replicator pages over all local objects and compares them with the master to see if they are still present.

Behaviour during Incremental Replication

The local phase is completely eliminated, respectively skipped.