LDAP controls, except for the following: A server MAY ignore non-
critical controls supplied with the LCUP control. A server MAY
ignore an LCUP defined control if it is non-critical and it is
supplied with other critical controls. If a server receives a
critical LCUP control with another critical control, and the server
does not support both controls at the same time, the server SHOULD
return unavailableCriticalExtension.
It is up to the server implementation to determine if the server
supports controls such as the Sort or VLV or similar controls that
change the order of the entries sent to the client. But note that it
may be difficult or impossible for a server to perform an incremental
synchronization in the presence of such controls, since the cookie
will typically be based off a change number, or Change Sequence
Number (CSN), or timestamp, or some criteria other than an
alphabetical order.
4.8. Replication Considerations
Use of an LCUP cookie with multiple DSAs in a replicated environment
is not defined by LCUP. An implementation of LCUP may support
continuation of an LCUP session with another DSA holding a replica of
the LCUP context. Clients MAY submit cookies returned by one DSA to
a different DSA; it is up to the server to determine if a cookie is
one they recognize or not and to return an appropriate result code if
not.
5. Client Side Considerations
5.1. Using Cookies with Different Search Criteria
The cookie received from the server after a synchronization session
SHOULD only be used with the same search specification as the search
that generated the cookie. Some servers MAY allow the cookie to be
used with a more restrictive search specification than the search
that generated the cookie. If the server does not support the
cookie, it MUST return lcupInvalidCookie. This is because the client
can end up with an incomplete data store otherwise. A more
restrictive search specification is one that would generate a subset
of the data produced by the original search specification.
5.2. Renaming the Base Object
Because an LCUP client specifies the area of the tree with which it
wishes to synchronize through the standard LDAP search specification,
the client can be returned noSuchObject error if the root of the
synchronization area was renamed between the synchronization sessions
or during a synchronization session. If this condition occurs, the
client can attempt to locate the root by using the root’s UUID saved
in client’s local data store. It then can repeat the synchronization
request using the new search base. In general, a client can detect
that an entry was renamed and apply the changes received to the right
entry by using the UUID rather than DN based addressing.
5.3. Use of Persistent Searches With Respect to Resources
Each active persistent operation requires that an open TCP connection
be maintained between an LDAP client and an LDAP server that might
not otherwise be kept open. Therefore, client implementors are
encouraged to avoid using persistent operations for non-essential
tasks and to close idle LDAP connections as soon as practical. The
server may close connections if server resources become tight.
5.4. Continuation References to Other LCUP Contexts
The client MAY receive a continuation reference
(SearchResultReference [RFC2251 SECTION 4.5.3]) if the search request
spans multiple parts of the DIT, some of which may require a
different LCUP cookie, some of which may not even be managed by LCUP.
The client SHOULD maintain a cache of the LDAP URLs returned in the
continuation references and the cookies associated with them. The
client is responsible for performing another LCUP search to follow
the references, and SHOULD use the cookie corresponding to the LDAP
URL for that reference (if it has a cookie).
5.5. Referral Handling
The client may receive a referral (Referral [RFC2251 SECTION 4.1.11])
when the search base is a subordinate reference, and this will end
the operation.
5.6. Multiple Copies of Same Entry During Sync Phase
The server MAY send the same entry multiple times during a sync phase
if the entry changes during the sync phase. The client SHOULD use
the last sent copy of the entry as the current one.
5.7. Handling Server Out of Resources Condition
If the client receives an lcupResourcesExhausted or
lcupSecurityViolation resultCode, the client SHOULD wait at least 5
seconds before attempting another operation. It is RECOMMENDED that
the client use an exponential backoff strategy, but different clients
may want to use different backoff strategies.
6. Server Implementation Considerations
6.1. Server Support for UUIDs
Servers MUST support UUIDs. UUIDs are required in the Sync Update
control. Additionally, server implementers SHOULD make the UUID
values for the entries available as an attribute of the entry, and
provide indexing or other mechanisms to allow clients to search for
an entry using the UUID attribute in the search filter. The
syncUpdate control provides a field UUIDAttribute to allow the server
to let the client know the name or OID of the attribute to use to
search for an entry by UUID.
6.2. Example of Using an RUV as the Cookie Value
By design, the protocol supports multiple cookie schemes. This is to
allow different implementations the flexibility of storing any
information applicable to their environment. A reasonable
implementation for an LDUP compliant server would be to use the
Replica Update Vector (RUV). For each master, RUV contains the
largest CSN seen from this master. In addition, RUV implemented by
some directory servers (not yet in LDUP) contains replica generation
- an opaque string that identifies the replica’s data store. The
replica generation value changes whenever the replica’s data is
reloaded. Replica generation is intended to signal the
replication/synchronization peers that the replica’s data was
reloaded and that all other replicas need to be reinitialized. RUV
satisfies the three most important properties of the cookie: (1) it
uniquely identifies the state of client’s data, (2) it can be used to
synchronize with multiple servers, and (3) it can be used to detect
that the server’s data was reloaded. If RUV is used as the cookie,
entries last modified by a particular master must be sent to the
client in the order of their last modified CSN. This ordering
guarantees that the RUV can be updated after each entry is sent.
6.3. Cookie Support Issues
6.3.1. Support for Multiple Cookie Schemes
A server may support one or more LCUP cookie schemes. It is expected
that schemes will be published along with their OIDs as RFCs. The
server’s DIT may be partitioned into different sections which may
have different cookies associated with them. For example, some
servers may use some sort of replication mechanism to support LCUP.
If so, the DIT may be partitioned into multiple replicas. A client
may send an LCUP search request that spans multiple replicas. Some
parts of the DIT spanned by the search request scope may support LCUP
and some may not. The server MUST send a SearchResultReference
[RFC2251, SECTION 4.5.3] when the LCUP Context for a returned entry
changes. The server SHOULD send all references to other LCUP
Contexts in the search scope first, in order to allow the clients to
process these searches in parallel. The LDAP URL(s) returned MUST
contain the DN(s) of the base of another section of the DIT (however
the server implementation has partitioned the DIT). The client will
then issue another LCUP search using the LDAP URL returned. Each
section of the DIT MAY require a different cookie value, so the
client SHOULD maintain a cache, mapping the different LDAP URL values
to different cookies. If the cookie changes, the scheme may change
as well, but the cookie scheme MUST be the same within a given LCUP
Context.
6.3.2. Information Contained in the Cookie
The cookie must contain enough information to allow the server to
determine whether the cookie can be safely used with the search
specification it is attached to. As discussed earlier in the
document, the cookie SHOULD only be used with the search
specification that is equal to the one for which the cookie was
generated, but some servers MAY support using a cookie with a search
specification that is more restrictive than the one used to generate
the cookie.
6.4. Persist Phase Response Time
The specification makes no guarantees about how soon a server should
send notification of a changed entry to the client during the persist
phase. This is intentional as any specific maximum delay would be
impossible to meet in a distributed directory service implementation.
Server implementers are encouraged to minimize the delay before
sending notifications to ensure that clients’ needs for timeliness of
change notification are met.
6.5. Scaling Considerations
Implementers of servers that support the mechanism described in this
document should ensure that their implementation scales well as the
number of active persistent operations and the number of changes made
in the directory increases. Server implementers are also encouraged
to support a large number of client connections if they need to
support large numbers of persistent operations.
6.6. Alias Dereferencing
LCUP design does not consider issues associated with alias
dereferencing in search. Clients MUST specify derefAliases as either
neverDerefAliases or derefFindingBaseObj. Servers are to return
protocolError if the client specifies either derefInSearching or
derefAlways.
7. Synchronizing Heterogeneous Data Stores
Clients, like a meta directory join engine, synchronizing multiple
writable data stores, will only work correctly if each piece of
information comes from a single authoritative data source. In a
replicated environment, an LCUP Context should employ the same
conflict resolution scheme across all its replicas. This is because
different systems have different notions of time and different update
resolution procedures. As a result, a change applied on one system
can be discarded by the other, thus preventing the data stores from
converging.
8. IANA Considerations
This document lists several values that have been registered by the
IANA. The following LDAP result codes have been assigned by IANA as
described in section 3.6 of [RFC3383]:
lcupResourcesExhausted 113
lcupSecurityViolation 114
lcupInvalidData 115
lcupUnsupportedScheme 116
lcupReloadRequired 117
The three controls defined in this document have been registered as
LDAP Protocol Mechanisms as described in section 3.2 of [RFC3383].
One OID, 1.3.6.1.1.7, has been assigned by IANA as described in
section 3.1 of [RFC3383]. The OIDs for the controls defined in this
document are derived as follows from the one assigned by IANA:
LCUP Sync Request Control 1.3.6.1.1.7.1
LCUP Sync Update Control 1.3.6.1.1.7.2
LCUP Sync Done Control 1.3.6.1.1.7.3
9. Security Considerations
In some situations, it may be important to prevent general exposure
of information about changes that occur in an LDAP server. Therefore,
servers that implement the mechanism described in this document
SHOULD provide a means to enforce access control on the entries
returned and MAY also provide specific access control mechanisms to
control the use of the controls and extended operations defined in
this document.
As with normal LDAP search requests, a malicious client can initiate
a large number of persistent search requests in an attempt to consume
all available server resources and deny service to legitimate
clients. The protocol provides the means to stop malicious clients
by disconnecting them from the server. The servers that implement
the mechanism SHOULD provide the means to detect the malicious
clients. In addition, the servers SHOULD provide the means to limit
the number of resources that can be consumed by a single client.
10. References
10.1. Normative References
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2251] Wahl, M., Howes, T., and S. Kille, "Lightweight
Directory Access Protocol (v3)", RFC 2251, December
1997.
[RFC3383] Zeilenga, K., "Internet Assigned Numbers Authority
(IANA) Considerations for Lightweight Directory Access
Protocol (LDAP)", BCP 64, RFC 3383, September 2002.
[RFC3909] Zeilenga, K., "Lightweight Directory Access Protocol
(LDAP) Cancel Operation", RFC 3909, October 2004.
[X.680] ITU-T, "Abstract Syntax Notation One (ASN.1) -
Specification of Basic Notation", X.680, 1994.
[X.690] ITU-T, "Specification of ASN.1 encoding rules: Basic,
Canonical, and Distinguished Encoding Rules", X.690,
1994.
[UUID] International Organization for Standardization (ISO),
"Information technology - Open Systems Interconnection -
Remote Procedure Call", ISO/IEC 11578:1996.
10.2. Informative References
[RFC3384] Stokes, E., Weiser, R., Moats, R., and R. Huber,
"Lightweight Directory Access Protocol (version 3)
Replication Requirements", RFC 3384, October 2002.
[RFC3671] Zeilenga, K., "Collective Attributes in the Lightweight
Directory Access Protocol (LDAP)", RFC 3671, December
2003.
[RFC3672] Zeilenga, K. and S. Legg, "Subentries in the Lightweight
Directory Access Protocol (LDAP)", RFC 3672, December
2003.
11. Acknowledgments
The LCUP protocol is based in part on the Persistent Search Change
Notification Mechanism defined by Mark Smith, Gordon Good, Tim Howes,
and Rob Weltman, the LDAPv3 Triggered Search Control defined by Mark
Wahl, and the LDAP Control for Directory Synchronization defined by
Michael Armijo. The members of the IETF LDUP working group made
significant contributions to this document.
Appendix - Features Left Out of LCUP
There are several features present in other protocols or considered
useful by clients that are currently not included in the protocol
primarily because they are difficult to implement on the server.
These features are briefly discussed in this section.
Triggered Search Change Type
This feature is present in the Triggered Search specification. A
flag is attached to each entry returned to the client indicating the
reason why this entry is returned. The possible reasons from the
document are:
- notChange: the entry existed in the directory and matched the
search at the time the operation is being performed,
- enteredSet: the entry entered the result,
- leftSet: the entry left the result,
- modified: the entry was part of the result set, was modified or
renamed, and still is in the result set.
The leftSet feature is particularly useful because it indicates to
the client that an entry is no longer within the client’s search
specification and the client can remove the associated data from its
data store. Ironically, this feature is the hardest to implement on
the server because the server does not keep track of the client’s
state and has no easy way of telling which entries moved out of scope
between synchronization sessions with the client. A compromise could
be reached by only providing this feature for the operations that
occur while the client is connected to the server. This is easier to
accomplish because the decision about the change type can be made
based only on the change without need for any historical information.
This, however, would add complexity to the protocol.
Persistent Search Change Type
This feature is present in the Persistent Search specification.
Persistent search has the notion of changeTypes. The client
specifies which type of updates will cause entries to be returned,
and optionally whether the server tags each returned entry with the
type of change that caused that entry to be returned.
For LCUP, the intention is full synchronization, not partial. Each
entry returned by an LCUP search will have some change associated
with it that may concern the client. The client may have to have a
local index of entries by DN or UUID to determine if the entry has
been added or just modified. It is easy for clients to determine if
the entry has been deleted because the entryLeftSet value of the Sync
Update control will be TRUE.
Sending Changes
Some earlier synchronization protocols sent the client(s) only the
modified attributes of the entry rather than the entire entry. While
this approach can significantly reduce the amount of data returned to
the client, it has several disadvantages. First, unless a separate
mechanism (like the change type described above) is used to notify
the client about entries moving into the search scope, sending only
the changes can result in the client having an incomplete version of
the data. Let’s consider an example. An attribute of an entry is
modified. As a result of the change, the entry enters the scope of
the client’s search. If only the changes are sent, the client would
never see the initial data of the entry. Second, this feature is
hard to implement since the server might not contain sufficient
information to construct the changes based solely on the server’s
state and the client’s cookie. On the other hand, this feature can
be easily implemented by the client assuming that the client has the
previous version of the data and can perform value by value
comparisons.
Data Size Limits
Some earlier synchronization protocols allowed clients to control the
amount of data sent to them in the search response. This feature was
intended to allow clients with limited resources to process
synchronization data in batches. However, an LDAP search operation
already provides the means for the client to specify the size limit
by setting the sizeLimit field in the SearchRequest to the maximum
number of entries the client is willing to receive. While the
granularity is not the same, the assumption is that regular LDAP
clients that can deal with the limitations of the LDAP protocol will
implement LCUP.
Data Ordering
Some earlier synchronization protocols allowed a client to specify
that parent entries should be sent before the children for add
operations and children entries sent before their parents during
delete operations. This ordering helps clients to maintain a
hierarchical view of the data in their data store. While possibly
useful, this feature is relatively hard to implement and is expensive
to perform.
Authors’ Addresses
Rich Megginson
Netscape Communications Corp., an America Online company.
360 W. Caribbean Drive
Sunnyvale, CA 94089
USA
Phone: +1 505 797-7762
EMail: rmegginson0224@aol.com
Olga Natkovich
Yahoo, Inc.
701 First Ave.
Sunnyvale, CA 94089
USA
Phone: +1 408 349-6153
EMail: olgan@yahoo-inc.com
Mark Smith
Pearl Crescent, LLC
447 Marlpool Drive
Saline, MI 48176
USA
Phone: +1 734 944-2856
EMail: mcs@pearlcrescent.com
Jeff Parham
Microsoft Corporation
One Microsoft Way
Redmond, WA 98052-6399
USA
Phone: +1 425 882-8080
EMail: jeffparh@microsoft.com
Full Copyright Statement
Copyright (C) The Internet Society (2004).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and at www.rfc-editor.org, and except as set
forth therein, the authors retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the ISOC’s procedures with respect to rights in ISOC Documents can
be found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at ietf-
ipr@ietf.org.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.