idnits 2.17.1 draft-good-ldap-changelog-01.txt: 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? == No 'Intended status' indicated for this document; assuming Proposed Standard 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 separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 35 instances of too long lines in the document, the longest one being 8 characters in excess of 72. ** The abstract seems to contain references ([2], [3], [1]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == 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 (10 March 2000) is 8803 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Unexpected draft version: The latest known version of draft-good-ldap-ldif is -05, but you're referring to -06. ** Obsolete normative reference: RFC 2251 (ref. '2') (Obsoleted by RFC 4510, RFC 4511, RFC 4512, RFC 4513) Summary: 7 errors (**), 0 flaws (~~), 2 warnings (==), 3 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 Change Record Object Class Definition Gordon Good 2 INTERNET-DRAFT Netscape Communications 3 10 March 2000 5 Definition of an Object Class to Hold LDAP Change Records 6 Filename: draft-good-ldap-changelog-01.txt 8 Status of this Memo 10 This document is an Internet-Draft and is in full conformance with 11 all provisions of Section 10 of RFC2026. 13 Internet-Drafts are working documents of the Internet Engineering 14 Task Force (IETF), its areas, and its working groups. Note that other 15 groups may also distribute working documents as Internet-Drafts. 17 Internet-Drafts are draft documents valid for a maximum of six months 18 and may be updated, replaced, or obsoleted by other documents at any 19 time. It is inappropriate to use Internet- Drafts as reference 20 material or to cite them other than as "work in progress." 22 The list of current Internet-Drafts can be accessed at 23 http://www.ietf.org/ietf/1id-abstracts.txt 25 The list of Internet-Draft Shadow Directories can be accessed at 26 http://www.ietf.org/shadow.html. 28 This Internet Draft expires September 10, 2000. 30 Abstract 32 In order to support more flexible replication methods, it is 33 desirable to specify some manner in which an LDAP client may retrieve 34 a set of changes which have been applied to an LDAP server's 35 database. The client, which may be another LDAP server, may then 36 choose to update its own replicated copy of the data. This document 37 specifies an object class which may be used to represent changes 38 applied to an LDAP server. It also specifies a method for 39 discovering the location of the container object which holds these 40 change records, so that clients and servers have a common rendezvous 41 point for this information. 43 Background and Intended Usage 45 This document describes an objectclass which can be used to represent 46 changes which have been applied to a directory server. It also 47 suggests a common location for a container which holds these objects. 49 A client may update its local copy of directory information by 50 reading the entries within this container, and applying the changes 51 to its local database. 53 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 54 "SHOULD", "SHOULD NOT", "RECOMMENDED", and "MAY" in this document are 55 to be interpreted as described in RFC 2119 [3]. 57 New Attribute Types Used in the changeLogEntry Object Class 59 ( 2.16.840.1.113730.3.1.5 60 NAME 'changeNumber' 61 DESC 'a number which uniquely identifies a change made to a 62 directory entry' 63 SYNTAX 'INTEGER' 64 EQUALITY 'integerMatch' 65 ORDERING 'integerOrderingMatch' ) 67 ( 2.16.840.1.113730.3.1.6 68 NAME 'targetDN' 69 DESC 'the DN of the entry which was modified' 70 EQUALITY distinguishedNameMatch 71 SYNTAX 'DN' ) 73 ( 2.16.840.1.113730.3.1.7 74 NAME 'changeType' 75 DESC 'the type of change made to an entry' 76 EQUALITY caseIgnoreMatch 77 SYNTAX 'DirectoryString' ) 79 ( 2.16.840.1.113730.3.1.8 80 NAME 'changes' 81 DESC 'a set of changes to apply to an entry' 82 SYNTAX 'OctetString' ) 84 ( 2.16.840.1.113730.3.1.9 85 NAME 'newRDN' 86 DESC 'the new RDN of an entry which is the target of a 87 modrdn operation' 88 EQUALITY distinguishedNameMatch 89 SYNTAX 'DN' ) 91 ( 2.16.840.1.113730.3.1.10 92 NAME 'deleteOldRDN' 93 DESC 'a flag which indicates if the old RDN should be retained 94 as an attribute of the entry' 95 EQUALITY booleanMatch 96 SYNTAX 'BOOLEAN' ) 98 ( 2.16.840.1.113730.3.1.11 99 NAME 'newSuperior' 100 DESC 'the new parent of an entry which is the target of a 101 moddn operation' 102 EQUALITY distinguishedNameMatch 103 SYNTAX 'DN' ) 105 Schema Definition of the changeLogEntry Object Class 107 ( 2.16.840.1.113730.3.2.1 108 NAME 'changeLogEntry' 109 SUP top 110 STRUCTURAL 111 MUST ( 112 changeNumber $ targetDN $ changeType 113 ) 114 MAY ( 115 changes $ newRDN $ deleteOldRDN $ newSuperior 116 ) 117 ) 119 Discussion of changeLogEntry Attributes: 121 changeNumber: the change number, as assigned by the supplier. This 122 integer MUST strictly increase as new entries are added, and must 123 always be unique within a given server. Syntax: INTEGER 125 targetdn: the distinguished name of the entry which was added, 126 modified or deleted. In the case of a modrdn operation, the targetdn 127 gives the DN of the entry before it was modified. Syntax: DN 129 changeType: the type of change. One of: "add", "delete", "modify", 130 "modrdn". Later RFCs may define additional values for changeType. 131 Syntax: DirectoryString 133 changes: the changes which were made to the directory server. These 134 changes are in LDIF format, which is described in [1]. 135 Syntax: OctetString 137 newRDN: the new RDN (Relative Distinguished Name) of the entry, if the 138 changeType is "modrdn". If the changeType attribute does not have the 139 value "modrdn", then there should be no values contained in the newRDN 140 attribute. 141 Syntax: DN 142 deleteOldRDN: a flag which tells whether the old RDN of the entry 143 should be retained as a distinguished attribute of the entry, or 144 should be deleted. A value of "FALSE" indicates that the RDN should be 145 retained as a distinguished attribute, and a value of "TRUE" indicates 146 that it should not be retained as a distinguished attribute of the 147 entry. If any value other than "TRUE" or "FALSE" is contained in the 148 deleteOldRDN attribute, or if the deleteOldRDN contains multiple 149 values, the RDN should be retained as a distinguished attribute (that 150 is, "FALSE" is the default if no values are present, or if illegal 151 values are present). 152 Syntax: BOOLEAN 154 newSuperior: if present, gives the name of the entry which 155 becomes the immediate superior of the existing entry. This optional 156 attribute reflects LDAPv3 functionality, and MUST NOT be generated 157 by LDAPv2 servers [2]. 158 Syntax: DN 160 Discussion of the changeLogEntry object class 162 The changeLogEntry object class is used to represent changes made to a 163 directory server. The set of changes made to a directory server, then, 164 is given by the ordered set of all entries within the changelog 165 container, ordered by changeNumber. 167 A client may synchronize its local copy of a remote directory server's 168 contents by searching the remote server's changelog container for any 169 entries where the changenumber is greater than or equal to the last 170 change previously retrieved from that server. If the entry with the 171 changenumber matching the last change retrieved is not returned in the 172 search results, then the server's changelog has been trimmed. The 173 client must then fall back to reading the entire directory to bring its 174 copy in sync with the server's. 176 Assuming that the client has successfully retrieved one or more changelog 177 entries from the server, it can then use the information contained in each 178 entry to update the corresponding entry (named by the targetDN attribute) 179 in its local copy of the database. 181 Note that, due to access control restrictions, the client is not guaranteed 182 read access to the "changes" attribute. If the client discovers that the 183 "changes" attribute has no values, then it must read the entry given by 184 the targetDN attribute, possibly only retrieving attributes it deems 185 "interesting". However, in the case of delete and modrdn operations, there 186 is never a "changes" attribute, so it is never necessary to read the target 187 entry in these cases. 189 Examples of the changeLogEntry object class 191 In each example below, the "changes" attribute is shown in plain text, 192 with embedded newlines. This is done for clarity. It is intended that 193 newlines be stored in the entry literally, not encoded in any way. 194 If a "changes" attribute value is stored in an LDIF file, it must 195 base-64 encoded. 197 Example 1: A changeLogEntry representing the addition of a 198 new entry to the directory 200 dn: changenumber=1923, cn=changelog 201 changenumber: 1923 202 targetdn: cn=Barbara Jensen, ou=Accounting, o=Ace Industry, c=US 203 changetype: add 204 changes: cn: Barbara Jensen\ncn: Babs Jensen\nsn: Jensen\n 205 givenname: Barbara\ntelephonenumber: +1 212 555-1212\nmail: babs@ace.com\n 206 objectclass: top\nobjectclass: person\nobjectclass: organizationalPerson\n 207 objectclass: inetOrgPerson 209 Example 2: A changeLogEntry representing the deletion of an entry 210 from the directory 212 dn: changenumber=2933, cn=changelog 213 changenumber: 2933 214 targetdn: cn=Gern Jensen, ou=Product Testing, o=Ace Industry, c=US 215 changetype: delete 217 Example 3: A changeLogEntry representing the modification of an entry 218 in the directory 220 dn: changenumber=5883, cn=changelog 221 changenumber: 5883 222 targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, c=US 223 changetype: modify 224 changes: delete: telephonenumber\ntelephonenumber: 1212\n-\n 225 add: telephonenumber\ntelephonenumber: +1 212 555 1212\n- 227 Example 4: A changeLogEntry representing a modrdn operation performed 228 on an entry in the directory 230 dn: changenumber=10042, cn=changelog 231 changenumber: 10042 232 targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, c=US 233 changetype: modrdn 234 newrdn: cn=Bjorn J Jensen 235 deleteoldrdn: FALSE 237 Location of the container containing changeLogEntry objects 239 For LDAPv3 servers, the location of the container which holds 240 changeLogEntry objects is obtained by reading the "changeLog" attribute 241 of a server's root DSE. For example, if the container's root is 242 "cn=changelog", then the root DSE must have an attribute named 243 "changeLog" with the value "cn=changelog". 245 The "changelog" attribute is defined as follows: 247 ( 2.16.840.1.113730.3.1.35 248 NAME 'changelog' 249 DESC 'the distinguished name of the entry which contains 250 the set of entries comprising this server's changelog' 251 EQUALITY distinguishedNameMatch 252 SYNTAX 'DN' 253 ) 255 For LDAPv2 servers, the name of the changelog container must be 256 "cn=changelog". 258 Interoperability between LDAPv2 and LDAPv3 implementations 260 Implementors are discouraged from developing implementations in which 261 an LDAPv2 server is synchronized from an LDAPv3 server using the 262 changelog method described in this document. Problems can arise when an 263 LDAPv2 server reads a "moddn" changelog entry which gives a new 264 superior. Since LDAPv2 does not support such an operation, there is not 265 way for the v2 server to perform the moddn operation atomically. It 266 could, of course, delete all the entries under the old superior and add 267 them under the new superior entry, but such an operation would either 268 not be atomic, or require extensive server-side support on the LDAPv2 269 server to make the operation appear as if it were atomic. 271 It is recommended that servers which only implement LDAPv2 should 272 refuse to synchronize from LDAPv3 servers. Before beginning 273 synchronization, the LDAPv2 server should attempt to read the root DSE 274 of the supplier server. If the root DSE is present, and the 275 supportedldapversion attribute contained in the root DSE contains the 276 value "3", then the LDAPv2 server should immediately disconnect and 277 proceed no further with synchronization. 279 Security Considerations 281 Servers implementing this scheme MUST NOT allow the "changes" 282 attribute to be generally readable. The "changes" attribute contains 283 all modifications made to an entry, and some changes may contain 284 sensitive data, e.g. passwords. 286 If a server does allow read access on the "changes: attribute to a 287 particular bound DN, then that DN should be trusted. For example, two 288 cooperating servers may exchange the password for some DN which is 289 granted read access to the "changes" attribute of the changeLog. This 290 would allow one server to retrieve changes and apply them directly to 291 its database. 293 In situations where the "changes" attribute is not readable by a client, 294 that client may still use the entries in the changeLog to construct a 295 list of entry DNs which are known to have changed since the last time 296 the client synchronized. The client may then read each of those entries, 297 subject to whatever access control is in effect on the server, 298 and update its local copy of each entry. 300 Servers implementing this scheme should disallow write access to the 301 changelog container object and all entries contained within. 303 Acknowledgements 305 This material is based in part upon work supported by the National 306 Science Foundation under Grant No. NCR-9416667. 308 References 310 [1] Good, G., "The LDAP Data Interchange Format", INTERNET-DRAFT 311 draft-good-ldap-ldif-06.txt, Netscape Communications Corp., March 2000 312 314 [2] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access 315 Protocol (v3)", RFC 2251 Critical Angle, Inc., Netscape Communications Corp., 316 ISODE Consortium, July, 1997, 317 319 [3] S. Bradner, "Key Words for use in RFCs to Indicate Requirement 320 Levels", Harvard University, RFC 2119, March 1997, 321 323 Author's Address 325 Gordon Good 326 Netscape Communications Corp. 327 501 E. Middlefield Rd. 328 Mailstop MV068 329 Mountain View, CA 94043, USA 330 Phone: +1 650 937-3825 331 EMail: ggood@netscape.com 333 This Internet Draft expires September 10, 2000