This article describes ways to upgrade to a new version of FIXEdge.

The difference between FIXEdge Installation and upgrade is that upgrading keeps the working configuration unchanged, but uses a new version of binaries with the new features and fixes.

Preparation

1. Make sure you have sufficient administration permissions for further uninstall/install procedures.
2. Download a new FIX Edge package for the corresponding OS version;
3. Make a backup copy of your current installation (configuration and binaries);
4. Make a copy of your current license (engine.license).
   If your license has expired or was lost, contact sales@btobits.com to obtain a new one;
5. If you need to save data queued by Managed Queue then backup all the files from FixLayer.<managed_queue_name>.Storage.SQLite.FileName parameters in FIXEdge.properties

How to replace your current FIXEdge version with a new one

This section shows how to upgrade the existing FIXEdge version and keep all configuration files unchanged.

Upgrade Process

1. Make sure that there is a backup copy of the working installation.
2. Stop the FIXEdge service process
3. Stop the FIXICC-agent service process
4. Uninstall the FIXEdge service(s)
5. Uninstall the FIXICC Agent service(s)

6. Upgrade FIXEdge binaries
   Copy and overwrite all files in FIXEdge's <FIXEdge installation>/bin/ directory with new binaries from the FIXEdge package
   

   If scripts in bin/ directory (*.sh or *.cmd) were modified earlier then they should be recovered from the backup 

7. Adjust FIXEdge configuration parameters if needed. 
   Make sure that your configuration files correspond to the most recent changes/improvements in the new product versions
   

   1. Visit the FIXEdge Release Notes page and look through the changes made from the current FIXEdge version to target the FIXEdge version.
      1. If the most recent product changes require an update of your current FIXEdge's and FIXICC's config files, adjust them to satisfy the new requirements;
      2. If the most recent product changes don't affect your current FIXEdge's and FIXICC's config files, you may leave them as they are;
      3. If you have any doubts, please contact SupportFIXAntenna@epam.com;

   It is critically important to update all absolute paths in the configuration.

   We recommend using relative paths for simplifying the upgrade steps.

   Before version 5.11, FIXEdge's instance directory had the name <FixEdge1>. As of version 5.11, FIXEdge's instance directory name is <FIXEdge1>.

8. Upgrade FIXICC
   Remove the <FIXEdge installation>/fixicc-agent/ and <FIXEdge installation>/fixicc/ directories
   Copy all files in FIXEdge's <FIXEdge installation>/fixicc-agent/ directory with new binaries from the FIXEdge package
   Copy all files in FIXEdge's <FIXEdge installation>/fixicc/ directory with new binaries from the FIXEdge package

9. If there were changes in fixicc-agent and fixicc configuration then replace the new configuration with the configuration from the backup

   The default Windows path for fixicc-agent configuration is: fixicc-agent\FIXEdge1.fixicc-agent\conf\

   The default Linux path for fixicc-agent configuration is: fixicc-agent/conf

   i.e. the following configuration should be re-used from the old FIXEdge version

   • fixicc/etc/fixengine.properties
   • fixicc/etc/fixicc/log4j.properties
   • fixicc-agent/conf/fixengine.properties
   • fixicc-agent/conf/agent.properties
   • fixicc-agent/conf/log4j.properties
   • fixicc-agent/conf/OrderAckTCPMonitor.properties 
   • fixicc-agent/conf/security.properties
10. Upgrade Transport Adaptors and Handlers if you use them:
    1. Visit FIXEdge Release Notes page;
    2. Look through the changes made with Transport Adaptors and Handlers from the current FIXEdge version to target the FIXEdge version:
       1. If any improvements/bugfixes were done in the JMS Adaptor, then:
          1. Replace all jar files for the JMS adapter with new jar files from the FIXEdge package in FIXEdge's FIXEdge1\conf\jms-ta-distribution\lib directory;
          2. Replace all jar files for the JMS adapter with new jar files from the FIXEdge package in FIXEdge's FIXEdge1\conf\jms-ta-distribution\tool\lib directory;
       2. If any improvements/bugfixes were done in the RabbitMQ Adaptor, then:
          1. Replace all jar files for the RMQ adapter with new jar files from the FIXEdge package in FIXEdge's FIXEdge1\conf\amqp-ta-distribution\lib directory;
       3. if using the Kafka Transport Adapter serializer plugins make sure that the adapter is already updated in the bin directory (see step #6) then update the Kafka plugins in the plugins/ directory:
          For example:
          Windows: plugins/b2b_fixserver_kafka_test_serializer.dll
          Linux: plugins/libb2b_fixserver_kafka_test_serializer.so
       4. If any improvements/bugfixes were done in other Transport Adaptors or Handlers, then:
          1. Replace corresponding binaries with new ones from the package with SupAdapters in FIXEdge's <bin> directory;

       If you have several instances of one Transport Adaptor, (meaning that there are several copies of one TA library), you need to upgrade all of them.

    "Replace" in this context means that files should be deleted from the current FE directory and new files from the package should be added there. This clarification is made in order to avoid the situation when two (or more) of the same libraries with different versions appear in the directory as it may cause issues.

11. If using the Managed Queue, update managed queue plugin in <FIXEdge installation>/plugins/ directory:
    Windows: b2b_fixserver_plugin_queue_observer.dll
    Linux: libb2b_fixserver_plugin_queue_observer.so
12. If using the Managed Queue, (i.e. FixLayer.ManagedQueue.Sessions parameter is configured) recover the queue files that were done in step #5 in the Preparation section.
    If data from the queue is not needed then you can skip this step. A new file will be created automatically after restarting the FIXEdge instance if it is missing.
13. Copy your FIXEdge license into the license file path;
14. Install the FIXEdge service(s);
15. Install the FIXICC-agent service(s);
16. Start the FIXICC-agent process;
17. Start the FIXEdge process.

How to upgrade FIXEdge and keep the current version running

This section shows how to set up a new copy of FIXEdge that would be an upgraded version of the current FIXEdge.

In this case, all required configuration is transferred and the working version is not stopped so the upgrade can be smooth to the users.

Upgrade Process

1. Make sure that there is a backup copy of the working installation.
2. Unpack the archive with the new FIXEdge version to a new directory.
3. Replace all files in the FIXEdge1\conf directory of the new FIXEdge instance with the working ones from the current (old) FIXEdge version.
   Make sure that the working configuration remains unchanged.

4. Make adjustments to FIXEdge configuration parameters if needed. 
   If FIXEdge uses absolute paths, they should be updated with the new paths.
   

   It is critically important to update all absolute paths in the configuration.

   We recommend using relative paths to simplify the upgrade steps.

   Before version 5.11, FIXEdge's instance directory had the name <FixEdge1>. As of version 5.11, FIXEdge's instance directory name is <FIXEdge1>.

5. FIXICC configuration parameters adjustment
   

   Skip this step if there are no changes in fixicc and fixicc-agent configuration.

   If you're unsure then follow the steps below.

   1. FIXICC changes in the new installation directory
      1. Replace fixicc/etc/fixengine.properties with a file from the working (old) FIXEdge version
         
      2. Replace fixicc/etc/fixicc/log4j.properties with a file from the working (old) FIXEdge version

   2. FIXICC-agent changes

      The default Windows path for fixicc-agent configuration is: fixicc-agent\FIXEdge1.fixicc-agent\conf\

      The default Linux path for fixicc-agent configuration is: fixicc-agent/conf

      1. Replace fixicc-agent/conf/fixengine.properties with a file from the working (old) FIXEdge version
         
      2. Replace fixicc-agent/conf/agent.properties with a file from the working (old) FIXEdge version
      3. Replace fixicc-agent/conf/log4j.properties with a file from the working (old) FIXEdge version
      4. Replace fixicc-agent/conf/OrderAckTCPMonitor.properties with a file from the working (old) FIXEdge version
      5. Replace fixicc-agent/conf/security.properties with a file from the working (old) FIXEdge version
         
         

6. If you use Transport Adaptors or Handlers, you need to make sure that they are configured properly:
   

   If you have several instances of one Transport Adapter in your current configuration, please follow the How to configure several instances of one adapter instructions to set it up in a new configuration.

   1. For the JMS Adaptor, RabbitMQ Adaptor, SMTP Adaptor, FMXML Handler, BLLanguageExtension Handler - all corresponding libraries are already in the FIXEdge1\bin directory of the new FIXEdge instance, so nothing is required;

   2. If you use any other Transport Adaptors or Handlers, you need to put corresponding libraries to the FIXEdge1\bin directory of the new FIXEdge instance - see the installation guides for the relevant adaptor/handler for details;

   3. The CME STP Adapter is provided separately as a part of the Supplementary Adapters and Handlers package (SupAdapters-FE-*)
      The new version of the package should be downloaded and binaries should be replaced.
      

      Using the old version of the adapter's library may lead to application failures

7. If you use Failover Cluster, please follow Failover Cluster instructions to configure it for the new FIXEdge instance;
8. Make sure that your configuration files correspond to the most recent changes/improvements in the new product versions:
   1. Visit the FIXEdge Release Notes page;

   2. Look through the changes made from the current FIXEdge version to target the FIXEdge version:

      1. If the most recent product changes require an update of your current FIXEdge's and FIXICC's config files, adjust them to satisfy the new requirements;
      2. If the most recent product changes don't affect your current FIXEdge's and FIXICC's config files, you may leave them as they are;
      3. In case of doubts, please contact SupportFIXAntenna@epam.com;
9. If using the Managed Queue, (i.e. FixLayer.ManagedQueue.Sessions parameter is configured) recover the queue files that were done in step #5 in the Preparation section
   If data from the queue is not needed, you can skip this step. A new file will be created automatically after restarting the FIXEdge instance if it is missing
10. Copy your FIXEdge license into the license file path;
11. The new FIXEdge is now installed as a separate one; however, it still requires additional steps for using it in parallel with the old version.  

Additional steps for running two FIXEdges in parallel

The main goal behind this process is to distinguish two FIXEdges and avoid configuration conflicts such as mutual ports.

1. Perform configuration steps from instructions on How to install two instances of FIXEdge on one host
2. Make sure that all services from the new FIXEdges are installed

3. Run FIXICC and adjust the servers list

   Sometimes it's required to remove all content of FIXICC's working dir <.fixicc>  except the servers.xml file.

   Working dir is normally placed in the C:\Users\%USER%\AppData\Roaming directory;

Upgrade verification

Run FIXEdge and check the version in the version.log

2016-09-20 10:46:19,459 UTC   INFO    [CC_Layer]  5552  FIXEdge Version X.Y.Z (rxyz) started

How to revert the upgrade procedure

If you need to revert changes in order to use your original FIXEdge version (from before the upgrade), you need to do the following steps:

1. Stop the FIXEdge process;
2. Stop the FIXICC-agent process;
3. Uninstall the FIXEdge service(s);
4. Uninstall the FIXICC Agent service(s);
   
5. Remove all content of FIXICC's working dir <.fixicc>  except servers.xml file. Working dir is normally placed in C:\Users\%USER%\AppData\Roaming directory;
   
6. Restore your backup copy with original FIXEdge version;
7. Install the FIXEdge service(s) of the restored original FIXEdge version;
8. Install the FIXICC-agent service(s) of the restored original FIXEdge version;
9. Start the FIXICC-agent process of the restored original FIXEdge version;
10. Start the FIXEdge process of the restored original FIXEdge version.

Troubleshooting

FIXEdge started to fail after the Upgrade

If FIXEdge started to crash after the upgrade and some adapters or handlers are used in the configuration, most likely step #4 in the Upgrade process wasn't done properly

Please check that all adapters and handlers (e.g. CME STP Adapter) have the same revision as FIXEdge in versions.log

2019-08-05 19:46:17,886 UTC   INFO    [Version]  22036  TransportLayer' version 0.1.1.5(r31)
2019-08-05 19:46:17,886 UTC   INFO    [Version]  22036  FIXEdge version 6.7.0 (r31)
2019-08-05 19:46:18,317 UTC   INFO    [Version]  22036  FIXMLConverter version 0.0.2.19(r31)
2019-08-05 19:46:18,390 UTC   INFO    [Version]  22036  BusinessLayer version 0.0.20.00(r31)
2019-08-05 19:46:18,392 UTC   INFO    [Version]  22036  Engine Adaptor version 0.0.1.17(r31)
2019-08-05 19:46:18,402 UTC   INFO    [Version]  22036  The B2BITS FIX Engine 2.25.1 (r51)
2019-08-05 19:46:19,279 UTC   INFO    [Version]  22036  FIX Engine AdminProtocol version 3.0
2019-08-05 19:46:22,398 UTC   INFO    [Version]  22036  FixEngine version 0.0.2.2(r31)
2019-08-05 19:46:22,399 UTC   INFO    [Version]  22036  FixLayer version 0.2.1.5(r31)
2019-08-05 19:46:22,411 UTC   INFO    [Version]  22036  STP Transport Adaptor version 0.1 (r31)

Solution:

Upgrade transport adapters and handlers to the same version as FIXEdge