Request control MUST be specified as follows:
updateType - MUST be set to syncOnly or syncAndPersist
sendCookieInterval - MAY be set
scheme - MAY be set - if set, the server MUST use this
specified scheme or return lcupUnsupportedScheme
(see above) - if not set, the server MAY use any
scheme it supports.
cookie - MUST NOT be set
If the request was successful, the client will receive results as
described in the section "LCUP Search Responses" below.
4.1.2. Incremental or Update Synchronization
For an incremental or update synchronization, the fields of the Sync
Request control MUST be specified as follows:
updateType - MUST be set to syncOnly or syncAndPersist
sendCookieInterval - MAY be set
scheme - MUST be set
cookie - MUST be set
The client SHOULD always use the latest cookie it received from the
server.
If the request was successful, the client will receive results as
described in the section "LCUP Search Responses" below.
4.1.3. Persistent Only
For persistent only search request, the fields of the Sync Request
MUST be specified as follows:
updateType - MUST be set to persistOnly
sendCookieInterval - MAY be set
scheme - MAY be set - if set, the server MUST use this
specified scheme or return
lcupUnsupportedScheme (see above) - if not set,
the server MAY use any scheme it supports.
cookie - MAY be set, but the server MUST ignore it
If the request was successful, the client will receive results as
described in the section "LCUP Search Responses" below.
4.2. LCUP Search Responses
In response to the client’s LCUP request, the server returns zero or
more SearchResultEntry or SearchResultReference PDUs that fit the
client’s specification, followed by a SearchResultDone PDU. The
behavior is as specified in [RFC2251 Section 4.5]. Each
SearchResultEntry or SearchResultReference PDU also contains a Sync
Update control that describes the LCUP state of the returned entry.
The SearchResultDone PDU contains a Sync Done control. The following
sections specify behaviors in addition to [RFC2251 Section 4.5].
4.2.1 Sync Update Informational Responses
The server may use the Sync Update control to return information not
related to a particular entry. It MAY do this at any time to return
a cookie to the client, or to inform the client that the sync phase
of a syncAndPersist search is complete and the persist phase has
begun. It MAY do this during the persist phase even though no entry
has changed that would have normally triggered a response. In order
to do this, it is REQUIRED to return the following:
- A SearchResultEntry PDU with the objectName field set to the DN of
the baseObject of the search request and with an empty attribute
list.
- A Sync Update control value with the fields set to the following:
stateUpdate - MUST be set to TRUE
entryUUID - SHOULD be set to the UUID of the baseObject of the
search request
entryLeftSet - MUST be set to FALSE
persistPhase - MUST be FALSE if the search is in the sync phase of a
request, and MUST be TRUE if the search is in the
persist phase
UUIDAttribute - SHOULD only be set if this is either the first result
returned or if the attribute has changed
scheme - MUST be set if the cookie is set and the cookie
format has changed; otherwise, it MAY be omitted
cookie - SHOULD be set
If the server merely wants to return a cookie to the client, it
should return as above with the cookie field set.
During a syncAndPersist request, the server MUST return (as above)
immediately after the last entry of the sync phase has been sent and
before the first entry of the persist phase has been sent. In this
case, the persistPhase field MUST be set to TRUE. This allows the
client to know that the sync phase is complete and the persist phase
is starting.
4.2.2 Cookie Return Frequency
The cookie field of the Sync Update control value MAY be set in any
returned result, during both the sync phase and the persist phase.
The server should return the cookie to the client often enough for
the client to resync in a reasonable period of time in case the
search is disconnected or otherwise terminated. The
sendCookieInterval field in the Sync Request control is a suggestion
to the server of how often to return the cookie in the Sync Update
control. The server SHOULD respect this value.
The scheme field of the Sync Update control value MUST be set if the
cookie is set and the cookie format has changed; otherwise, it MAY be
omitted.
Some clients may have unreliable connections, for example, a wireless
device or a WAN connection. These clients may want to insure that
the cookie is returned often in the Sync Update control value, so
that if they have to reconnect, they do not have to process many
redundant entries. These clients should set the sendCookieInterval
in the Sync Request control value to a low number, perhaps even 1.
Some clients may have a limited bandwidth connection, and may not
want to receive the cookie very often, or even at all (however, the
cookie is always sent back in the Sync Done control value upon
successful completion). These clients should set the
sendCookieInterval in the Sync Request control value to a high
number.
A reasonable behavior of the server is to return the cookie only when
data in the LCUP context has changed, even if the client has
specified a frequent sendCookieInterval. If nothing has changed, the
server can probably save some bandwidth by not returning the cookie.
4.2.3. Definition of an Entry That Has Entered the Result Set
An entry SHALL BE considered to have entered the client’s search
result set if one of the following conditions is met:
- During the sync phase for an incremental sync operation, the entry
is present in the search result set but was not present before;
this can be due to the entry being added via an LDAP Add
operation, or by the entry being moved into the result set by an
LDAP Modify DN operation, or by some modification to the entry
that causes it to enter the result set (e.g., adding an attribute
value that matches the clients search filter), or by some meta-
data change that causes the entry to enter the result set (e.g.,
relaxing of some access control that permits the entry to be
visible to the client).
- During the persist phase for a persistent search operation, the
entry enters the search result set; this can be due to the entry
being added via an LDAP Add operation, or by the entry being moved
into the result set by an LDAP Modify DN operation, or by some
modification to the entry that causes it to enter the result set
(e.g., adding an attribute value that matches the clients search
filter), or by some meta-data change that causes the entry to
enter the result set (e.g., relaxing of some access control that
permits the entry to be visible to the client).
4.2.4. Definition of an Entry That Has Changed
An entry SHALL BE considered to be changed if one or more of the
attributes in the attribute list in the search request have been
modified. For example, if the search request listed the attributes
"cn sn uid", and there is an entry in the client’s search result set
with the "cn" attribute that has been modified, the entry is
considered to be modified. The modification may be due to an LDAP
Modify operation or by some change to the meta-data for the entry
(e.g., virtual attributes) that causes some change to the value of
the specified attributes.
The converse of this is that an entry SHALL NOT BE considered to be
changed if none of the attributes in the attribute list of the search
request are modified attributes of the entry. For example, if the
search request listed the attributes "cn sn uid", and there is an
entry in the client’s search result set with the "foo" attribute that
has been modified, and none of the "cn" or "sn" or "uid" attributes
have been modified, the entry is NOT considered to be changed.
4.2.5. Definition of an Entry That Has Left the Result Set
An entry SHALL BE considered to have left the client’s search result
set if one of the following conditions is met:
- During the sync phase for an incremental sync operation, the entry
is not present in the search result set but was present before;
this can be due to the entry being deleted via an LDAP Delete
operation, or by the entry leaving the result set via an LDAP
Modify DN operation, or by some modification to the entry that
causes it to leave the result set (e.g., changing/removing an
attribute value so that it no longer matches the client’s search
filter), or by some meta-data change that causes the entry to
leave the result set (e.g., adding of some access control that
denies the entry to be visible to the client).
- During the persist phase for a persistent search operation, the
entry leaves the search result set; this can be due to the entry
being deleted via an LDAP Delete operation, or by the entry
leaving the result set via an LDAP Modify DN operation, or by some
modification to the entry that causes it to leave the result set
(e.g., changing/removing an attribute value so that it no longer
matches the client’s search filter), or by some meta-data change
that causes the entry to leave the result set (e.g., adding of
some access control that denies the entry to be visible to the
client).
4.2.6. Results For Entries Present in the Result Set
An entry SHOULD be returned as present under the following
conditions:
- The request is an initial synchronization or full resync request
and the entry is present in the client’s search result set
- The request is an incremental synchronization and the entry has
changed or entered the result set since the last sync
- The search is in the persist phase and the entry enters the result
set or changes
For a SearchResultEntry return, the fields of the Sync Update control
value MUST be set as follows:
stateUpdate - MUST be set to FALSE
entryUUID - MUST be set to the UUID of the entry
entryLeftSet - MUST be set to FALSE
persistPhase - MUST be set to FALSE if during the sync phase or TRUE
if during the persist phase
UUIDAttribute - SHOULD only be set if this is either the first result
returned or if the attribute has changed
scheme - as above
cookie - as above
The searchResultReference return will look the same, except that the
entryUUID is not required. If it is specified, it MUST contain the
UUID of the DSE holding the reference knowledge.
4.2.7. Results For Entries That Have Left the Result Set
An entry SHOULD be returned as having left the result set under the
following conditions:
- The request is an incremental synchronization during the sync
phase and the entry has left the result set
- The search is in the persist phase and the entry has left the
result set
- The entry has left the result set as a result of an LDAP Delete or
LDAP Modify DN operation against the entry itself (i.e., not as a
result of an operation against its parent or ancestor)
For a SearchResultEntry return where the entry has left the result
set, the fields of the Sync Update control value MUST be set as
follows:
stateUpdate - MUST be set to FALSE
entryUUID - MUST be set to the UUID of the entry that left the
result set
entryLeftSet - MUST be set to TRUE
persistPhase - MUST be set to FALSE if during the sync phase or TRUE
if during the persist phase
UUIDAttribute - SHOULD only be set if this is either the first result
returned or if the attribute has changed
scheme - as above
cookie - as above
The searchResultReference return will look the same, except that the
entryUUID is not required. If it is specified, it MUST contain the
UUID of the DSE holding the reference knowledge.
Some server implementations keep track of deleted entries using a
tombstone - a hidden entry that keeps track of the state, but not all
of the data, of an entry that has been deleted. In this case, the
tombstone may not contain all of the original attributes of the
entry, and therefore it may be impossible for the server to determine
if an entry should be removed from the result set based on the
attributes in the client’s search request. Servers SHOULD keep
enough information about the attributes in the deleted entries to
determine if an entry should be removed from the result set. Since
this may not be possible, the server MAY return an entry as having
left the result set even if it is not or never was in the client’s
result set. Clients MUST ignore these notifications.
4.3. Responses Requiring Special Consideration
The following sections describe special handling that may be required
when returning results.
4.3.1. Returning Results During the Persistent Phase
During the persistent phase, the server SHOULD return the changed
entries to the client as quickly as possible.
4.3.2. No Mixing of Sync Phase with Persist Phase
During a sync phase, the server MUST NOT return any entries with the
persistPhase flag set to TRUE, and during the persist phase, all
entries returned MUST have the persistPhase flag set to TRUE. The
server MUST NOT mix and match sync phase entries with persist phase
entries. If there are any sync phase entries to return, they MUST be
returned before any persist phase entries are returned.
4.3.3. Returning Updated Results During the Sync Phase
There may be updates to the entries in the result set of a sync phase
search during the actual search operation. If the DSA is under a
heavy update load, and it attempts to send all of those updated
entries to the client in addition to the other updates it was already
planning to send for the sync phase, the server may never get to the
end of the sync phase. Therefore, it is left up to the discretion of
the server implementation to decide when the client is "in sync" -
that is, when to end a syncOnly request, or when to send the Sync
Update Informational Response between the sync phase and the persist
phase of a syncAndPersist request. The server MAY send the same
entry multiple times during the sync phase if the entry changes
during the sync phase.
A reasonable behavior is for the server to generate a cookie based on
the server state at the time the client initiated the LCUP request,
and only send entries up to that point during the sync phase. Entries
updated after that point will be returned only during the persist
phase of a syncAndPersist request, or only upon an incremental
synchronization.
4.3.4. Operational Attributes and Administrative Entries
An operational attribute SHOULD be returned if it is specified in the
attributes list and would normally be returned as subject to the
constraints of [RFC2251 Section 4.5]. If the server does not support
syncing of operational attributes, the server MUST return a
SearchResultDone message with a resultCode of unwillingToPerform.
LDAP Subentries [RFC3672] SHOULD be returned if they would normally
be returned by the search request. If the server does not support
syncing of LDAP Subentries, and the server can determine from the
search request that the client has requested LDAP Subentries to be
returned (e.g., search control or search filter), the server MUST
return a SearchResultDone message with a resultCode of
unwillingToPerform. Otherwise, the server MAY simply omit returning
LDAP Subentries.
4.3.5. Virtual Attributes
An entry may have attributes whose presence in the entry, or presence
of values of the attribute, is generated on the fly, possibly by some
mechanism outside of the entry, elsewhere in the DIT. An example of
this is collective attributes [RFC3671]. These attributes shall be
referred to in this document as virtual attributes.
LCUP treats these attributes the same way as normal, non-virtual
attributes. A virtual attribute SHOULD be returned if it is
specified in the attributes list and would normally be returned as
subject to the constraints of [RFC2251 Section 4.5]. If the server
does not support syncing of virtual attributes, the server MUST
return a SearchResultDone message with a resultCode of
unwillingToPerform.
One consequence of this is that if you change the definition of a
virtual attribute such that it makes the value of that attribute
change in many entries in the client’s search scope, this means that
a server may have to return many entries to the client as a result of
that one change. It is not anticipated that this will be a frequent
occurrence, and the server has the option to simply force the client
to resync if necessary.
It is also possible that a future LDAP control will allow the client
to request only virtual or only non-virtual attributes.
4.3.6. Modify DN and Delete Operations Applied to Subtrees
There is a special case where a Modify DN or a Delete operation is
applied to the base entry of a subtree, and either that base entry or
entries in the subtree are within the scope of an LCUP search
request. In this case, all of the entries in the subtree are
implicitly renamed or removed.
In either of these cases, the server MUST do one of the following:
- treat all of these entries as having been renamed or removed and
return each entry to the client as such
- decide that this would be prohibitively expensive, and force the
client to resync
If the search base object has been renamed, and the client has
received a noSuchObject as the result of a search request, the client
MAY use the entryUUID and UUIDAttribute to locate the new DN that is
the result of the modify DN operation.
4.3.7. Convergence Guarantees
If at any time during an LCUP search, either during the sync phase or
the persist phase, the server determines that it cannot guarantee
that it can bring the client’s copy of the data to eventual
convergence, it SHOULD immediately terminate the LCUP search request
and return a SearchResultDone message with a resultCode of
lcupReloadRequired. This can also happen at the beginning of an
incremental synchronization request, if the client presents a cookie
that is out of date or otherwise unable to be processed. The client
should then issue an initial synchronization request.
This can happen, for example, if the data on the server is reloaded,
or if there has been some change to the meta-data that makes it
impossible for the server to determine if a particular entry should
or should not be part of the search result set, or if the meta-data
change makes it too resource intensive for the server to calculate
the proper result set.
The server can also return lcupReloadRequired if it determines that
it would be more efficient for the client to perform a reload, for
example, if too many entries have changed and a simple reload would
be much faster.
4.4. LCUP Search Termination
4.4.1. Server Initiated Termination
When the server has successfully finished processing the client’s
request, it attaches a Sync Done control to the SearchResultDone
message and sends it to the client. However, if the SearchResultDone
message contains a resultCode that is not success or canceled, the
Sync Done control MAY be omitted. Although the LCUP cookie is
OPTIONAL in the Sync Done control value, it MUST be set if the
SearchResultDone resultCode is success or canceled. The server
SHOULD also set the cookie if the resultCode is
lcupResourcesExhausted, timeLimitExceeded, sizeLimitExceeded, or
adminLimitExceeded. This allows the client to more easily resync
later. If some error occurred, either an LDAP search error (e.g.,
insufficientAccessRights) or an LCUP error (e.g.,
lcupUnsupportedScheme), the cookie MAY be omitted. If the cookie is
set, the scheme MUST be set also if the cookie format has changed,
otherwise, it MAY be omitted.
If server resources become tight, the server can terminate one or
more search operations by sending a SearchResultDone message to the
client(s) with a resultCode of lcupResourcesExhausted. The server
SHOULD attach a Sync Done control with the cookie set. A server side
policy is used to decide which searches to terminate. This can also
be used as a security mechanism to disconnect clients that are
suspected of malicious actions, but if the server can infer that the
client is malicious, the server SHOULD return lcupSecurityViolation
instead.
4.4.2. Client Initiated Termination
If the client needs to terminate the synchronization process and it
wishes to obtain the cookie that represents the current state of its
data, it issues an LDAP Cancel operation [RFC3909]. The server
responds immediately with a LDAP Cancel response [RFC3909]. The
server MAY send any pending SearchResultEntry or
SearchResultReference PDUs if the server cannot easily abort or
remove those search results from its outgoing queue. The server
SHOULD send as few of these remaining messages as possible. Finally,
the server sends the message SearchResultDone with the Sync Done
control attached. If the search was successful up to that point, the
resultCode field of the SearchResultDone message MUST be canceled
[RFC3909], and the cookie MUST be set in the Sync Done control. If
there is an error condition, the server MAY return as described in
section 4.4.1 above, or MAY return as described in [RFC3909].
If the client is not interested in the state information, it can
simply abandon the search operation or disconnect from the server.
4.5. Size and Time Limits
The server SHALL support size and time limits as specified in
[RFC2251, Section 5]. The server SHOULD ensure that if the operation
is terminated due to these conditions, the cookie is sent back to the
client.
4.6. Operations on the Same Connection
It is permissible for the client to issue other LDAP operations on
the connection used by the protocol. Since each LDAP
request/response carries a message id there will be no ambiguity
about which PDU belongs to which operation. By sharing the
connection among multiple operations, the server will be able to
conserve its resources.
4.7. Interactions with Other Controls
LCUP defines neither restrictions nor guarantees about the ability to
use the controls defined in this document in conjunction with other