1. The site information (including public key, etc.) of the site it will be replicating.
2. The last transaction ID it received from each server in the site.
3. The timestamp of the last transaction it received from each server in the site.
4. Authentication credentials that give the secondary permission to do replication with the primary.

In the handle server, server replication is done in a separate thread. The replication daemon is a thread that retrieves handle transactions from the primary servers or some other source (depending on the server configuration). The replication daemon should only run on secondaries, not on primary servers.

The replication daemon does the following:

Handle server replication communication is based on two request/response pairs. The secondary server sends out a request for new transactions or it sends a request for a dump of all the handles in the primary server. What follows is a description of the request and associated responses.

This is the request used to retrieve any new transactions from a server. This request is used for server<->server (or replicator<->server) communication. The request needs to provide the following information to the server being queried:

The last transaction ID will allow the server being queried to determine which transactions need to be returned. The queried server will send every transaction that has a transaction ID greater than the last transaction ID and hashes to the requesting server. Knowing the last time the transactions were queried will allow the server being queried to determine if the entire set of handles needs to be "dumped" again.

The following describes the body of the Retrieve Transactions Request handle protocol message as defined in Section 2 of RFC 3652.

The Message Header of any Retrieve Transactions Request must set its <OpCode> to OC_RETRIEVE_TXN_LOG and its <ResponseCode> to 0.

	<Message Body of Retrieve Transactions Request>	::=	<LastTransactionID>
			<LastQueryDate>
			<ReceieverHashType>
			<NumberOfServers>
			<ServerNumber>

where:

<LastTransactionID>
A 8-byte unsigned integer that specifies the last Transaction ID.

<LastQueryDate>
A 8-byte unsigned integer that specifies the last query date. The date unit is milliseconds. The value of the date is the milliseconds since January 1, 1970, 00:00:00 GMT.

<ReceiverHashType>
A 1-byte value that identifies how the handles are hashed on the server.

<NumberOfServers>
A 4-byte unsigned integer that specifies the number of servers in the site.

<ServerNumber>
A 4-byte unsigned integer that specifies which server in the site is sending the request.

This is the response used to forward new transactions to a replicated site/server. This response is used for server<->server or (replicator<->server) communication. The response has two valid states. It will either be SENDING_TRANSACTIONS or it will indicate a NEED_TO_REDUMP all the handles for the servers being replicated. If NEED_TO_REDUMP is returned then the secondary site/server will request all the handles from all the servers in the primary site. If the Retrieve Transactions Response status is SENDING_TRANSACTIONS, the primary server wil stream all new transactions to the requesting secondary server. The following describes the body of the handle protocol message as defined in Section 2 of RFC 3652.

The Message Header of any Retrieve Transactions Request must set its <OpCode> to RETRIEVE_TXN_LOG. A successful Retrieve Transactions Response must set its <ResponseCode> to RC_SUCCESS. This message is streamable.

	<Message Body of Retrieve Transactions Request>	::=	<RequestDigest>
			<DataFormatVersion>
			<Status>
			<Stream>
			<EndTransmissionRecord>
			<LastQueryDate>

where:

<RequestDigest>
Optional field as defined in section 2.2.3 of RFC 3652. Including the request digest enables the client to ensure that the response being received is actually in response to the request that was sent. This prevents a malevolent entity from returning a different response (a response previously signed by the server as a valid response to a different request) to the client, and giving the client bad information.

<DataFormatVersion>
A 4-byte unsigned integer that specifies the data format version. The value of this integer is set to 1. This record is signed using the primary server's private key.

<Status>
A 4-byte unsigned integer. This record is signed using the primary server's private key. This integer specifies the status code that indicates if transactions are being sent or if a redump of all handles is needed.

If the date of the specified last transaction ID is later than the date of the last replication request, then the requesting server has missed some transactions. The requesting server needs to request a dump of all handles.

To indicate a redump is needed, the status code integer is set to 1.

To indicate transactions are being sent, the status code integer is set to 2.

<Stream>
A stream composed of all the new transactions that hash to the requesting server. If the handle referred to in the transaction hashes to the requesting server then the transaction is sent to the requestor.

If the handle hashes to the requesting server, the following data is sent to the requestor for each transaction.

	<Transaction Data>	::=	<RecordType>
			<TransactionID>
			<Handle>
			<TransactionAction>
			<TransactionDate>
			<HandleValue>

where:

<RecordType>
A 1-byte unsigned integer that specifies the type of the record being streamed. The value of this integer is set to 1 for handle records.

<TransactionID>
A 8-byte unsigned integer that specifies the Transaction ID.

<Handle>
A 4-byte unsigned integer followed by the bytes that specify the name of the handle. The integer specifies the length of the handle name.

<TransactionAction>
A one-byte unsigned integer that specifies the action being carried out in the transaction. The table below shows the possible integer values. Refer to Section 3.6 for details on the transaction types and the integer value associated with each transaction type.

<TransactionDate>
An 8-byte unsigned integer that specifies the transaction date. The value of the date is the milliseconds since January 1, 1907, 00:00:00 GMT.

<HandleValue>
If the transaction is a handle create or a handle update, the handle values being created or updated need to be sent. A 4-byte unsigned integer followed by a list of handle values. The integer indicates the number of handle values in the list.

<EndTransmissionRecord>
A 1-byte unsigned integer whose value is 0. This byte represents the ending summary record. This byte is sent when the server finishes streaming the handles that hash to the requesting server.

<LastQueryDate>
An 8-byte unsigned integer. This integer is the date the requestor should use for the next RetrieveTxnRequest. This is needed so that in the event that there have been no transactions in a while, the requestor does not have to redump the entire database. This record is signed using the primary server's private key. The date unit is milliseconds. The value of the date is the milliseconds since January 1, 1907, 00:00:00 GMT.

This is the request used to retrieve all handles from a server. This request is used for server<->server (or replicator<->server) communication. The requesting server needs to specify which handles to send (filtered by how the handles are hashed)

The following describes the body of the Dump Handles Request handle protocol message as defined in Section 2 of RFC 3652:

The Message Header of any Dump Handles Request must set its <OpCode> to <OC_DUMP_HANDLES> and its <ResponseCode> to 0.

	<Message Body of Dump Handles Request>	::=	<ReceiverHashType>
			<NumberofServers>
			<ServerNumber>

where:

<ReceiverHashType>
A 1-byte value that identifies how the handles are hashed on the server.

<NumberOfServers>
A 4-byte unsigned integer that specifies the number of servers in the site.

<Server Number>
A 4-byte unsigned integer that specifies which server this is in the site.

This is the response used to send all handles in the database to a replicated site/server. This response is used for server<->server (or replicator<->server) communication. This response is used by the primary server to send all of the handles that hash to the requestor beginning with the transaction ID specified in the Dump Handles Request. The message is signed using the normal handle response signature format as defined in Section 2.2.4 of RFC 3652. The following describes the body of the Dump Handles Response handle protocol message as defined in Section 2 of RFC 3652.

The Message Header of any Dump Handles Response must set its <OpCode> to OC_RETRIEVE_TXN_LOG. A successful Dump Handles Response must set its <ResponseCode> to RC_SUCCESS. This message is streamable.

	<Message Body of Dump Handles Response>	::=	<RequestDigest>
			<DataFormatVersion>
			<Stream>
			<EndTransmissionRecord>
			<LastTxnId>

where:

<RequestDigest>
Optional field as defined in section 2.2.3 of RFC 3652. Including the request digest ensures that the response received is actually in response to the request that was sent. This prevents a malevolent entity from returning a different response (a response previously signed by the server as a valid response to a different request) to the client, and giving the client bad information.

<DataFormatVersion>
A 4-byte unsigned integer that specifies the data format version. The value of this integer is set to 1. This value is signed using the primary server's private key.

<Stream>
A stream composed of the handle values that hash to the requesting server. Each block that is sent is signed using the primary server's private key. Only a handle that hashes to the requesting server is streamed. The value being streamed will either be used to populate the handle database or the naming authority database.

If a handle hashes to the requesting server, the following bytes are streamed:

The data sent to the requestor for each record is defined as follows:

	<Data returned for each database record>	::=	<RecordType>
			<RecordData>

For Handle Records:

<RecordType>
A 1-byte integer that specifies that the record being streamed is a prefix (naming authority) record. The value of this integer is set to 1 for handle records.

<RecordData>
A 4-byte unsigned integer followed by a list of handle values. The integer indicates the number of handle values in the list.

For Prefix (Naming Authority) Records:

<RecordType>
One-byte integer that specifies that the record being streamed is a naming authority record. The value of this integer is set to 2 for prefix records.

<RecordData>
A 4-byte unsigned integer followed by the prefix value. The integer indicates the length of the prefix value.

<EndTransmissionRecord>
One-byte unsigned integer whose value is 0. This byte represents the ending summary record. This byte is sent when the server finishes streaming the handles that hash to the requesting server.

<LastTxnId>
An 8-byte unsigned integer that specifies the date the requestor should use for the next Request Handles Request to the primary server. This is needed so that the server does not have to redump all the handles at each request.

   

      Op_Code | Symbolic Name       | Remark

      --------|---------------------|-------------------------

       1001   | OC_RETRIEVE_TXN_LOG | Retrieve Transaction Log

       1002   | OC_DUMP_HANDLES     | Dump Handles

The Retrieve Transactions Response Message streams transactions to the secondary server. This section provides a little more detail on each of these transactions types.

   

      Transaction Actions       | Integer Value

      --------------------------|--------------

       ACTION_PLACEHOLDER       |       0

       ACTION_CREATE_HANDLE     |       1
       
       ACTION_DELETE_HANDLE     |       2
       
       ACTION_UPDATE_HANDLE     |       3
       
       ACTION_HOME_NA           |       4
       
       ACTION_UNHOME_NA         |       5
       
       ACTION_DELETE_ALL        |       6

ACTION_PLACEHOLDER
A dummy value that doesn't represent any actual transaction.

ACTION_CREATE_HANDLE
Specifies a transaction that creates a handle.

ACTION_DELETE_HANDLE
Specifies a transaction that deletes a handle.

ACTION_UPDATE_HANDLE
Specifies a transaction that updates the value(s) of a handle.

ACTION_HOME_NA
Specifies a transaction that homes a prefix on a handle server.

ACTION_UNHOME_NA
Specifies a transaction that unhomes a prefix from a handle server.

ACTION_DELETE_ALL
Specifies a transaction that deletes all handles from a handle server.

The Dump Handles Request/Response and the ACTION_DELETE_ALL transaction should be used carefully. Setting up secondary servers such that they alert an administrator when a Dump Handles Request or ACTION_DELETE_ALL transaction is received, and requiring administrator confirmation of these actions, are recommended.

(See also Interface Specification Handle System Protocol (ver 2.1) Specification , RFC 3652.)