3.3.4.2 FrsRpcStartPromotionParent Message (Opnum 2)

The FrsRpcStartPromotionParent method requests the server that is the Upstream Partner to start a volatile connection for the purpose of seeding the system volume (SYSVOL) folder on the container.

 unsigned long FrsRpcStartPromotionParent(
   [in] handle_t Handle,
   [in, string, unique] PWCHAR ParentAccount,
   [in, string, unique] PWCHAR ParentPassword,
   [in, string, unique] PWCHAR ReplicaSetName,
   [in, string, unique] PWCHAR ReplicaSetType,
   [in, string, unique] PWCHAR CxtionName,
   [in, string, unique] PWCHAR PartnerName,
   [in, string, unique] PWCHAR PartnerPrincName,
   [in] unsigned long PartnerAuthLevel,
   [in, range(sizeof(GUID),sizeof(GUID))] 
     unsigned long GuidSize,
   [in, size_is(GuidSize), unique] 
     unsigned char* CxtionGuid,
   [in, size_is(GuidSize), unique] 
     unsigned char* PartnerGuid,
   [in, out, size_is(GuidSize), unique] 
     unsigned char* ParentGuid
 );

Handle: Binding handle obtained when the partner authenticates with the file replication service.

ParentAccount: Valid account on the DC that functions as the parent. MUST be NULL (indicating to use the current connecting client's credential).

ParentPassword: Password for an account on the DC. MUST be NULL.

ReplicaSetName: RDN name of the replica set that the caller requested.

ReplicaSetType: String that specifies the type of the replica set that the caller requested. The string MUST be treated in a case-insensitive manner, and there MUST NOT be white space in the string. The value MUST be one of the following.

Value

Meaning

"Enterprise"

Enterprise Replica Set.

"Domain"

Domain Replica Set.

CxtionName: Fully qualified domain name of the machine receiving this call.

PartnerName: Fully qualified domain name of the caller.

PartnerPrincName: Name of the caller to use for Kerberos authentication in the format of [Domain Name]\[Host Name]$.

PartnerAuthLevel: Authentication type and level. MUST be one of the following values. <76>

Value

Meaning

0x00000000

Encrypted Kerberos

0x00000001

No authentication

GuidSize: Size of the array allocated to hold the globally unique identifier (GUID). MUST be 0x00000010.

CxtionGuid: Temporary value for the connection. The GUID is generated randomly and is not persisted in Active Directory.

PartnerGuid: GUID that identifies the replica set on the replication partner.

ParentGuid: GUID value that identifies the parent for the inbound connection.

Return Values: The method MUST return 0 on success; otherwise, it MUST return a nonzero error code, as defined by the vendor.

To create a \SYSVOL volume (required for the server to operate as a DC), the FrsRpcStartPromotionParent method requests a volatile connection on the server for the purpose of seeding a \SYSVOL folder. This is necessary because of the following: During DC promotion, the newly promoted DC creates a set of Active Directory objects, which includes the connection objects. When the newly promoted DC is trying to replicate the contents from another DC in the domain (the process is called initial sync), the other DC might not know the newly created connection, either because the DS replication service has not replicated the connection out to the other DC or because the other DC has not polled the Directory Service yet. The newly created DC creates a volatile connection for only the initial sync and calls this RPC function to inform the other DC about this volatile connection. In this way, the other DC does not reject the initial sync request. <77> Once the initial sync is completed, NTFRS starts using the connection generated by Knowledge Consistency Checker (KCC) for normal synchronization.

On receiving this message, the server MUST validate the following:

  • Verify that the current local member is really a DC by querying the local member's computer object in the domain, as specified in [MS-ADSC] section 2.21.

  •  Verify that the client MUST be really a DC by querying the client's computer object in the domain, as specified in [MS-ADSC] section 2.21.

  •  Verify GuidSize MUST be 0x10.

  •  Verify ReplicaSetName is not NULL and MUST exist on the server.

  •  Verify ReplicaSetType MUST be either Enterprise or Domain.

  •  Verify CxtionName MUST NOT be NULL.

  •  Verify PartnerName MUST NOT be NULL.

  •  Verify PartnerPrincName MUST NOT be NULL.

  •  Verify CxtionGuid MUST NOT be NULL.

  •  Verify PartnerGuid MUST NOT be NULL.

  •  Verify ParentGuid MUST NOT be NULL.

  •  Verify PartnerAuthLevel MUST be either 0 (Encrypted Kerberos) or 1 (no authentication).

If the parameter validation fails, the server MUST fail the operation with ERROR_INVALID_PARAMETER, as specified in [MS-ERREF] section 2.2; otherwise, the server MUST do the following:

  • Find the local replica as identified by ReplicaSetName by reading the Active Directory objects.

  •  Set the local replica's GUID as ParentGuid.

  • Create a new connection in the local replica with the following parameters:

    • Connection direction MUST be set to Outbound.

    • Mark the connection to be volatile.

    •  Connection name MUST be set to CxtionGuid.

    •  Connection GUID MUST be set to CxtionGuid.

    •  Connection partner name MUST be set to PartnerName.

    •  Connection partner GUID MUST be set to PartnerGuid.

    •  Connection state MUST be set to unjoined state.

    • The first time promotion for SYSVOL MUST wait for connection establishment request (section 3.3.4.4.4).