Internet Draft Gordon Good
draft-good-ldap-changelog-03.txt Loudcloud
Intended Category: Informational Ludovic Poitou
Expires: May 2002 Sun Microsystems
20 November, 2001
Definition of an Object Class to Hold LDAP Change Records
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC 2026.
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.
Copyright 2001, The Internet Society. All rights Reserved.
Please see the Copyright Section near the end of this document for
more information.
1. 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 that 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 that may be used to represent changes
applied to an LDAP server. It also specifies a method for
discovering the location of the container object that holds these
change records, so that clients and servers have a common rendezvous
point for this information.
Good & Poitou [Page 1]
INTERNET-DRAFT Change Record Object Class November 2001
2. Background and Intended Usage
This document describes an object class that can be used to
represent changes that have been applied to a single directory
server. This object class is not intended to be used in a multi-
mastered replication environment, where changes can occur on more
than one master server.
This document also suggests a common location for a container to
hold these objects.
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].
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 1.3.6.1.4.1.1466.115.121.1.27
EQUALITY integerMatch
ORDERING integerOrderingMatch
SINGLE-VALUE
)
( 2.16.840.1.113730.3.1.6
NAME 'targetDN'
DESC 'the DN of the entry which was modified'
EQUALITY distinguishedNameMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.12
SINGLE-VALUE
)
( 2.16.840.1.113730.3.1.7
NAME 'changeType'
DESC 'the type of change made to an entry'
EQUALITY caseIgnoreMatch
SYNTAX 1.3.6.1.4.1.1466.115.121.1.15
SINGLE-VALUE
)
( 2.16.840.1.113730.3.1.8
NAME 'changes'
DESC 'a set of changes to apply to an entry'
SYNTAX 1.3.6.1.4.1.1466.115.121.1.40
)
Good & Poitou Expires May 20, 2002 [Page 2]
INTERNET-DRAFT Change Record Object Class November 2001
( 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 1.3.6.1.4.1.1466.115.121.1.12
SINGLE-VALUE
)
( 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 1.3.6.1.4.1.1466.115.121.1.7
SINGLE-VALUE
)
( 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 1.3.6.1.4.1.1466.115.121.1.12
SINGLE-VALUE
)
4. 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 )
)
5. 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
Good & Poitou Expires May 20, 2002 [Page 3]
INTERNET-DRAFT Change Record Object Class November 2001
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
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, 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
6. 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. As a changeNumber is
unique, it is recommended that the changeNumber attribute be used to
name changeLogEntry entries.
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
Good & Poitou Expires May 20, 2002 [Page 4]
INTERNET-DRAFT Change Record Object Class November 2001
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.
Servers implementing this document MUST trim the changeLogEntry
entries only in changeNumber order.
7. Examples of the changeLogEntry object class
In each example below, the "changes" attribute is shown in plain
text, with embedded new-line characters. This is done for clarity.
It is intended that new-line characters 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\nobjectclass: top\nobjectclass: person\nobjectclass:
organizationalPerson\nobjectclass: 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
Good & Poitou Expires May 20, 2002 [Page 5]
INTERNET-DRAFT Change Record Object Class November 2001
changenumber: 10042
targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry,
c=US
changetype: modrdn
newrdn: cn=Bjorn J Jensen
deleteoldrdn: FALSE
8. Location of the container containing changeLogEntry objects
For LDAPv3 servers, the location of the container that 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 1.3.6.1.4.1.1466.115.121.1.12
)
For LDAPv2 servers, the name of the changelog container must be
"cn=changelog".
9. 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 no 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 who 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.
10. Security Considerations
Good & Poitou Expires May 20, 2002 [Page 6]
INTERNET-DRAFT Change Record Object Class November 2001
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.
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 that
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.
11. Acknowledgements
This material is based in part upon work supported by the National
Science Foundation under Grant No. NCR-9416667.
12. References
[1] Good, G., "The LDAP Data Interchange Format (LDIF) - Technical
Specification", RFC 2849, June 2000.
[2] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access
Protocol (v3)", RFC 2251, July 1997.
[3] S. Bradner, "Key Words for use in RFCs to Indicate Requirement
Levels", RFC 2119, March 1997.
13. Authors's Address
Gordon Good
Loudcloud, Inc.
599 N. Mathilda Avenue
Sunnyvale, CA 94085
USA
Phone: +1 408 744-7300
EMail: ggood@loudcloud.com
Ludovic Poitou
Sun Microsystems Inc.
Good & Poitou Expires May 20, 2002 [Page 7]
INTERNET-DRAFT Change Record Object Class November 2001
14 Chemin du vieux chene
38240 Meylan
France
Phone: +33 476 188 212
Email: ludovic.poitou@Sun.com
14. Full Copyright Statement
Copyright 2001, The Internet Society. All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph
are included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assigns.
This document and the information contained herein is provided on an
"AS IS" basis and THE AUTHORS, THE INTERNET SOCIETY, AND THE
INTERNET ENGINEERING TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Good & Poitou Expires May 20, 2002 [Page 8]