Skip to main content

Quick tutorial for replication agent

Quickly install, configure, and test your replication installation

This tutorial shows how to start a sample replication environment with a FairCom unmanaged replication agent. A replication agent is unmanaged when it is not controlled by FairCom Replication Manager but acts as a server thread dealing with the source server data. When not using the FairCom Replication Manager the configuration is up to the end user. 

For this tutorial both servers are running on the same machine. In a production environment the servers would normally run on different machines. 

The unmanaged replication agent uses a special mode called Replication Agent Manager, which is implemented to improve its thread management. The Replication Agent Manager has slight differences in the way files are resynced and deployed to the target server.

  1. Install a primary server environment. This is the<faircom>\server directory of your installed FairCom bundle.

  2. Create a secondary server environment. Create a<faircom>\secondary directory and copy the following folders and their contents from the primary<faircom>directory into the <faircom>\secondary directory you just created.

    • config

    • data

    • server

    • tranlog

  3. Configure the primary server by adding the following keyword to the primary server<faircom>\config\ctsrvr.cfg\server file:

    REPL_NODEID 10.0.0.1

    Note

    This is not the IP address of the running machine. it is just an ID that the connecting replication agents will use to uniquely identify the server. Leave it unchanged for the sake of this tutorial.

  4. Start the primary server.

  5. Configure the secondary server. Copy the following files from the<faircom>\drivers\ctree.c.replication\tutorials\config\secondary directory to the<faircom>\secondary\config\ directory.

    ctagent.json
ctreplagent.cfg
ctsrvr.cfg
deploy.cfg
deployfilefilter.xml
deployresyncfilelist.txt
filefilter.xml
resyncfilelist.txt

    Note

    The differences between the primary and secondary ctsrvr.cfg files are:

    • A different SERVER_NAME and SQL_PORT to avoid network conflicts as the servers are running on the same machine.

    • The REPL_NODEID is different from the one assigned to the primary server.

    • PLUGIN ctagent;./agent/ctagent.dll is used in the secondary server instead of PLUGIN cthttpd;./web/cthttpd.dll which is in the primary server, so the HTTPD plugin will not be loaded with the secondary server. This prevents port conflicts that would occur because the servers are running on the same machine.

      Important

      Linux/UNIX users must edit the <faircom>/secondary/config/ctsrvr.cfg file. Change

      PLUGIN            ctagent;./agent/ctagent.dll

      to

      PLUGIN          ctagent;./agent/libctagent.so

  6. Start the secondary server.

  7. Create directories named subdir1 and subdir2 under the primary server's LOCAL_DIRECTORY (<faircom>\data).

  8. Create directories named subdir1 and subdir2 under the secondary server's LOCAL_DIRECTORY (<faircom>\secondary\data).

    Note

    Run the following commands from a command prompt.

  9. Configure your replication environment:

    tools\repadm.exe -c addagent ..\config\ctreplagent.cfg -s FAIRCOMT -u admin -p ADMIN

  10. Start your replication agent:

    tools\repadm.exe -c startagent agent1 -s FAIRCOMT -u admin -p ADMIN

  11. Make sure the agent is active:

    tools\repadm.exe -c isactive -a agent1 -i 1 1 -s FAIRCOMT -u admin -p ADMIN

    You will see “y” if it is active or “n” otherwise.

  12. Create the test files on the primary server (replace user name, password, and server name with your settings):

    ctmtap fc mT mr aa hsubdir1\mark uADMIN pADMIN sFAIRCOMS@localhost
ctmtap fc mT mr aa hsubdir2\mark uADMIN pADMIN sFAIRCOMS@localhost

  13. As the replication agent filters are configured to replicate data creation, check the hsubdir1 and hsubdir2 directories of the secondary server. You should see the replica of the files that you created in the primary server.

  14. Run some activity on the files:

    ctmtap aa hsubdir1\mark n100000 t4 uADMIN pADMIN sFAIRCOMS

  15. While ctmtap is running, in another shell use repadm to check the replication activity:

    repadm -c getstate -a agent1 -u admin -p ADMIN -s FAIRCOMT

At this point, the replication is up and running.

Replication agent advanced operations

This section shows how to perform operations with the replication agent by running repadm commands from a command prompt.

  • Reconfigure the agent without stopping the server. This operation shows how a user can change the configuration of the replication agent without stopping the target server.

    Use repadm to stop the agent.

    repadm -c shutdown -a agent1 -u admin -p ADMIN -s FAIRCOMT

    Change the following line in the target server ctreplagent.cfg file from:

    redirect C:\faircomdb\primary\server\data C:\faircomdb\secondary\server\data

    to:

    redirect <faircom>\server\data <faircom>\secondary\data

    <faircom>is the ABSOLUTE path that contains your servers.

    For example:

    redirect C:\FairCom\db\FairCom-DB.windows.64bit.v13.0.2.32\data C:\FairCom\db\FairCom-DB.windows.64bit.v13.0.2.32\secondary\data

    Restart the server using repadm.

    repadm -c startagent agent1 -u admin -p ADMIN -s FAIRCOMT

  • Redeploy/resync a list of files. This command takes advantage of the resync feature which deploys the files from the source server to the target server.

    The steps of the initial tutorial copied all the required files to complete this command. This command can only be run on servers using the replication agent manager. If the replication agent manager is not used, the resync command can be used instead.

    Important

    You must first correctly complete the “Reconfigure the agent without stopping the server” operation.

    Run the repadm deployfilegroups action.

    repadm -c deployfilegroups agent1 ..\config\deploy.cfg -u admin -p ADMIN -s FAIRCOMT

  • Pause the agent activity.

    repadm -c pause -a agent1 -u admin -p ADMIN -s FAIRCOMT

    This command pauses the activity of the replication agent. The agent stops reading the source server transaction logs and applying the changes to the target server files.

  • Check the replication agent activity.

    repadm -c getstate -i 1 10 -a agent1 -u admin -p ADMIN -s FAIRCOMT

    This command shows the activity of the internal agent threads and their progress on the transaction logs. In this specific case, the command shows the status for 10 seconds, one per second.

  • Check the replication agent exception log

    repadm -c getlog -a agent1 -u admin -p ADMIN -s FAIRCOMT

    This command queries the replication agent exception logs. It is useful because the presence of exceptions in the log may cause the replication activity to stop until they are cleared.

  • Get the count of exceptions in the replication agent exception log:

    repadm -c getexceptionlogcount -a agent1 -u admin -p ADMIN -s FAIRCOMT

    Similar to the previous command this command shows the count of the exceptions listed in the replication agent exception log. This command shows the count once and exists.

  • Purge the transaction log:

    repadm -c purgelog -a agent1 -u admin -p ADMIN -s FAIRCOMT

    This command clears the agent transaction log. It may be useful to resume the replication activity after a blocking error. It is usually a good idea to resync or redeploy the files after clearing the logs because the files might be out of sync after a blocking error.

  • Check if the replication agent is working in synchronous mode:

    repadm -c getsyncmode -a agent1 -u admin -p ADMIN -s FAIRCOMT -i 1 1

    This command checks whether the replication agent is using the synchronous mode.

  • See the repadm documentation for more repadm utility commands.

Make your replication installation and configuration work properly

replicationinstallationconfigurationreplication agent