Replication agent

1. Stop the source server and target servers.

2. Copy the files.

3. Block all traffic to the source server at the system or network level.

   Note

   Any source activity at this point may break the point-in-time relationship between the copied files and the transaction logs, leading to inconsistent data between the source and target. Preferred procedures prevent this vulnerability.

4. Generate a ctreplagent_<agentid>.ini with entry #current.

5. Start the source server, the target server, and the Replication Agent.

6. Release traffic to the source server.

The steps below explain the general approach to adding a server to a replicated system and starting it at the correct point in time.

1. When you are ready to make a copy of the files from the source server, first run ctstat ‑var on the source server.

   Example 1. Run ctstat ‑var

   # ctstat -var -h 1 -u ADMIN -p ADMIN -s source
   
   name                               lowlog  curlog       curpos
   source(SERVER)                          6       9      9237667 

   
   
   

2. Observe and take note of the server's current log number (curlog) and log position (curpos).

   In the Example 1, “Run ctstat ‑var” log 9 is the current log used by the server. It is recommended to set the minimum log to the previous log (in this case log 8).

3. Use the ctrepd utility with the ‑setlog and ‑unqid options to instruct the source server to keep the current log and later logs based on the log number determined in Step 2.

   Example 2. ctrepd utility

   If your new Replication Agent will use the ID MYREPLAGENTID and you want to set the minimum transaction log to 8, and the source server is named source, use this command.

   This will cause the source server to keep log 8 and later logs until your new Replication Agent has been started and has processed that log's operations.

   # ctrepd -unqid:MYREPLAGENTID -setlog:8 -s source
   
   name                               lowlog  curlog       curpos
   source(SERVER)                          6       9      9237667
   -MYREPLAGENTID                          8       0            0 

   
   
   

4. Create a point-in-time copy of the files from the source server using either of the following options:

   • Dynamic Dump

     Use dynamic dump to make a copy of the files from the source server, and then restore them on the target server using the ctrdmp utility. The utility creates the file ctreplagent_<agentid>.ini containing the log number and log position for your new Replication Agent to use. This approach has the advantage that the source server is paused only for a brief time while it reaches a quiet transaction state. The server can then resume normal operations while the files are copied to the dynamic dump backup file.

   • Quiesce & Copy

     Use the ctQUIET() function (for example through the ctadmn utility) to pause the source server and close the files. Run ctstat ‑var on the source server and note the server's current log number and log position after you have paused the source server. Make a copy of the files using a system copy command, then resume server operation. In the Replication Agent's working directory, create ctreplagent_<agentid>.ini as a text file containing the following two lines:

     log_number log_offset
     log_number log_offset 

     Example 3. Two lines in the ctreplagent_<agentid>.ini file

     If your source server is currently on log 35 at offset 12345678, create ctreplagent_<agentid>.ini containing the following two lines.

     35 12345678
     35 12345678

     
     
     

5. Copy the files created in Step 4 from the source server to the target server.

   Note

   If you used Dynamic Dump in Step 4, copy the ctreplagent_<agentid>.ini file from the dump restore area to the Replication Agent's working directory.

6. If you used Quiesce & Copy in step Step 4 , create ctreplagent_<agentid>.ini in the Replication Agent's working directory.

7. Start the Replication Agent.

   Note

   The Replication Agent looks for the ctreplagent_<agentid>.ini file in its working directory when it starts up. If it exists, it sets its position to the position specified in the file. It then deletes the ctreplagent_<agentid>.ini file so it does not use that position again the next time it starts. If you used Dynamic Dump in Step 4, the Replication Agent will find the correct starting point in the ctreplagent_<agentid>.ini created by the dynamic dump restore that you copied to the Replication Agent’s working directory.

8. Using ctstat ‑var on the source server, observe that the Replication Agent is now connected and is progressing in processing the transaction logs.

1. Create a Dynamic Dump script to back up files for replication.

2. Stop the secondary server and the Replication Agent if already running.

3. Execute the Dynamic Dump at the desired point in time on the primary server.

   Tip

   Use the !DATE and !TIME options to automatically schedule your dump.

4. Using the same dynamic dump script used to back up the files, restore the files on the secondary server with the ctrdmp utility.

   Tip

   Consider the !REDIRECT option for positioning files if different directory structures are different between the servers.

5. Copy the ctreplagent_<agentid>.ini file into the Replication Agent's working directory.

6. Restart the secondary server with the data now in sync with the primary server.

7. Restart the Replication Agent.

   Replication then commences from the log position on the primary server when the files were initially backed up, replicating changes since the backup and quickly synchronizing the secondary server with the primary.

1. Enable replication by inserting the following lines into the ctsrvr.cfg file:

   ; Plugins
   PLUGIN cthttpd;./web/cthttpd.dll
   PLUGIN ctagent;./agent/ctAgent.dll

   These lines enable the plugin that handles web communication (services.json) and the agent that performs the replication (ctagent).

2. Use the ctagent.json and services.json files to configure the replication plugin:

   ctagent.json

   {
   	"embedded": true,
   	"log_file": "agentLog.txt",
   	"memphis_server_name": "MEMPHIS",
   	"memphis_sql_port": 7000,
   	"memphis_host": "localhost",
   	"memphis_database": "MEMPHIS",
   	"ctree_check_mask": "*.dat;*.idx;*.fdd;*.fsd",
   	"inactive_timeout": 600
   }

   services.json

   {
   	"listening_http_port": 8080,
   	"listening_https_port": 8443,
   	"ssl_certificate": "./web/fccert.pem",
   	"document_root": "./web/apps",
   	
   	"applications": [
   		"ctree;ctREST.dll",
   		"AceMonitor;ctMonitor.dll",
   		"SQLExplorer;ctSQLExplorer.dll",
   		"ISAMExplorer;ctISAMExplorer.dll",
   		"ReplicationManager;ctReplicationManager.dll"
   	]
   }

3. Optionally enable diagnostic logging by adding the following lines to ctreplagent.cfg:

   diagnostics logship
   diagnostics logread

   The replication agent supports optional diagnostic logging for its log ship and log read threads. When diagnostic logging is enabled, these threads write messages to ctreplagent.log to indicate the offset that the log ship thread has written to the copy of the log files, and the log read thread is reading. The offset=[a,b,c] values in the log read message are (a) the requested log read offset, (b) the last byte actually read, and (c) the last requested byte to read. (b) and (c) are equal if the full amount was read (that is, bytesread is equal to size). We expect these log read offset values to always be less than the log ship's current write log position. These example messages show an expected situation: the last byte read by the log read thread is 0x789ab, which is equal to the last byte written by the log ship thread as shown in the "write to log copy position" message.