Change Record Object Class Definition Gordon Good
INTERNET-DRAFT Netscape Communications
10 March 2000
Definition of an Object Class to Hold LDAP Change Records
Filename: draft-good-ldap-changelog-01.txt
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
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.
This Internet Draft expires September 10, 2000.
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 which 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 which may be used to represent changes
applied to an LDAP server. It also specifies a method for
discovering the location of the container object which holds these
change records, so that clients and servers have a common rendezvous
point for this information.
Background and Intended Usage
This document describes an objectclass which can be used to represent
changes which have been applied to a directory server. It also
suggests a common location for a container which holds these objects.
Good March 9, 2000 [Page 1]
INTERNET-DRAFT Change Record Object Class 11 March 1998
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].
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 'INTEGER'
EQUALITY 'integerMatch'
ORDERING 'integerOrderingMatch' )
( 2.16.840.1.113730.3.1.6
NAME 'targetDN'
DESC 'the DN of the entry which was modified'
EQUALITY distinguishedNameMatch
SYNTAX 'DN' )
( 2.16.840.1.113730.3.1.7
NAME 'changeType'
DESC 'the type of change made to an entry'
EQUALITY caseIgnoreMatch
SYNTAX 'DirectoryString' )
( 2.16.840.1.113730.3.1.8
NAME 'changes'
DESC 'a set of changes to apply to an entry'
SYNTAX 'OctetString' )
( 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 'DN' )
( 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 'BOOLEAN' )
Good March 9, 2000 [Page 2]
INTERNET-DRAFT Change Record Object Class 11 March 1998
( 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 'DN' )
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
)
)
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
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
Good March 9, 2000 [Page 3]
INTERNET-DRAFT Change Record Object Class 11 March 1998
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 attribute, or if the deleteOldRDN contains multiple
values, 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
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.
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 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.
Good March 9, 2000 [Page 4]
INTERNET-DRAFT Change Record Object Class 11 March 1998
Examples of the changeLogEntry object class
In each example below, the "changes" attribute is shown in plain text,
with embedded newlines. This is done for clarity. It is intended that
newlines 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\n
objectclass: top\nobjectclass: person\nobjectclass: organizationalPerson\n
objectclass: 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
changenumber: 10042
targetdn: cn=Bjorn Jensen, ou=Product Development, o=Ace Industry, c=US
changetype: modrdn
newrdn: cn=Bjorn J Jensen
deleteoldrdn: FALSE
Good March 9, 2000 [Page 5]
INTERNET-DRAFT Change Record Object Class 11 March 1998
Location of the container containing changeLogEntry objects
For LDAPv3 servers, the location of the container which 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 'DN'
)
For LDAPv2 servers, the name of the changelog container must be
"cn=changelog".
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 not
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 which 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.
Security Considerations
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.
Good March 9, 2000 [Page 6]
INTERNET-DRAFT Change Record Object Class 11 March 1998
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 which 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.
Acknowledgements
This material is based in part upon work supported by the National
Science Foundation under Grant No. NCR-9416667.
References
[1] Good, G., "The LDAP Data Interchange Format", INTERNET-DRAFT
draft-good-ldap-ldif-06.txt, Netscape Communications Corp., March 2000
<URL:ftp://ftp.ietf.org/internet-drafts/draft-good-ldap-ldif-06.txt>
[2] Wahl, M., Howes, T., Kille, S., "Lightweight Directory Access
Protocol (v3)", RFC 2251 Critical Angle, Inc., Netscape Communications Corp.,
ISODE Consortium, July, 1997,
<URL:ftp://ftp.isi.edu/in-notes/rfc2251.txt>
[3] S. Bradner, "Key Words for use in RFCs to Indicate Requirement
Levels", Harvard University, RFC 2119, March 1997,
<URL:http://ds.internic.net/rfc/rfc2119.txt>
Author's Address
Gordon Good
Netscape Communications Corp.
501 E. Middlefield Rd.
Mailstop MV068
Good March 9, 2000 [Page 7]
INTERNET-DRAFT Change Record Object Class 11 March 1998
Mountain View, CA 94043, USA
Phone: +1 650 937-3825
EMail: ggood@netscape.com
This Internet Draft expires September 10, 2000
Good March 9, 2000 [Page 8]