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.
Install a primary server environment. This is the
<faircom>\server
directory of your installed FairCom bundle.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
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.
Start the primary server.
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 ofPLUGIN 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. ChangePLUGIN ctagent;./agent/ctagent.dll
to
PLUGIN ctagent;./agent/libctagent.so
Start the secondary server.
Create directories named
subdir1
andsubdir2
under the primary server's LOCAL_DIRECTORY (<faircom>\data
).Create directories named
subdir1
andsubdir2
under the secondary server's LOCAL_DIRECTORY (<faircom>\secondary\data
).Note
Run the following commands from a command prompt.
Configure your replication environment:
tools\repadm.exe -c addagent ..\config\ctreplagent.cfg -s FAIRCOMT -u admin -p ADMIN
Start your replication agent:
tools\repadm.exe -c startagent agent1 -s FAIRCOMT -u admin -p ADMIN
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.
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
As the replication agent filters are configured to replicate data creation, check the
hsubdir1
andhsubdir2
directories of the secondary server. You should see the replica of the files that you created in the primary server.Run some activity on the files:
ctmtap aa hsubdir1\mark n100000 t4 uADMIN pADMIN sFAIRCOMS
While
ctmtap
is running, in another shell userepadm
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.