Skip to main content

Manual replication using Replication Agent

This section explains how to configure manual replication using Replication Agent. Manual replication is intended for customers transitioning from existing FairCom replication using the first generation of the Replication Agent. It allows the latest FairCom replication to use existing configuration files already in place under previous FairCom releases.

Synchronizing data

To commence replication, desired replicated files must be first synchronized between systems. There are multiple methods to achieve this. Simple filesystem copies can be used as well as Hot Backups and restores which directly coordinate starting positions with replication. This section will describe the best options for your specific scenario.

Note

When adding a server to a replicated system it is important to pause log purging on the source server before copying the files. This prevents activity on the source server while the files are being copied, which would cause any transaction logs to be deleted.

You will need to start the Replication Agent reading the source server's transaction log at the position that corresponds to the point in time where you copied the files. To accomplish this, you must ensure the source server keeps the transaction logs from the time you copied the files until you have started the new Replication Agent. Step 1 through Step 3in the Preferred procedures  show exactly how this is none. The Quick guide provides the basic steps.

Quick guide:
  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.ini with entry #current.

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

  6. Release traffic to the source server.

Preferred procedures:

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.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.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.ini file

      If your source server is currently on log 35 at offset 12345678, create ctreplagent.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.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.ini in the Replication Agent's working directory.

  7. Start the Replication Agent.

    Note

    The Replication Agent looks for the ctreplagent.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.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.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 Replication Agent is now connected and is progressing in processing the transaction logs.

Copy files manually when appropriate. As long as the source and target servers are not operational and data and index files are in a clean state they can be copied with any OS utility such as rsync, or compressed into an archived, transferred, and uncompressed on the remote target. When copying in this manner it is assumed that replication will be commenced from a clean starting point. It is important to remove all existing REPLSTATEDT.FCS files from the target.

Alternatively, creating a ctreplagent.ini file with a single #current entry will force replication to commence with the first entry added to existing source transaction logs.

The FairCom DB Dynamic Dump restore process automatically generates a ctreplagent.ini starting file after a successful restore. The position in ctreplagent.ini is in sync with the position at which time the restored files were originally backed up.

  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.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.

Keep the required transaction logs

Once the Replication Agent starts, it will register its log requirements with the source server (if using the default agent configuration, remember_log_pos) and from that point on the source server should maintain enough logs for that Replication Agent to continue from its position when it restarts — for example, if a replica went offline for a day, all the logs from the time it stopped will be kept by the source server.

However, before a particular Replication Agent is first connected to a source server (only the very first time) you need to ensure that the transaction logs from the time of your dynamic dump are maintained until you get the Replication Agents started. You can do this by starting and then stopping each Replication Agent prior to making the dynamic dump. This will establish a minimum log requirement associated with that Replication Agent (reader) unique ID so the source server does not discard any required transaction logs until the Replication Agent has consumed them.

If you have already had these agents running against the source server and are simply changing target servers, then you can ignore this since they will already have established a minimum log requirement.

Ideally, the target file in a replication environment would never be out-of-sync with the source. In some situations, the target server or the Replication Agent goes down or loses its connection. When all parts of the system are up again and the connections are reestablished, the Replication Agent is able to catch up with all the updates that must be applied from the moment that it stopped replicating. Although it may take some time to apply the missing updates from the backlog, it should not miss any. Unfortunately, some problems could happen in this process, making it possible that the replica file might get out of sync.

Problems that may occur causing the replica file to be out of sync:
  • A lost transaction log file from the source side was not applied to the target, making it impossible to bring the target copy back in sync.

  • A conflict while applying the modification to the target (perhaps an inadvertent update to the target while replication was inactive).

The replication resync feature provides a way to stop replication on one or more files in a replicated environment and resynchronize them. It copies current files from the source server to the target server and then restarts the replication of these files.

The administrator can use repadm -c resync and repadm -c resyncclean to manage the resync operation. The new modes allow the user to indicate the name of the source file to be synchronized. A text file with a list of source file names can be provided in case of multiple files to be synchronized. Based on the source file name, the Replication Agent identifies the target file based on the existing redirect rules.

Note

FairCom replication support is backward compatible with replication deployments prior to V12. Legacy replication configurations can continue to be used independently of Replication Manager, which may be desirable in scenarios such as an application using a predefined replication setup.

ctagent plugin

The 2020 release of the FairCom Database Engine introduces plugins, which run applications inside the database process. The ctagent plugin provides the built-in replication feature of each FairCom server. It replaces previous replication components. All original Replication Agent process functionality is now encapsulated into this advanced multi-threaded server-side module.

Replication models

Three models of replication are supported:

Note

All modes are available in V12 FairCom servers and newer as well as the Replication Manager for extended flexibility of your replication needs.

  • Managed

    FairCom Replication Manager is the default FairCom replication support. This model takes advantage of a centrally managed replication database for persisting replication plans containing publications and subscriptions. Details for this method are available in the Replication Manager guide.

  • Manual Replication Manager Remote Mode

    In this model, Replication Manager can be deployed and alternatively used exactly as the prior Replication Agent model for existing environments as they migrate to full Replication Manager support. That is, it can be located on any node in your replication network topology. Using Replication Manager in this mode is a smart transition model to consider. This model does not persist replication plans, publications, and subscriptions in the central database. Replication is configured exactly as before in the external ctreplagent.cfg files. However, you gain the benefit of having new replication support deployed and ready to tackle new replication challenges.

  • Manual Local Mode

    This model enables local direct server replication based on the previous Replication Agent ctreplagent.cfg configuration. This mode is much like prior FairCom replication support, however, without a separate Replication Agent executable required. Replication functionality is provided within servers themselves from the ctagent plugin simplifying deployment and configuration.

Configure ctagent plugin for manual mode

Each FairCom database plugin, including ctagent, is configured with its own configuration file in JSON format for ease of use.

Manual replication mode refers to using existing ctreplagent.cfg configurations, that is, not managed via <FC_PROD_REPLCIATION_MGR>. A simple JSON format configuration in ctagent.json points to existing configuration files for immediate transitioning to this model.

Note

In manual mode, all replication-related operations (definition reads and persistence) are skipped. From a configuration standpoint, in general, all paths are relative to the configured ctagent server’s executing process directory.

Only two configuration elements are required to be defined:
  • "managed": < true | false > 

    The default is true, which is the default Replication Manager usage. false enables manual mode. When false ctagent plugin doesn't connect to a central replication database and executes within the process it is configured.

    Note

    In case of false, or omitted, even if the replication database is not available it keeps trying to reconnect automatically from time to time.

  • "configurationFileList": [ <cfg file1>, <cfg file>, and so forth ]

    The default is an empty array. Each configuration filename element can be a full path or relative to the server working directory. Each element creates one extra instance of a Replication Agent thread to be started from the server ctagent plugin. No central replication database connection is necessary for starting these instances, however, if ctagent is configured within the Replication Manager in this manner, it is also able to start these separated ctreplagent.cfg instances coexisting with managed instances managed from replication definitions for total flexibility.

Example

Given all classic legacy files are located in a replication folder alongside config and server folders consider the following manual ctatgent configuration.

{
	"managed": false,
	"configurationFileList":[
		"../replication/ctreplagent1.cfg",
		"../replication/ctreplagent2.cfg"
	]
}

As with prior replication, authentication files are required in manual mode. In ctreplagent.cfgsource_authfile and target_authfile files should include a path relative to the main server process.

; Source server connection info
source_authfile ../replication/source_auth.set
source_server FAIRCOMS@localhost
; Target server connection info
target_authfile ../replication/target_auth.set
target_server FAIRCOMT@localhost

On success, you should find the following messages logged to CTSTATUS.FCS.

Wed Oct 28 15:49:20 2020
 - User# 00026	ctagentd - Starting Agent
Wed Oct 28 15:49:20 2020
 - User# 00026	ctagentd - Agent is detached from Memphis...
Wed Oct 28 15:49:20 2020
 - User# 00026	ctagentd - Agent plugin is ready

The replication status logctreplagent.log, will be located in the main server folder unless specifically configured by log_file_name option in ctreplagent.cfg. This is essential when more than one replication agent is configured such that each replication log is separately maintained.

Fri Nov 13 09:15:28 2020: INF: ** Starting replication agent logging for process 9616
Fri Nov 13 09:15:28 2020: INF: Using replication change buffer version 2
Fri Nov 13 09:15:30 2020: INF: Connected to data target 'FAIRCOMT@localhost'.
Fri Nov 13 09:15:30 2020: INF: Connected to data source 'FAIRCOMS@localhost'.
Fri Nov 13 09:15:30 2020: INF: Successfully set file filter using XML file '<..\config\replication\filefilter.xml'
Fri Nov 13 09:15:30 2020: INF: Started replication agent.
Fri Nov 13 09:15:30 2020: INF: Starting scan with log 1, position 65536

Replicated file definitions

Replication support previously required specific server configuration entries in ctsrvr.cfg defining exactly what files are eligible for replication and allowed wildcard support for flexibility. However, this required server downtime making it an administrative exception task.

Replicated file definitions can now be added directly to your ctreplagent.cfg file, avoiding downtime on production servers. This allows for easier configuration and ad hoc modifications. An XML-based definition format is used. A file filter definition is used to define replicated files. This can be embedded directly in ctreplagent.cfg, or referenced from an external XML file.

File filter defnition

<?xml version="1.0" encoding="us-ascii"?>
<replfilefilter version="1" update="1" persistent="y">
	<file status="include" regexPath=".\ctreeSQL.dbs">.*((data|dat|db))</file>
	<purpose>create_file</purpose>
	<purpose>read_log</purpose>
</replfilefilter>

Each <file> entry takes the place of a REPLICATE ctsrvr.cfg entry.

Note

The use of expression filters for the file descriptions. Regular expressions allow for detailed and complex file specifications in a single entry.

This XML entry is referenced in your ctreplagent.cfg file with the file_filter configuration option.

 file_filter <../config/replication/filter1.xml

Note

The use of a single < character preceding the filename is intended. Do not include a closing > or you will receive an error.

The <purpose> element defines operations available for this replication usage, including:
  • create_file

  • read_log

  • sync_commit

This section outlines procedures to configure replication between two FairCom servers running on the same machine. The following procedure includes basic steps for setting up Classic Replication Agent from the FairCom DB V12 package (these same procedures apply for both FairCom Edge and FairCom RTG packages).

  1. Extract the FairCom DB V12 package (FairCom-DB.<platform>.v12.<version>.<tar.gz or zip>) on the target machine.

  2. Check the following directory tree:

    FairCom-DB.WinX64.v12.0.0.121 > config > replication
  3. Rename config/ctagent.json to config/ctagent.json.old to cause the original file to be ignored by the server.

    Note

    This can easily be reverted.

  4. Copy config/replication/ctagent.json to config/ctagent.json.

  5. Edit config/ctagent.json to leave only one ctreplagent.cfg in the configurationFileList.

    {
        "managed": false,
        "configurationFileList": [
        "../config/replication/ctreplagent1.cfg"
        ]
    }

    Note

    The ctreplagent.cfg path is relative to the server’s working directory.

  6. Edit config/replication/ctreplagent1.cfg and set both source_server and target_server to reflect the SERVER_NAME from ctsrvr.cfg and the IP address of the machine that the FairCom server is running on.

    ; Target server connection info
    target_authfile ../config/replication/target_auth.set
    target_server FAIRCOM2@127.0.0.1
    ; Source server connection info
    source_authfile ../config/replication/source_auth.set
    source_server FAIRCOM1@127.0.0.1

    Note

    • If using SERVER_PORT instead, the format is <port number>@<network address>. The # indicates that the next part will be a number, instead of a string.

    • If authentication information has changed, you will need to generate new .set files (see ctcmdset - Configuration File Encoding Utility).

  7. Edit the config/replication/filter1.xml file, which is referenced in the following keyword in ctreplagent1.cfgfile_filter <../config/replication/filter1.xml.

  8. Update the replication filter rule for replicating all the data files in the default ctreeSQL database path.

    <?xml version="1.0" encoding="us-ascii"?>
    <replfilefilter version="1" persistent="y">
        <file status="include">.\ctreeSQL.dbs\*.dat</file>
        <purpose>create_file</purpose>
        <purpose>read_log</purpose>
    </replfilefilter>

    Note

    The "include" path is relative to the "data" directory on the source server.

  9. Edit the config/ctsrvr.cfg to enable the ctagent plugin by removing the ; in front of the following keyword.

    PLUGIN ctagent;./agent/ctagent.dll
  10. Start the target server.

    Just after initializing the regular FairCom DB server, the ctagent plugin will be initialized and the embedded Replication Agent configured in the config/ctagent.json file will be started.

  11. Check the following messages in the data/CTSTATUS.FCS log file.

    Wed Nov 11 17:53:12 2020
     - User# 00025	ctagentd - Starting Agent
    Wed Nov 11 17:53:12 2020
     - User# 00025	ctagentd - Agent is not managed by Replication Manager...
    Wed Nov 11 17:53:12 2020
     - User# 00025	ctagentd - Agent plugin is ready
  12. Check the FairCom DB log, which is referenced in the following keyword in ctreplagent.cfglog_file_name ../config/replication/replagent1.log.

    It should present messages saying that it was able to connect to both source and target servers.

    Wed Nov 11 17:53:12 2020: INF: ** Starting replication agent logging for process 21356
    Wed Nov 11 17:53:12 2020: INF: Using replication change buffer version 2
    Wed Nov 11 17:53:12 2020: INF: Connected to data target 'FAIRCOMS2@localhost'.
    Wed Nov 11 17:53:12 2020: INF: Connected to data source 'FAIRCOMS@localhost'.
    Wed Nov 11 17:53:12 2020: INF: Successfully set file filter using XML file '<../config/replication/filter1.xml'
    Wed Nov 11 17:53:12 2020: INF: Started replication agent.
    Wed Nov 11 17:53:12 2020: INF: Starting scan with log 1, position 65536
  13. Using SQL Explorer (or any other means), create a new table in the source server’s default ctreeSQL database.

    Note

    • Replication will cause the same file to be created in the target server’s ./data/ctreeSQL.dbs/ directory.

    • In this test, the database operations of adding the new physical files into the database dictionaries are not replicated. The files will be physically created, but they must be manually added to the dictionary.

File definitions can be specified by an external XML definition. This allows dynamically enabling replication without stopping and starting servers for configuration changes. This file can be set in ctreplagent.cfg and changed at runtime using repadm -c changefilter and -c removefilter with -x option indicating the external filter file name. repadm requests the replication agent to perform the specified filter operation and the replication agent applies the filter to the source server if the purposes indicate that it applies to the source server.

Example 4. XML file filters definition
<?xml version="1.0" encoding="us-ascii"?>
<replfilefilter version="1" update="1" persistent="y">
	<file status="include">mark.dat</file>
	<file status="exclude">donotreplicate*.dat</file>
	<file status="include" regexPath=".\ctreeSQL.dbs">.*((data|dat|db))</file>
	<purpose>create_file</purpose>
	<purpose>open_file</purpose>
	<purpose>read_log</purpose>
	<purpose>sync_commit</purpose>
</replfilefilter>


Attributes

Table 1. Attributes

Attribute

Description

version="1.0"

is the XML format version defining the current specification

persistent="y"

persists the filter definition on the source source such that it is automatically loaded on startup

update="1"

processes an update to the current file filter



Elements

Table 2. Elements

Element

Description

<file>

is a list of files to include or exclude from replication supporting regular expressions

Note

The regexPath tag specifies an optional path as a regular expression and is applied to only the file name without a path.

<purpose>

indicates the purposes of the filter

open_file

applies names to the source server like the server configuration REPLICATE does enabling matching files for replication

read_log

applies to the source server to determine which log entries are returned to the replication log reader like the original replication file filter does

sync_commit

makes a synchronous commit of the specified replicated file

create_file

creates a file on target if it does not exist