How to upgrade a replication server environment from v11.5 to v13 (RTG v5)

Upgrading your FairCom replication server environment from version 11.5 (RTG v2.5) to version 13 (RTG v5) requires four high-level steps:

1. Shutdown Existing Version
2. Install New Version
3. Configure New Version
4. Start New Version

Shutdown Existing Version

To ensure a safe and consistent upgrade, follow these steps to shut down your current environment:

1. Have all clients cleanly exit.
2. Perform a normal controlled shutdown of the primary server as described in point 2 of the FairCom upgrade guide:
   1. Use the server console, Windows toolbar, Windows Service, or command-line utilities (ctadmn or ctstop) to shut down the server.
3. Block the ability of any clients to attach to the primary server.
   1. Change the primary server name/port in ctsrvr.cfg so that clients attempting to connect to the known server name/port will fail.
4. Restart the primary server with no clients attached and allow a successful automatic recovery to take place.
5. Shutdown the replication agent ctreplagent with the following command:
   1. repadm -c shutdown -s FAIRAGENT
6. Change replication agent configuration ctreplagent.cfg to reflect the primary server name/port change.
7. Restart the replication agent ctreplagent.
8. Monitor the progress of replication with the following command:
   1. repadm -c getstate -s FAIRAGENT
   2. Check the logpos values and wait for 3 or 4 consecutive entries (at least more than 2) where the log position didn't change, indicating that pending transactions have been replicated.
   3. Example output:

      1. [fctech@test replication]$ ./repadm -c getstate -s FAIRAGENT
         c-treeACE(tm) Version 11.5.1.51923(Build-180302) Replication Agent Management Utility
         Copyright (C) 1992 - 2018 FairCom Corporation
         ALL RIGHTS RESERVED.
         s t   lognum     logpos   state    seqno time func
         y y        1     482689  source     2638    0 ctReplGetNextChange
         y y        1     494266  source     2713    0 ctReplGetNextChange
         y y        1     499230  source     2750    0 ctReplGetNextChange
         y y        1     499230  source     2754    0 ctReplGetNextChange
         y y        1     499230  source     2755    0 ctReplGetNextChange
         y y        1     499230  source     2756    0 ctReplGetNextChange

9. Shutdown the primary server again.
10. Shutdown the replication agent ctreplagent again:
    1. repadm -c shutdown -s FAIRAGENT
11. Change the primary server name/port in ctsrvr.cfg back to the original name/port.
12. Change replication agent configuration ctreplagent.cfg to reflect the primary server name/port change.
13. Perform a normal controlled shutdown of the replica server as described in point 2 of the FairCom upgrade guide.

Install New Version

Once all servers are stopped, proceed as follows:

1. Remove all existing transaction logs and associated files (L*.FCS, S*.FCS, D*.FCS, I*.FCS, and *.FCT) as described in point 6 of the FairCom upgrade guide. Do not remove FAIRCOM.FCS unless specifically instructed.
2. Install the new server binaries to both primary and replica locations as described in point 7 of the FairCom upgrade guide:
   1. Copy your new FairCom server directory into the existing one. Protect your ctsrvr.cfg and ctsrvr.set files to preserve custom settings. Additionally, move the existing configuration files ctsrvr.cfg and ctsrvr.set from the server/ directory to the config/ directory.

Configure New Version

After installing the new binaries, configure the environment as follows:

1. Ensure both the primary and replica ctsrvr.cfg files include a REPL_NODEID entry each set to a unique ID in an IPv4 address format (e.g., xxx.xxx.xxx.xxx):

   1. ; source server configuration
      REPL_NODEID 10.0.0.1

   2. ; target server configuration
      REPL_NODEID 10.0.0.2

2. Ensure the replica ctsrvr.cfg contains:
   1. PLUGIN cthttpd;./web/libcthttpd.so
3. Ensure services.json (in the replica config/ directory) has the ctagent service enabled:

   1. {
          "serviceName": "ctagent",
          "serviceLibrary": "./agent/libctagent.so",
          "enabled": true
      },

4. Ensure ctagent.json (in the replica config/ directory) looks exactly as follows:

   1. {
          "managed": false,
          "configurationFileList": [
              "../config/ctreplagent.cfg"
          ]
      }

5. Copy ctreplagent.cfg, target_auth.set, and source_auth.set from your previous installation to the replica config/ directory.
6. Ensure ctreplagent.cfg (in the replica config/ directory) sets source_nodeid and target_nodeid to the unique IDs defined in step 1:

   1. source_nodeid 10.0.0.1
      target_nodeid 10.0.0.2

7. Ensure ctreplagent.cfg (in the replica config/ directory) assigns a unique name to the unique_id for each replica server in your replication environment:
   1. unique_id REPLAGENT
8. Ensure target_auth.set and source_auth.set referenced in ctreplagent.cfg (in the replica config/ directory) are prepended with ../config/: 

   1. target_authfile ../config/target_auth.set
      source_authfile ../config/source_auth.set

9. Optionally add log_file_name and log_level to ctreplagent.cfg (in the replica config/ directory):

   1. log_file_name ctreplagent.log
      log_level info

Start New Version

You are now ready to start the upgraded environment:

1. Start the primary server and the replica server.

For further details and troubleshooting, refer to the official FairCom documentation:   Steps to upgrade FairCom server