idnits 2.17.1 draft-good-ldap-changelog-03.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. ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 93 instances of too long lines in the document, the longest one being 4 characters in excess of 72. Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 379 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.) -- Couldn't find a document date in the document -- date freshness check skipped. Checking references for intended status: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 2251 (ref. '2') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) Summary: 8 errors (**), 0 flaws (~~), 2 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-03.txt Loudcloud 4 Intended Category: Informational Ludovic Poitou 5 Expires: May 2002 Sun Microsystems 7 20 November, 2001 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 2001, The Internet Society. 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, which 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. This object class is not intended to be used in a multi- 55 mastered replication environment, where changes can occur on more 56 than one master server. 58 This document also suggests a common location for a container to 59 hold these objects. 61 A client may update its local copy of directory information by 62 reading the entries within this container, and applying the changes 63 to its local database. 65 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 66 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document 67 are to be interpreted as described in RFC 2119 [3]. 69 3. New Attribute Types Used in the changeLogEntry Object Class 71 ( 2.16.840.1.113730.3.1.5 72 NAME 'changeNumber' 73 DESC 'a number which uniquely identifies a change made to a 74 directory entry' 75 SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 76 EQUALITY integerMatch 77 ORDERING integerOrderingMatch 78 SINGLE-VALUE 79 ) 81 ( 2.16.840.1.113730.3.1.6 82 NAME 'targetDN' 83 DESC 'the DN of the entry which was modified' 84 EQUALITY distinguishedNameMatch 85 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 86 SINGLE-VALUE 87 ) 89 ( 2.16.840.1.113730.3.1.7 90 NAME 'changeType' 91 DESC 'the type of change made to an entry' 92 EQUALITY caseIgnoreMatch 93 SYNTAX 1.3.6.1.4.1.1466.115.121.1.15 94 SINGLE-VALUE 95 ) 97 ( 2.16.840.1.113730.3.1.8 98 NAME 'changes' 99 DESC 'a set of changes to apply to an entry' 100 SYNTAX 1.3.6.1.4.1.1466.115.121.1.40 101 ) 102 ( 2.16.840.1.113730.3.1.9 103 NAME 'newRDN' 104 DESC 'the new RDN of an entry which is the target of a 105 modrdn operation' 106 EQUALITY distinguishedNameMatch 107 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 108 SINGLE-VALUE 109 ) 111 ( 2.16.840.1.113730.3.1.10 112 NAME 'deleteOldRDN' 113 DESC 'a flag which indicates if the old RDN should be retained 114 as an attribute of the entry' 115 EQUALITY booleanMatch 116 SYNTAX 1.3.6.1.4.1.1466.115.121.1.7 117 SINGLE-VALUE 118 ) 120 ( 2.16.840.1.113730.3.1.11 121 NAME 'newSuperior' 122 DESC 'the new parent of an entry which is the target of a 123 moddn operation' 124 EQUALITY distinguishedNameMatch 125 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 126 SINGLE-VALUE 127 ) 129 4. Schema Definition of the changeLogEntry Object Class 131 ( 2.16.840.1.113730.3.2.1 132 NAME 'changeLogEntry' 133 SUP top 134 STRUCTURAL 135 MUST ( changeNumber $ targetDN $ changeType ) 136 MAY ( changes $ newRDN $ deleteOldRDN $ newSuperior ) 137 ) 139 5. Discussion of changeLogEntry Attributes: 141 changeNumber: the change number, as assigned by the supplier. This 142 integer MUST strictly increase as new entries are added, and must 143 always be unique within a given server. 144 Syntax: INTEGER 146 targetdn: the distinguished name of the entry which was added, 147 modified or deleted. In the case of a modrdn operation, the 148 targetdn gives the DN of the entry before it was modified. 149 Syntax: DN 151 changeType: the type of change. One of: "add", "delete", "modify", 152 "modrdn". Later RFCs may define additional values for changeType. 153 Syntax: DirectoryString 154 changes: the changes which were made to the directory server. These 155 changes are in LDIF format, which is described in [1]. 156 Syntax: OctetString 158 newRDN: the new RDN (Relative Distinguished Name) of the entry, if 159 the changeType is "modrdn". If the changeType attribute does not 160 have the value "modrdn", then there should be no values contained in 161 the newRDN attribute. 162 Syntax: DN 164 deleteOldRDN: a flag which tells whether the old RDN of the entry 165 should be retained as a distinguished attribute of the entry, or 166 should be deleted. A value of "FALSE" indicates that the RDN should 167 be retained as a distinguished attribute, and a value of "TRUE" 168 indicates that it should not be retained as a distinguished 169 attribute of the entry. If any value other than "TRUE" or "FALSE" 170 is contained in the deleteOldRDN, the RDN should be retained as a 171 distinguished attribute (that is, "FALSE" is the default if no 172 values are present, or if illegal values are present). 173 Syntax: BOOLEAN 175 newSuperior: if present, gives the name of the entry which becomes 176 the immediate superior of the existing entry. This optional 177 attribute reflects LDAPv3 functionality, and MUST NOT be generated 178 by LDAPv2 servers [2]. 179 Syntax: DN 181 6. Discussion of the changeLogEntry object class 183 The changeLogEntry object class is used to represent changes made to 184 a directory server. The set of changes made to a directory server, 185 then, is given by the ordered set of all entries within the 186 changelog container, ordered by changeNumber. As a changeNumber is 187 unique, it is recommended that the changeNumber attribute be used to 188 name changeLogEntry entries. 190 A client may synchronize its local copy of a remote directory 191 server's contents by searching the remote server's changelog 192 container for any entries where the changenumber is greater than or 193 equal to the last change previously retrieved from that server. If 194 the entry with the changenumber matching the last change retrieved 195 is not returned in the search results, then the server's changelog 196 has been trimmed. The client must then fall back to reading the 197 entire directory to bring its copy in sync with the server's. 199 Assuming that the client has successfully retrieved one or more 200 changelog entries from the server, it can then use the information 201 contained in each entry to update the corresponding entry (named by 202 the targetDN attribute) in its local copy of the database. 204 Note that, due to access control restrictions, the client is not 205 guaranteed read access to the "changes" attribute. If the client 206 discovers that the "changes" attribute has no values, then it must 207 read the entry given by the targetDN attribute, possibly only 208 retrieving attributes it deems "interesting". However, in the case 209 of delete and modrdn operations, there is never a "changes" 210 attribute, so it is never necessary to read the target entry in 211 these cases. 213 Servers implementing this document MUST trim the changeLogEntry 214 entries only in changeNumber order. 216 7. Examples of the changeLogEntry object class 218 In each example below, the "changes" attribute is shown in plain 219 text, with embedded new-line characters. This is done for clarity. 220 It is intended that new-line characters be stored in the entry 221 literally, not encoded in any way. If a "changes" attribute value is 222 stored in an LDIF file, it must base-64 encoded. 224 Example 1: A changeLogEntry representing the addition of a new entry 225 to the directory 227 dn: changenumber=1923, cn=changelog 228 changenumber: 1923 229 targetdn: cn=Barbara Jensen, ou=Accounting, o=Ace Industry, c=US 230 changetype: add 231 changes: cn: Barbara Jensen\ncn: Babs Jensen\nsn: Jensen\n 232 givenname: Barbara\ntelephonenumber: +1 212 555-1212\nmail: 233 babs@ace.com\nobjectclass: top\nobjectclass: person\nobjectclass: 234 organizationalPerson\nobjectclass: inetOrgPerson 236 Example 2: A changeLogEntry representing the deletion of an entry 237 from the directory 239 dn: changenumber=2933, cn=changelog 240 changenumber: 2933 241 targetdn: cn=Gern Jensen, ou=Product Testing, o=Ace Industry, c=US 242 changetype: delete 244 Example 3: A changeLogEntry representing the modification of an 245 entry in the directory 247 dn: changenumber=5883, cn=changelog 248 changenumber: 5883 249 targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, 250 c=US 251 changetype: modify 252 changes: delete: telephonenumber\ntelephonenumber: 1212\n-\n 253 add: telephonenumber\ntelephonenumber: +1 212 555 1212\n- 255 Example 4: A changeLogEntry representing a modrdn operation 256 performed on an entry in the directory 258 dn: changenumber=10042, cn=changelog 259 changenumber: 10042 260 targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, 261 c=US 262 changetype: modrdn 263 newrdn: cn=Bjorn J Jensen 264 deleteoldrdn: FALSE 266 8. Location of the container containing changeLogEntry objects 268 For LDAPv3 servers, the location of the container that holds 269 changeLogEntry objects is obtained by reading the "changeLog" 270 attribute of a server's root DSE. For example, if the container's 271 root is "cn=changelog", then the root DSE must have an attribute 272 named "changeLog" with the value "cn=changelog". 274 The "changelog" attribute is defined as follows: 276 ( 2.16.840.1.113730.3.1.35 277 NAME 'changelog' 278 DESC 'the distinguished name of the entry which contains 279 the set of entries comprising this server's changelog' 280 EQUALITY distinguishedNameMatch 281 SYNTAX 1.3.6.1.4.1.1466.115.121.1.12 282 ) 284 For LDAPv2 servers, the name of the changelog container must be 285 "cn=changelog". 287 9. Interoperability between LDAPv2 and LDAPv3 implementations 289 Implementors are discouraged from developing implementations in 290 which an LDAPv2 server is synchronized from an LDAPv3 server using 291 the changelog method described in this document. Problems can arise 292 when an LDAPv2 server reads a "moddn" changelog entry which gives a 293 new superior. Since LDAPv2 does not support such an operation, there 294 is no way for the v2 server to perform the moddn operation 295 atomically. It could, of course, delete all the entries under the 296 old superior and add them under the new superior entry, but such an 297 operation would either not be atomic, or require extensive server- 298 side support on the LDAPv2 server to make the operation appear as if 299 it were atomic. 301 It is recommended that servers who only implement LDAPv2 should 302 refuse to synchronize from LDAPv3 servers. Before beginning 303 synchronization, the LDAPv2 server should attempt to read the root 304 DSE of the supplier server. If the root DSE is present, and the 305 supportedldapversion attribute contained in the root DSE contains 306 the value "3", then the LDAPv2 server should immediately disconnect 307 and proceed no further with synchronization. 309 10. Security Considerations 310 Servers implementing this scheme MUST NOT allow the "changes" 311 attribute to be generally readable. The "changes" attribute 312 contains all modifications made to an entry, and some changes may 313 contain sensitive data, e.g. Passwords. 315 If a server does allow read access on the "changes: attribute to a 316 particular bound DN, then that DN should be trusted. For example, 317 two cooperating servers may exchange the password for some DN that 318 is granted read access to the "changes" attribute of the changeLog. 319 This would allow one server to retrieve changes and apply them 320 directly to its database. 322 In situations where the "changes" attribute is not readable by a 323 client, that client may still use the entries in the changeLog to 324 construct a list of entry DNs which are known to have changed since 325 the last time the client synchronized. The client may then read 326 each of those entries, subject to whatever access control is in 327 effect on the server, and update its local copy of each entry. 329 Servers implementing this scheme should disallow write access to the 330 changelog container object and all entries contained within. 332 11. Acknowledgements 334 This material is based in part upon work supported by the National 335 Science Foundation under Grant No. NCR-9416667. 337 12. References 339 [1] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical 340 Specification", RFC 2849, June 2000. 342 [2] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access 343 Protocol (v3)", RFC 2251, July 1997. 345 [3] S. Bradner, "Key Words for use in RFCs to Indicate Requirement 346 Levels", RFC 2119, March 1997. 348 13. Authors's Address 350 Gordon Good 351 Loudcloud, Inc. 352 599 N. Mathilda Avenue 353 Sunnyvale, CA 94085 354 USA 355 Phone: +1 408 744-7300 356 EMail: ggood@loudcloud.com 358 Ludovic Poitou 359 Sun Microsystems Inc. 361 14 Chemin du vieux chene 362 38240 Meylan 363 France 364 Phone: +33 476 188 212 365 Email: ludovic.poitou@Sun.com 367 14. Full Copyright Statement 369 Copyright 2001, The Internet Society. All Rights Reserved. 371 This document and translations of it may be copied and furnished to 372 others, and derivative works that comment on or otherwise explain it 373 or assist in its implementation may be prepared, copied, published 374 and distributed, in whole or in part, without restriction of any 375 kind, provided that the above copyright notice and this paragraph 376 are included on all such copies and derivative works. However, this 377 document itself may not be modified in any way, such as by removing 378 the copyright notice or references to the Internet Society or other 379 Internet organizations, except as needed for the purpose of 380 developing Internet standards in which case the procedures for 381 copyrights defined in the Internet Standards process must be 382 followed, or as required to translate it into languages other than 383 English. 385 The limited permissions granted above are perpetual and will not be 386 revoked by the Internet Society or its successors or assigns. 388 This document and the information contained herein is provided on an 389 "AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE 390 INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR 391 IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 392 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 393 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.