synchronization state of the client copy, the server SHALL return the
initial content.
A Synchronization Session may span multiple LDAP sessions between the
client and the server. The client SHOULD issue each Sync request of
a session to the same server. (Note: Shadowing considerations are
discussed in Section 6.)
3.2. Content Determination
The content to be provided is determined by parameters of the Search
Request, as described in [RFC4511], and possibly other controls. The
same content parameters SHOULD be used in each Sync request of a
session. If different content is requested and the server is
unwilling or unable to process the request, the server SHALL return
the initial content as if no cookie had been provided or return an
empty content with the e-syncRefreshRequired LDAP result code. The
decision between the return of the initial content and the return of
the empty content with the e-syncRefreshRequired result code MAY be
based on reloadHint in the Sync Request Control from the client.
The content may not necessarily include all entries or references
that would be returned by a normal search operation, nor, for those
entries included, all attributes returned by a normal search. When
the server is unwilling or unable to provide synchronization for any
attribute for a set of entries, the server MUST treat all filter
components matching against these attributes as Undefined and MUST
NOT return these attributes in SearchResultEntry responses.
Servers SHOULD support synchronization for all non-collective user-
application attributes for all entries.
The server may also return continuation references to other servers
or to itself. The latter is allowed as the server may partition the
entries it holds into separate synchronization contexts.
The client may chase all or some of these continuations, each as a
separate content synchronization session.
3.3. refreshOnly Mode
A Sync request with mode refreshOnly and with no cookie is a poll for
initial content. A Sync request with mode refreshOnly and with a
cookie representing a synchronization state is a poll for content
update.
3.3.1. Initial Content Poll
Upon receipt of the request, the server provides the initial content
using a set of zero or more SearchResultEntry and
SearchResultReference Messages followed by a SearchResultDone
Message.
Each SearchResultEntry Message SHALL include a Sync State Control of
state add, an entryUUID containing the entry’s UUID, and no cookie.
Each SearchResultReference Message SHALL include a Sync State Control
of state add, an entryUUID containing the UUID associated with the
reference (normally the UUID of the associated named referral
[RFC3296] object), and no cookie. The SearchResultDone Message SHALL
include a Sync Done Control having refreshDeletes set to FALSE.
A resultCode value of success indicates that the operation
successfully completed. Otherwise, the result code indicates the
nature of the failure. The server may return e-syncRefreshRequired
result code on the initial content poll if it is safe to do so when
it is unable to perform the operation due to various reasons.
reloadHint is set to FALSE in the SearchRequest Message requesting
the initial content poll.
If the operation is successful, a cookie representing the
synchronization state of the current client copy SHOULD be returned
for use in subsequent Sync Operations.
3.3.2. Content Update Poll
Upon receipt of the request, the server provides the content refresh
using a set of zero or more SearchResultEntry and
SearchResultReference Messages followed by a SearchResultDone
Message.
The server is REQUIRED to:
a) provide the sequence of messages necessary for eventual
convergence of the client’s copy of the content to the server’s
copy,
b) treat the request as an initial content request (e.g., ignore
the cookie or the synchronization state represented in the
cookie),
c) indicate that the incremental convergence is not possible by
returning e-syncRefreshRequired,
d) return a resultCode other than success or e-
syncRefreshRequired.
A Sync Operation may consist of a single present phase, a single
delete phase, or a present phase followed by a delete phase.
In each phase, for each entry or reference that has been added to the
content or been changed since the previous Sync Operation indicated
by the cookie, the server returns a SearchResultEntry or
SearchResultReference Message, respectively, each with a Sync State
Control consisting of state add, an entryUUID containing the UUID of
the entry or reference, and no cookie. Each SearchResultEntry
Message represents the current state of a changed entry. Each
SearchResultReference Message represents the current state of a
changed reference.
In the present phase, for each entry that has not been changed since
the previous Sync Operation, an empty SearchResultEntry is returned
whose objectName reflects the entry’s current DN, whose attributes
field is empty, and whose Sync State Control consists of state
present, an entryUUID containing the UUID of the entry, and no
cookie. For each reference that has not been changed since the
previous Sync Operation, an empty SearchResultReference containing an
empty SEQUENCE OF LDAPURL is returned with a Sync State Control
consisting of state present, an entryUUID containing the UUID of the
entry, and no cookie. No messages are sent for entries or references
that are no longer in the content.
Multiple empty entries with a Sync State Control of state present
SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
value with refreshDeletes set to FALSE. syncUUIDs contain a set of
UUIDs of the entries and references unchanged since the last Sync
Operation. syncUUIDs may be empty. The Sync Info Message of
syncIdSet may contain a cookie to represent the state of the content
after performing the synchronization of the entries in the set.
In the delete phase, for each entry no longer in the content, the
server returns a SearchResultEntry whose objectName reflects a past
DN of the entry or is empty, whose attributes field is empty, and
whose Sync State Control consists of state delete, an entryUUID
containing the UUID of the deleted entry, and no cookie. For each
reference no longer in the content, a SearchResultReference
containing an empty SEQUENCE OF LDAPURL is returned with a Sync State
Control consisting of state delete, an entryUUID containing the UUID
of the deleted reference, and no cookie.
Multiple empty entries with a Sync State Control of state delete
SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
value with refreshDeletes set to TRUE. syncUUIDs contain a set of
UUIDs of the entries and references that have been deleted from the
content since the last Sync Operation. syncUUIDs may be empty. The
Sync Info Message of syncIdSet may contain a cookie to represent the
state of the content after performing the synchronization of the
entries in the set.
When a present phase is followed by a delete phase, the two phases
are delimited by a Sync Info Message containing syncInfoValue of
refreshPresent, which may contain a cookie representing the state
after completing the present phase. The refreshPresent contains
refreshDone, which is always FALSE in the refreshOnly mode of Sync
Operation because it is followed by a delete phase.
If a Sync Operation consists of a single phase, each phase and hence
the Sync Operation are marked as ended by a SearchResultDone Message
with Sync Done Control, which SHOULD contain a cookie representing
the state of the content after completing the Sync Operation. The
Sync Done Control contains refreshDeletes, which is set to FALSE for
the present phase and set to TRUE for the delete phase.
If a Sync Operation consists of a present phase followed by a delete
phase, the Sync Operation is marked as ended at the end of the delete
phase by a SearchResultDone Message with Sync Done Control, which
SHOULD contain a cookie representing the state of the content after
completing the Sync Operation. The Sync Done Control contains
refreshDeletes, which is set to TRUE.
The client can specify whether it prefers to receive an initial
content by supplying reloadHint of TRUE or to receive a e-
syncRefreshRequired resultCode by supplying reloadHint of FALSE
(hence absent), in the case that the server determines that it is
impossible or inefficient to achieve the eventual convergence by
continuing the current incremental synchronization thread.
A resultCode value of success indicates that the operation is
successfully completed. A resultCode value of e-syncRefreshRequired
indicates that a full or partial refresh is needed. Otherwise, the
result code indicates the nature of failure. A cookie is provided in
the Sync Done Control for use in subsequent Sync Operations for
incremental synchronization.
3.4. refreshAndPersist Mode
A Sync request with mode refreshAndPersist asks for initial content
or content update (during the refresh stage) followed by change
notifications (during the persist stage).
3.4.1. refresh Stage
The content refresh is provided as described in Section 3.3, except
that the successful completion of content refresh is indicated by
sending a Sync Info Message of refreshDelete or refreshPresent with a
refreshDone value set to TRUE instead of a SearchResultDone Message
with resultCode success. A cookie SHOULD be returned in the Sync
Info Message to represent the state of the content after finishing
the refresh stage of the Sync Operation.
3.4.2. persist Stage
Change notifications are provided during the persist stage.
As updates are made to the DIT, the server notifies the client of
changes to the content. DIT updates may cause entries and references
to be added to the content, deleted from the content, or modified
within the content. DIT updates may also cause references to be
added, deleted, or modified within the content.
Where DIT updates cause an entry to be added to the content, the
server provides a SearchResultEntry Message that represents the entry
as it appears in the content. The message SHALL include a Sync State
Control with state of add, an entryUUID containing the entry’s UUID,
and an optional cookie.
Where DIT updates cause a reference to be added to the content, the
server provides a SearchResultReference Message that represents the
reference in the content. The message SHALL include a Sync State
Control with state of add, an entryUUID containing the UUID
associated with the reference, and an optional cookie.
Where DIT updates cause an entry to be modified within the content,
the server provides a SearchResultEntry Message that represents the
entry as it appears in the content. The message SHALL include a Sync
State Control with state of modify, an entryUUID containing the
entry’s UUID, and an optional cookie.
Where DIT updates cause a reference to be modified within the
content, the server provides a SearchResultReference Message that
represents the reference in the content. The message SHALL include a
Sync State Control with state of modify, an entryUUID containing the
UUID associated with the reference, and an optional cookie.
Where DIT updates cause an entry to be deleted from the content, the
server provides a SearchResultEntry Message with no attributes. The
message SHALL include a Sync State Control with state of delete, an
entryUUID containing the entry’s UUID, and an optional cookie.
Where DIT updates cause a reference to be deleted from the content,
the server provides a SearchResultReference Message with an empty
SEQUENCE OF LDAPURL. The message SHALL include a Sync State Control
with state of delete, an entryUUID containing the UUID associated
with the reference, and an optional cookie.
Multiple empty entries with a Sync State Control of state delete
SHOULD be coalesced into one or more Sync Info Messages of syncIdSet
value with refreshDeletes set to TRUE. syncUUIDs contain a set of
UUIDs of the entries and references that have been deleted from the
content. The Sync Info Message of syncIdSet may contain a cookie to
represent the state of the content after performing the
synchronization of the entries in the set.
With each of these messages, the server may provide a new cookie to
be used in subsequent Sync Operations. Additionally, the server may
also return Sync Info Messages of choice newCookie to provide a new
cookie. The client SHOULD use the newest (last) cookie it received
from the server in subsequent Sync Operations.
3.5. Search Request Parameters
As stated in Section 3.1, the client SHOULD specify the same
content-controlling parameters in each Search Request of the session.
All fields of the SearchRequest Message are considered content-
controlling parameters except for sizeLimit and timeLimit.
3.5.1. baseObject
As with the normal search operation, the refresh and persist stages
are not isolated from DIT changes. It is possible that the entry
referred to by the baseObject is deleted, renamed, or moved. It is
also possible that the alias object used in finding the entry
referred to by the baseObject is changed such that the baseObject
refers to a different entry.
If the DIT is updated during processing of the Sync Operation in a
manner that causes the baseObject no longer to refer to any entry or
in a manner that changes the entry the baseObject refers to, the
server SHALL return an appropriate non-success result code, such as
noSuchObject, aliasProblem, aliasDereferencingProblem, referral, or
e-syncRefreshRequired.
3.5.2. derefAliases
This operation does not support alias dereferencing during searching.
The client SHALL specify neverDerefAliases or derefFindingBaseObj for
the SearchRequest derefAliases parameter. The server SHALL treat
other values (e.g., derefInSearching, derefAlways) as protocol
errors.
3.5.3. sizeLimit
The sizeLimit applies only to entries (regardless of their state in
Sync State Control) returned during the refreshOnly operation or the
refresh stage of the refreshAndPersist operation.
3.5.4. timeLimit
For a refreshOnly Sync Operation, the timeLimit applies to the whole
operation. For a refreshAndPersist operation, the timeLimit applies
only to the refresh stage including the generation of the Sync Info
Message with a refreshDone value of TRUE.
3.5.5. filter
The client SHOULD avoid filter assertions that apply to the values of
the attributes likely to be considered by the server as ones holding
meta-information. See Section 4.
3.6. objectName
The Sync Operation uses entryUUID values provided in the Sync State
Control as the primary keys to entries. The client MUST use these
entryUUIDs to correlate synchronization messages.
In some circumstances, the DN returned may not reflect the entry’s
current DN. In particular, when the entry is being deleted from the
content, the server may provide an empty DN if the server does not
wish to disclose the entry’s current DN (or, if deleted from the DIT,
the entry’s last DN).
Also note that the entry’s DN may be viewed as meta information (see
Section 4.1).
3.7. Canceling the Sync Operation
Servers MUST implement the LDAP Cancel [RFC3909] Operation and
support cancellation of outstanding Sync Operations as described
here.
To cancel an outstanding Sync Operation, the client issues an LDAP
Cancel [RFC3909] Operation.
If at any time the server becomes unwilling or unable to continue
processing a Sync Operation, the server SHALL return a
SearchResultDone with a non-success resultCode indicating the reason
for the termination of the operation.
Whether the client or the server initiated the termination, the
server may provide a cookie in the Sync Done Control for use in
subsequent Sync Operations.
3.8. Refresh Required
In order to achieve the eventually-convergent synchronization, the
server may terminate the Sync Operation in the refresh or persist
stages by returning an e-syncRefreshRequired resultCode to the
client. If no cookie is provided, a full refresh is needed. If a
cookie representing a synchronization state is provided in this
response, an incremental refresh is needed.
To obtain a full refresh, the client then issues a new
synchronization request with no cookie. To obtain an incremental
reload, the client issues a new synchronization with the provided
cookie.
The server may choose to provide a full copy in the refresh stage
(e.g., ignore the cookie or the synchronization state represented in
the cookie) instead of providing an incremental refresh in order to
achieve the eventual convergence.
The decision between the return of the initial content and the return
of the e-syncRefreshRequired result code may be based on reloadHint
in the Sync Request Control from the client.
In the case of persist stage Sync, the server returns the resultCode
of e-syncRefreshRequired to the client to indicate that the client
needs to issue a new Sync Operation in order to obtain a synchronized
copy of the content. If no cookie is provided, a full refresh is
needed. If a cookie representing a synchronization state is
provided, an incremental refresh is needed.
The server may also return e-syncRefreshRequired if it determines
that a refresh would be more efficient than sending all the messages
required for convergence.
Note that the client may receive one or more of SearchResultEntry,
SearchResultReference, and/or Sync Info Messages before it receives a
SearchResultDone Message with the e-syncRefreshRequired result code.
3.9. Chattiness Considerations
The server MUST ensure that the number of entry messages generated to
refresh the client content does not exceed the number of entries
presently in the content. While there is no requirement for servers
to maintain history information, if the server has sufficient history
to allow it to reliably determine which entries in the prior client
copy are no longer present in the content and the number of such
entries is less than or equal to the number of unchanged entries, the
server SHOULD generate delete entry messages instead of present entry
messages (see Section 3.3.2).
When the amount of history information maintained in the server is
not enough for the clients to perform infrequent refreshOnly Sync
Operations, it is likely that the server has incomplete history
information (e.g., due to truncation) by the time those clients
connect again.
The server SHOULD NOT resort to full reload when the history
information is not enough to generate delete entry messages. The
server SHOULD generate either present entry messages only or present
entry messages followed by delete entry messages to bring the client
copy to the current state. In the latter case, the present entry
messages bring the client copy to a state covered by the history
information maintained in the server.
The server SHOULD maintain enough (current or historical) state
information (such as a context-wide last modify time stamp) to
determine if no changes were made in the context since the content
refresh was provided and, when no changes were made, generate zero
delete entry messages instead of present messages.
The server SHOULD NOT use the history information when its use does
not reduce the synchronization traffic or when its use can expose
sensitive information not allowed to be received by the client.
The server implementor should also consider chattiness issues that
span multiple Sync Operations of a session. As noted in Section 3.8,
the server may return e-syncRefreshRequired if it determines that a
reload would be more efficient than continuing under the current
operation. If reloadHint in the Sync Request is TRUE, the server may
initiate a reload without directing the client to request a reload.
The server SHOULD transfer a new cookie frequently to avoid having to
transfer information already provided to the client. Even where DIT
changes do not cause content synchronization changes to be
transferred, it may be advantageous to provide a new cookie using a
Sync Info Message. However, the server SHOULD avoid overloading the
client or network with Sync Info Messages.
During persist mode, the server SHOULD coalesce multiple outstanding
messages updating the same entry. The server MAY delay generation of
an entry update in anticipation of subsequent changes to that entry
that could be coalesced. The length of the delay should be long
enough to allow coalescing of update requests issued back to back but
short enough that the transient inconsistency induced by the delay is
corrected in a timely manner.
The server SHOULD use the syncIdSet Sync Info Message when there are
multiple delete or present messages to reduce the amount of
synchronization traffic.
Also note that there may be many clients interested in a particular
directory change, and that servers attempting to service all of these
at once may cause congestion on the network. The congestion issues
are magnified when the change requires a large transfer to each
interested client. Implementors and deployers of servers should take
steps to prevent and manage network congestion.
3.10. Operation Multiplexing
The LDAP protocol model [RFC4511] allows operations to be multiplexed
over a single LDAP session. Clients SHOULD NOT maintain multiple
LDAP sessions with the same server. Servers SHOULD ensure that
responses from concurrently processed operations are interleaved
fairly.
Clients SHOULD combine Sync Operations whose result set is largely
overlapping. This avoids having to return multiple messages, once
for each overlapping session, for changes to entries in the overlap.
Clients SHOULD NOT combine Sync Operations whose result sets are
largely non-overlapping. This ensures that an event requiring an
e-syncRefreshRequired response can be limited to as few result sets
as possible.
4. Meta Information Considerations
4.1. Entry DN
As an entry’s DN is constructed from its relative DN (RDN) and the
entry’s parent’s DN, it is often viewed as meta information.
While renaming or moving to a new superior causes the entry’s DN to
change, that change SHOULD NOT, by itself, cause synchronization
messages to be sent for that entry. However, if the renaming or the
moving could cause the entry to be added or deleted from the content,
appropriate synchronization messages should be generated to indicate
this to the client.
When a server treats the entry’s DN as meta information, the server
SHALL either
- evaluate all MatchingRuleAssertions [RFC4511] to TRUE if
matching a value of an attribute of the entry, otherwise
Undefined, or
- evaluate all MatchingRuleAssertion with dnAttributes of TRUE as
Undefined.
The latter choice is offered for ease of server implementation.
4.2. Operational Attributes
Where values of an operational attribute are determined by values not
held as part of the entry it appears in, the operational attribute
SHOULD NOT support synchronization of that operational attribute.
For example, in servers that implement the X.501 subschema model
[X.501], servers should not support synchronization of the
subschemaSubentry attribute as its value is determined by values held
and administrated in subschema subentries.
As a counter example, servers that implement aliases [RFC4512][X.501]
can support synchronization of the aliasedObjectName attribute as its
values are held and administrated as part of the alias entries.
Servers SHOULD support synchronization of the following operational
attributes: createTimestamp, modifyTimestamp, creatorsName,
modifiersName [RFC4512]. Servers MAY support synchronization of
other operational attributes.
4.3. Collective Attributes
A collective attribute is "a user attribute whose values are the same
for each member of an entry collection" [X.501]. Use of collective
attributes in LDAP is discussed in [RFC3671].
Modification of a collective attribute generally affects the content
of multiple entries, which are the members of the collection. It is
inefficient to include values of collective attributes visible in
entries of the collection, as a single modification of a collective
attribute requires transmission of multiple SearchResultEntry (one
for each entry of the collection that the modification affected).
Servers SHOULD NOT synchronize collective attributes appearing in
entries of any collection. Servers MAY support synchronization of