[Docs] [txt|pdf] [Tracker] [WG] [Email] [Diff1] [Diff2] [Nits]

Versions: (draft-megginson-ldup-lcup) 00 01 02 03 04 05 06 RFC 3928

   LDUP
   Internet Draft                                  R. Megginson, Editor
   Document: draft-ietf-ldup-lcup-05.txt                       M. Smith
   Category: Proposed Standard                                 Netscape
   Expires: July 2003                                    Communications
                                                                  Corp.
                                                           O. Natkovich
                                                                  Yahoo
                                                              J. Parham
                                                              Microsoft
                                                            Corporation

                                                             April 2003


                        LDAP Client Update Protocol


Status of this Memo

   This document is an Internet-Draft and is in full conformance with
   all provisions of Section 10 of RFC 2026 [RFC2026].

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
        http://www.ietf.org/ietf/1id-abstracts.txt
   The list of Internet-Draft Shadow Directories can be accessed at
        http://www.ietf.org/shadow.html.

Abstract

   This document defines the Lightweight Directory Access Protocol
   (LDAP) Client Update Protocol (LCUP). The protocol is intended to
   allow an LDAP client to synchronize with the content of a directory
   information tree (DIT) stored by an LDAP server and to be notified
   about the changes to that content.

Conventions used in this document





Megginson, et. al.      Expires - October 2003                [Page 1]

                     LDAP Client Update Protocol           April 2003


   In the protocol flow definition, the notation C->S and S->C specifies
   the direction of the data flow from the client to the server and from
   the server to the client respectively.
   The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
   "SHOULD", "SHOULD NOT", "RECOMMENDED",  "MAY", and "OPTIONAL" in this
   document are to be interpreted as described in RFC 2119 [RFC2119].

Table of Contents

   1. Overview......................................................3
   2. Applicability.................................................4
   3. Specification of Protocol Elements............................5
     3.1 Universally Unique Identifiers.............................5
     3.2 LCUP Scheme and LCUP Cookie................................5
     3.3 LCUP Context...............................................6
     3.4 Additional LDAP Result Codes defined by LCUP...............6
     3.5 Sync Request Control.......................................6
     3.6 Sync Update Control........................................7
     3.7 Sync Done Control..........................................8
   4. Protocol Usage and Flow.......................................8
     4.1 LCUP Search Requests.......................................8
       4.1.1 Initial Synchronization and Full Resync................9
       4.1.2 Incremental or Update Synchronization..................9
       4.1.3 Persistent Only.......................................10
     4.2 LCUP Search Responses.....................................10
       4.2.1 Sync Update Informational Responses...................10
       4.2.2 Cookie Return Frequency...............................11
       4.2.3 Definition of an Entry That Has Entered the Result Set11
       4.2.4 Definition of an Entry That Has Changed...............12
       4.2.5 Definition of an Entry That Has Left the Result Set...12
       4.2.6 Results For Entries Present in the Result Set.........13
       4.2.7 Results For Entries That Have Left the Result Set.....14
     4.3 Responses Requiring Special Consideration.................15
       4.3.1 Returning Results During the Persistent Phase.........15
       4.3.2 No Mixing of Sync Phase with Persist Phase............15
       4.3.3 Returning Updated Results During the Sync Phase.......15
       4.3.4 Operational Attributes and Administrative Entries.....15
       4.3.5 Virtual Attributes....................................16
       4.3.6 Modify DN and Delete Operations Applied to Subtrees...16
       4.3.7 Convergence Guarantees................................16
     4.4 LCUP Search Termination...................................17
       4.4.1 Server Initiated Termination..........................17
       4.4.2 Client Initiated Termination..........................17
     4.5 Protocol Flow.............................................18
     4.6 Size and Time Limits......................................18
     4.7 Operations on the Same Connection.........................18
     4.8 Interactions with Other Controls..........................18
   5. Client Side Considerations...................................19
     5.1 Using Cookies with Different Search Criteria..............19


Megginson, et. al.      Expires - October 2003                [Page 2]

                     LDAP Client Update Protocol           April 2003


     5.2 Renaming the Base Object..................................19
     5.3 Use of Persistent Searches With Respect to Resources......19
     5.4 Continuation References to Other LCUP Contexts............20
     5.5 Referral Handling.........................................20
     5.6 Multiple Copies of Same Entry During Sync Phase...........20
     5.7 Handling Server Out of Resources Condition................20
   6. Server Implementation Considerations.........................20
     6.1 Server Support for UUIDs..................................20
     6.2 Example of Using an RUV as the Cookie Value...............20
     6.3 Cookie Support Issues.....................................21
       6.3.1 Support for Multiple Cookie Schemes...................21
       6.3.2 Information Contained in the Cookie...................21
     6.4 Persist Phase Response Time...............................22
     6.5 Scaling Considerations....................................22
     6.6 Alias Dereferencing.......................................22
   7. Synchronizing Heterogeneous Data Stores......................22
   IANA Considerations.............................................22
   Security Considerations.........................................23
   Normative References............................................23
   Informative References..........................................24
   Acknowledgments.................................................24
   Author's Addresses..............................................24
   Full Copyright Statement........................................25
   Appendix - Features Left Out of LCUP............................26


1. Overview

   The LCUP protocol is intended to allow LDAP clients to synchronize
   with the content stored by LDAP servers.

   The problem areas addressed by the protocol include:

   - Mobile clients that maintain a local read-only copy of the
     directory data.  While off-line, the client uses the local copy of
     the data.  When the client connects to the network, it synchronizes
     with the current directory content and can optionally receive
     notification about the changes that occur while it is on-line.  For
     example, a mail client can maintain a local copy of the corporate
     address book that it synchronizes with the master copy whenever the
     client is connected to the corporate network.

   - Applications intending to synchronize heterogeneous data stores.  A
     meta directory application, for instance, would periodically
     retrieve a list of modified entries from the directory, construct
     the changes and apply them to a foreign data store.

   - Clients that need to take certain actions when a directory entry is
     modified.  For instance, an electronic mail repository may want to


Megginson, et. al.      Expires - October 2003                [Page 3]

                     LDAP Client Update Protocol           April 2003


     perform a "create mailbox" task when a new person entry is added to
     an LDAP directory and a "delete mailbox" task when a person entry
     is removed.

   The problem areas not being considered:

   - directory server to directory server synchronization.  The IETF is
     developing a LDAP replication protocol, called LDUP [RFC3384],
     which is specifically designed to address this problem area.

   There are currently several protocols in use for LDAP client server
   synchronization.  While each protocol addresses the needs of a
   particular group of clients (e.g., on-line clients or off-line
   clients), none satisfies the requirements of all clients in the
   target group.  For instance, a mobile client that was off-line and
   wants to become up to date with the server and stay up to date while
   connected can't be easily supported by any of the existing protocols.

   LCUP is designed such that the server does not need to maintain state
   information on behalf of the client.  The clients are responsible for
   storing the information about how up to date they are with respect to
   the server's content.  LCUP design avoids the need for LCUP-specific
   update agreements to be made between client and server prior to LCUP
   use.  The client decides when and from where to retrieve the changes.
   LCUP design requires clients to initiate the update session and
   "pull" the changes from server.

   LCUP operations are subject to administrative and access control
   policies enforced by the server.

2. Applicability

   LCUP will work best if the following conditions are met:

   1) The server stores some degree of historical state or change
   information to reduce the amount of wire traffic required for
   incremental synchronizations.  The optimal balance between server
   state and wire traffic varies amongst implementations and usage
   scenarios, and is therefore left in the hands of implementers.

   2) The client cannot be assumed to understand the physical
   information model (virtual attributes, operational attributes,
   subentries, etc.) implemented by the server.  Optimizations would be
   possible if such assumptions could be made.

   3) Meta data changes and renames and deletions of large subtrees are
   very infrequent.  LCUP makes these assumptions in order to reduce
   client complexity required to deal with these special operations,



Megginson, et. al.      Expires - October 2003                [Page 4]

                     LDAP Client Update Protocol           April 2003


   though when they do occur they may result in a large number of
   incremental update messages or a full resync.

3. Specification of Protocol Elements

   The following sections define the new elements required to use this
   protocol.

3.1 Universally Unique Identifiers

   Distinguished names can change, so are therefore unreliable as
   identifiers.  A Universally Unique Identifier (or UUID for short)
   MUST be used to uniquely identify entries used with LCUP.  The UUID
   is part of the Sync Update control value (see below) returned with
   each search result.  The server SHOULD provide the UUID as a single
   valued operational attribute of the entry (e.g. "entryUUID").  We
   RECOMMEND that the server provides a way to do efficient (i.e.
   indexed) searches for values of UUID e.g. by using a search filter
   like (entryUUID=<some UUID value>) to quickly search for and retrieve
   an entry based on its UUID.  Servers SHOULD use a UUID format as
   specified in [UUID].  The UUID used by LCUP is a value of the
   following ASN.1 type:

      LCUPUUID ::= OCTET STRING

3.2 LCUP Scheme and LCUP Cookie

   The LCUP protocol uses a cookie to hold the state of the client's
   data with respect to the server's data.  Each cookie format is
   uniquely identified by its scheme.  The LCUP Scheme is a value of the
   following ASN.1 type:

      LCUPScheme ::= LDAPOID

   This is the OID which identifies the format of the LCUP Cookie value.
   The scheme OID, as all object identifiers, MUST be unique for a given
   cookie scheme.  The cookie value may be opaque or it may be exposed
   to LCUP clients.   For cookie schemes that expose their value, the
   preferred form of documentation is an RFC.  It is expected that there
   will be one or more standards track cookie schemes where the value
   format is exposed and described in detail.

   The LCUP Cookie is a value of the following ASN.1 type:

      LCUPCookie ::= OCTET STRING

   This is the actual data describing the state of the client's data.
   This value may be opaque, or its value may have some well-known
   format, depending on the scheme.


Megginson, et. al.      Expires - October 2003                [Page 5]

                     LDAP Client Update Protocol           April 2003



   Further uses of the LCUP Cookie value are described below.

3.3 LCUP Context

   A part of the DIT which is enabled for LCUP is referred to as an LCUP
   Context.  A server may support one or more LCUP Contexts.  For
   example, a server with two naming contexts may support LCUP in one
   naming context but not the other, or support different LCUP cookie
   schemes in each naming context.  Each LCUP Context MAY use a
   different cookie scheme.  An LCUP search will not cross an LCUP
   Context boundary, but will instead return a SearchResultReference
   message, with the LDAP URL specifying the same host and port as
   currently being searched, and with the baseDN set to the baseDN of
   the new LCUP Context.  The client is then responsible for issuing
   another search using the new baseDN, and possibly a different cookie
   if that LCUP Context uses a different cookie.  The client is
   responsible for maintaining a mapping of the LDAP URL to its
   corresponding cookie.

3.4 Additional LDAP Result Codes defined by LCUP

   Implementations of this specification SHALL recognize the following
   additional resultCode values.  The LDAP result code names and numbers
   defined in the following table are to be replaced with IANA assigned
   result code names and numbers per RFC 3383 [RFC3383].

   lcupResourcesExhausted  (TBD)  the server is running out of resources
   lcupSecurityViolation   (TBD)  the client is suspected of malicious
                                  actions
   lcupInvalidData         (TBD)  invalid scheme or cookie was supplied by
                                  the client
   lcupUnsupportedScheme   (TBD)  The cookie scheme is a valid OID but is
                                  not supported by this server
   lcupReloadRequired      (TBD)  indicates that client data needs to be
                                  reinitialized.  This reason is returned
                                  if the server does not contain
                                  sufficient information to synchronize
                                  the client or if the server's data was
                                  reloaded since the last synchronization
                                  session

   The uses of these codes are described below.

3.5 Sync Request Control

   The Sync Request Control is an LDAP Control [RFC2251, Section 4.1.2]
   where the controlType is the object identifier IANA-ASSIGNED-OID.1



Megginson, et. al.      Expires - October 2003                [Page 6]

                     LDAP Client Update Protocol           April 2003


   and the controlValue, an OCTET STRING, contains a BER-encoded
   syncRequestControlValue.

      syncRequestControlValue ::= SEQUENCE {
         updateType           ENUMERATED {
                                 syncOnly       (0),
                                 syncAndPersist (1),
                                 persistOnly    (2) },
         sendCookieInterval   INTEGER    OPTIONAL,
         scheme               LCUPScheme OPTIONAL,
         cookie               LCUPCookie OPTIONAL
        }

   sendCookieInterval - the server SHOULD send the cookie back in the
   Sync Update control value (defined below) for every
   sendCookieInterval number of SearchResultEntry and
   SearchResultReference PDUs returned to the client.  For example, if
   the value is 5, the server SHOULD send the cookie back in the Sync
   Update control value for every 5 search results returned to the
   client.  If this value is absent, zero or less than zero, the server
   chooses the interval.

   The Sync Request Control is only applicable to the searchRequest
   message.  Use of this control is described below.

3.6 Sync Update Control

   The Sync Update Control is an LDAP Control [RFC2251, Section 4.1.2]
   where the controlType is the object identifier IANA-ASSIGNED-OID.2
   and the controlValue, an OCTET STRING, contains a BER-encoded
   syncUpdateControlValue.

      syncUpdateControlValue ::= SEQUENCE {
         stateUpdate    BOOLEAN,
         entryUUID      LCUPUUID OPTIONAL, -- REQUIRED for entries --
         UUIDAttribute  AttributeType OPTIONAL,
         entryLeftSet   BOOLEAN,
         persistPhase   BOOLEAN,
         scheme         LCUPScheme OPTIONAL,
         cookie         LCUPCookie OPTIONAL
      }

   The field UUIDAttribute contains the name or OID of the attribute
   that the client should use to perform searches for entries based on
   the UUID.  The client should be able to use it in an equality search
   filter e.g. "(<uuid attribute>=<entry UUID value>)" and should be
   able to use it in the attribute list of the search request to return
   its value.  The UUIDAttribute field may be omitted if the server does
   not support searching on the UUID values.


Megginson, et. al.      Expires - October 2003                [Page 7]

                     LDAP Client Update Protocol           April 2003



   The Sync Update Control is only applicable to SearchResultEntry and
   SearchResultReference messages.  Although entryUUID is OPTIONAL, it
   MUST be used with SearchResultEntry messages.  Use of this control is
   described below.

3.7 Sync Done Control

   The Sync Done Control is an LDAP Control [RFC2251, Section 4.1.2]
   where the controlType is the object identifier IANA-ASSIGNED-OID.3
   and the controlValue contains a BER-encoded syncDoneValue.

      syncDoneValue ::= SEQUENCE {
         scheme      LCUPScheme OPTIONAL,
         cookie      LCUPCookie OPTIONAL
      }

   The Sync Done Control is only applicable to SearchResultDone message.
   Use of this control is described below.

4. Protocol Usage and Flow

4.1 LCUP Search Requests

   A client initiates a synchronization or persistent search session
   with a server by attaching a Sync Request control to an LDAP
   searchRequest message.  The search specification determines the part
   of the directory information tree (DIT) the client wishes to
   synchronize with, the set of attributes it is interested in and the
   amount of data the client is willing to receive.  The Sync Request
   control contains the client's request specification.

   If there is an error condition, the server MUST immediately return a
   SearchResultDone message with the resultCode set to an error code.
   This table maps a condition to its corresponding behavior and
   resultCode.

   Condition                       Behavior or resultCode

   Sync Request Control is not     Server behaves as [RFC2251, Section
   supported                       4.1.2] - specifically, if the
                                   criticality of the control is FALSE,
                                   the server will process the request
                                   as a normal search request

   Scheme is not supported         lcupUnsupportedScheme

   A control value field is        lcupInvalidData
   invalid (e.g. illegal


Megginson, et. al.      Expires - October 2003                [Page 8]

                     LDAP Client Update Protocol           April 2003


   updateType, or the scheme is
   not a valid OID, or the cookie
   is invalid)

   Server is running out of        lcupResourcesExhausted
   resources

   Server suspects client of       lcupSecurityViolation
   malicious behavior (frequent
   connects/disconnects, etc.)

   The server cannot bring the     lcupReloadRequired
   client up to date (server data
   has been reloaded, or other
   changes that prevent
   convergence)

4.1.1 Initial Synchronization and Full Resync

   For an initial synchronization or full resync, 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 - 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.




Megginson, et. al.      Expires - October 2003                [Page 9]

                     LDAP Client Update Protocol           April 2003


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 PDU that fits 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


Megginson, et. al.      Expires - October 2003               [Page 10]

                     LDAP Client Update Protocol           April 2003


      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 lets the
   client 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



Megginson, et. al.      Expires - October 2003               [Page 11]

                     LDAP Client Update Protocol           April 2003


   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:




Megginson, et. al.      Expires - October 2003               [Page 12]

                     LDAP Client Update Protocol           April 2003


   - 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.


Megginson, et. al.      Expires - October 2003               [Page 13]

                     LDAP Client Update Protocol           April 2003



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

   An entry SHOULD be returned as having left the result set under the
   following conditions:

   - 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.


Megginson, et. al.      Expires - October 2003               [Page 14]

                     LDAP Client Update Protocol           April 2003



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 MUST 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].




Megginson, et. al.      Expires - October 2003               [Page 15]

                     LDAP Client Update Protocol           April 2003


   LDAP Subentries [SUBENTRY] MUST be returned if they would normally be
   returned by the search request.

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 [COLLECTIVE].  These attributes shall
   be referred to in this document as virtual attributes.

   LCUP treats these attributes the same way as normal, non-virtual
   attributes.  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


Megginson, et. al.      Expires - October 2003               [Page 16]

                     LDAP Client Update Protocol           April 2003


   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
   lcupClientDisconnect, 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
   lcupClientDisconnect.  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



Megginson, et. al.      Expires - October 2003               [Page 17]

                     LDAP Client Update Protocol           April 2003


   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 [CANCEL].  The server
   responds immediately with a LDAP Cancel response [CANCEL].  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
   [CANCEL], 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 [CANCEL].

   If the client is not interested in the state information, it can
   simply abandon the search operation or disconnect from the server.

4.5 Protocol Flow

   The client server interaction can proceed in three different ways
   depending on the client's requirements.  Protocol flows beginning
   with an asterisk (*) are optional or conditional.

   <What to do about this section?????????????????>

4.6 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.7 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.8 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
   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


Megginson, et. al.      Expires - October 2003               [Page 18]

                     LDAP Client Update Protocol           April 2003


   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 CSN, or timestamp, or
   some criteria other than an alphabetical order.

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.




Megginson, et. al.      Expires - October 2003               [Page 19]

                     LDAP Client Update Protocol           April 2003


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


Megginson, et. al.      Expires - October 2003               [Page 20]

                     LDAP Client Update Protocol           April 2003


   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


Megginson, et. al.      Expires - October 2003               [Page 21]

                     LDAP Client Update Protocol           April 2003


   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.

IANA Considerations





Megginson, et. al.      Expires - October 2003               [Page 22]

                     LDAP Client Update Protocol           April 2003


   This document lists several values that are to be assigned by IANA.
   The following LDAP result codes are to be assigned by IANA as
   described in section 3.6 of [RFC3383]:

      lcupResourcesExhausted
      lcupSecurityViolation
      lcupInvalidData
      lcupUnsupportedScheme
      lcupReloadRequired

   The three controls defined in this document are to be registed as
   LDAP Protocol Mechanisms as described in section 3.2 of [RFC3383].
   One OID, IANA-ASSIGNED-OID, is to be 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:

      Sync Request Control    IANA-ASSIGNED-OID.1
      Sync Update Control     IANA-ASSIGNED-OID.2
      Sync Done Control       IANA-ASSIGNED-OID.3

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.

Normative References

   [RFC2026]    Bradner, S., "The Internet Standards Process -- Revision
                3", BCP 9, RFC 2026, October 1996.

   [RFC2119]    S. Bradner, "Key words for use in RFCs to Indicate
                Requirement Levels", BCP 14 (also RFC 2119), March 1997.

   [RFC2251]    M. Wahl, T. Howes, S. Kille, "Lightweight Directory
                Access Protocol (v3)", RFC 2251, December 1997.


Megginson, et. al.      Expires - October 2003               [Page 23]

                     LDAP Client Update Protocol           April 2003



   [RFC2252]    M. Wahl, A. Coulbeck, T. Howes, S. Kille, "Lightweight
                Directory Access Protocol (v3): Attribute Syntax
                Definitions", RFC 2252, December 1997.

   [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.

   [CANCEL]     K. Zeilenga, "LDAP Cancel Extended Operation", draft-
                zeilenga-ldap-cancel-xx.txt, a work in progress.

   [UUID]       International Organization for Standardization (ISO),
                "Information technology - Open Systems Interconnection -
                Remote Procedure Call", ISO/IEC 11578:1996.

   [RFC3383]    K. Zeilenga, "IANA Considerations for LDAP", BCP 64 also
                RFC 3383), September 2002.

Informative References

   [RFC3384]    E. Stokes, et. al., "LDAPv3 Replication Requirements",
                RFC3384, October 2002.

   [SUBENTRY]   K. Zeilenga, S. Legg, "Subentries in LDAP", draft-
                zeilenga-ldap-subentry-xx.txt, a work in progress.

   [COLLECTIVE] K. Zeilenga, "Collective Attributes in LDAP", draft-
                zeilenga-ldap-collective-xx.txt, a work in progress.

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.


Author's Addresses

   Rich Megginson
   Netscape Communications Corp., an America Online company.
   360 W. Caribbean Drive
   Sunnyvale, CA 94089


Megginson, et. al.      Expires - October 2003               [Page 24]

                     LDAP Client Update Protocol           April 2003


   USA
   Phone: +1 505 797-7762
   Email: richm@netscape.com

   Olga Natkovich
   Yahoo, Inc.
   701 First Ave.
   Sunnyvale, CA 94089
   Phone: +1 408 349-6153
   Email: olgan@yahoo-inc.com

   Mark Smith
   Netscape Communications Corp., an America Online company.
   360 W. Caribbean Drive
   Sunnyvale, CA 94089
   USA
   Phone: +1 650 937-3477
   Email: mcs@netscape.com

   Jeff Parham
   Microsoft Corporation
   One Microsoft Way
   Redmond, WA 98052-6399
   Phone: +1 425 882-8080
   Email: jeffparh@microsoft.com

Full Copyright Statement

   Copyright (C) The Internet Society (2003).  All Rights Reserved.

   This document and translations of it may be copied and furnished to
   others, and derivative works that comment on or otherwise explain it
   or assist in its implementation may be prepared, copied, published
   and distributed, in whole or in part, without restriction of any
   kind, provided that the above copyright notice and this paragraph are
   included on all such copies and derivative works.  However, this
   document itself may not be modified in any way, such as by removing
   the copyright notice or references to the Internet Society or other
   Internet organizations, except as needed for the purpose of
   developing Internet standards in which case the procedures for
   copyrights defined in the Internet Standards process must be
   followed, or as required to translate it into languages other than
   English.

   The limited permissions granted above are perpetual and will not be
   revoked by the Internet Society or its successors or assigns.

   This document and the information contained herein is provided on an
   "AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING


Megginson, et. al.      Expires - October 2003               [Page 25]

                     LDAP Client Update Protocol           April 2003


   TASK FORCE DISCLAIMS 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.

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
   draft 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


Megginson, et. al.      Expires - October 2003               [Page 26]

                     LDAP Client Update Protocol           April 2003


   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.




Megginson, et. al.      Expires - October 2003               [Page 27]


Html markup produced by rfcmarkup 1.108, available from http://tools.ietf.org/tools/rfcmarkup/