< draft-ietf-ldup-mrm-01.txt   draft-ietf-ldup-mrm-02.txt >
INTERNET DRAFT Mandatory LDAP Replica Management February 2002 INTERNET DRAFT Mandatory LDAP Replica Management March 2003
Internet-Draft Ryan Moats Internet-Draft Ryan Moats
LDAP Duplication/Replication/Update Lemur Networks, Inc. LDAP Duplication/Replication/Update Lemur Networks, Inc.
Protocols WG Rick Huber Protocols WG Rick Huber
Intended Category: Standard AT&T Laboratories Expires September 2003 AT&T Laboratories
Expires August 2002 John McMeeking John McMeeking
IBM IBM
February 2002 March 2003
Mandatory LDAP Replica Management Mandatory LDAP Replica Management
Filename: draft-ietf-ldup-mrm-01.txt Filename: draft-ietf-ldup-mrm-02.txt
Status of this Memo Status of this Memo
This document is an Internet-Draft and is in full conformance with all This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026. provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering Task Internet-Drafts are working documents of the Internet Engineering Task
Force (IETF), its areas, and its working groups. Note that other Force (IETF), its areas, and its working groups. Note that other
groups may also distribute working documents as Internet-Drafts. groups may also distribute working documents as Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference material time. It is inappropriate to use Internet-Drafts as reference material
or to cite them other than as "work in progress." or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/lid-abstracts.txt. http://www.ietf.org/ietf/lid-abstracts.txt.
skipping to change at page 1, line 53 skipping to change at page 1, line 52
replication among products from many different vendors. Defining the replication among products from many different vendors. Defining the
mechanism to move data among replicas is a necessary part of this work, mechanism to move data among replicas is a necessary part of this work,
but management of the replicated environment must also be standardized but management of the replicated environment must also be standardized
for replication to be truly interoperable. for replication to be truly interoperable.
This document presents the replication management functions that must This document presents the replication management functions that must
be performed. Whenever possible, these functions are defined in terms be performed. Whenever possible, these functions are defined in terms
of existing LDAP functionality using existing LDAP operations and of existing LDAP functionality using existing LDAP operations and
existing data definitions. In some cases, changes or additions to the existing data definitions. In some cases, changes or additions to the
existing model are required, and specifications for these changes are existing model are required, and specifications for these changes are
included in this document. included in this document.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in [RFC2119]. document are to be interpreted as described in [RFC2119].
1 Table of Contents Table of Contents
Status of this Memo...................................................1 Status of this Memo...................................................1
Abstract..............................................................1 Abstract..............................................................1
1 Table of Contents ..................................................2 Table of Contents.....................................................2
2 Introduction .......................................................3 1 Introduction .......................................................3
3 Administrative Precursors ..........................................3 2 Administrative Precursors ..........................................4
4 Operational "Atoms" ................................................4 3 Operational "Atoms" ................................................4
4.1 Add area of replication to a server ..............................4 3.1 Add area of replication to a server ............................5
4.2 Delete area of replication from a server .........................5 3.2 Delete area of replication from a server .......................5
4.3 Copy base of area of replication between servers .................5 3.3 Copy base of area of replication between servers ...............6
4.4 Create server entry for an area of replication ...................5 3.4 Create server entry for an area of replication .................6
4.5 Delete server entry from an area of replication ..................6 3.5 Delete server entry from an area of replication ................6
4.6 Modify replica ...................................................6 3.6 Modify replica .................................................7
4.6.1 Change Replica Type ............................................6 3.6.1 Change Replica Type .........................................7
4.6.2 Change Between Full/Partial Replica ............................7 3.6.2 Change Between Full/Partial Replica .........................7
4.6.3 Change Replica URI for one server for one area of replication ..7 3.6.3 Change Replica URI for one server for one area of replication
4.7 Add Replication Agreement ........................................7 8
4.8 Delete Replication Agreement .....................................8 3.7 Add Replication Agreement ......................................8
4.9 Modify Replication Agreement .....................................8 3.8 Delete Replication Agreement ...................................9
4.10 Suspend Replication .............................................9 3.9 Modify Replication Agreement ...................................9
4.11 Resume Replication ..............................................9 3.10 Suspend Replication ..........................................9
4.12 Trigger an Immediate Replica Cycle ..............................9 3.11 Resume Replication ..........................................10
4.13 Immediately Terminate a Replica Cycle ..........................10 3.12 Trigger an Immediate Replica Cycle ..........................10
4.14 Search with Meta-Data ..........................................11 3.13 Immediately Terminate a Replica Cycle .......................11
4.15 Changing Replication Meta-Data .................................11 3.14 Search with Meta-Data .......................................11
4.15.1 Add with Meta-Data ...........................................11 3.15 Changing Replication Meta-Data ..............................12
4.15.2 Delete with Meta-Data ........................................12 3.15.1 Add with Meta-Data .......................................12
4.15.3 Modify with Meta-Data ........................................12 3.15.2 Delete with Meta-Data ....................................13
4.16 Write-Unwriteable Control ......................................12 3.15.3 Modify with Meta-Data ....................................13
5 Common Tasks ......................................................13 3.16 Write-Unwriteable Control ...................................13
5.1 Add a new replica to an existing replica group ..................13 4 Common Tasks ......................................................14
5.1.1 Large area of replication support .............................14 4.1 Add a new replica to an existing replica group ................14
5.2 Verify replication information is present between two servers ...15 4.1.1 Large area of replication support ..........................15
5.2.1 Verify that replication objects exist .........................15 4.2 Verify replication information is present between two servers .16
5.2.2 Verify that it is valid for replication to occur between these 4.2.1 Verify that replication objects exist ......................17
servers ............................................................16 4.2.2 Verify that it is valid for replication to occur between
5.3 Start replication between two servers ...........................17 these servers .....................................................18
5.4 Suspend Replication activity on one area of a server ............17 4.3 Start replication between two servers .........................18
5.5 Suspend Replication activity on all areas of a server ...........17 4.4 Suspend Replication activity on one area of a server ..........19
5.6 Restart Replication activity on one area of a server ............17 4.5 Suspend Replication activity on all areas of a server .........19
5.7 Restart Replication activity on all areas of a server ...........17 4.6 Restart Replication activity on one area of a server ..........19
5.8 Halt replication ................................................18 4.7 Restart Replication activity on all areas of a server .........19
5.9 List status of a particular area of replication on a given 4.8 Halt replication ..............................................19
server .............................................................18 4.9 List status of a particular area of replication on a given
5.9.1 Local Replica On-Line .........................................18 server .............................................................20
5.9.2 Remote Replicas On-Line .......................................18 4.9.1 Local Replica On-Line ......................................20
5.9.3 Check Status of Outward Replication ...........................18 4.9.2 Remote Replicas On-Line ....................................20
5.9.4 Check Status of Incoming Replication ..........................19 4.9.3 Check Status of Outward Replication ........................20
5.10 List all areas of replication defined on a given server and 4.9.4 Check Status of Incoming Replication .......................20
their status .......................................................19 4.10 List all areas of replication defined on a given server and
5.11 Restore a server and replication agreements after a server their status .......................................................21
crash ..............................................................19 4.11 Restore a server and replication agreements after a server
5.11.1 Recent Backup is Available ...................................19 crash 21
5.11.2 Backup is Not Available ......................................20 4.11.1 Recent Backup is Available ...............................21
5.12 Split an Area of Replication ...................................20 4.11.2 Backup is Not Available ..................................22
5.13 Move an existing area of replication to a new server ...........21 4.12 Split an Area of Replication ................................22
5.14 Join two Areas of Replication ..................................21 4.13 Move an existing area of replication to a new server ........23
5.14.1 Preconditions ................................................21 4.14 Join two Areas of Replication ...............................23
5.14.2 Procedure ....................................................21 4.14.1 Preconditions ............................................23
5.14.3 Server requirements ..........................................21 4.14.2 Procedure ................................................24
5.15 Stop Replicating an Area of Replication ........................22 4.14.3 Server requirements ......................................24
5.16 Convert a read-only replica to an updateable replica ...........22 4.15 Stop Replicating an Area of Replication. ....................24
5.17 Convert an updateable replica to a read-only replica ...........23 4.16 Convert a read-only replica to an updateable replica ........25
5.18 Postpone a Replica Cycle to a Later Time .......................23 4.17 Convert an updateable replica to a read-only replica ........25
5.19 Examine Replication Audit History on a Server ..................23 4.18 Postpone a Replica Cycle to a Later Time ....................26
5.20 Compare Two Replicas on Two Servers for Differences ............23 4.19 Examine Replication Audit History on a Server ...............26
5.21 Fix an Entry Without Triggering Replication ....................24 4.20 Compare Two Replicas on Two Servers for Differences .........26
5.22 Check Reported Schema Mismatches Discovered During Replication .25 4.21 Fix an Entry Without Triggering Replication .................27
5.23 Adding a new directory server to a replica group and 4.22 Check Reported Schema Mismatches Discovered During Replication
initializing the contents ..........................................25 27
5.24 Restore from the master failure in a single-master system ......25 4.23 Adding a new directory server to a replica group and
6 Formal Specifications .............................................26 initializing the contents ..........................................28
6.1 New/Modified Object Classes .....................................26 4.24 Restore from the master failure in a single-master system ...28
6.2 New/Modified Attributes .........................................26 5 Formal Specifications .............................................29
6.3 New/Modified Extended Operations ................................26 5.1 New/Modified Object Classes ...................................29
6.4 New/Modified Replication Primitives .............................26 5.2 New/Modified Attributes .......................................29
6.5 New/Modified Controls ...........................................26 5.3 New/Modified Extended Operations ..............................29
7 Security Considerations ...........................................26 5.4 New/Modified Replication Primitives ...........................29
8 Acknowledgements ..................................................27 5.5 New/Modified Controls .........................................29
9 References ........................................................27 6 Security Considerations ...........................................30
Authors' Addresses:..................................................28 7 Acknowledgements ..................................................30
Full Copyright Statement.............................................28 8 References ........................................................31
Authors' Addresses:..................................................31
Full Copyright Statement.............................................32
2 Introduction 1 Introduction
In the LDAP replication architecture [Arch], the LDAP servers and In the LDAP replication architecture [Arch], the LDAP servers and
replication agreements between them are represented by entries in the replication agreements between them are represented by entries in the
directory tree, as part of the replicated naming context. The LDAP directory tree, as part of the replicated naming context. The LDAP
replication information model [InfoMod] describes the contents of these replication information model [InfoMod] describes the contents of these
entries. entries.
Replication management entries, such as replicaSubentries or Replication management entries, such as replicaSubentries or
replication agreements, can be altered on any updateable replica using replication agreements, can be altered on any updateable replica using
standard LDAP operations [RFC2251]. These entries are explicitly standard LDAP operations [RFC2251]. These entries are explicitly
included in the directory entries governed by any agreement associated included in the directory entries governed by any agreement associated
with this area of replication. As a result, all servers with a replica with this area of replication. As a result, all servers with a replica
of an area of replication will have access to information about all
other replicas of that area of replication and associated agreements. other replicas of that area of replication and associated agreements.
The deployment and maintenance of a replicated directory network The deployment and maintenance of a replicated directory network
involves the creation and management of the replicas themselves and involves the creation and management of the replicas themselves and
associated replication control information (e.g. replicationSubentries associated replication control information (e.g. replicationSubentries
and replication agreements). This document outlines the administrative and replication agreements). This document outlines the administrative
actions necessary to create and maintain replication agreements. actions necessary to create and maintain replication agreements.
Typically, administrative tools will guide the administrator and Typically, administrative tools will guide the administrator and
facilitate these actions. facilitate these actions.
3 Administrative Precursors 2 Administrative Precursors
In this document the term "administrative user" refers to an identity In this document the term "administrative user" refers to an identity
that will be performing replication configuration by binding to and that will be performing replication configuration by binding to and
invoking operations on directory servers. Most LDAP server invoking operations on directory servers. Most LDAP server
implementations have the concept of a superuser or power user, however implementations have the concept of a superuser or power user, however
this need not be the same as the administrative user, so long as the this need not be the same as the administrative user, so long as the
administrative user has been granted appropriate privileges. The administrative user has been granted appropriate privileges. The
administrative user MAY be running as an autonomous process, and MUST administrative user MAY be running as an autonomous process, and MUST
be capable of securely maintaining its own credentials. be capable of securely maintaining its own credentials.
of an area of replication will have access to information about all
Deployments SHOULD create an administrative user identity that is Deployments SHOULD create an administrative user identity that is
granted access to all servers holding a replica of a naming context to granted access to all servers holding a copy of a replicated area to
perform the procedures described below, in particular to read the root perform the procedures described below, in particular to read the root
DSE, the replicationContext prefix entry and all subordinate DSE, the replicationContext prefix entry and all subordinate
subentries. The administrative user who will be viewing or modifying subentries. The administrative user who will be viewing or modifying
the replication status MUST have already been provided with and the replication status MUST have already been provided with and
established in the directory server or servers appropriate established in the directory server or servers appropriate
authentication credentials and authorization rights to retrieve authentication credentials and authorization rights to retrieve
attributes and invoke DIT modification operations that are beyond the attributes and invoke DIT modification operations that are beyond the
ability of the 'average' directory user. ability of the 'average' directory user.
Through out-of-band means one of the following will have occurred: 3 Operational "Atoms"
1. the administrative user and the directory server have agreed upon
a shared secret which the administrator will use to authenticate
itself, or
2. the administrative user will have a certificate (or other network
credential) that can be validated by the directory server.
Note that the secret in the first case need not be held by the
directory server itself but could be maintained by an authentication
service trusted by the directory server.
4 Operational "Atoms"
The following operational atoms are used to build up more complex tasks The following operational atoms are used to build up more complex tasks
in section 5. in section 4.
Most of these operational "atoms" make the following assumptions: Most of these operational "atoms" make the following assumptions:
Through prior LDAP or out-of-band means the administrative user MUST Through prior LDAP or out-of-band means the administrative user MUST
have been granted the following access control permissions to the have been granted the following access control permissions to the
directory in order to establish replication: directory in order to establish replication:
- Create the naming context prefix entry - Create the naming context prefix entry
- Create subentries immediately below the naming context prefix
entry - Create subentries immediately below the naming context prefix
entry
In several sections below, we refer to "source" and "target" servers. In several sections below, we refer to "source" and "target" servers.
The "source" server is a server that already holds a copy of the area The "source" server is a server that already holds a copy of the area
of replication. It may already be replicating that area with other of replication. It may already be replicating that area with other
servers. The "target" server does not currently hold a copy of the servers. The "target" server does not currently hold a copy of the
area of replication. The "target" is being added to the replica-group. area of replication. The "target" is being added to the replica-group.
The LDUP Architecture [Arch] allows for read-only replicas. Setting up The LDUP Architecture [Arch] allows for read-only replicas. Setting up
and maintaining a read-only replica will sometimes require that the and maintaining a read-only replica will sometimes require that the
administrator create or modify data on the read-only replica. In this administrator create or modify data on the read-only replica. In this
case, the Write-Unwriteable control (Section 4.16) should be used. case, the Write-Unwriteable control (Section 3.16) should be used.
4.1 Add area of replication to a server In the remainder of the document, any numbered list of steps is
intended to be performed in the order given. Un-numbered (dash) lists
will be used where order is unimportant.
3.1 Add area of replication to a server
The client SHOULD invoke a ModifyRequest in which the object field is The client SHOULD invoke a ModifyRequest in which the object field is
the context prefix of the replication context, and the modification the context prefix of the replication context, and the modification
list consists of a single item to add the value replicationContext to list consists of a single item to add the value replicationContext to
the attribute objectClass. If the server responds with the resultCode the attribute objectClass. If the server responds with the resultCode
attributeOrValueExists, then the value is already there. If the server attributeOrValueExists, then the value is already there. If the server
responds with a resultCode other than attributeOrValueExists or responds with a resultCode other than attributeOrValueExists or
success, then this is an error. Should an error occur at this point, success, then this is an error. Should an error occur at this point,
the server is in an inconsistent state and needs to be fixed. the server is in an inconsistent state and needs to be fixed.
After this step is completed, the server will begin storing change After this step is completed, the server will begin storing change
information for this area of replication. information for this area of replication.
4.2 Delete area of replication from a server 3.2 Delete area of replication from a server
On the target server, the client SHOULD invoke a SearchRequest to find On the target server, the client SHOULD invoke a SearchRequest to find
all replicaSubentry objects which refer to the area of replication: all replicaSubentry objects which refer to the area of replication:
1. Retrieve all the values of the replicaContextRoots attribute in the 1. Retrieve all the values of the replicaContextRoots attribute in the
root DSE of the server. Each value is the distinguished name of root DSE of the server. Each value is the distinguished name of
the base entry of the base entry of a Replication Context held on the base entry of a Replication Context held on the server.
the server.
2. Perform a one-level LDAP search in each replicaContextRoot for 2. Perform a one-level LDAP search in each replicaContextRoot for
objects of class replicaSubentry whose replicaURI attribute points objects of class replicaSubentry whose replicaURI attribute points
to the given server (e.g. use a filter of to the given server (e.g. use a filter of
"(&(objectclass=replicaSubentry-2)(replicaURI=ldap://thisserver))") "(&(objectclass=replicaSubentry-2)(replicaURI=ldap://thisserver))")
where "thisserver" is the DNS name of the given server. where "thisserver" is the fully-qualified DNS name of the given
server with the associated port if it is not port 389.
The client then examines the subtreeSpecifications to determine which The client then examines the subtreeSpecifications to determine which
one it wants and then deletes all replicaSubentries with that one it wants and then deletes all replicaSubentries with that
subtreeSpecification. subtreeSpecification.
If any of the DelRequests fail, the area of replication has not been If any of the DelRequests fail, the area of replication has not been
completely removed. completely removed.
After this step is completed, the target server will no longer After this step is completed, the target server will no longer
replicate this area of replication nor will it record changes for later replicate this area of replication nor will it record changes for later
replication. However, the other servers in the replica group for this replication. However, the other servers in the replica group for this
area will still have a replicaSubentry for the given server, and this area will still have a replicaSubentry for the given server, and this
should be cleaned up. should be cleaned up on all servers that hold the replica.
WG Issue: This is a reason for the subtreeSpecification issue. If it WG Issue: This is a reason for the subtreeSpecification issue. If it
were a DN, this would be much easier. Otherwise, we're going to need a were a DN, this would be much easier. Otherwise, we're going to need a
matching rule for subtreeSpecification. matching rule for subtreeSpecification.
4.3 Copy base of area of replication between servers 3.3 Copy base of area of replication between servers
In this section, the "target server" is the server on which the client In this section, the "target server" is the server on which the client
has just modified the root DSE. has just modified the root DSE.
The client MUST separately contact another server, one that already The client MUST separately contact another server, one that already
holds a copy of this replication context, and issue a SearchRequest on holds a copy of this replication context, and issue a SearchRequest on
that server in which the baseObject is the DN of the base of the area that server in which the baseObject is the DN of the base of the area
of replication, the scope baseObject, the filter "(objectClass=*)" and of replication, the scope baseObject, the filter "(objectClass=*)" and
the attributes list {"*", entryUuid}. If the client cannot obtain the the attributes list {"*", entryUuid}. If the client cannot obtain the
single entry at this point, the procedure will fail. single entry at this point, the procedure will fail.
Now that it has the entry, the client SHOULD invoke an AddWithMetaData Now that it has the entry, the client SHOULD invoke an AddWithMetaData
(see 4.15.1) on the target server with entry set to the DN of the base (see 3.15.1) on the target server with entry set to the DN of the base
of the area of replication and attributes the same list as obtained in of the area of replication and attributes the same list as obtained in
the previous search. the previous search.
If the server returns a resultCode other than success, it is an error, If the server returns a resultCode other than success, it is an error,
and the server will be in an inconsistent state. and the server will be in an inconsistent state.
4.4 Create server entry for an area of replication 3.4 Create server entry for an area of replication
Each server needs to have in its copy of the area of replication a Each server needs to have in its copy of the area of replication a
replicaSubentry for each of the servers involved in replicating that replicaSubentry for each of the servers involved in replicating that
area before replication can be started. These entries MUST have the area before replication can be started. These entries MUST have the
following attributes: following attributes:
1. objectclass, with values top, ldapSubentry and replicaSubentry - objectclass, with values top, Subentry and replicaSubentry
2. cn - cn
3. replicaURI - replicaURI
4. replicaType - replicaType
and MAY contain other attributes, as described in the Information Model and MAY contain other attributes, as described in the Information Model
[InfoMod]. [InfoMod].
WG Issue: This means that InfoMod needs to explicitly define WG Issue: This means that InfoMod needs to explicitly define
replicaOnline as DSA specific with a default value of FALSE. replicaOnline as DSA specific with a default value of FALSE.
4.5 Delete server entry from an area of replication 3.5 Delete server entry from an area of replication
On the target server, the client SHOULD invoke a SearchRequest to find On the target server, the client SHOULD invoke a SearchRequest to find
all replicaSubentry objects which refer to the area of replication: all replicaSubentry objects which refer to the area of replication:
1. Retrieve all the values of the replicaContextRoots attribute in 1. Retrieve all the values of the replicaContextRoots attribute in
the root DSE of the server. Each value is the distinguished the root DSE of the server. Each value is the distinguished
name of the base entry of the base entry of a Replication name of the base entry of the base entry of a Replication
Context held on the server. Context held on the server.
2. Perform a one-level LDAP search in each replicaContextRoot for 2. Perform a one-level LDAP search in each replicaContextRoot for
objects of class replicaSubentry whose replicaURI attribute objects of class replicaSubentry whose replicaURI attribute
points to the given server (e.g. use a filter of points to the given server (e.g. use a filter of
"(&(objectclass=replicaSubentry- "(&(objectclass=replicaSubentry-2)
2)(replicaURI=ldap://thisserver))") where "thisserver" is the (replicaURI=ldap://thisserver))") where "thisserver" is the
DNS name of the given server. fully-qualified DNS name of the given server. The subentry
control MUST be included on this operation.
The client then examines the subtreeSpecifications and the replicaURI The client then examines the subtreeSpecifications and the replicaURI
to determine which one(s) it wants and then deletes all to determine which one(s) it wants and then deletes all
replicaSubentries with that proper subtreeSpecification and replicaURI. replicaSubentries with that proper subtreeSpecification and replicaURI.
If any of the DelRequests fail, the area of replication has not been If any of the DelRequests fail, the area of replication has not been
completely removed. completely removed.
WG Issue: This is another reason for the subtreeSpecification issue. WG Issue: This is another reason for the subtreeSpecification issue.
If it were a DN, this would be much easier. Otherwise, we're going to If it were a DN, this would be much easier. Otherwise, we're going to
need a matching rule for subtreeSpecification. need a matching rule for subtreeSpecification.
4.6 Modify replica 3.6 Modify replica
4.6.1 Change Replica Type 3.6.1 Change Replica Type
Note: This section covers only the simple protocol operation to change Note: This section covers only the simple protocol operation to change
the replica type. Section 5.16 covers the full set of operations for the replica type. Section 4.16 covers the full set of operations for
converting from a ReadOnly to an Updateable replica. converting from a ReadOnly to an Updateable replica.
The client SHOULD invoke a ModifyRequest with the Write-Unwriteable The client SHOULD invoke a ModifyRequest with the Write-Unwriteable
control (Section 4.16) in which the object field is the control (Section 3.16) in which the object field is the
replicationSubentry, and the modification list consists of a single replicationSubentry, and the modification list consists of a single
item to change the value of the attribute replicaType. If the server item to change the value of the attribute replicaType. If the server
responds with the resultCode attributeOrValueExists, then the value is responds with the resultCode attributeOrValueExists, then the value is
already there. If the server responds with a resultCode other than already there. If the server responds with a resultCode other than
attributeOrValueExists or success, then this is an error. attributeOrValueExists or success, then this is an error.
4.6.2 Change Between Full/Partial Replica 3.6.2 Change Between Full/Partial Replica
Note: This section currently discusses how to change between fractional Note: This section currently discusses how to change between fractional
and full replication. Once the information model supports sparse and full replication. Once the information model supports sparse
replication, it will need to be added here. replication, it will need to be added here.
This section only discusses only the simple LDAP protocol operations to This section only discusses the simple LDAP protocol operations to
change between full and partial replicas. Additional actions are change between full and partial replicas. Additional actions are
discussed in Section 5.15. discussed in Section 4.15.
To switch from fractional to full replication, a client SHOULD invoke a To switch from fractional to full replication, a client SHOULD invoke a
ModifyRequest with the Write-Unwriteable control (Section 4.16) in ModifyRequest with the Write-Unwriteable control (Section 3.16) in
which the object field is the replicaSubentry, and the modification which the object field is the replicaSubentry, and the modification
list consists of two items: one to remove the attribute list consists of two items: one to remove the attribute
attributeExclusionFilter and the other to remove the attribute attributeExclusionFilter and the other to remove the attribute
attributeInclusionFilter. If the server responds with a resultCode attributeInclusionFilter. If the server responds with a resultCode
other than noSuchAttribute or success then an error has occurred. other than noSuchAttribute or success then an error has occurred.
To switch from full to fractional replication, a client SHOULD invoke a To switch from full to fractional replication, a client SHOULD invoke a
ModifyRequest with the Write-Unwriteable control in which the object ModifyRequest with the Write-Unwriteable control in which the object
field is the replicaSubentry, and the modification list consists of one field is the replicaSubentry, and the modification list consists of one
or two items: one to add the attribute attributeExclusionFilter and/or or two items: one to add the attribute attributeExclusionFilter and/or
the other to add the attribute attributeInclusionFilter. If the server the other to add the attribute attributeInclusionFilter. If the server
responds with a resultCode other than attributeOrValueExists or responds with a resultCode other than attributeOrValueExists or
success, then an error has occurred. success, then an error has occurred.
4.6.3 Change Replica URI for one server for one area of replication 3.6.3 Change Replica URI for one server for one area of replication
Note: This section covers only the simple protocol operation to change Note: This section covers only the simple protocol operation to change
the replica URI. Replication will carry this change to other servers. the replica URI. Replication will carry this change to other servers.
The client SHOULD invoke a ModifyRequest in which the object field is The client SHOULD invoke a ModifyRequest in which the object field is
the replicationSubentry, and the modification list consists of a single the replicationSubentry, and the modification list consists of a single
item to change the value of the attribute replicaURI to the new value. item to delete the old value of the attribute replicaURI and add the
If the server responds with the resultCode attributeOrValueExists, then new value. If the server responds with the resultCode
the value is already there. If the server responds with a resultCode attributeOrValueExists, then the value is already there. If the server
other than attributeOrValueExists or success, then this is an error. responds with a resultCode other than attributeOrValueExists or
success, then this is an error.
4.7 Add Replication Agreement 3.7 Add Replication Agreement
Each server that acts as a supplier in replication sessions needs to Each server that acts as a supplier in replication sessions needs to
have in its copy of the area of replication a replicaAgreementSubentry have in its copy of the area of replication a replicaAgreementSubentry
for each server that it replicates to. ReplicaAgreementSubentry for each server that it replicates to. ReplicaAgreementSubentry
objects are created as subordinates of the replicaSubentry representing objects are created as subordinates of the replicaSubentry representing
the supplier server. These entries MUST have the following attributes: the supplier server. These entries MUST have the following attributes:
1. objectclass, with values top, ldapSubentry and - objectclass, with values top, Subentry and replicaAgreementSubentry-
replicaAgreementSubentry-2, and 2, and
2. cn - cn
and MAY contain other attributes, as described in the Information Model and MAY contain other attributes, as described in the Information Model
[InfoMod]. The cn attribute value has no significance to replication. [InfoMod]. The cn attribute value has no significance to replication.
The cn attribute SHOULD have a value that is meaningful to the The cn attribute SHOULD have a value that is meaningful to the
replication administrator. replication administrator.
These objects MUST have the following attributes (defined as optional These objects MUST have the following attributes (defined as optional
in the Information Model) for replication to occur: in the Information Model) for replication to occur:
replicaDN - replicaDN
If replicaDN is absent, no replication occurs under this agreement.
WG Issue: We have asked Info Mod authors if there a reason to allow a If replicaDN is absent, no replication occurs under this agreement.
replication agreement to be created without a replicaDN? The
Information Model explicity allows this, but the effect is to cause the
agreement to be ignored. We think the attribute should be a MUST, and
further, that it should not be modifiable.
A client AddRequest creates the replicaAgreementSubentry. The entry A client AddRequest creates the replicaAgreementSubentry. The entry
field of the AddRequest is the DN of the agreement (formed by using the field of the AddRequest is the DN of the agreement (formed by using the
cn attribute as the RDN naming attribute in combination with the DN of cn attribute as the RDN naming attribute in combination with the DN of
the parent replicaSubentry). The attributes field of the AddRequest the parent replicaSubentry). The attributes field of the AddRequest
contains the required attributes for the agreement and any optional contains the required attributes for the agreement and any optional
attributes that are to be defined at this time. attributes that are to be defined at this time.
Note: while replicationAgreementSubentries could be replicated, since Note: while replicationAgreementSubentries could be replicated, since
the replicationCredentialsDN are contained in the the replicationCredentialsDN are contained in the
replicationAgreementSubentry, there is a bootstrapping issue with replicationAgreementSubentry, there is a bootstrapping issue with
replicating via anonymous replication. To avoid this, clients MAY replicating via anonymous replication. To avoid this, clients MAY
create the replicationAgreementSubentries on all servers. If they do create the replicationAgreementSubentries on all servers. If they do
this, they should use the AddWithMetaData operation (Section 4.15.1) to this, they should use the AddWithMetaData operation (Section 3.15.1) to
ensure that all replicationAgreementSubentries have the same entryUUID. ensure that all replicationAgreementSubentries have the same entryUUID.
4.8 Delete Replication Agreement 3.8 Delete Replication Agreement
To delete a replication agreement a LDAP client SHOULD invoke a To delete a replication agreement a LDAP client SHOULD invoke a
DeleteRequest naming the replicaAgreementSubentry to be deleted. DeleteRequest naming the replicaAgreementSubentry to be deleted.
The termination of replication agreements should be done with caution The termination of replication agreements should be done with caution
as it can easily result in a partition of the directory servers if as it can easily result in a partition of the directory servers if
performed incorrectly. performed incorrectly.
Once all replication agreements have been terminated between a server Once all replication agreements have been terminated between a server
and others for a naming context, then that copy of the context on the and others for a naming context, then that copy of the context on the
server will be divergent, and any updates made there will not be server will be divergent, and any updates made there will not be
propagated to any other server. propagated to any other server.
4.9 Modify Replication Agreement 3.9 Modify Replication Agreement
To modify a replication agreement, the client SHOULD invoke a To modify a replication agreement, the client SHOULD invoke a
ModifyRequest naming the replicaAgreementSubentry. The modification ModifyRequest naming the replicaAgreementSubentry. The modification
list MAY include any of the following attributes: list MAY include any of the following attributes:
1. attributeExclusionFilter - attributeExclusionFilter
2. description - description
3. replicaDN
4. replicationMechanismOID - replicaDN
5. replicationCredentialsDN - replicationMechanismOID
6. replicationScheduleDN - replicationCredentialsDN
- replicationScheduleDN
No further administrative action is required for these changes to take No further administrative action is required for these changes to take
affect. affect.
Changing the replicaDN attribute has the effect of ending the existing Changing the replicaDN attribute has the effect of ending the existing
agreement with the replica named by the old replicaDN value (if a value agreement with the replica named by the old replicaDN value (if a value
was present). Similary, changing the replicationMechanismOID attribute was present). Similary, changing the replicationMechanismOID attribute
to specify ietf-ldup-full-update has the effect of ending incremental to specify ietf-ldup-full-update has the effect of ending incremental
replication relationship. In this respect, these changes are replication relationship. In this respect, these changes are
equivalent to deleting a replication agreement and have the same equivalent to deleting a replication agreement and have the same
considerations (see section 4.8) considerations (see section 3.8)
The replicationStatus attribute cannot be modified. The replicationStatus attribute cannot be modified.
4.10 Suspend Replication 3.10 Suspend Replication
The client SHOULD invoke a ModifyRequest in which the object field is The client SHOULD invoke a ModifyRequest in which the object field is
the DN of the target replicationSubentry, and the modification list the DN of the target replicationSubentry, and the modification list
consists of a single item to change the value of replicaOnline consists of a single item to change the value of replicaOnline
attribute to false. If the server responds with the resultCode attribute to false. If the server responds with the resultCode
attributeOrValueExists, then the value is already there. If the server attributeOrValueExists, then the value is already there. If the server
responds with a resultCode other than attributeOrValueExists or responds with a resultCode other than attributeOrValueExists or
success, then this is an error. success, then this is an error.
If replicaOnline is FALSE for a replicaSubentry that represents the If replicaOnline is FALSE for a replicaSubentry that represents the
server containing the instance of the replicaSubentry, the server MUST server containing the instance of the replicaSubentry, the server MUST
NOT initiate or accept any new incremental replication sessions. If NOT initiate or accept any new incremental replication sessions. If
replicaOnline is FALSE for a replicaSubentry that represents a replica replicaOnline is FALSE for a replicaSubentry that represents a replica
other than the server containing the instance of the replicaSubentry, other than the server containing the instance of the replicaSubentry,
the server MUST NOT initiate or accept any new incremental replication the server MUST NOT initiate or accept any new incremental replication
sessions with that replica. sessions with that replica.
4.11 Resume Replication 3.11 Resume Replication
The client SHOULD invoke a ModifyRequest in which the object field is The client SHOULD invoke a ModifyRequest in which the object field is
the DN of the target replicationSubentry, and the modification list the DN of the target replicationSubentry, and the modification list
consists of a single item to change the value of replicaOnline consists of a single item to change the value of replicaOnline
attribute to true. If the server responds with the resultCode attribute to true. If the server responds with the resultCode
attributeOrValueExists, then the value is already there. If the server attributeOrValueExists, then the value is already there. If the server
responds with a resultCode other than attributeOrValueExists or responds with a resultCode other than attributeOrValueExists or
success, then this is an error. success, then this is an error.
If replicaOnline is TRUE for a replicaSubentry that represents the If replicaOnline is TRUE for a replicaSubentry that represents the
server containing the instance of the replicaSubentry, the server MAY server containing the instance of the replicaSubentry, the server MAY
initiate or accept new incremental replication sessions. If initiate or accept new incremental replication sessions. If
replicaOnline is TRUE for a replicaSubentry that represents a replica replicaOnline is TRUE for a replicaSubentry that represents a replica
other than the server containing the instance of the replicaSubentry, other than the server containing the instance of the replicaSubentry,
the server MAY initiate or accept new incremental replication sessions the server MAY initiate or accept new incremental replication sessions
with that replica. with that replica.
4.12 Trigger an Immediate Replica Cycle 3.12 Trigger an Immediate Replica Cycle
An immediate replication cycle can be triggered using an LDAP extended An immediate replication cycle can be triggered using an LDAP extended
operation - "Trigger Replication". This operation takes 4 or 5 operation - "Trigger Replication". This operation takes 4 or 5
arguments: arguments:
1. The distinguished name of the replicaSubentry for the target replica. . The distinguished name of the replicaSubentry for the target replica.
If there is no instance of this entry on the server where the If there is no instance of this entry on the server where the
extended operation is executed, the operation is not performed and an extended operation is executed, the operation is not performed and an
error is returned. error is returned.
2. The LDAP URL of the target server. (Note: Per [Req] M8, a single . The LDAP URL of the target server. (Note: Per [Req] M8, a single
Replication Agreement may accommodate more than one pair of servers. Replication Agreement may accommodate more than one pair of servers.
Thus this argument is necessary.) Thus this argument is necessary.)
3. Type of replication session to be performed (full update or . Type of replication session to be performed (full update or
incremental update). incremental update).
4. Flags indicating whether the replication session is online or . Flags indicating whether the replication session is online or
offline, and if offline whether the server should create the offline offline, and if offline whether the server should create the offline
file or read the offline file. See Section 5.1.1 for more details of file or read the offline file. See Section 4.1.1 for more details of
offline replication. offline replication.
. If the replication session is offline, the name of the file to be
5. If the replication session is offline, the name of the file to be used.
used.
All other required information (connection information, authentication All other required information (connection information, authentication
information, etc.) is obtained from the Replication Agreement. information, etc.) is obtained from the Replication Agreement.
The server on which the operation is executed immediately initiates a The server on which the operation is executed immediately initiates a
replica cycle with the target server. Updates are transferred in both replica cycle with the target server. Updates are transferred in both
directions if allowed by the replication agreement. directions if allowed by the replication agreement.
If either the target server or the server executing the extended If either the target server or the server executing the extended
operation has a currently-active replica cycle for the replication operation has a currently-active replica cycle for the replication
context specified by the extended operation, the extended operation context specified by the extended operation, the extended operation
will fail ([Arch] Section 10). will fail ([Arch] Section 10).
Since replication is normally an asynchronous operation, the Trigger Since replication is normally an asynchronous operation, the Trigger
Replication extended operation completes and returns status when Replication extended operation completes and returns status when
replication is started. It does not wait for completion of the replica replication is started. It does not wait for completion of the replica
cycle and the returned status indicates whether the cycle was started cycle and the returned status indicates whether the cycle was started
successfully, not whether it completed successfully. Further progress successfully, not whether it completed successfully. Further progress
of the replica cycle can be checked using other mechanisms (e.g. of the replica cycle can be checked using other mechanisms (e.g.
Section 5.9). Section 4.9).
The detailed syntax of the operation and associated response are The detailed syntax of the operation and associated response are
presented in Section 6.3. presented in Section 5.3.
4.13 Immediately Terminate a Replica Cycle 3.13 Immediately Terminate a Replica Cycle
Note: this section discusses just the operation for terminating a Note: this section discusses just the operation for terminating a
replica cycle. See section 5.18 for a discussion of suspending replica cycle. See section 4.18 for a discussion of suspending
replication or changing the replication schedule. replication or changing the replication schedule.
An in-progress replication cycle can be terminated immediately using an An in-progress replication cycle can be terminated immediately using an
LDAP extended operation - "Terminate Replication". This operation LDAP extended operation - "Terminate Replication". This operation
takes 2 arguments: takes 2 arguments:
1. The distinguished name of the replicaSubentry for the target 1. The distinguished name of the replicaSubentry for the target
replica. If there is no instance of this entry on the server replica. If there is no instance of this entry on the server
where the extended operation is executed, the operation is not where the extended operation is executed, the operation is not
performed and an error is returned. performed and an error is returned.
skipping to change at page 10, line 46 skipping to change at page 11, line 33
An in-progress replication cycle can be terminated immediately using an An in-progress replication cycle can be terminated immediately using an
LDAP extended operation - "Terminate Replication". This operation LDAP extended operation - "Terminate Replication". This operation
takes 2 arguments: takes 2 arguments:
1. The distinguished name of the replicaSubentry for the target 1. The distinguished name of the replicaSubentry for the target
replica. If there is no instance of this entry on the server replica. If there is no instance of this entry on the server
where the extended operation is executed, the operation is not where the extended operation is executed, the operation is not
performed and an error is returned. performed and an error is returned.
2. The LDAP URL of the target server. (Note: Per [Req] M8, a single 2. The LDAP URL of the target server. (Note: Per [Req] M8, a single
Replication Agreement may accommodate more than one pair of Replication Agreement may accommodate more than one pair of
servers. Thus this argument is necessary.) servers. Thus this argument is necessary.)
All other required information is obtained from the Replication All other required information is obtained from the Replication
Agreement. Agreement.
The server on which the operation is executed immediately terminates The server on which the operation is executed immediately terminates
its current replica cycle with the target server. Termination will not its current replica cycle with the target server. Termination will not
interrupt transmission of a Replication Update [Arch], it will occur interrupt transmission of a Replication Update [Arch], it will occur
only between Replication Updates. only between Replication Updates.
The detailed syntax of the operation and associated response are The detailed syntax of the operation and associated response are
presented in Section 6.3. presented in Section 5.3.
Note: If data is queued awaiting replication between a pair of servers Note: If data is queued awaiting replication between a pair of servers
and if replication is set to trigger on updates, the replication system and if replication is set to trigger on updates, the replication system
may automatically start a new replica cycle shortly after a cycle is may automatically start a new replica cycle shortly after a cycle is
terminated. To avoid this, the replication schedule should be adjusted terminated. To avoid this, the replication schedule should be adjusted
to suspend replication before the Terminate Replication extended to suspend replication before the Terminate Replication extended
operation is issued. operation is issued.
4.14 Search with Meta-Data 3.14 Search with Meta-Data
Many pieces of replication meta-data are used by LDUP. In some cases Many pieces of replication meta-data are used by LDUP. In some cases
(entryUUID, createdEntryCSN) they are stored as operational attributes (entryUUID, createdEntryCSN) they are stored as operational attributes
and can be read using the LDAP search operation. Other meta-data and can be read using the LDAP search operation. Other meta-data
(deleted entries, CSNs related to changes of attribute values) are not (deleted entries, CSNs related to changes of attribute values) are not
visible via normal LDAP operations but must be obtainable by visible via normal LDAP operations but must be obtainable by
administrative users attempting to deal with replication problems (e.g. administrative users attempting to deal with replication problems (e.g.
dealing with Lost+Found entries). dealing with Lost+Found entries).
"Search with Meta-Data" is an extended operation that is modeled on the "Search with Meta-Data" is an extended operation that is modeled on the
skipping to change at page 11, line 23 skipping to change at page 12, line 16
visible via normal LDAP operations but must be obtainable by visible via normal LDAP operations but must be obtainable by
administrative users attempting to deal with replication problems (e.g. administrative users attempting to deal with replication problems (e.g.
dealing with Lost+Found entries). dealing with Lost+Found entries).
"Search with Meta-Data" is an extended operation that is modeled on the "Search with Meta-Data" is an extended operation that is modeled on the
LDAP search operation [RFC2251]. There is an additional parameter that LDAP search operation [RFC2251]. There is an additional parameter that
indicates what additional data should be returned be the search. The indicates what additional data should be returned be the search. The
following values are permitted: following values are permitted:
- deletedEntries - Any deleted entries in the scope of the search - deletedEntries - Any deleted entries in the scope of the search
are returned. Deleted entries can be distinguished from non- are returned. Deleted entries can be distinguished from non-
deleted entries because the deleted entries will have a value in deleted entries because the deleted entries will have a value in
their deletedEntryCSN attribute. If the deletedEntries their deletedEntryCSN attribute. If the deletedEntries
controlValue is given, the deletedEntryCSN attribute is controlValue is given, the deletedEntryCSN attribute is
automatically added to the AttributeDescriptionList of the search. automatically added to the AttributeDescriptionList of the search.
- attributeChangeState - Each attribute value returned as part of - attributeChangeState - Each attribute value returned as part of
the search will be returned as a triple consisting of the the search will be returned as a triple consisting of the
attribute value, the deleted flag associated with the value, and attribute value, the deleted flag associated with the value, and
the modificationCSN associated with the value. the modificationCSN associated with the value.
The formal specification of the Search with Meta-Data extended The formal specification of the Search with Meta-Data extended
operation is given in Section 6.3. operation is given in Section 5.3.
Note: Search with Meta-Data is designed as an extended operation Note: Search with Meta-Data is designed as an extended operation
rather than a control because the format of the returned data (sets of rather than a control because the format of the returned data (sets of
triples) is different from a normal LDAP search operation. Other than triples) is different from a normal LDAP search operation. Other than
this, Search with Meta-Data operates the same as search. this, Search with Meta-Data operates the same as search.
4.15 Changing Replication Meta-Data 3.15 Changing Replication Meta-Data
When fixing a replication problem, administrators need a way to modify When fixing a replication problem, administrators need a way to modify
meta-data values that are normally treated as operational attributes meta-data values that are normally treated as operational attributes
(createdEntryCSN, entryUUID) or as completely hidden data (createdEntryCSN, entryUUID) or as completely hidden data
(deletedEntryCSN, deleted flag, modificationCSN). (deletedEntryCSN, deleted flag, modificationCSN).
This set of extended operations mirrors the normal LDAP operations that This set of extended operations mirrors the normal LDAP operations that
allow modification, but they allow modification of the associated meta- allow modification, but they allow modification of the associated meta-
data as well. data as well.
4.15.1 Add with Meta-Data 3.15.1 Add with Meta-Data
The Add with Meta-Data extended operation is modeled on the LDAP Add The Add with Meta-Data extended operation is modeled on the LDAP Add
operation [RFC2251]. operation [RFC2251].
The differences from the standard LDAP Add operation are: The differences from the standard LDAP Add operation are:
- Each value is specified as a triple consisting of the value, the - Each value is specified as a triple consisting of the value, the
deleted flag to be associated with that value, and the deleted flag to be associated with that value, and the
modificationCSN to be associated with that value. modificationCSN to be associated with that value.
- A value may be supplied for the createdEntryCSN attribute. - A value may be supplied for the createdEntryCSN attribute.
skipping to change at page 12, line 4 skipping to change at page 12, line 58
The Add with Meta-Data extended operation is modeled on the LDAP Add The Add with Meta-Data extended operation is modeled on the LDAP Add
operation [RFC2251]. operation [RFC2251].
The differences from the standard LDAP Add operation are: The differences from the standard LDAP Add operation are:
- Each value is specified as a triple consisting of the value, the - Each value is specified as a triple consisting of the value, the
deleted flag to be associated with that value, and the deleted flag to be associated with that value, and the
modificationCSN to be associated with that value. modificationCSN to be associated with that value.
- A value may be supplied for the createdEntryCSN attribute. - A value may be supplied for the createdEntryCSN attribute.
- A value may be supplied for the entryUUID attribute. - A value may be supplied for the entryUUID attribute.
- If the Add with Meta-Data extended operation is executed on a - If the Add with Meta-Data extended operation is executed on a
readonly replica it will be executed locally rather than returning readonly replica it will be executed locally rather than returning
a referral to an updateable replica. a referral to an updateable replica.
The formal specification of Add with Meta-Data is in Section 6.3. The formal specification of Add with Meta-Data is in Section 5.3.
4.15.2 Delete with Meta-Data 3.15.2 Delete with Meta-Data
The Delete with Meta-Data extended operation is modeled on the LDAP The Delete with Meta-Data extended operation is modeled on the LDAP
Delete operation [RFC2251]. The differences from the standard LDAP Delete operation [RFC2251]. The differences from the standard LDAP
Delete operation are: Delete operation are:
- A deletedEntryCSN may be supplied with the Delete with Meta-Data - A deletedEntryCSN may be supplied with the Delete with Meta-Data
extended operation. In this case the delete operation is extended operation. In this case the delete operation is
performed as in [RFC2251], except that the value of the performed as in [RFC2251], except that the value of the
deletedEntryCSN is taken from the controlValue. deletedEntryCSN is taken from the controlValue.
- It may be flagged as a noRecordDelete. In this case the targeted - It may be flagged as a noRecordDelete. In this case the targeted
entry is deleted with no meta-data left behind (no deletedEntry or entry is deleted with no meta-data left behind (no deletedEntry or
"tombstone"). "tombstone").
- If the Delete with Meta-Data extended operation is executed on a - If the Delete with Meta-Data extended operation is executed on a
readonly replica it will be executed locally rather than returning readonly replica it will be executed locally rather than returning
a referral to an updateable replica. a referral to an updateable replica.
The formal specification of the Delete with Meta-Data extended The formal specification of the Delete with Meta-Data extended
operation is given in Section 6.3. operation is given in Section 5.3.
4.15.3 Modify with Meta-Data 3.15.3 Modify with Meta-Data
The Modify with Meta-Data extended operation is modeled on the LDAP The Modify with Meta-Data extended operation is modeled on the LDAP
Modify operation [RFC2251]. Modify operation [RFC2251].
The differences from the standard LDAP Modify operation are: The differences from the standard LDAP Modify operation are:
- Each value is specified as a triple consisting of the value, the - Each value is specified as a triple consisting of the value, the
deleted flag to be associated with that value, and the deleted flag to be associated with that value, and the
modificationCSN to be associated with that value. modificationCSN to be associated with that value.
- The createdEntryCSN attribute may be modified. - The createdEntryCSN attribute may be modified.
- The entryUUID attribute may be modified. - The entryUUID attribute may be modified.
- If the Modify with Meta-Data extended operation is executed on a - If the Modify with Meta-Data extended operation is executed on a
readonly replica it will be executed locally rather than returning readonly replica it will be executed locally rather than returning
a referral to an updateable replica. a referral to an updateable replica.
The formal specification of Modify with Meta-Data is in Section 6.3. The formal specification of Modify with Meta-Data is in Section 5.3.
4.16 Write-Unwriteable Control 3.16 Write-Unwriteable Control
There are a number of attributes defined in [InfoMod] which are marked There are a number of attributes defined in [InfoMod] which are marked
"NO-USER-MODIFICATION". When fixing replication problems, there may be "NO-USER-MODIFICATION". When fixing replication problems, there may be
times when these values need to be changed. In addition, when times when these values need to be changed. In addition, when
administering readonly replicas it may be necessary for administrators administering readonly replicas it may be necessary for administrators
to modify values on readonly replicas. The Write-Unwriteable control to modify values on readonly replicas. The Write-Unwriteable control
handles these cases. handles these cases.
The control can be attached to an LDAP modify operation. If the The control can be attached to an LDAP modify operation. If the
control is present, it allows the modify operation to change values control is present, it allows the modify operation to change values
that are marked "NO-USER-MODIFICATION". Also, if the control is that are marked "NO-USER-MODIFICATION" (the only exception is
present, modify operations can be executed on readonly replicas. In
this case the readonly replica will not return a referral to an
updateable replica and the operation will be performed on the readonly
replica.
The formal specification of the control is given in Section 6.5. attributes which are locally calculated by the implementation). Also,
if the control is present, modify operations can be executed on
readonly replicas. In this case the readonly replica will not return a
referral to an updateable replica and the operation will be performed
on the readonly replica.
The formal specification of the control is given in Section 5.5.
The current list of NO-USER-MODIFICATION attributes in [InfoMod] is: The current list of NO-USER-MODIFICATION attributes in [InfoMod] is:
attributeExclusionFilter (Section 8.2.4) attributeExclusionFilter (Section 8.2.4)
attributeInclusionFilter (Section 8.2.5) attributeInclusionFilter (Section 8.2.5)
replicationStatus (Section 8.2.7) replicationStatus (Section 8.2.7)
replicaType (Section 8.2.8) replicaType (Section 8.2.8)
updateVector (Section 8.2.9) updateVector (Section 8.2.9)
secondsToWaitDefault (Section 8.2.18) secondsToWaitDefault (Section 8.2.18)
secondsToWait1 (Section 8.2.19) secondsToWait1 (Section 8.2.19)
secondsToWait2 (Section 8.2.21) secondsToWait2 (Section 8.2.21)
5 Common Tasks 4 Common Tasks
There are many tasks that administrators need to perform in a There are many tasks that administrators need to perform in a
replicated environment. This section describes many typical tasks and replicated environment. This section describes many typical tasks and
describes how they are performed in terms of the atoms defined above. describes how they are performed in terms of the atoms defined above.
5.1 Add a new replica to an existing replica group 4.1 Add a new replica to an existing replica group
Assume there is an existing replica group for a given area of Assume there is an existing replica group for a given area of
replication. To add one new server (which does not already hold a copy replication. To add one new server (which does not already hold a copy
of the area) to the replica group, perform the following steps: of the area) to the replica group, perform the following steps:
1. Copy the base entry of the area of replication from one of the 1. Copy the base entry of the area of replication from one of the
current servers to the new server (Section4.3). current servers to the new server (Section3.3).
2. On one of the existing servers in the replica group, create the 2. On one of the existing servers in the replica group, create the
replicaSubentry for the new server with the replicaOnline replicaSubentry for the new server with the replicaOnline
attribute set to "false" (Section 4.4). Replication will copy attribute set to "false" (Section 3.4). Replication will copy
this to all the existing replicas (trigger immediate replication this to all the existing replicas (trigger immediate replication
per Section 4.12 if necessary). Since replicaOnline does not per Section 3.12 if necessary). Since replicaOnline does not
replicate, it needs to be set "false" on all existing servers. replicate, it needs to be set "false" on all existing servers.
3. On the new server, create a replicaSubentry for one of the other 3. On the new server, create a replicaSubentry for one of the other
servers in the replica group with the replicaOnline attribute set servers in the replica group with the replicaOnline attribute set
to "false". The UUID of this replicaSubentry MUST be identical to "false". The UUID of this replicaSubentry MUST be identical
to the UUID it has on the existing replicas, so Add with Meta- to the UUID it has on the existing replicas, so Add with Meta-
Data (Section 4.15.1) should be used to create the entry. Data (Section 3.15.1) should be used to create the entry.
4. If the authentication mechanism used for replication requires 4. If the authentication mechanism used for replication requires
credentials, make appropriate entries on all existing servers for credentials, make appropriate entries on all existing servers for
the new server and make appropriate entries for all the existing the new server and make appropriate entries for all the existing
servers on the new server. If any of the credential data is in servers on the new server. If any of the credential data is in
the current area of replication, use Add with Meta-Data on the the current area of replication, use Add with Meta-Data on the
new server and make the UUIDs the same as those on the existing new server and make the UUIDs the same as those on the existing
servers. servers.
5. Create the replication agreement(s) on one of the existing 5. Create the replication agreement(s) on one of the existing
servers and let it replicate to the other existing servers servers and let it replicate to the other existing servers
(Section 4.9). (Section 3.7).
6. Set the replicaOnline attribute to true for the new server on 6. Set the replicaOnline attribute to true for the new server on
both the source and target servers (Section 4.11). both the source and target servers (Section 3.11).
7. On the source server, trigger an immediate "full update" replica 7. On the source server, trigger an immediate "full update" replica
cycle (Section 4.12). The data replicated will include the cycle (Section 3.12). The data replicated will include the
replicaSubentries and replication agreements for all other replicaSubentries and replication agreements for all other
servers in the replica group since they are in the area of servers in the replica group since they are in the area of
replication. replication.
8. On the new server, set the replicaOnline attributes in the 8. On the new server, set the replicaOnline attributes in the
replicaSubentries for all the other servers to "true". replicaSubentries for all the other servers to "true".
9. On the servers in the replica group other than the source server, 9. On the servers in the replica group other than the source server,
set the replicaOnline attribute in the replicaSubentry for the set the replicaOnline attribute in the replicaSubentry for the
target server to "true". target server to "true".
5.1.1 Large area of replication support 4.1.1 Large area of replication support
In some cases, an area of replication is so large or available In some cases, an area of replication is so large or available
bandwidth so small that out-of-band mechanisms (e.g. mailing a tape) bandwidth so small that out-of-band mechanisms (e.g. mailing a tape)
need to be used to transport the initial copy from the source to the need to be used to transport the initial copy from the source to the
target. The target then needs to be updated with changes made to the target. The target then needs to be updated with changes made to the
source since the copy was made. source since the copy was made.
While LDIF is typically used to transport bulk LDAP data, it is not While LDIF is typically used to transport bulk LDAP data, it is not
suitable here because it does not transport replication meta-data suitable here because it does not transport replication meta-data
(CSNs, GUIDs, etc.). To ensure that all needed data is available; bulk (CSNs, GUIDs, etc.). To ensure that all needed data is available; bulk
skipping to change at page 14, line 22 skipping to change at page 15, line 33
In some cases, an area of replication is so large or available In some cases, an area of replication is so large or available
bandwidth so small that out-of-band mechanisms (e.g. mailing a tape) bandwidth so small that out-of-band mechanisms (e.g. mailing a tape)
need to be used to transport the initial copy from the source to the need to be used to transport the initial copy from the source to the
target. The target then needs to be updated with changes made to the target. The target then needs to be updated with changes made to the
source since the copy was made. source since the copy was made.
While LDIF is typically used to transport bulk LDAP data, it is not While LDIF is typically used to transport bulk LDAP data, it is not
suitable here because it does not transport replication meta-data suitable here because it does not transport replication meta-data
(CSNs, GUIDs, etc.). To ensure that all needed data is available; bulk (CSNs, GUIDs, etc.). To ensure that all needed data is available; bulk
replication data is stored as a stream of protocol elements from replication data is stored as a stream of protocol elements from
[Proto] in network byte order. There is an LDAP extended operation [Proto] in network byte order. There is an LDAP extended operation
that will either cause a server to generate or read a stream of that will either cause a server to generate or read a stream of
protocol elements (see Section 4.12). Use of the extended operation to protocol elements (see Section 3.12). Use of the extended operation to
generate or a read a file is OPTIONAL, but if the file is generated it generate or a read a file is OPTIONAL, but if the file is generated it
MUST be a stream of protocol elements. MUST be a stream of protocol elements.
The following restrictions are imposed on the data stream: The following restrictions are imposed on the data stream:
- The BIND operation is unauthenticated. The extended operation - The BIND operation is unauthenticated. The extended operation
that causes the destination server to read protocol elements from that causes the destination server to read protocol elements from
a local file should be restricted to privileged users only (See a local file should be restricted to privileged users only (See
Section 7); this provides authentication for the operation. Section 6); this provides authentication for the operation.
- The "supplier initiated" protocol flow is used. - The "supplier initiated" protocol flow is used.
- A "full update" replication session is assumed. - A "full update" replication session is assumed.
- Since input is coming from a file, there are no responses. The - Since input is coming from a file, there are no responses. The
stream of protocol elements should assume that all response codes stream of protocol elements should assume that all response codes
are "REPL_SUCCESS". are "REPL_SUCCESS".
- Since this is a "full update" session, [Proto] specifies that "the - Since this is a "full update" session, [Proto] specifies that "the
consumer's update vector should be assumed to be set to times consumer's update vector should be assumed to be set to times
'earlier than' the oldest times known to the supplier server." 'earlier than' the oldest times known to the supplier server."
Thus the protocol stream can be generated without receiving a Thus the protocol stream can be generated without receiving a
createGroupingResponse extended operation from the consumer. createGroupingResponse extended operation from the consumer.
skipping to change at page 14, line 45 skipping to change at page 16, line 4
- The "supplier initiated" protocol flow is used. - The "supplier initiated" protocol flow is used.
- A "full update" replication session is assumed. - A "full update" replication session is assumed.
- Since input is coming from a file, there are no responses. The - Since input is coming from a file, there are no responses. The
stream of protocol elements should assume that all response codes stream of protocol elements should assume that all response codes
are "REPL_SUCCESS". are "REPL_SUCCESS".
- Since this is a "full update" session, [Proto] specifies that "the - Since this is a "full update" session, [Proto] specifies that "the
consumer's update vector should be assumed to be set to times consumer's update vector should be assumed to be set to times
'earlier than' the oldest times known to the supplier server." 'earlier than' the oldest times known to the supplier server."
Thus the protocol stream can be generated without receiving a Thus the protocol stream can be generated without receiving a
createGroupingResponse extended operation from the consumer. createGroupingResponse extended operation from the consumer.
- The value of the groupCookie in the endGroupingRequest extended - The value of the groupCookie in the endGroupingRequest extended
operation is ignored. operation is ignored.
Once the file has been loaded on the destination server, the Once the file has been loaded on the destination server, the
destination server should initiate a replication session with the destination server should initiate a replication session with the
source server (Section 4.14). This will pick up changes that have source server (Section 3.12). This will pick up changes that have
occurred since the original file was created. occurred since the original file was created.
In summary, to add a new server to an existing replica group for a In summary, to add a new server to an existing replica group for a
large replica, follow these steps (steps 1-7 are the same as steps 1-7 large replica, follow these steps (steps 1-7 are the same as steps 1-7
of Section 5.1): of Section 4.1):
1. Copy the base entry of the area of replication from one of the 1. Copy the base entry of the area of replication from one of the
current servers to the new server (Section4.3). current servers to the new server (Section3.3).
2. On one of the existing servers in the replica group, create the 2. On one of the existing servers in the replica group, create the
replicaSubentry for the new server with the replicaOnline replicaSubentry for the new server with the replicaOnline
attribute set to "false" (Section 4.4). Replication will copy attribute set to "false" (Section 3.4). Replication will copy
this to all the existing replicas. Since replicaOnline does not this to all the existing replicas. Since replicaOnline does not
replicate, it needs to be set "false" on all existing servers. replicate, it needs to be set "false" on all existing servers.
(Trigger immediate replication per Section 3.12 if necessary.)
(Trigger immediate replication per Section 4.12 if necessary.)
3. On the new server, create a replicaSubentry for one of the other 3. On the new server, create a replicaSubentry for one of the other
servers in the replica group with the replicaOnline attribute set servers in the replica group with the replicaOnline attribute set
to "false". The UUID of this replicaSubentry MUST be identical to "false". The UUID of this replicaSubentry MUST be identical
to the UUID it has on the existing replicas, so Add with Meta- to the UUID it has on the existing replicas, so Add with Meta-
Data (Section 4.15.1) should be used to create the entry. Data (Section 3.15.1) should be used to create the entry.
4. If the authentication mechanism used for replication requires 4. If the authentication mechanism used for replication requires
credentials, make appropriate entries on all existing servers for credentials, make appropriate entries on all existing servers for
the new server and make appropriate entries for all the existing the new server and make appropriate entries for all the existing
servers on the new server. If any of the credential data is in servers on the new server. If any of the credential data is in
the current area of replication, use Add with Meta-Data on the the current area of replication, use Add with Meta-Data on the
new server and make the UUIDs the same as those on the existing new server and make the UUIDs the same as those on the existing
servers. servers.
5. Create the replication agreement(s) on one of the existing 5. Create the replication agreement(s) on one of the existing
servers and let it replicate to the other existing servers servers and let it replicate to the other existing servers
(Section 4.9). (Section 3.7).
6. Set the replicaOnline attribute to "true" for the new server on 6. Set the replicaOnline attribute to "true" for the new server on
both the source and target servers (Section 4.11). both the source and target servers (Section 3.11).
7. Generate an update file on the source server (Section 4.12) 7. Generate an update file on the source server (Section 3.12)
8. Transport the file to the destination site by any appropriate 8. Transport the file to the destination site by any appropriate
means means (FTP, express parcel, postal mail, etc.)
9. Load the file on the destination server 9. Load the file onto the destination server (create a disk file
10. Import the file into LDAP (Section 4.12) from tape if necessary)
10. Import the file into LDAP (Section 3.12)
11. Set the replicaOnline attribute to true for the new server 11. Set the replicaOnline attribute to true for the new server
12. Trigger a replica session between the source and destination 12. Trigger a replica session between the source and destination
machine to pick up changes since the file was generated (Section machine to pick up changes since the file was generated (Section
4.12) 3.12)
5.2 Verify replication information is present between two servers 4.2 Verify replication information is present between two servers
This section describes steps that verify the proper replication This section describes steps that verify the proper replication
information is present for replication to occur between two replicas. information is present for replication to occur between two replicas.
There are two parts to this process: There are two parts to this process:
1. Verify that the necessary objects have been created on both 1. Verify that the necessary objects have been created on both
replicas. These objects include replicaSubentry objects replicas. These objects include replicaSubentry objects
representing the replicas, replication agreements describing representing the replicas, replication agreements describing
consumer-supplier relationships between the replicas, and the consumer-supplier relationships between the replicas, and the
credential and schedule objects named in the agreements. credential and schedule objects named in the agreements.
2. Verify that it is valid to replicate between the replicas. For 2. Verify that it is valid to replicate between the replicas. For
example, a fractional replica cannot act as a supplier to a full example, a fractional replica cannot act as a supplier to a full
replica. replica.
5.2.1 Verify that replication objects exist 4.2.1 Verify that replication objects exist
This section describes how to verify that the necessary replication This section describes how to verify that the necessary replication
objects exist. Within this section the term replica refers to one of objects exist. Within this section the term replica refers to one of
the two replicas for which information is being verified. It is the two replicas for which information is being verified. It is
assumed that an administrator has identified the replicas (both the IP assumed that an administrator has identified the replicas (both the IP
address/host name and the replicaId), the area of replication, and address/host name and the replicaId), the area of replication, and
which of the replicas are expected to act as suppliers. One or both of which of the replicas are expected to act as suppliers. One or both of
the replicas must be a supplier to the other replica. the replicas must be a supplier to the other replica.
1. The client SHOULD invoke an object scope search specifying the DN 1. The client SHOULD invoke an object scope search specifying the DN
of the root entry of the area of replication. This entry MUST of the root entry of the area of replication. This entry MUST
exist on both servers, and the objectclass attribute values MUST exist on both servers, and the objectclass attribute values MUST
include the value replicationContext. include the value replicationContext.
2. On the replicas which the administrator has indicated is a 2. On the replicas which the administrator has indicated is a
supplier, the client SHOULD invoke a baseObject scope search of supplier, the client SHOULD invoke a baseObject scope search of
the root DSE requesting the replicationSubentries attribute. The the root DSE requesting the replicationSubentries attribute. The
value for this attribute MUST name exactly one replicaSubentry value for this attribute MUST name exactly one replicaSubentry
object that is a child of the root entry of the area of object that is a child of the root entry of the area of
replication. The distinguished name of the entry MUST be of the replication. The distinguished name of the entry MUST be of the
form: form:
cn=<replicaId>,<DN of root entry of area of replication>
3. On each supplier replica, the client SHOULD invoke a baseObject
scope search specifying the DN of replicaSubentry that was
identified in the replicaSubentries attribute of the root DSE in
the previous step. This object MUST exist for replication to
occur, and MUST include the value replicaSubentry in the list of
objectclass values. The client SHOULD invoke an object scope
search for the other server. The base DN for this search is of
the form:
cn=<replicaId>,<DN of root entry of area of replication> cn=<replicaId>,<DN of root entry of area of replication>
where <replicaId> is the replicaId of the other replica. This 3. On each supplier replica, the client SHOULD invoke a baseObject
object MUST exist, and MUST include the value replicaSubentry in scope search specifying the DN of replicaSubentry that was
the list objectclass values. identified in the replicaSubentries attribute of the root DSE in
4. On each supplier replica, the client SHOULD invoke a singleLevel the previous step. This object MUST exist for replication to
search, specifying the DN of replicaSubentry for that replica as occur, and MUST include the value replicaSubentry in the list of
the baseObject, and a search filter like: objectclass values. The client SHOULD invoke an object scope
(&(objectclass=replicationAgreementSubentry-2) search for the other server. The base DN for this search is of
(replicaDN=<consumer-replica-subentry-DN>)) the form:
where <consumer-replica-subentry-DN is the DN of the cn=<replicaId>,<DN of root entry of area of replication>
replicaSubentry representing the other server, which is the where <replicaId> is the replicaId of the other replica. This
consumer in this agreement. There MUST be at least one entry in object MUST exist, and MUST include the value replicaSubentry in
the search results. For incremental update replication to occur at the list objectclass values.
least one of the entries in the search results MUST have a 4. On each supplier replica, the client SHOULD invoke a oneLevel
replicationMechanismOID attribute which is either absent or has search, specifying the DN of replicaSubentry for that replica as
the value ietf-ldup-incremental-update [Proto]. the baseObject, and a search filter like:
5. On each supplier replica, the client SHOULD invoke a baseObject (&(objectclass=replicationAgreementSubentry-2)
for each object named in the replicationCredentialsDN and (replicaDN=<consumer-replica-subentry-DN>))
replicationScheduleDN attribute values of the replicationAgreement where <consumer-replica-subentry-DN is the DN of the
entries discovered in the previous step. These attributes are replicaSubentry representing the other server, which is the
optional, but if the values are present, the objects named by the consumer in this agreement. There MUST be at least one entry in
values of these attributes MUST exist. the search results. For incremental update replication to occur at
least one of the entries in the search results MUST have a
replicationMechanismOID attribute which is either absent or has
the value ietf-ldup-incremental-update [Proto].
5. On each supplier replica, the client SHOULD invoke a baseObject
for each object named in the replicationCredentialsDN and
replicationScheduleDN attribute values of the replicationAgreement
entries discovered in the previous step. These attributes are
optional, but if the values are present, the objects named by the
values of these attributes MUST exist.
If all the above steps are successful, the objects necessary for If all the above steps are successful, the objects necessary for
replication to occur have been created. replication to occur have been created.
5.2.2 Verify that it is valid for replication to occur between 4.2.2 Verify that it is valid for replication to occur between
these servers these servers
For a replica to act as a supplier to another replica, the set of For a replica to act as a supplier to another replica, the set of
entries and attributes specified in the consumer replica's fractional entries and attributes specified in the consumer replica's fractional
entry specification MUST also be present in the supplier's fractional entry specification MUST also be present in the supplier's fractional
entry specification. The fractional entry specification is defined by entry specification. The fractional entry specification is defined by
the attributeExclusionFilter and attributeInclusionFilter attributes of the attributeExclusionFilter and attributeInclusionFilter attributes of
the replicaSubentry object for the replica. If these attributes are the replicaSubentry object for the replica. If these attributes are
not present the replica is a full replica. not present the replica is a full replica.
The client SHOULD perform a baseObject scope search on the supplier The client SHOULD perform a baseObject scope search on the supplier
replica specifying the replicaSubentry objects for both replicas to replica specifying the replicaSubentry objects for both replicas to
obtain the fractional entry specification for the replicas. The obtain the fractional entry specification for the replicas. The
following conditions MUST be satisfied: following conditions MUST be satisfied:
1. The attributeExclusionFilter of the supplier MUST NOT contain 1. The attributeExclusionFilter of the supplier MUST NOT contain
attributes that are not present in the attributeExclusionFilter of attributes that are not present in the attributeExclusionFilter of
the consumer. This condition is also satisfied if the the consumer. This condition is also satisfied if the
attributeExclsionFilter attribute is absent from either the attributeExclsionFilter attribute is absent from either the
supplier replicaSubentry or both the supplier and consumer supplier replicaSubentry or both the supplier and consumer
replicaSubentry objects. replicaSubentry objects.
2. The attributeExclusionFilter of the supplier MUST NOT contain 2. The attributeExclusionFilter of the supplier MUST NOT contain
attributes that are present in the attributeInclusionFilter of the attributes that are present in the attributeInclusionFilter of the
consumer. This condition is also satisfied if the consumer. This condition is also satisfied if the
attributeExclusion filter attribute is absent from the supplier attributeExclusion filter attribute is absent from the supplier
replicaSubentry, or if the attributeInclusionFliter attribute is replicaSubentry, or if the attributeInclusionFliter attribute is
absent from the consumer replicaSubentry. absent from the consumer replicaSubentry.
3. The attributeInclusionFilter of the consumer MUST NOT contain 3. The attributeInclusionFilter of the consumer MUST NOT contain
attributes that are not present in the attributeInclusionFilter of attributes that are not present in the attributeInclusionFilter of
the supplier. This condition is also satisfied if the the supplier. This condition is also satisfied if the
attributeInclusionFilter attribute either is absent from the attributeInclusionFilter attribute either is absent from the
consumer replicaSubentry or is absent from both the supplier and consumer replicaSubentry or is absent from both the supplier and
consumer replicaSubentry objects. consumer replicaSubentry objects.
5.3 Start replication between two servers 4.3 Start replication between two servers
For this operation, the client SHOULD follow the steps in Section 5.1 For this operation, the client SHOULD follow the steps in Section 4.1
followed by starting replication as specified in Section 4.11. followed by starting replication as specified in Section 3.11.
5.4 Suspend Replication activity on one area of a server 4.4 Suspend Replication activity on one area of a server
For this operation, the client SHOULD issue a search request to find For this operation, the client SHOULD issue a search request to find
the replicationSubentry of the target area on the target server. Then the replicationSubentry of the target area on the target server. Then
the client SHOULD suspend replication for this area as specified in the client SHOULD suspend replication for this area as specified in
Section 4.10. Section 3.10.
Note: As replicaOnline is DSA-specific, changing the value to false on Note: As replicaOnline is DSA-specific, changing the value to false on
one server will not change the value on other servers. Those servers one server will not change the value on other servers. Those servers
will keep trying to initiate replication and failing. To avoid this, will keep trying to initiate replication and failing. To avoid this,
replicaOnline must be set to false on all servers. replicaOnline must be set to false on all servers.
5.5 Suspend Replication activity on all areas of a server 4.5 Suspend Replication activity on all areas of a server
The client SHOULD retrieve all the values of the replicaSubentries The client SHOULD retrieve all the values of the replicaSubentries
attribute in the root DSE of the server. The client SHOULD then attribute in the root DSE of the server. The client SHOULD then
suspend replication on the replicationSubentry for the target server by suspend replication on the replicationSubentry for the target server by
following Section 4.10. following Section 3.10.
Note: As replicaOnline is DSA-specific, changing the value to false on Note: As replicaOnline is DSA-specific, changing the value to false on
one server will not change the value on other servers. Those servers one server will not change the value on other servers. Those servers
will keep trying to initiate replication and failing. To avoid this, will keep trying to initiate replication and failing. To avoid this,
replicaOnline must be set to false on all servers. replicaOnline must be set to false on all servers.
5.6 Restart Replication activity on one area of a server 4.6 Restart Replication activity on one area of a server
For this operation, the client SHOULD issue a search request to find For this operation, the client SHOULD issue a search request to find
the replicationSubentry of the target area on the target server. Then the replicationSubentry of the target area on the target server. Then
the client SHOULD resume replication for this area as specified in the client SHOULD resume replication for this area as specified in
Section 4.11. Section 3.11.
Note: if the client turned off replicaOnline on all servers in an area Note: if the client turned off replicaOnline on all servers in an area
of replication (as discussed in sections 5.4 and 5.5 above), the client of replication (as discussed in sections 4.4 and 4.5 above), the client
will need to turn on replicaOnline on all servers to resume will need to turn on replicaOnline on all servers to resume
replication. replication.
5.7 Restart Replication activity on all areas of a server 4.7 Restart Replication activity on all areas of a server
The client SHOULD retrieve all the values of the replicaSubentries The client SHOULD retrieve all the values of the replicaSubentries
attribute in the root DSE of the server. Then the client SHOULD take attribute in the root DSE of the server. Then the client SHOULD take
each area in turn and contact each server in that area's replication each area in turn and contact each server in that area's replication
group. The client SHOULD then resume replication for each group. The client SHOULD then resume replication for each
replicationSubentry for the target server by following Section 4.11. replicationSubentry for the target server by following Section 3.11.
Note: if the client turned off replicaOnline on all servers in an area Note: if the client turned off replicaOnline on all servers in an area
of replication (as discussed in sections 5.4 and 5.5 above), the client of replication (as discussed in sections 4.4 and 4.5 above), the client
will need to turn on replicaOnline on all servers to resume will need to turn on replicaOnline on all servers to resume
replication. replication.
5.8 Halt replication 4.8 Halt replication
To halt replication (i.e. terminate a current replication session and To halt replication (i.e. terminate a current replication session and
then prevent further replication occurring), the client follows the then prevent further replication occurring), the client follows the
appropriate steps from sections 5.4 and 5.5 above, inserting the step appropriate steps from sections 4.4 and 4.5 above, inserting the step
of issuing a termination operation (as specified in Section 4.13) after of issuing a termination operation (as specified in Section 3.13) after
replicaOnline is set to FALSE. The reason for terminating after setting replicaOnline is set to FALSE. The reason for terminating after setting
replicaOnline to FALSE is to avoid a new replication session starting replicaOnline to FALSE is to avoid a new replication session starting
immediately after the terminating operation is complete. immediately after the terminating operation is complete.
Note: the difference between Halt and Suspend replication is that Note: the difference between Halt and Suspend replication is that
suspend allows a currently ongoing replication session to finish, while suspend allows a currently ongoing replication session to finish, while
halt specifically invokes the operation of 4.13 to immediately halt specifically invokes the operation of 3.13 to immediately
terminate an ongoing replication session. terminate an ongoing replication session.
5.9 List status of a particular area of replication on a given server 4.9 List status of a particular area of replication on a given server
There are many pieces of information that could be considered "status". There are many pieces of information that could be considered "status".
A number of them are listed below, and a description of how to read A number of them are listed below, and a description of how to read
them is provided. them is provided.
An area of replication is defined by its replicaSubentry (the An area of replication is defined by its replicaSubentry (the
replicaSubentry that refers to the local server in its replicaURI replicaSubentry that refers to the local server in its replicaURI
attribute). The DN of this subentry will be called SDN in the rest of attribute). The DN of this subentry will be called SDN in the rest of
this section. this section.
5.9.1 Local Replica On-Line 4.9.1 Local Replica On-Line
To determine whether the given area of replication on the local server To determine whether the given area of replication on the local server
is on-line, check the replicaOnline attribute of SDN. is on-line, check the replicaOnline attribute of SDN.
5.9.2 Remote Replicas On-Line 4.9.2 Remote Replicas On-Line
To determine which other servers have the same replica on-line, do a To determine which other servers have the same replica on-line, do a
one-level LDAP search in the parent container of SDN. The filter one-level LDAP search in the parent container of SDN. The filter
should be set to find entries of objectclass replicaSubentry-2 which should be set to find entries of objectclass replicaSubentry-2 which
have subtreeSpecification identical to the subtreesSpecification of SDN have subtreeSpecification identical to the subtreesSpecification of SDN
The replicaURI and replicaOnline attributes of the objects that match The replicaURI and replicaOnline attributes of the objects that match
the filter will show what other servers hold this replica and whether the filter will show what other servers hold this replica and whether
they are on-line or off-line. they are on-line or off-line. Since replicaOnline is DSA-specific,
this search MUST be performed on each server that holds the replica.
5.9.3 Check Status of Outward Replication 4.9.3 Check Status of Outward Replication
If the area of replication in question uses replication agreements, If the area of replication in question uses replication agreements,
there is an optional replicationStatus attribute in the replication there is an optional replicationStatus attribute in the replication
agreement. If it exists, it holds a human-readable text message agreement. If it exists, it holds a human-readable text message
containing the status of the most recent attempt at replication for the containing the status of the most recent attempt at replication for the
replication agreement which contains it. To get the status for all replication agreement which contains it. To get the status for all
outgoing replication from the local server, do a one-level LDAP search outgoing replication from the local server, do a one-level LDAP search
with base SDN, filter of objectclass=replicaAgreementSubentry-2, and with base SDN, filter of objectclass=replicaAgreementSubentry-2, and
retrieve the replicationStatus attribute. retrieve the replicationStatus attribute.
5.9.4 Check Status of Incoming Replication 4.9.4 Check Status of Incoming Replication
To get the status for incoming replication to the local server, locate To get the status for incoming replication to the local server, locate
the replicaSubentries for other replicas of the area of replication as the replicaSubentries for other replicas of the area of replication as
described in Section 5.9.2. Then for each replicaSubentry, do a one- described in Section 4.9.2. Then for each replicaSubentry, do a one-
level LDAP search with base being that replicaSubentry using a filter level LDAP search with base being that replicaSubentry using a filter
of (objectclass=replicaAgreementSubentry-2), and retrieve the of (objectclass=replicaAgreementSubentry-2), and retrieve the
replicationStatus attribute. replicationStatus attribute.
5.10 List all areas of replication defined on a given server and their To be safe, replicationStatus SHOULD always be checked on the supplier
server. The copy on the consumer server may not be correct if there
was a replication problem. In the multi-master case, any server may
act as a supplier and all servers that hold the replica SHOULD be
checked.
4.10 List all areas of replication defined on a given server and their
status status
To find all the areas of replication on a given server, do the To find all the areas of replication on a given server, do the
following on that server: following on that server:
1. Retrieve all the values of the replicaContextRoots attribute in the 1. Retrieve all the values of the replicaContextRoots
attribute in the root DSE of the server. Each value is the
root DSE of the server. Each value is the distinguished name of distinguished name of the base entry of a Replication Context
the base entry of the base entry of a Replication Context held on held on the server.
the server. 2. Perform a one-level LDAP search in each replicaContextRoot for
2. Perform a one-level LDAP search in each replicaContextRoot for objects of class replicaSubentry whose replicaURI attribute
objects of class replicaSubentry whose replicaURI attribute points points to the given server (e.g. use a filter of
to the given server (e.g. use a filter of "(&(objectclass=replicaSubentry-
"(&(objectclass=replicaSubentry-2)(replicaURI=ldap://thisserver))") 2)(replicaURI=ldap://thisserver))") where "thisserver" is the
where "thisserver" is the DNS name of the given server. fully-qualified DNS name of the given server.
This will provide a list of all replicas held on the given server. This will provide a list of all replicas held on the given server.
Section 5.9 describes how to determine the status of each area. Section 4.9 describes how to determine the status of each area.
5.11 Restore a server and replication agreements after a server crash 4.11 Restore a server and replication agreements after a server crash
To restore a server and replication agreements after a server crash, To restore a server and replication agreements after a server crash,
the following steps SHOULD be performed. the following steps SHOULD be performed.
5.11.1 Recent Backup is Available 4.11.1 Recent Backup is Available
If a sufficiently recent backup is available, each area of replication If a sufficiently recent backup is available, each area of replication
MAY be recovered by doing the following: MAY be recovered by doing the following:
Note that the backup must contain UUIDs and CSNs. Note that the backup must contain UUIDs and CSNs.
1. Suspend replication to the server from all supplier servers (see 1. Suspend replication to the server from all supplier servers (see
Section 4.10). Section 3.10).
2. Restore the directory data and replication meta-data from the 2. Restore the directory data and replication meta-data from the
backup. backup.
3. If replication agreements to the server have been deleted, 3. If replication agreements to the server have been deleted,
recreate the desired replication agreements. recreate the desired replication agreements.
4. Compare the update vector for this replica, to the update vectors 4. Compare the update vector for this replica, to the update vectors
for other replicas (on the servers that hold the replicas). If for other replicas (on the servers that hold the replicas). If
the update vector for this server is greater than the minimum of the update vector for this server is greater than the minimum of
the CSNs present in the other update vectors, resume replication the CSNs present in the other update vectors, resume replication
to this server. No further action is necessary, as the other to this server. No further action is necessary, as the other
servers contain sufficient replication updates to recover all servers contain sufficient replication updates to recover all
subsequent updates via incremental replication. Otherwise, subsequent updates via incremental replication. Otherwise,
continue to the next step. containue to the next step.
5. Suspend replication to a replica that acts as a supplier to this 5. Suspend replication to a replica that acts as a supplier to this
server. This is done so that no changes occur on the supplier server. This is done so that no changes occur on the supplier
while recovery is in progress. while recovery is in progress.
6. Compare the DITs for each area of replication on this server with 6. Compare the DITs for each area of replication on this server with
the DIT on one of the servers acting as a supplier to this server the DIT on one of the servers acting as a supplier to this server
(section 5.20). For each difference found, repair the entry (section 4.20). For each difference found, repair the entry
(section 5.21). (section 4.21).
7. Set the recovered server's update vector on the recovered server 7. Set the recovered server's update vector on the recovered server
to the value of update vector for the area of replication on the to the value of update vector for the area of replication on the
supplier server. supplier server.
8. Resume replication to the supplier replica and to the recovered 8. Resume replication to the supplier replica and to the recovered
server. server.
5.11.2 Backup is Not Available 4.11.2 Backup is Not Available
If a sufficiently recent backup is not available, the following steps If a sufficiently recent backup is not available, the following steps
SHOULD be performed: SHOULD be performed:
1. Suspend replication to the server from all supplier servers (see 1. Suspend replication to the server from all supplier servers (see
Section 4.10).
2. Clear the contents of the server. The mechanism for doing this is Section 3.10).
2. Clear the contents of the server. The mechanism for doing this is
implementation specific. implementation specific.
3. Initialize the areas of replication on the server as if adding a 3. Initialize the areas of replication on the server as if adding a
new server to a replica group (section 5.1). new server to a replica group (section 4.1).
4. Start replication. 4. Start replication.
5.12 Split an Area of Replication 4.12 Split an Area of Replication
To split an area of replication, the atoms are: To split an area of replication, the atoms are:
1. Add the replicationContext objectclass to the root entry of the 1. Add the replicationContext objectclass to the root entry of the
new area of replication (Section 4.1) new area of replication (Section 3.1)
2. Create replicaSubentry objects under the new area of replication 2. Create replicaSubentry objects under the new area of replication
for each replica of the parent area of replication (Section 4.4) for each replica of the parent area of replication (Section 3.4)
3. Create replicaAgreement objects (and schedules) under the new 3. Create any replication credentials objects and
replicaSubentries, where agreements are created that correspond to replicaEventSchedule objects that will be referenced by the
each agreement defined for the parent (Section 4.7). replicaAgreement objects to be created in step 4.
JAM - I put the above there in case of any referential integrity
issues.
4. Create replicaAgreement objects under the new replicaSubentries,
where agreements are created that correspond to each agreement
defined for the parent (Section 3.7).
WG Issue: Schedules are referenced by DN. RVH - Can the schedules WG Issue: Schedules are referenced by DN. RVH - Can the schedules
of a different area of replication be referenced? Is there of a different area of replication be referenced? Is there
something that says that the schedules must be IN the area of something that says that the schedules must be IN the area of
replication they control? JAM - I think that schedules and replication they control? JAM - I think that schedules and
credentials need only be accessible to the replicas that use them. credentials need only be accessible to the replicas that use them.
That said, they are defined as subentries, and ought at least be That said, they are defined as subentries, and ought at least be
under a replicaSubentry. RDM - If this means that there are no under a replicaSubentry. RDM - If this means that there are no
reusable schedules and credentials, I think that is a Bad Thing reusable schedules and credentials, I think that is a Bad Thing.
TJH- Thinks nothing in infomod says that schedules are not
reusable. RVH- But infomod requires schedule to be under the
replicaSubentry, so they can't be reused because they can only be
under one replicaSubentry. Maybe we will settle this when we talk
to the infomod authors. JAM - infomod says it is thought these
objects will be placed below replicaAgreements but this is not
required. Maybe we can drop this issue? Or maybe we want infomod
to explicitly say that schedules can be placed elsewhere (so they
can be shared/reused?). Also, I think we decided that schedules
did not need to be subentries, or at least that
subtreespecification had no meaning for schedules.
4. Modify the subtreespecification of the superior replica's 5. Modify the subtreespecification of the superior replica's
replicaSubentry to exclude the new subordinate area of replicaSubentry to exclude the new subordinate area of
replication. replication.
JAM - Doesn't the scope of a subentry exclude subordinate
subentries governing the same kind of administrative area? So we
could remove this step?
These operations must be performed on each server containing a replica These operations must be performed on each server containing a replica
of the parent area of replication. of the parent area of replication.
WG Issue: RVH - Why? - Aren't all of the items changed WITHIN the WG Issue: RVH - Why? - Aren't all of the items changed WITHIN the
original area of replication? So won't they replicate as long as step original area of replication? So won't they replicate as long as step
4 is done last? JAM - Once the new area of replication is defined on 4 is done last? JAM - Once the new area of replication is defined on
one server, it quite likely defines the bounds of the superior. That one server, it quite likely defines the bounds of the superior. That
means that any further activity in the new area is replicated according means that any further activity in the new area is replicated according
to the subentries and agreements defined for it - initially none. It to the subentries and agreements defined for it - initially none. It
would be cleaner, in some respects, though, it would be nice if would be cleaner, in some respects, though, it would be nice if
defining the new area of replication cloned the subentries, agreements, defining the new area of replication cloned the subentries, agreements,
etc. from the superior and was replicated. RDM - If that isn't covered etc. from the superior and was replicated. RDM - If that isn't covered
in info-mod, I think it probably should be. in info-mod, I think it probably should be.
5.13 Move an existing area of replication to a new server 4.13 Move an existing area of replication to a new server
First add the area of replication to the new server as described in First add the area of replication to the new server as described in
Section 4.1. Then delete the area of replication from the old server
as described in Section 3.2.
Section 5.1. Then delete the area of replication from the old server Note that the "atom" in Section 3.2 will remove the old server from the
as described in Section 4.2.
Note that the "atom" in Section 4.2 will remove the old server from the
replica group but it will not delete the entries in the area of replica group but it will not delete the entries in the area of
replication from the old server. If the entries are to be deleted, replication from the old server. If the entries are to be deleted,
this can be done using standard LDAP operations after the old server is this can be done using standard LDAP operations after the old server is
removed from the replica group. removed from the replica group.
5.14 Join two Areas of Replication 4.14 Join two Areas of Replication
This section describes how to join two areas of replication. This section describes how to join two areas of replication.
5.14.1 Preconditions 4.14.1 Preconditions
Before joining two areas of replication there are certain preconditions Before joining two areas of replication, certain preconditions need to
that need to be satisfied: be satisfied:
1. Any server that contains a replica of one area of replication must 1. Any server that contains a replica of one area of replication must
also contain a replica of the other area of replication. This may also contain a replica of the other area of replication. This may
require copying either area of replication to additional servers, require copying either area of replication to additional servers,
or deleting either area of replication from servers. or deleting either area of replication from servers.
2. The replicas on any given server MUST be of the same type. Both 2. The replicas on any given server MUST be of the same type. Both
replicas must be updateable, both-readonly, or both primary. replicas must be updateable, both-readonly, or both primary.
Furthermore, if the replicas are readonly, they must both be full Furthermore, if the replicas are readonly, they must both be full
replicas, or must both be fractional replicas with identical replicas, or must both be fractional replicas with identical
fractional entry specifications. fractional entry specifications.
3. One area of replication must be directly subordinate to the other. 3. One area of replication must be directly subordinate to the other.
5.14.2 Procedure 4.14.2 Procedure
1. In each of the superior area's replicaSubentries, change the 1. In each of the superior area's replicaSubentries, change the
subtreespecification attribute to include the subordinate area. subtreespecification attribute to include the subordinate area.
2. Remove the replicationContext object class from the root of the 2. Remove the replicationContext object class from the root of the
subordinate area (this will replicate, so it only needs to be done subordinate area (this will replicate, so it only needs to be done
on one server). on one server).
3. To clean up, remove the replicaSubentry entries (and any 3. To clean up, remove the replicaSubentry entries (and any
subordinate replication agreements) from the subordinate area of subordinate replication agreements) from the subordinate area of
replication. replication.
5.14.3 Server requirements 4.14.3 Server requirements
When the replicationContext objectclass is removed from the root of an When the replicationContext objectclass is removed from the root of an
area of replication, the server MUST immediately treat entries within area of replication, the server MUST immediately treat entries within
the area of replication as belonging to the parent area of replication the area of replication as belonging to the parent area of replication
(if there is any). This includes replicating any pending replication (if there is any). This includes replicating any pending replication
updates (those not yet replicated to other replicas) as if they updates (those not yet replicated to other replicas) as if they
occurred under the parent area of replication, as well as preserving occurred under the parent area of replication, as well as preserving
any Lost and Found entries. any Lost and Found entries.
The replicaSubentries have a subtreespecification attribute which The replicaSubentries have a subtreespecification attribute which
skipping to change at page 22, line 17 skipping to change at page 24, line 50
has to be changed. If the subtreespecification is changed BEFORE the has to be changed. If the subtreespecification is changed BEFORE the
subordinate replicationContext is removed, we should be OK. Depending subordinate replicationContext is removed, we should be OK. Depending
on the implementation, some changes may be sent twice (once in each of on the implementation, some changes may be sent twice (once in each of
the overlapping areas of replication), but that shouldn't matter - the overlapping areas of replication), but that shouldn't matter -
conflict resolution can sort things out. conflict resolution can sort things out.
If a server receives a request to delete the replicationContext from an If a server receives a request to delete the replicationContext from an
area of replication, and there is a parent area of replication, the area of replication, and there is a parent area of replication, the
Server MUST verify that these replicas are of the same type, and if Server MUST verify that these replicas are of the same type, and if
fractional, that the fractional entry specifications are identical. If fractional, that the fractional entry specifications are identical. If
the replicas are not of the same type, the request MUST be failed with the replicas are not of the same type, the request MUST fail with
resultCode unwillingToPerform. resultCode unwillingToPerform.
5.15 Stop Replicating an Area of Replication. 4.15 Stop Replicating an Area of Replication.
This section describes how to stop replicating an area of replication. This section describes how to stop replicating an area of replication.
At the end of the procedure, the subtree represented by the area of At the end of the procedure, the subtree represented by the area of
replication will exist on one server, all replication agreements will replication will exist on one server, all replication agreements will
have been deleted, and the root of the area of replication will no have been deleted, and the root of the area of replication will no
longer be an area of replication. The server on which the subtree will longer be an area of replication. The server on which the subtree will
remain is referred to as the surviving replica. To stop replicating remain is referred to as the surviving replica.
an area of replication, a client with administrative authority should To stop replicating an area of replication, a client with
perform the following operations: administrative authority should perform the following operations:
1. Change the replica type of the non-surviving replicas to readonly 1. Change the replica type of the non-surviving replicas to readonly
(see section 4.6.1) (see section 3.6.1)
2. Halt replication by changing the replicaOnline attribute of all 2. Halt replication by changing the replicaOnline attribute of all
replicaSubentries on all servers to "false". replicaSubentries on all servers to "false".
After halting, the client MAY optionally delete information by: After halting, the client MAY optionally delete information by:
3. Delete all replication agreements (Section 4.8). 3. Delete all replication agreements (Section 3.8).
4. Delete all replicaSubentries under the area of replication 4. Delete all replicaSubentries under the area of replication
(section 4.5) (section 3.5)
5. Issue a modifyRequest to the surviving server where the object 5. Issue a modifyRequest to the surviving server where the object
field is the DN of the area of replication, and the modifications field is the DN of the area of replication, and the modifications
list consists of a single item, delete the attribute objectclass list consists of a single item, delete the attribute objectclass
with value replicationContext (Section 4.2). with value replicationContext (Section 3.2).
5.16 Convert a read-only replica to an updateable replica 4.16 Convert a read-only replica to an updateable replica
To convert a read-only replica to an updateable replica, the client To convert a read-only replica to an updateable replica, the client
SHOULD send a single request that follows section 4.8.1 to change the SHOULD send a single request that follows section 4.8.1 to change the
replica type to '2' (Updatable) using the write unwritable control replica type in the replicaSubentry on the target server to '2'
(4.16). (Updatable) using the write unwritable control (3.16).
If the read-only replica is not a full replica, this request SHOULD
also follow section 3.6.2 to make it a full replica before making it
updateable.
If the read-only replica is not complete, this request SHOULD also
follow section 4.6.2 to first change the replica type to complete.
As noted in [InfoMod], "The consequences of having incomplete As noted in [InfoMod], "The consequences of having incomplete
updateable replicas are not fully understood. LDAP DSAs MAY require updateable replicas are not fully understood. LDAP DSAs MAY require
updateable replicas to be complete replicas." If the DSA requires the updateable replicas to be complete replicas." If the DSA requires the
updatebale replica to be complete and the client sends a single request updatebale replica to be complete and the client sends a single request
that follows section 4.6.1 *only* and the readOnly replica is not that follows section 3.6.1 *only* and the readOnly replica is not
currently complete, the DSA may respond with an unwillingToPerform currently complete, the DSA may respond with an unwillingToPerform
error. error.
The DSA upon receiving and processing the request should trigger an The DSA upon receiving and processing the request should trigger an
immediate replica cycle to receive necessary data to make the target immediate replica cycle to receive necessary data to make the target
replica complete. replica complete.
Note: single-master implementations may not support the concept of two Note: single-master implementations may not support the concept of two
updateable masters being simultaneously active. In this case, the updateable masters being simultaneously active. In this case, the
client must convert the original master to read only via the following client must convert the original master to read only via the following
section before converting the new master to updateable via these steps. section before converting the new master to updateable via these steps.
5.17 Convert an updateable replica to a read-only replica 4.17 Convert an updateable replica to a read-only replica
To convert an updateable replica to a read-only replica, the client To convert an updateable replica to a read-only replica, the client
SHOULD send a single request that follows section 4.6.1 to change the SHOULD send a single request that follows section 3.6.1 to change the
replica type to '3' (Read-Only). replica type in the replicaSubentry to '3' (Read-Only).
The server, upon receiving and processing such a request SHOULD: The server, upon receiving and processing such a request SHOULD:
(a) Accept only LDAP search requests for that replica. 1. Accept only LDAP search requests for that replica.
(b) Finish replicating changes that had been accumulated. 2. Finish replicating changes that had been accumulated.
5.18 Postpone a Replica Cycle to a Later Time 4.18 Postpone a Replica Cycle to a Later Time
To temporarily halt replication to a particular server see Section 4.4.
To temporarily halt replication to a particular server see Section 5.4.
To temporarily halt replication on all servers for a particular area of To temporarily halt replication on all servers for a particular area of
replication see Section 5.5. To resume replication after these replication see Section 4.5. To resume replication after these
temporary halts, see Section 5.6 and 5.7 respectively. temporary halts, see Section 4.6 and 4.7 respectively.
To change the schedule for scheduled replication, find the To change the schedule for scheduled replication, find the
replicaAgreementSubentry for the given replication (see Section 5.9 and replicaAgreementSubentry for the given replication (see Section 4.9 and
5.10). The replicationScheduleDN attribute of the 4.10). The replicationScheduleDN attribute of the
replicaAgreementSubentry contains the DN of the scheduling information. replicaAgreementSubentry contains the DN of the scheduling information.
Information on how to set the scheduling information can be found in Information on how to set the scheduling information can be found in
[Infomod], [RFC3060], and [Policy]. [Infomod], [RFC3060], and [Policy].
If a replica cycle is already in progress, it can be terminated as If a replica cycle is already in progress, it can be terminated as
described in Section 4.13. described in Section 3.13.
Note that there are several events that may trigger a replica cycle, Note that there are several events that may trigger a replica cycle,
and schedule is only one of them. If, for example, a given replication and schedule is only one of them. If, for example, a given replication
agreement triggers replication whenever a change is made in the area of agreement triggers replication whenever a change is made in the area of
replication, a new cycle may be triggered as soon as the current cycle replication, a new cycle may be triggered as soon as the current cycle
is terminated. is terminated.
5.19 Examine Replication Audit History on a Server 4.19 Examine Replication Audit History on a Server
While whether DSAs store replication audit history in the directory is While whether DSAs store replication audit history in the directory is
outside the scope of this document, DSAs MUST store audit history in a outside the scope of this document, DSAs MUST store audit history in a
file available to users of the underlying operating system (OS). A file available to users of the underlying operating system (OS). A
person wanting to examine the replication audit history should make use person wanting to examine the replication audit history should make use
of the underlying OS. Whether they are required to have special of the underlying OS. Whether they are required to have special
permissions is outside the scope of this document. permissions is outside the scope of this document.
The reason for storing this information outside the directory is so The reason for storing this information outside the directory is so
that the administrator may still have access to it in cases of that the administrator may still have access to it in cases of
directory failure or inaccessibility. directory failure or inaccessibility.
5.20 Compare Two Replicas on Two Servers for Differences 4.20 Compare Two Replicas on Two Servers for Differences
It may be desirable to compare replicas of an area of replication on It may be desirable to compare replicas of an area of replication on
two servers for differences. The process for doing this is to do a two servers for differences. The process for doing this is to do a
recursive singleLevel search starting at the root entry of the area of recursive singleLevel search starting at the root entry of the area of
replication. The search SHOULD specify an attribute list that includes replication. The search SHOULD specify an attribute list that includes
the value '*' (all non-operational attributes), as well as the the value ?*? (all non-operational attributes), as well as the
following operational attributes: entryUuid. Each search is performed following operational attributes: entryUuid. Each search is performed
on both servers, and the results compared as follows: on both servers, and the results compared as follows:
1. If the DN of an entry matches the DN of a subordinate area of 1. If the DN of an entry matches the DN of a subordinate area of
replication identified in the replicationContexts root DSE replication identified in the replicationContexts root DSE
attribute for that server, exclude that entry from further attribute for that server, exclude that entry from further
processing. processing.
2. Compare the set of RDNs from the search on each server to
2. Compare the set of RDNs from the search on each server to
determine if there are entries present on one server that are not determine if there are entries present on one server that are not
present on the other server. present on the other server.
3. For each entry, compare the set of attribute values returned from 3. For each entry that exists in both servers, compare the set of
each server to determine if there attribute values present in the attribute values returned from each server to determine if there
entry on one server that are not present in the entry on the other attribute values present in the entry on one server that are not
server. present in the entry on the other server.
4. For each entry that is not the root of a subordinate area of 4. For each entry that is not the root of a subordinate area of
replication, form the search and comparisons described above. replication, form the search and comparisons described above.
5.21 Fix an Entry Without Triggering Replication 4.21 Fix an Entry Without Triggering Replication
When conflicts cause entries to be put in the Lost+Found area, the When conflicts cause entries to be put in the Lost+Found area, the
administrator needs a mechanism to make appropriate changes. These administrator needs a mechanism to make appropriate changes. These
changes may include fixes to replication meta-data (UUIDs, CSNs, etc.) changes may include fixes to replication meta-data (UUIDs, CSNs, etc.)
that cannot be changed using normal LDAP operations. Once the revised that cannot be changed using normal LDAP operations. Once the revised
entries have been stored, any future replication operations will be entries have been stored, any future replication operations will be
based on the modified meta-data. based on the modified meta-data.
The "atoms" of Section 4.14 can be used to read meta-data that is not The "atoms" of Section 3.14 can be used to read meta-data that is not
readable through normal LDAP operations. entryUUID and createdEntryCSN readable through normal LDAP operations. entryUUID and createdEntryCSN
are available as operational attributes so they can be read with a are available as operational attributes so they can be read with a
normal LDAP "search". The atoms of Section 4.15 can be used to write normal LDAP "search". The atoms of Section 3.15 can be used to write
meta-data. meta-data.
Typically, an administrator would resolve a replication conflict using Typically, an administrator would resolve a replication conflict using
the following steps: the following steps:
1. Read (using Section 4.14) and temporarily store all the meta-data 1. Read (using Section 3.14) and temporarily store all the meta-data
associated with a conflicting set of entries (where some of the associated with a conflicting set of entries (where some of the
entries may be in Lost+Found) entries may be in Lost+Found)
2. Decide what the final result should be (including all associated 2. Decide what the final result should be (including all associated
meta-data) meta-data)
3. Depending on the complexity of the change and on whether the 3. Depending on the complexity of the change and on whether the
entry to be changed has children: entry to be changed has children:
a. Delete (using Delete with Meta-Data defined in Section 4.15.2) a. Delete (using Delete with Meta-Data defined in Section 3.15.2)
the conflicting entry or entries, and the conflicting entry or entries, and
b. Build the "correct" new entry or entries (with all appropriate b. Build the "correct" new entry or entries (with all appropriate
meta-data) on all affected nodes using Add with Meta-Data from meta-data) on all affected nodes using Add with Meta-Data from
Section 4.15.1; or Section 3.15.1; or
c. Use Modify with Meta-Data (Section 4.15.3) to make the change. c. Use Modify with Meta-Data (Section 3.15.3) to make the change.
Changes may need to be made on several replicas. In all cases, care Changes may need to be made on several replicas. In all cases, care
should be taken to keep the UUIDs of the entries consistent across should be taken to keep the UUIDs of the entries consistent across
replicas. replicas.
5.22 Check Reported Schema Mismatches Discovered During Replication 4.22 Check Reported Schema Mismatches Discovered During Replication
DSAs MAY store the result of reported schema mismatches in the DSAs MAY store the result of reported schema mismatches in the
directory. They SHOULD store the schema mismatch and any resulting directory. They SHOULD store the schema mismatch and any resulting
action in the Audit History. The record SHOULD include the type of action in the Audit History. The record SHOULD include the type of
mismatch (some examples may be found in [USAGE]) as well as the mismatch (some examples may be found in [USAGE]) as well as the
resulting action: items moved to lost+found, items not added, etc. resulting action: items moved to lost+found, items not added, etc.
5.23 Adding a new directory server to a replica group and initializing 4.23 Adding a new directory server to a replica group and initializing
the contents the contents
In this case, the client: In this case, the client:
1. Copies the base entry for the area of replication from a source to 1. Copies the base entry for the area of replication from a source to
the target (section 4.3) the target (section 3.3)
2. Create the entries for the new server on all servers in the replica 2. Create the entries for the new server on all servers in the replica
group (section 4.4) group (section 3.4)
3. Create the entries for the existing replica group servers on the new 3. Create the entries for the existing replica group servers on the new
(section 4.4) (section 3.4)
4. Create the replication agreement on the new server and one other 4. Create the replication agreement on the new server and one other
server (section 4.7) server (section 3.7)
5. Client issues a "Initiate Full Update" request to a full replica for 5. Client issues a "Initiate Full Update" request to a full replica for
the new replica -- or new replica requests consumer initiated full the new replica -- or new replica requests consumer initiated full
update (section 4.12). update (section 3.12).
5.24 Restore from the master failure in a single-master system 4.24 Restore from the master failure in a single-master system
To provide a fast fail-over mechanism for the failure of the master To provide a fast fail-over mechanism for the failure of the master
server in a single-master system, the following steps SHOULD be server in a single-master system, the following steps SHOULD be
performed: performed:
1. When the system is initially set up, at least one server SHOULD be 1. When the system is initially set up, at least one server SHOULD be
designated as the fail-over server. This does not reflect a designated as the fail-over server. This does not reflect a
special replica type for the server, rather it reflects an special replica type for the server, rather it reflects an
administrative decision. This server is referred to as the fail- administrative decision. This server is referred to as the fail-
over replica in the following steps. over replica in the following steps.
skipping to change at page 26, line 5 skipping to change at page 28, line 56
replicaType of the fail-over server to updateable or primary (see replicaType of the fail-over server to updateable or primary (see
section 5.17). The fail-over server is now ready to act as a section 5.17). The fail-over server is now ready to act as a
master server. master server.
WG Issue: The above steps imply the need to ensure that the master WG Issue: The above steps imply the need to ensure that the master
replicates changes to the fail-over server before replicating a change replicates changes to the fail-over server before replicating a change
to other servers. Otherwise, a replica may have changes that have not to other servers. Otherwise, a replica may have changes that have not
been replicated to the fail-over server. This can be accomplished by been replicated to the fail-over server. This can be accomplished by
requiring that if writable replica notes that there is only one other requiring that if writable replica notes that there is only one other
replica with replication agreements defined, the supplier should replica with replication agreements defined, the supplier should
replicate to that server first. replicate to that server first. TJH- More generally, replicate first
to servers that are suppliers.
WG Issue: Step 2 implies that a replica that acts as a supplier to no WG Issue: Step 2 implies that a replica that acts as a supplier to no
other server need only keep sufficient state information to satisfy other server need only keep sufficient state information to satisfy
idempotency and conflict resolution. idempotency and conflict resolution.
If the above steps are not taken, a full read-only replica can be If the above steps are not taken, a full read-only replica can be
promoted to a master by following these steps: promoted to a master by following these steps:
1. Designate one replica as the new master server. This master 1. Designate one replica as the new master server. This master
SHOULD be a replica that has an update vector at least as recent SHOULD be a replica that has an update vector at least as recent
as any other replica. Do not change the replicaType at this time. as any other replica. Do not change the replicaType at this time.
2. Perform pair-wise DIT comparisons between the new master and each 2. Perform pair-wise DIT comparisons between the new master and each
other replica. Record the discrepancies and ensure that the other replica. Record the discrepancies and ensure that the
affected entries are removed or fixed on all servers (see section affected entries are removed or fixed on all servers (see section
5.21 - fix entries) 4.21 - fix entries)
3. On the new master, change the replicaType to updateable or primary 3. On the new master, change the replicaType to updateable or primary
and mark the replicaSubentry for the new master as offline. This and mark the replicaSubentry for the new master as offline. This
ensures that the server will hold client updates for future ensures that the server will hold client updates for future
replication but not replicate them at this time. replication but not replicate them at this time.
4. Add replication agreements, replication credentials entries, and 4. Add replication agreements, replication credentials entries, and
replication schedule entries as needed between the new master and replication schedule entries as needed between the new master and
all other replicas. all other replicas.
5. On the new master, mark the replicaSubentry online. Replication 5. On the new master, mark the replicaSubentry online. Replication
of the replication agreements and other client updates will start. of the replication agreements and other client updates will start.
6 Formal Specifications 5 Formal Specifications
The Replica Management features depend heavily on defined LDAP and LDUP The Replica Management features depend heavily on defined LDAP and LDUP
structure, operations, and data formats. But some changes will be structure, operations, and data formats. But some changes will be
needed to accommodate Replica Management. All these changes are pulled needed to accommodate Replica Management. All these changes are pulled
together in this section for easy reference. together in this section for easy reference.
6.1 New/Modified Object Classes 5.1 New/Modified Object Classes
TBD TBD
6.2 New/Modified Attributes 5.2 New/Modified Attributes
TBD TBD
6.3 New/Modified Extended Operations 5.3 New/Modified Extended Operations
Trigger Replica Operation Trigger Replica Operation
TBD TBD
6.4 New/Modified Replication Primitives 5.4 New/Modified Replication Primitives
TBD TBD
6.5 New/Modified Controls 5.5 New/Modified Controls
TBD TBD
6 Security Considerations
7 Security Considerations
For security purposes it is important to be able to limit the number of For security purposes it is important to be able to limit the number of
individuals with administrative access and to track the actions individuals with administrative access and to track the actions
performed by each administrator. Thus, servers SHOULD allow multiple performed by each administrator. Thus, servers SHOULD allow multiple
administrative users, and they SHOULD allow each administrative user to administrative users, and they SHOULD allow each administrative user to
have distinct rights. It SHOULD be possible to log all of the have distinct rights. It SHOULD be possible to log all of the
administrative actions discussed in this document and the log entry administrative actions discussed in this document and the log entry
SHOULD include the identity of the administrator performing the action. SHOULD include the identity of the administrator performing the action.
In all cases, it is assumed that the client establishes a connection to In all cases, it is assumed that the client establishes a connection to
the LDAP server and SHOULD authenticate using a recommended the LDAP server and SHOULD authenticate using a recommended
skipping to change at page 27, line 44 skipping to change at page 30, line 46
Start TLS has been invoked, and use this to decide whether to use Start TLS has been invoked, and use this to decide whether to use
DIGEST-MD5 or EXTERNAL. See [RFC2830] for more information on TLS. DIGEST-MD5 or EXTERNAL. See [RFC2830] for more information on TLS.
Some of the controls/extended operations defined in this document allow Some of the controls/extended operations defined in this document allow
modification of the data that controls replication document (Modify modification of the data that controls replication document (Modify
with Meta-Data) or modification of data in the DIT (Trigger Immediate with Meta-Data) or modification of data in the DIT (Trigger Immediate
Replica Cycle from a file). Unauthorized use of these features can Replica Cycle from a file). Unauthorized use of these features can
destroy a directory. Directories which support these features MUST destroy a directory. Directories which support these features MUST
also provide a mechanism to restrict their use to authorized users. also provide a mechanism to restrict their use to authorized users.
8 Acknowledgements 7 Acknowledgements
Thanks to Mark Wahl and Ed Reed for providing a lot of the initial Thanks to Mark Wahl and Ed Reed for providing a lot of the initial
text. text.
This document is a product of the LDUP Working Group of the IETF. The This document is a product of the LDUP Working Group of the IETF. The
contributions of its members are greatly appreciated. contributions of its members are greatly appreciated.
9 References 8 References
[Arch] J. Merrells, E. Reed, U. Srinvasan, "LDAP Replication [Arch] J. Merrells, E. Reed, U. Srinvasan, "LDAP Replication
Architecture", draft-ietf-ldup-model-01.txt. Architecture", draft-ietf-ldup-model-01.txt.
[InfoMod] E. Reed, "LDAP Replication Information Model", draft-ietf- [InfoMod] E. Reed, "LDAP Replication Information Model", draft-ietf-
ldup-infomod-00.txt. ldup-infomod-00.txt.
[Policy] J. Strassner, A. Westerinen, E. Ellesson, B. Moore, R. Moats, [Policy] J. Strassner, A. Westerinen, E. Ellesson, B. Moore, R. Moats,
"Policy Core LDAP Schema", Internet draft, draft-ietf-policy-core- "Policy Core LDAP Schema", Internet draft, draft-ietf-policy-core-
schema-13.txt, November 2001. schema-13.txt, November 2001.
skipping to change at page 28, line 6 skipping to change at page 31, line 18
Architecture", draft-ietf-ldup-model-01.txt. Architecture", draft-ietf-ldup-model-01.txt.
[InfoMod] E. Reed, "LDAP Replication Information Model", draft-ietf- [InfoMod] E. Reed, "LDAP Replication Information Model", draft-ietf-
ldup-infomod-00.txt. ldup-infomod-00.txt.
[Policy] J. Strassner, A. Westerinen, E. Ellesson, B. Moore, R. Moats, [Policy] J. Strassner, A. Westerinen, E. Ellesson, B. Moore, R. Moats,
"Policy Core LDAP Schema", Internet draft, draft-ietf-policy-core- "Policy Core LDAP Schema", Internet draft, draft-ietf-policy-core-
schema-13.txt, November 2001. schema-13.txt, November 2001.
[Proto] E. Stokes, G. Good, R. Harrison, T. Hahn, "The LDUP Replication [Proto] E. Stokes, G. Good, R. Harrison, T. Hahn, "The LDUP Replication
Update Protocol", Internet Draft, draft-ietf-ldup-protcol-03.txt, Update Protocol", Internet Draft, draft-ietf-ldup-protcol-03.txt,
November 2001. November 2001.
[Req] E. Stokes, R. Weiser, R. Moats, R. Huber, "LDAPv3 Replication [Req] E. Stokes, R. Weiser, R. Moats, R. Huber, "LDAPv3 Replication
Requirements", Internet Draft, draft-ietf-ldup-replica-req-10.txt, July Requirements", Internet Draft, draft-ietf-ldup-replica-req-10.txt, July
2001. 2001.
[RFC2119] S. Bradner, "Key Words for Use in RFCs to Indicate [RFC2119] S. Bradner, "Key Words for Use in RFCs to Indicate
Requirement Levels", RFC 2119, March 1997. Requirement Levels", RFC 2119, March 1997.
[RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access [RFC2251] M. Wahl, T. Howes, S. Kille, "Lightweight Directory Access
Protocol (v3)", RFC 2251, December 1997. Protocol (v3)", RFC 2251, December 1997.
[RFC2829] M. Wahl, H. Alvestrand, J. Hodges, RL Morgan, "Authentication [RFC2829] M. Wahl, H. Alvestrand, J. Hodges, RL Morgan, "Authentication
Methods for LDAP", RFC 2829, May 2000. Methods for LDAP", RFC 2829, May 2000.
[RFC2830] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access [RFC2830] J. Hodges, R. Morgan, M. Wahl, "Lightweight Directory Access
Protocol (v3): Extension for Transport Layer Security", RFC 2830, May Protocol (v3): Extension for Transport Layer Security", RFC 2830, May
2000. 2000.
[RFC3060] B. Moore, E. Ellesson, J. Strassner, A. Westerinen, "Policy [RFC3060] B. Moore, E. Ellesson, J. Strassner, A. Westerinen, " Policy
Core Information Model -- Version 1 Specification", RFC 3060, February Core Information Model -- Version 1 Specification", RFC 3060, February
2001. 2001.
[Usage] R. Huber, et al. "General Usage Profile for LDAPv3 Replication", [Usage] R. Huber, et al. "General Usage Profile for LDAPv3 Replication,"
draft-ietf-ldup-usage-profile-02, November 2001. draft-ietf-ldup-usage-profile-02, November 2001.
Authors' Addresses: Authors' Addresses:
Ryan Moats Ryan Moats
Lemur Networks, Inc. Lemur Networks, Inc.
Email: rmoats@lemurnetworks.net Email: rmoats@lemurnetworks.net
Rick Huber Rick Huber
AT&T Laboratories AT&T Laboratories
 End of changes. 212 change blocks. 
448 lines changed or deleted 489 lines changed or added

This html diff was produced by rfcdiff 1.48. The latest version is available from http://tools.ietf.org/tools/rfcdiff/