idnits 2.17.1 draft-good-ldap-changelog-04.txt: ** The Abstract section seems to be numbered Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Looks like you're using RFC 2026 boilerplate. This must be updated to follow RFC 3978/3979, as updated by RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack an Authors' Addresses Section. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Line 389 has weird spacing: '...for the purpo...' == The document seems to lack the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords -- however, there's a paragraph with a matching beginning. Boilerplate error? (The document does seem to have the reference to RFC 2119 which the ID-Checklist requires). -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (1 March 2003) is 7698 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2251 (ref. '2') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Internet Draft Gordon Good 3 draft-good-ldap-changelog-04.txt Loudcloud 4 Intended Category: Informational Ludovic Poitou 5 Expires: September 2003 Sun Microsystems 7 1 March 2003 9 Definition of an Object Class to Hold LDAP Change Records 11 Status of this Memo 13 This document is an Internet-Draft and is in full conformance with 14 all provisions of Section 10 of RFC 2026. 16 Internet-Drafts are working documents of the Internet Engineering 17 Task Force (IETF), its areas, and its working groups. Note that 18 other groups may also distribute working documents as Internet- 19 Drafts. 21 Internet-Drafts are draft documents valid for a maximum of six 22 months and may be updated, replaced, or obsoleted by other documents 23 at any time. It is inappropriate to use Internet- Drafts as 24 reference material or to cite them other than as "work in progress." 26 The list of current Internet-Drafts can be accessed at 27 http://www.ietf.org/ietf/1id-abstracts.txt 29 The list of Internet-Draft Shadow Directories can be accessed at 30 http://www.ietf.org/shadow.html. 32 Copyright (C) The Internet Society (2003). All Rights Reserved. 34 Please see the Copyright Section near the end of this document for 35 more information. 37 1. Abstract 39 In order to support more flexible replication methods, it is 40 desirable to specify some manner in which an LDAP client may 41 retrieve a set of changes that have been applied to an LDAP server's 42 database. The client, who may be another LDAP server, may then 43 choose to update its own replicated copy of the data. This document 44 specifies an object class that may be used to represent changes 45 applied to an LDAP server. It also specifies a method for 46 discovering the location of the container object that holds these 47 change records, so that clients and servers have a common rendezvous 48 point for this information. 50 2. Background and Intended Usage 52 This document describes an object class that can be used to 53 represent changes that have been applied to a single directory 54 server. 56 This object class is not intended to be used in a multi-mastered 57 replication environment, where changes can occur on more than one 58 master server. 60 This document also suggests a common location for a container to 61 hold 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", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 68 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document 69 are to be interpreted as described in RFC 2119 [3]. 71 3. New Attribute Types Used in the changeLogEntry Object Class 73 ( 2.16.840.1.113730.3.1.5 74 NAME 'changeNumber' 75 DESC 'a number which uniquely identifies a change made to a 76 directory entry' 77 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 78 EQUALITY integerMatch 79 ORDERING integerOrderingMatch 80 SINGLE-VALUE 81 ) 83 ( 2.16.840.1.113730.3.1.6 84 NAME 'targetDN' 85 DESC 'the DN of the entry which was modified' 86 EQUALITY distinguishedNameMatch 87 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 88 SINGLE-VALUE 89 ) 91 ( 2.16.840.1.113730.3.1.7 92 NAME 'changeType' 93 DESC 'the type of change made to an entry' 94 EQUALITY caseIgnoreMatch 95 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 96 SINGLE-VALUE 97 ) 99 ( 2.16.840.1.113730.3.1.8 100 NAME 'changes' 101 DESC 'a set of changes to apply to an entry' 102 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 103 ) 105 ( 2.16.840.1.113730.3.1.9 106 NAME 'newRDN' 107 DESC 'the new RDN of an entry which is the target of a 108 modrdn operation' 109 EQUALITY distinguishedNameMatch 110 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 111 SINGLE-VALUE 112 ) 114 ( 2.16.840.1.113730.3.1.10 115 NAME 'deleteOldRDN' 116 DESC 'a flag which indicates if the old RDN should be retained 117 as an attribute of the entry' 118 EQUALITY booleanMatch 119 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 120 SINGLE-VALUE 121 ) 123 ( 2.16.840.1.113730.3.1.11 124 NAME 'newSuperior' 125 DESC 'the new parent of an entry which is the target of a 126 moddn operation' 127 EQUALITY distinguishedNameMatch 128 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 129 SINGLE-VALUE 130 ) 132 4. Schema Definition of the changeLogEntry Object Class 134 ( 2.16.840.1.113730.3.2.1 135 NAME 'changeLogEntry' 136 SUP top 137 STRUCTURAL 138 MUST ( changeNumber $ targetDN $ changeType ) 139 MAY ( changes $ newRDN $ deleteOldRDN $ newSuperior ) 140 ) 142 5. Discussion of changeLogEntry Attributes: 144 changeNumber: the change number, as assigned by the supplier. This 145 integer MUST strictly increase as new entries are added, and must 146 always be unique within a given server. 147 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 151 targetdn gives the DN of the entry before it was modified. 152 Syntax: DN 154 changeType: the type of change. One of: "add", "delete", "modify", 155 "modrdn". Later RFCs may define additional values for changeType. 156 Syntax: DirectoryString 158 changes: the changes which were made to the directory server. These 159 changes are in LDIF format, which is described in [1]. 160 Syntax: OctetString 162 newRDN: the new RDN (Relative Distinguished Name) of the entry, if 163 the changeType is "modrdn". If the changeType attribute does not 164 have the value "modrdn", then there should be no values contained in 165 the newRDN attribute. 166 Syntax: DN 168 deleteOldRDN: a flag which tells whether the old RDN of the entry 169 should be retained as a distinguished attribute of the entry, or 170 should be deleted. A value of "FALSE" indicates that the RDN should 171 be retained as a distinguished attribute, and a value of "TRUE" 172 indicates that it should not be retained as a distinguished 173 attribute of the entry. If any value other than "TRUE" or "FALSE" 174 is contained in the deleteOldRDN, the RDN should be retained as a 175 distinguished attribute (that is, "FALSE" is the default if no 176 values are present, or if illegal values are present). 177 Syntax: BOOLEAN 179 newSuperior: if present, gives the name of the entry which becomes 180 the immediate superior of the existing entry. This optional 181 attribute reflects LDAPv3 functionality, and MUST NOT be generated 182 by LDAPv2 servers [2]. 183 Syntax: DN 185 6. Discussion of the changeLogEntry object class 187 The changeLogEntry object class is used to represent changes made to 188 a directory server. The set of changes made to a directory server, 189 then, is given by the ordered set of all entries within the 190 changelog container, ordered by changeNumber. As a changeNumber is 191 unique, it is recommended that the changeNumber attribute be used to 192 name changeLogEntry entries. 194 A client may synchronize its local copy of a remote directory 195 server's contents by searching the remote server's changelog 196 container for any entries where the changenumber is greater than or 197 equal to the last change previously retrieved from that server. If 198 the entry with the changenumber matching the last change retrieved 199 is not returned in the search results, then the server's changelog 200 has been trimmed. The client must then fall back to reading the 201 entire directory to bring its copy in sync with the server's. 203 Assuming that the client has successfully retrieved one or more 204 changelog entries from the server, it can then use the information 205 contained in each entry to update the corresponding entry (named by 206 the targetDN attribute) in its local copy of the database. 208 Note that, due to access control restrictions, the client is not 209 guaranteed read access to the "changes" attribute. If the client 210 discovers that the "changes" attribute has no values, then it must 211 read the entry given by the targetDN attribute, possibly only 212 retrieving attributes it deems "interesting". However, in the case 213 of delete and modrdn operations, there is never a "changes" 214 attribute, so it is never necessary to read the target entry in 215 these cases. 217 Servers implementing this document MUST trim the changeLogEntry 218 entries only in changeNumber order. 220 7. Examples of the changeLogEntry object class 222 In each example below, the "changes" attribute is shown in plain 223 text, with embedded new-line characters. This is done for clarity. 224 It is intended that new-line characters be stored in the entry 225 literally, not encoded in any way. If a "changes" attribute value is 226 stored in an LDIF file, it must base-64 encoded. 228 Example 1: A changeLogEntry representing the addition of a new entry 229 to the directory 231 dn: changenumber=1923, cn=changelog 232 changenumber: 1923 233 targetdn: cn=Barbara Jensen, ou=Accounting, o=Ace Industry, c=US 234 changetype: add 235 changes: cn: Barbara Jensen\ncn: Babs Jensen\nsn: Jensen\n 236 givenname: Barbara\ntelephonenumber: +1 212 555-1212\nmail: 237 babs@ace.com\nobjectclass: top\nobjectclass: person\nobjectclass: 238 organizationalPerson\nobjectclass: inetOrgPerson 240 Example 2: A changeLogEntry representing the deletion of an entry 241 from the directory 243 dn: changenumber=2933, cn=changelog 244 changenumber: 2933 245 targetdn: cn=Gern Jensen, ou=Product Testing, o=Ace Industry, c=US 246 changetype: delete 248 Example 3: A changeLogEntry representing the modification of an 249 entry in the directory 251 dn: changenumber=5883, cn=changelog 252 changenumber: 5883 253 targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, 254 c=US 255 changetype: modify 256 changes: delete: telephonenumber\ntelephonenumber: 1212\n-\n 257 add: telephonenumber\ntelephonenumber: +1 212 555 1212\n- 259 Example 4: A changeLogEntry representing a modrdn operation 260 performed on an entry in the directory 262 dn: changenumber=10042, cn=changelog 263 changenumber: 10042 264 targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, 265 c=US 266 changetype: modrdn 267 newrdn: cn=Bjorn J Jensen 268 deleteoldrdn: FALSE 270 8. Location of the container containing changeLogEntry objects 272 For LDAPv3 servers, the location of the container that holds 273 changeLogEntry objects is obtained by reading the "changeLog" 274 attribute of a server's root DSE. For example, if the container's 275 root is "cn=changelog", then the root DSE must have an attribute 276 named "changeLog" with the value "cn=changelog". 278 The "changelog" attribute is defined as follows: 280 ( 2.16.840.1.113730.3.1.35 281 NAME 'changelog' 282 DESC 'the distinguished name of the entry which contains 283 the set of entries comprising this server's changelog' 284 EQUALITY distinguishedNameMatch 285 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 286 ) 288 For LDAPv2 servers, the name of the changelog container must be 289 "cn=changelog". 291 9. Interoperability between LDAPv2 and LDAPv3 implementations 292 Implementors are discouraged from developing implementations in 293 which an LDAPv2 server is synchronized from an LDAPv3 server using 294 the changelog method described in this document. Problems can arise 295 when an LDAPv2 server reads a "moddn" changelog entry which gives a 296 new superior. Since LDAPv2 does not support such an operation, there 297 is no way for the v2 server to perform the moddn operation 298 atomically. It could, of course, delete all the entries under the 299 old superior and add them under the new superior entry, but such an 300 operation would either not be atomic, or require extensive server- 301 side support on the LDAPv2 server to make the operation appear as if 302 it were atomic. 304 It is recommended that servers who only implement LDAPv2 should 305 refuse to synchronize from LDAPv3 servers. Before beginning 306 synchronization, the LDAPv2 server should attempt to read the root 307 DSE of the supplier server. If the root DSE is present, and the 308 supportedldapversion attribute contained in the root DSE contains 309 the value "3", then the LDAPv2 server should immediately disconnect 310 and proceed no further with synchronization. 312 10. Security Considerations 314 Servers implementing this scheme MUST NOT allow the "changes" 315 attribute to be generally readable. The "changes" attribute 316 contains all modifications made to an entry, and some changes may 317 contain sensitive data, e.g. Passwords. 319 If a server does allow read access on the "changes: attribute to a 320 particular bound DN, then that DN should be trusted. For example, 321 two cooperating servers may exchange the password for some DN that 322 is granted read access to the "changes" attribute of the changeLog. 323 This would allow one server to retrieve changes and apply them 324 directly to its database. 326 In situations where the "changes" attribute is not readable by a 327 client, that client may still use the entries in the changeLog to 328 construct a list of entry DNs which are known to have changed since 329 the last time the client synchronized. The client may then read 330 each of those entries, subject to whatever access control is in 331 effect on the server, and update its local copy of each entry. 333 Servers implementing this scheme should disallow write access to the 334 changelog container object and all entries contained within. 336 11.IANA Considerations 338 The OIDs used in this document have been assigned by Netscape 339 Communications Corp, under its ANSI-assigned private enterprise 340 allocation, for use in this specification. 342 12. Acknowledgements 344 This material is based in part upon work supported by the National 345 Science Foundation under Grant No. NCR-9416667. 347 13. Normative References 349 [1] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical 350 Specification", RFC 2849, June 2000. 352 [2] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access 353 Protocol (v3)", RFC 2251, July 1997. 355 [3] S. Bradner, "Key Words for use in RFCs to Indicate Requirement 356 Levels", RFC 2119, March 1997. 358 14. Authors's Address 360 Gordon Good 361 Loudcloud, Inc. 362 599 N. Mathilda Avenue 363 Sunnyvale, CA 94085 364 USA 365 Phone: +1 408 744-7300 366 EMail: ggood@loudcloud.com 368 Ludovic Poitou 369 Sun Microsystems Inc. 370 180 Avenue de l'Europe 371 Zirst de Montbonnot 372 38334 Saint Ismier cedex 373 France 374 Phone: +33 476 188 212 375 Email: ludovic.poitou@Sun.com 377 15. Full Copyright Statement 379 Copyright (C) The Internet Society (2003). All Rights Reserved. 381 This document and translations of it may be copied and furnished to 382 others, and derivative works that comment on or otherwise explain it 383 or assist in its implementation may be prepared, copied, published 384 and distributed, in whole or in part, without restriction of any 385 kind, provided that the above copyright notice and this paragraph 386 are included on all such copies and derivative works. However, this 387 document itself may not be modified in any way, such as by removing 388 the copyright notice or references to the Internet Society or other 389 Internet organizations, except as needed for the purpose of 390 developing Internet standards in which case the procedures for 391 copyrights defined in the Internet Standards process must be 392 followed, or as required to translate it into languages other than 393 English. 395 The limited permissions granted above are perpetual and will not be 396 revoked by the Internet Society or its successors or assigns. 398 This document and the information contained herein is provided on an 399 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE 400 INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR 401 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 402 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 403 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.