[Search] [txt|pdf|bibtex] [Tracker] [Email] [Diff1] [Diff2] [Nits]

Versions: 00 01 02 03 04                                                
     Internet Draft                                              Gordon Good
     draft-good-ldap-changelog-03.txt                              Loudcloud
     Intended Category: Informational                         Ludovic Poitou
     Expires: May 2002                                      Sun Microsystems
                                                           20 November, 2001
              Definition of an Object Class to Hold LDAP Change Records
     Status of this Memo
        This document is an Internet-Draft and is in full conformance with
        all provisions of Section 10 of RFC 2026.
        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-
        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
        The list of Internet-Draft Shadow Directories can be accessed at
        Copyright 2001, The Internet Society. All rights Reserved.
        Please see the Copyright Section near the end of this document for
        more information.
     1. Abstract
        In order to support more flexible replication methods, it is
        desirable to specify some manner in which an LDAP client may
        retrieve a set of changes that have been applied to an LDAP server's
        database.  The client, which may be another LDAP server, may then
        choose to update its own replicated copy of the data.  This document
        specifies an object class that may be used to represent changes
        applied to an LDAP server.  It also specifies a method for
        discovering the location of the container object that holds these
        change records, so that clients and servers have a common rendezvous
        point for this information.
     Good & Poitou                                                 [Page 1]

     INTERNET-DRAFT        Change Record Object Class         November 2001
     2. Background and Intended Usage
        This document describes an object class that can be used to
        represent changes that have been applied to a single directory
        server. This object class is not intended to be used in a multi-
        mastered replication environment, where changes can occur on more
        than one master server.
        This document also suggests a common location for a container to
        hold these objects.
        A client may update its local copy of directory information by
        reading the entries within this container, and applying the changes
        to its local database.
        The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
        "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document
        are to be interpreted as described in RFC 2119 [3].
     3. New Attribute Types Used in the changeLogEntry Object Class
        ( 2.16.840.1.113730.3.1.5
            NAME 'changeNumber'
            DESC 'a number which uniquely identifies a change made to a
                  directory entry'
            EQUALITY integerMatch
            ORDERING integerOrderingMatch
        ( 2.16.840.1.113730.3.1.6
            NAME 'targetDN'
            DESC 'the DN of the entry which was modified'
            EQUALITY distinguishedNameMatch
        ( 2.16.840.1.113730.3.1.7
            NAME 'changeType'
            DESC 'the type of change made to an entry'
            EQUALITY caseIgnoreMatch
        ( 2.16.840.1.113730.3.1.8
            NAME 'changes'
            DESC 'a set of changes to apply to an entry'
     Good & Poitou            Expires May 20, 2002                 [Page 2]

     INTERNET-DRAFT        Change Record Object Class         November 2001
        ( 2.16.840.1.113730.3.1.9
            NAME 'newRDN'
            DESC 'the new RDN of an entry which is the target of a
                  modrdn operation'
            EQUALITY distinguishedNameMatch
        ( 2.16.840.1.113730.3.1.10
            NAME 'deleteOldRDN'
            DESC 'a flag which indicates if the old RDN should be retained
                  as an attribute of the entry'
            EQUALITY booleanMatch
        ( 2.16.840.1.113730.3.1.11
            NAME 'newSuperior'
            DESC 'the new parent of an entry which is the target of a
                  moddn operation'
            EQUALITY distinguishedNameMatch
     4. Schema Definition of the changeLogEntry Object Class
        ( 2.16.840.1.113730.3.2.1
            NAME 'changeLogEntry'
            SUP top
            MUST ( changeNumber $ targetDN $ changeType )
            MAY ( changes $ newRDN $ deleteOldRDN $ newSuperior )
     5. Discussion of changeLogEntry Attributes:
        changeNumber: the change number, as assigned by the supplier.  This
        integer MUST strictly increase as new entries are added, and must
        always be unique within a given server.
        Syntax: INTEGER
        targetdn: the distinguished name of the entry which was added,
        modified or deleted.  In the case of a modrdn operation, the
        targetdn gives the DN of the entry before it was modified.
        Syntax: DN
        changeType: the type of change. One of: "add", "delete", "modify",
        "modrdn".  Later RFCs may define additional values for changeType.
        Syntax: DirectoryString
     Good & Poitou            Expires May 20, 2002                 [Page 3]

     INTERNET-DRAFT        Change Record Object Class         November 2001
        changes: the changes which were made to the directory server.  These
        changes are in LDIF format, which is described in [1].
        Syntax: OctetString
        newRDN: the new RDN (Relative Distinguished Name) of the entry, if
        the changeType is "modrdn".  If the changeType attribute does not
        have the value "modrdn", then there should be no values contained in
        the newRDN attribute.
        Syntax: DN
        deleteOldRDN: a flag which tells whether the old RDN of the entry
        should be retained as a distinguished attribute of the entry, or
        should be deleted.  A value of "FALSE" indicates that the RDN should
        be retained as a distinguished attribute, and a value of "TRUE"
        indicates that it should not be retained as a distinguished
        attribute of the entry.  If any value other than "TRUE" or "FALSE"
        is contained in the deleteOldRDN, the RDN should be retained as a
        distinguished attribute (that is, "FALSE" is the default if no
        values are present, or if illegal values are present).
        Syntax: BOOLEAN
        newSuperior: if present, gives the name of the entry which becomes
        the immediate superior of the existing entry.  This optional
        attribute reflects LDAPv3 functionality, and MUST NOT be generated
        by LDAPv2 servers [2].
        Syntax: DN
     6. Discussion of the changeLogEntry object class
        The changeLogEntry object class is used to represent changes made to
        a directory server.  The set of changes made to a directory server,
        then, is given by the ordered set of all entries within the
        changelog container, ordered by changeNumber. As a changeNumber is
        unique, it is recommended that the changeNumber attribute be used to
        name changeLogEntry entries.
        A client may synchronize its local copy of a remote directory
        server's contents by searching the remote server's changelog
        container for any entries where the changenumber is greater than or
        equal to the last change previously retrieved from that server.  If
        the entry with the changenumber matching the last change retrieved
        is not returned in the search results, then the server's changelog
        has been trimmed.  The client must then fall back to reading the
        entire directory to bring its copy in sync with the server's.
        Assuming that the client has successfully retrieved one or more
        changelog entries from the server, it can then use the information
        contained in each entry to update the corresponding entry (named by
        the targetDN attribute) in its local copy of the database.
        Note that, due to access control restrictions, the client is not
        guaranteed read access to the "changes" attribute.  If the client
     Good & Poitou            Expires May 20, 2002                 [Page 4]

     INTERNET-DRAFT        Change Record Object Class         November 2001
        discovers that the "changes" attribute has no values, then it must
        read the entry given by the targetDN attribute, possibly only
        retrieving attributes it deems "interesting".  However, in the case
        of delete and modrdn operations, there is never a "changes"
        attribute, so it is never necessary to read the target entry in
        these cases.
        Servers implementing this document MUST trim the changeLogEntry
        entries only in changeNumber order.
     7. Examples of the changeLogEntry object class
        In each example below, the "changes" attribute is shown in plain
        text, with embedded new-line characters.  This is done for clarity.
        It is intended that new-line characters be stored in the entry
        literally, not encoded in any way. If a "changes" attribute value is
        stored in an LDIF file, it must base-64 encoded.
        Example 1: A changeLogEntry representing the addition of a new entry
        to the directory
        dn: changenumber=1923, cn=changelog
        changenumber: 1923
        targetdn: cn=Barbara Jensen, ou=Accounting, o=Ace Industry, c=US
        changetype: add
        changes: cn: Barbara Jensen\ncn: Babs Jensen\nsn: Jensen\n
         givenname: Barbara\ntelephonenumber: +1 212 555-1212\nmail:
         babs@ace.com\nobjectclass: top\nobjectclass: person\nobjectclass:
         organizationalPerson\nobjectclass: inetOrgPerson
        Example 2: A changeLogEntry representing the deletion of an entry
        from the directory
        dn: changenumber=2933, cn=changelog
        changenumber: 2933
        targetdn: cn=Gern Jensen, ou=Product Testing, o=Ace Industry, c=US
        changetype: delete
        Example 3: A changeLogEntry representing the modification of an
        entry in the directory
        dn: changenumber=5883, cn=changelog
        changenumber: 5883
        targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry,
        changetype: modify
        changes: delete: telephonenumber\ntelephonenumber: 1212\n-\n
         add: telephonenumber\ntelephonenumber: +1 212 555 1212\n-
        Example 4: A changeLogEntry representing a modrdn operation
        performed on an entry in the directory
        dn: changenumber=10042, cn=changelog
     Good & Poitou            Expires May 20, 2002                 [Page 5]

     INTERNET-DRAFT        Change Record Object Class         November 2001
        changenumber: 10042
        targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry,
        changetype: modrdn
        newrdn: cn=Bjorn J Jensen
        deleteoldrdn: FALSE
     8. Location of the container containing changeLogEntry objects
        For LDAPv3 servers, the location of the container that holds
        changeLogEntry objects is obtained by reading the "changeLog"
        attribute of a server's root DSE.  For example, if the container's
        root is "cn=changelog", then the root DSE must have an attribute
        named "changeLog" with the value "cn=changelog".
        The "changelog" attribute is defined as follows:
        (   2.16.840.1.113730.3.1.35
            NAME 'changelog'
            DESC 'the distinguished name of the entry which contains
                  the set of entries comprising this server's changelog'
            EQUALITY distinguishedNameMatch
        For LDAPv2 servers, the name of the changelog container must be
     9. Interoperability between LDAPv2 and LDAPv3 implementations
        Implementors are discouraged from developing implementations in
        which an LDAPv2 server is synchronized from an LDAPv3 server using
        the changelog method described in this document. Problems can arise
        when an LDAPv2 server reads a "moddn" changelog entry which gives a
        new superior. Since LDAPv2 does not support such an operation, there
        is no way for the v2 server to perform the moddn operation
        atomically. It could, of course, delete all the entries under the
        old superior and add them under the new superior entry, but such an
        operation would either not be atomic, or require extensive server-
        side support on the LDAPv2 server to make the operation appear as if
        it were atomic.
        It is recommended that servers who only implement LDAPv2 should
        refuse to synchronize from LDAPv3 servers. Before beginning
        synchronization, the LDAPv2 server should attempt to read the root
        DSE of the supplier server. If the root DSE is present, and the
        supportedldapversion attribute contained in the root DSE contains
        the value "3", then the LDAPv2 server should immediately disconnect
        and proceed no further with synchronization.
     10. Security Considerations
     Good & Poitou            Expires May 20, 2002                 [Page 6]

     INTERNET-DRAFT        Change Record Object Class         November 2001
        Servers implementing this scheme MUST NOT allow the "changes"
        attribute to be generally readable.  The "changes" attribute
        contains all modifications made to an entry, and some changes may
        contain sensitive data, e.g. Passwords.
        If a server does allow read access on the "changes: attribute to a
        particular bound DN, then that DN should be trusted.  For example,
        two cooperating servers may exchange the password for some DN that
        is granted read access to the "changes" attribute of the changeLog.
        This would allow one server to retrieve changes and apply them
        directly to its database.
        In situations where the "changes" attribute is not readable by a
        client, that client may still use the entries in the changeLog to
        construct a list of entry DNs which are known to have changed since
        the last time the client synchronized.  The client may then read
        each of those entries, subject to whatever access control is in
        effect on the server, and update its local copy of each entry.
        Servers implementing this scheme should disallow write access to the
        changelog container object and all entries contained within.
     11. Acknowledgements
        This material is based in part upon work supported by the National
        Science Foundation under Grant No. NCR-9416667.
     12. References
        [1] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical
        Specification", RFC 2849, June 2000.
        [2] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access
        Protocol (v3)", RFC 2251, July 1997.
        [3] S. Bradner, "Key Words for use in RFCs to Indicate Requirement
        Levels", RFC 2119, March 1997.
     13. Authors's Address
        Gordon Good
        Loudcloud, Inc.
        599 N. Mathilda Avenue
        Sunnyvale, CA 94085
        Phone:  +1 408 744-7300
        EMail:  ggood@loudcloud.com
        Ludovic Poitou
        Sun Microsystems Inc.
     Good & Poitou            Expires May 20, 2002                 [Page 7]

     INTERNET-DRAFT        Change Record Object Class         November 2001
        14 Chemin du vieux chene
        38240 Meylan
        Phone: +33 476 188 212
        Email: ludovic.poitou@Sun.com
     14. Full Copyright Statement
        Copyright 2001, The Internet Society.  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
        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
     Good & Poitou            Expires May 20, 2002                 [Page 8]