5 Change Record Object Class Definition Gordon Good
6 INTERNET-DRAFT Netscape Communications
9 Definition of an Object Class to Hold LDAP Change Records
10 Filename: draft-good-ldap-changelog-00.txt
14 This document is an Internet-Draft. Internet-Drafts are working
15 documents of the Internet Engineering Task Force (IETF), its
16 areas, and its working groups. Note that other groups may also
17 distribute working documents as Internet-Drafts.
19 Internet-Drafts are draft documents valid for a maximum of six
20 months and may be updated, replaced, or obsoleted by other
21 documents at any time. It is inappropriate to use Internet-
22 Drafts as reference material or to cite them other than as
25 To learn the current status of any Internet-Draft, please check
26 the ``1id-abstracts.txt'' listing contained in the Internet-
27 Drafts Shadow Directories on ds.internic.net (US East Coast),
28 nic.nordu.net (Europe), ftp.isi.edu (US West Coast), or
29 munnari.oz.au (Pacific Rim).
31 This Internet Draft expires October 1st, 1998.
37 In order to support more flexible replication methods, it is
38 desirable to specify some manner in which an LDAP client may retrieve
39 a set of changes which have been applied to an LDAP server's
40 database. The client, which may be another LDAP server, may then
41 choose to update its own replicated copy of the data. This document
42 specifies an object class which may be used to represent changes
43 applied to an LDAP server. It also specifies a method for
44 discovering the location of the container object which holds these
45 change records, so that clients and servers have a common rendezvous
46 point for this information.
50 Background and Intended Usage
52 This document describes an objectclass which can be used to represent
56 Good March 11, 1998 [Page 1]
58 INTERNET-DRAFT Change Record Object Class 11 March 1998
61 changes which have been applied to a directory server. It also
62 suggests a common location for a container which holds these objects.
63 A client may update its local copy of directory information by
64 reading the entries within this container, and applying the changes
65 to its local database.
67 The key words "MUST", "MAY", and "SHOULD" used in this document are
68 to be interpreted as described in [3].
70 New Attribute Types Used in the changeLogEntry Object Class
72 ( 2.16.840.1.113730.3.1.5
74 DESC 'a number which uniquely identifies a change made to a
77 EQUALITY 'integerMatch'
78 ORDERING 'integerOrderingMatch' )
80 ( 2.16.840.1.113730.3.1.6
82 DESC 'the DN of the entry which was modified'
83 EQUALITY distinguishedNameMatch
86 ( 2.16.840.1.113730.3.1.7
88 DESC 'the type of change made to an entry'
89 EQUALITY caseIgnoreMatch
90 SYNTAX 'DirectoryString' )
92 ( 2.16.840.1.113730.3.1.8
94 DESC 'a set of changes to apply to an entry'
95 SYNTAX 'OctetString' )
97 ( 2.16.840.1.113730.3.1.9
99 DESC 'the new RDN of an entry which is the target of a
101 EQUALITY distinguishedNameMatch
104 ( 2.16.840.1.113730.3.1.10
106 DESC 'a flag which indicates if the old RDN should be retained
107 as an attribute of the entry'
108 EQUALITY booleanMatch
112 Good March 11, 1998 [Page 2]
114 INTERNET-DRAFT Change Record Object Class 11 March 1998
119 ( 2.16.840.1.113730.3.1.11
121 DESC 'the new parent of an entry which is the target of a
123 EQUALITY distinguishedNameMatch
127 Schema Definition of the changeLogEntry Object Class
129 ( 2.16.840.1.113730.3.2.1
130 NAME 'changeLogEntry'
134 changeNumber $ targetDN $ changeType
137 changes $ newRDN $ deleteOldRDN $ newSuperior
143 Discussion of changeLogEntry Attributes:
145 changeNumber: the change number, as assigned by the supplier. This
146 integer MUST strictly increase as new entries are added, and must
147 always be unique within a given server. Syntax: INTEGER
149 targetdn: the distinguished name of the entry which was added,
150 modified or deleted. In the case of a modrdn operation, the targetdn
151 gives the DN of the entry before it was modified. Syntax: DN
153 changeType: the type of change. One of: "add", "delete", "modify",
154 "modrdn". Later RFCs may define additional values for changeType.
155 Syntax: DirectoryString
157 changes: the changes which were made to the directory server. These
158 changes are in LDIF format, which is described in [1].
161 newRDN: the new RDN (Relative Distinguished Name) of the entry, if the
162 changeType is "modrdn". If the changeType attribute does not have the
163 value "modrdn", then there should be no values contained in the newRDN
168 Good March 11, 1998 [Page 3]
170 INTERNET-DRAFT Change Record Object Class 11 March 1998
175 deleteOldRDN: a flag which tells whether the old RDN of the entry
176 should be retained as a distinguished attribute of the entry, or
177 should be deleted. A value of "FALSE" indicates that the RDN should be
178 retained as a distinguished attribute, and a value of "TRUE" indicates
179 that it should not be retained as a distinguished attribute of the
180 entry. If any value other than "TRUE" or "FALSE" is contained in the
181 deleteOldRDN attribute, or if the deleteOldRDN contains multiple
182 values, the RDN should be retained as a distinguished attribute (that
183 is, "FALSE" is the default if no values are present, or if illegal
187 newSuperior: if present, gives the name of the entry which
188 becomes the immediate superior of the existing entry. This optional
189 attribute reflects LDAPv3 functionality, and MUST NOT be generated
190 by LDAPv2 servers [2].
195 Discussion of the changeLogEntry object class
197 The changeLogEntry object class is used to represent changes made to a
198 directory server. The set of changes made to a directory server, then,
199 is given by the ordered set of all entries within the changelog
200 container, ordered by changeNumber.
202 A client may synchronize its local copy of a remote directory server's
203 contents by searching the remote server's changelog container for any
204 entries where the changenumber is greater than or equal to the last
205 change previously retrieved from that server. If the entry with the
206 changenumber matching the last change retrieved is not returned in the
207 search results, then the server's changelog has been trimmed. The
208 client must then fall back to reading the entire directory to bring its
209 copy in sync with the server's.
211 Assuming that the client has successfully retrieved one or more changelog
212 entries from the server, it can then use the information contained in each
213 entry to update the corresponding entry (named by the targetDN attribute)
214 in its local copy of the database.
216 Note that, due to access control restrictions, the client is not guaranteed
217 read access to the "changes" attribute. If the client discovers that the
218 "changes" attribute has no values, then it must read the entry given by
219 the targetDN attribute, possibly only retrieving attributes it deems
220 "interesting". However, in the case of delete and modrdn operations, there
224 Good March 11, 1998 [Page 4]
226 INTERNET-DRAFT Change Record Object Class 11 March 1998
229 is never a "changes" attribute, so it is never necessary to read the target
230 entry in these cases.
234 Examples of the changeLogEntry object class
236 In each example below, the "changes" attribute is shown in plain text,
237 with embedded newlines. This is done for clarity. It is intended that
238 newlines be stored in the entry literally, not encoded in any way.
239 If a "changes" attribute value is stored in an LDIF file, it must
242 Example 1: A changeLogEntry representing the addition of a
243 new entry to the directory
245 dn: changenumber=1923, cn=changelog
247 targetdn: cn=Barbara Jensen, ou=Accounting, o=Ace Industry, c=US
249 changes: cn: Barbara Jensen\ncn: Babs Jensen\nsn: Jensen\n
250 givenname: Barbara\ntelephonenumber: +1 212 555-1212\nmail: babs@ace.com\n
251 objectclass: top\nobjectclass: person\nobjectclass: organizationalPerson\n
252 objectclass: inetOrgPerson
254 Example 2: A changeLogEntry representing the deletion of an entry
257 dn: changenumber=2933, cn=changelog
259 targetdn: cn=Gern Jensen, ou=Product Testing, o=Ace Industry, c=US
262 Example 3: A changeLogEntry representing the modification of an entry
265 dn: changenumber=5883, cn=changelog
267 targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, c=US
269 changes: delete: telephonenumber\ntelephonenumber: 1212\n-\n
270 add: telephonenumber\ntelephonenumber: +1 212 555 1212\n-
272 Example 4: A changeLogEntry representing a modrdn operation performed
273 on an entry in the directory
275 dn: changenumber=10042, cn=changelog
280 Good March 11, 1998 [Page 5]
282 INTERNET-DRAFT Change Record Object Class 11 March 1998
285 targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, c=US
287 newrdn: cn=Bjorn J Jensen
291 Location of the container containing changeLogEntry objects
293 For LDAPv3 servers, the location of the container which holds
294 changeLogEntry objects is obtained by reading the "changeLog" attribute
295 of a server's root DSE. For example, if the container's root is
296 "cn=changelog", then the root DSE must have an attribute named
297 "changeLog" with the value "cn=changelog".
299 The "changelog" attribute is defined as follows:
301 ( 2.16.840.1.113730.3.1.35
303 DESC 'the distinguished name of the entry which contains
304 the set of entries comprising this server's changelog'
305 EQUALITY distinguishedNameMatch
309 For LDAPv2 servers, the name of the changelog container must be
313 Differences from previous versions of this document
315 Differences between draft-ietf-asid-changelog-00.txt and
316 draft-ietf-asid-changelog-01.txt
318 1) Fixed a deficiency in the syntax of the changeNumber attribute. The
319 attribute now has INTEGER syntax, with appropriate matching and
320 ordering rules defined.
322 2) Removed unneeded substring matching rules from the changeType and
323 deleteOldRDN attribute definitions.
325 3) Made use of MAY, SHOULD, etc. consistent with RFC 2119.
327 4) Renamed document (now an individual submission).
329 5) Changed syntax of "changes" attribute from "Binary" to "OctetString".
331 6) Removed references to X.500 supplier and consumer-initiated
336 Good March 11, 1998 [Page 6]
338 INTERNET-DRAFT Change Record Object Class 11 March 1998
341 7) Updated references to current drafts/proposed standards documents.
343 Security Considerations
345 Servers implementing this scheme MUST NOT allow the "changes"
346 attribute to be generally readable. The "changes" attribute contains
347 all modifications made to an entry, and some changes may contain
348 sensitive data, e.g. passwords.
350 If a server does allow read access on the "changes: attribute to a
351 particular bound DN, then that DN should be trusted. For example, two
352 cooperating servers may exchange the password for some DN which is
353 granted read access to the "changes" attribute of the changeLog. This
354 would allow one server to retrieve changes and apply them directly to
357 In situations where the "changes" attribute is not readable by a client,
358 that client may still use the entries in the changeLog to construct a
359 list of entry DNs which are known to have changed since the last time
360 the client synchronized. The client may then read each of those entries,
361 subject to whatever access control is in effect on the server,
362 and update its local copy of each entry.
364 Servers implementing this scheme should disallow write access to the
365 changelog container object and all entries contained within.
371 This material is based in part upon work supported by the National
372 Science Foundation under Grant No. NCR-9416667.
378 [1] Good, G., "The LDAP Data Interchange Format", INTERNET-DRAFT
379 draft-good-ldap-ldif-03.txt, Netscape Communications Corp., March 1997,
380 <URL:ftp://ftp.ietf.org/internet-drafts/draft-good-ldap-ldif-03.txt>
382 [2] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access
383 Protocol (v3)", RFC 2251 Critical Angle, Inc., Netscape Communications Corp.,
384 ISODE Consortium, July, 1997,
385 <URL:ftp://ftp.isi.edu/in-notes/rfc2251.txt>
387 [3] S. Bradner, "Key Words for use in RFCs to Indicate Requirement
388 Levels", Harvard University, RFC 2119, March 1997,
392 Good March 11, 1998 [Page 7]
394 INTERNET-DRAFT Change Record Object Class 11 March 1998
397 <URL:http://ds.internic.net/rfc/rfc2119.txt>
403 Netscape Communications Corp.
404 501 E. Middlefield Rd.
406 Mountain View, CA 94043, USA
407 Phone: +1 415 937-3825
408 EMail: ggood@netscape.com
410 This Internet Draft expires October 1st, 1998.
448 Good March 11, 1998 [Page 8]