Cascading replication operation extended operation

Edit online

The cascading replication operation extended operation explains its use with the server and provides the results.

Description
Run a replication extended operation on every server in the full replication topology. This extended operation runs the requested action on the server on which it is issued. It cascades the call to all consumers beneath it in a replication topology.
Note: This extended operation is always enabled.
Request
OID
1.3.18.0.2.12.15
Syntax
requestValue ::= SEQUENCE {
action ActionValue,
subtreeDN DistinguishedName,
timeout INTEGER
}
ActionValue ::= INTEGER {
quiesce (0),
unquiesce (1),
replicateNow (2),
waitForReplication (3)
}
Response
OID
1.3.18.0.2.12.15
Syntax
responseValue ::= SEQUENCE {
    # LDAPResult fields 
		resultCode INTEGER (0..MAX),
    errorMessage LDAPString

		# Operation specific failure information:
    supplier LDAPString,
    consumer LDAPString,

    # Additional optional fields:
    additionalResultCode [1] INTEGER OPTIONAL,
    agreementDN [2] LDAPString OPTIONAL

}
When the resultCode is LDAP_TIMEOUT, the additionalResultCode field must be set to one of the following values: 
		additionalResultCode ENUMERATED {
       LDAP_REPLICATION_SUSPENDED      [1],
       LDAP_REPLICATION_RETRYING       [2], 
       LDAP_REPLICATION_ERROR_LOG_FULL [3]
    }
Note: The additionalResultCode and agreementDN fields are not present for servers earlier than IBM® Verify Directory, version 6.1.
The following codes are possible return codes:
  • LDAP_SUCCESS - Operation was successful
  • LDAP_NO_SUCH_OBJECT - Replication context or agreement does not exist
  • LDAP_UNWILLING_TO_PERFORM - Object is not a replication context
  • LDAP_NO_MEMORY
  • LDAP_OPERATIONS_ERROR
  • LDAP_INSUFFICIENT_ACCESS - Not authorized to run the operation
  • LDAP_PARAM_ERROR
  • LDAP_ENCODING_ERROR
  • LDAP_LOCAL_ERROR
  • LDAP_TIMEOUT - Operation did not complete within specified time
Behavior
The requested operation is run on the target server and on all replicas of the target server. This extended operation runs the requested action on the server it is issued on. It cascades the call to all consumers beneath it in a replication topology. The operation returns when one of the following conditions occurs:
  • The request is completed on all servers.
  • A failure occurred on a server (result indicates the failure and the server).
  • The timeout value is exceeded.
This extended operation is allowed only when:
  • The client is authenticated with update authority to all agreements in the specified subtree.
  • The client is authenticated as a master server for the specified subtree.

Sometimes when a wait for replication is called during the add replica, add master, or move operation in a replication, wait for replication time-out. No error is displayed that resulted in time-out. This error is occurred because the cascaded replication times out. To facilitate a better diagnosis, the replication response structure is updated. When the return code is LDAP_TIMEOUT, the additionalResultCode and agreementDN fields are set.

The additionalResultCode field is populated with error message. Following examples illustrate how the server handles the cascaded replication timeout cases and the possible error messages:
  • resultCode = LDAP_TIMEOUT without additionalResultCode means a directory server instance earlier than 6.1.
    Web Administration tool and ldapexop displays a message, for example: 
    Replication from supplier replica Supreplica_1 to consumer replica 
 hostname: port did not complete.

Replication agreement xxx is suspended.
  • resultCode = LDAP_TIMEOUT with additionalResultCode = LDAP_REPLICATION_SUSPENDED
    Web Administration tool and ldapexop displays a message, for example:
    Replication from supplier replica Supreplica_1 to consumer replica 
 hostname: port did not complete.

Replication agreement xxx is suspended.
  • resultCode = LDAP_TIMEOUT with additionalResultCode = LDAP_REPLICATION_RETRYING
    Web Administration tool and ldapexop displays a message, for example:
    Replication from supplier replica Supreplica_1 to consumer replica 
 hostname: port did not complete.

Replication agreement xxx is blocked on a failing change.
  • resultCode = LDAP_TIMEOUT with additionalResultCode = LDAP_REPLICATION_ERROR_LOG_FULL
    Web Administration tool and ldapexop displays a message, for example:
    Replication from supplier replica Supreplica_1 to consumer replica 
 hostname: port did not complete.

The replication error log is full for agreement xxx.

The agreementDN field contains the DN of the associated replication agreement. The agreementDN field is set whenever the server that detects the error is working with a particular agreement.

This response is sent for all requests from servers that have a well-formed request value. The response value consists of a resultCode with errorMessage and information about where the error was detected.

The supplier field contains the DNS host name of the server that reports the error. If the error occurs with a consumer server, the consumer field contains the DNS host name of the consumer server. The error is the server that is timed out and waiting for a response from a consumer. In this case, the supplier field is always completed but the consumer field might be empty. Since it is an error condition, the agreementDN field is populated, which provides information about the supplier and consumer.

The following persons are enabled to call the extended operation:
  • Primary Directory Administrator
  • Local Administration Group members with DirDataAdmin and ReplicationAdmin roles
  • Global Administration Group members
  • Master Server DN
  • Authenticated Directory User
Note: If the extended operation is called by a user who does not have access, LDAP_INSUFFICIENT_ACCESS is returned.
This extended operation has the following possible return codes:
  • LDAP_SUCCESS
  • LDAP_PROTOCOL_ERROR
  • LDAP_NO_MEMORY
  • LDAP_DECODING_ERROR
  • LDAP_UNDEFINED_TYPE
  • LDAP_INVALID_DN_SYNTAX
This extended operation is not supported by the Administration Server.
Scope
This extended operation affects only the current operation.
Auditing
Action: [Quiesce | Unquiesce | ReplNow | Wait | Unknown] 
Context DN: context DN
Timeout: timeout