Change Record Object Class Definition Gordon Good INTERNET-DRAFT Netscape Communications 10 March 2000 Definition of an Object Class to Hold LDAP Change Records Filename: draft-good-ldap-changelog-01.txt Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of 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. This Internet Draft expires September 10, 2000. 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 which 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 which may be used to represent changes applied to an LDAP server. It also specifies a method for discovering the location of the container object which holds these change records, so that clients and servers have a common rendezvous point for this information. Background and Intended Usage This document describes an objectclass which can be used to represent changes which have been applied to a directory server. It also suggests a common location for a container which holds these objects. Good March 9, 2000 [Page 1] INTERNET-DRAFT Change Record Object Class 11 March 1998 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]. 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' SYNTAX 'INTEGER' 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 SYNTAX 'DN' ) ( 2.16.840.1.113730.3.1.7 NAME 'changeType' DESC 'the type of change made to an entry' EQUALITY caseIgnoreMatch SYNTAX 'DirectoryString' ) ( 2.16.840.1.113730.3.1.8 NAME 'changes' DESC 'a set of changes to apply to an entry' SYNTAX 'OctetString' ) ( 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 SYNTAX 'DN' ) ( 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 SYNTAX 'BOOLEAN' ) Good March 9, 2000 [Page 2] INTERNET-DRAFT Change Record Object Class 11 March 1998 ( 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 SYNTAX 'DN' ) Schema Definition of the changeLogEntry Object Class ( 2.16.840.1.113730.3.2.1 NAME 'changeLogEntry' SUP top STRUCTURAL MUST ( changeNumber $ targetDN $ changeType ) MAY ( changes $ newRDN $ deleteOldRDN $ newSuperior ) ) 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 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 Good March 9, 2000 [Page 3] INTERNET-DRAFT Change Record Object Class 11 March 1998 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 attribute, or if the deleteOldRDN contains multiple values, 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 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. 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 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. Good March 9, 2000 [Page 4] INTERNET-DRAFT Change Record Object Class 11 March 1998 Examples of the changeLogEntry object class In each example below, the "changes" attribute is shown in plain text, with embedded newlines. This is done for clarity. It is intended that newlines 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\n objectclass: top\nobjectclass: person\nobjectclass: organizationalPerson\n objectclass: 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, c=US 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 changenumber: 10042 targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, c=US changetype: modrdn newrdn: cn=Bjorn J Jensen deleteoldrdn: FALSE Good March 9, 2000 [Page 5] INTERNET-DRAFT Change Record Object Class 11 March 1998 Location of the container containing changeLogEntry objects For LDAPv3 servers, the location of the container which 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 SYNTAX 'DN' ) For LDAPv2 servers, the name of the changelog container must be "cn=changelog". 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 not 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 which 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. Security Considerations 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. Good March 9, 2000 [Page 6] INTERNET-DRAFT Change Record Object Class 11 March 1998 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 which 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. Acknowledgements This material is based in part upon work supported by the National Science Foundation under Grant No. NCR-9416667. References [1] Good, G., "The LDAP Data Interchange Format", INTERNET-DRAFT draft-good-ldap-ldif-06.txt, Netscape Communications Corp., March 2000 [2] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access Protocol (v3)", RFC 2251 Critical Angle, Inc., Netscape Communications Corp., ISODE Consortium, July, 1997, [3] S. Bradner, "Key Words for use in RFCs to Indicate Requirement Levels", Harvard University, RFC 2119, March 1997, Author's Address Gordon Good Netscape Communications Corp. 501 E. Middlefield Rd. Mailstop MV068 Good March 9, 2000 [Page 7] INTERNET-DRAFT Change Record Object Class 11 March 1998 Mountain View, CA 94043, USA Phone: +1 650 937-3825 EMail: ggood@netscape.com This Internet Draft expires September 10, 2000 Good March 9, 2000 [Page 8]