Environment requirements

Hardware

A physical or virtual server with:

• 2 core CPU
• 2Gb RAM
• 40G storage

Software

1. FIXICC H2 machine:
   1. RHEL 7 / RHEL 8
   2. OpenJDK 1.8 
   3. (Optional since FIXICC H2 23Q1 release) Consul agent in client mode
2. FIXEdge Cpp/Java machine:
   1. (Optional since FIXICC H2 23Q1 release) Consul agent in client mode
3. On the network:
   1. PostgreSQL Database or HSQL Database (since FIXICC H2 23Q1 release):
      1. 1 user with DDL privileges to run the database migration or run normal FIXICC H2 operation
      2. 1 user without DDL privileges to run normal FIXICC H2 operation
   2. (Optional since FIXICC H2 23Q1 release) Consul cluster - can be deployed on the same machines as FIXEdge Cpp/Java or FIXICC H2
4. Client workstations:
   1. Chrome browser

Pre-configuration

Before you start working with the FIXICC H2, install and configure the FIX Engine and Consul application.

Consul configuration

To find the Consul installation instructions, please follow the link.

For non-production use, you can run the Consul in developer mode with the command: 

consul agent -dev

For production use - please follow the link.

To configure the encrypted connection from FIXICC H2 to the Consul on the Consul side, please follow the link.

FIXICC H2 without Consul

FIXICC H2 configuration

• The fixicch2.consulEnabled property must be set to 'false' in the local.app.properties configuration file.

Example:

###############################################################################
#                                  Other                                      #
###############################################################################
 
cuba.rest.anonymousEnabled=true
cuba.anonymousLogin=anonymous
 
cuba.dbmsType = postgres
cuba.dataSourceProvider = application
cuba.dataSource.username = cuba
cuba.dataSource.password = cuba
cuba.dataSource.dbName = fixicch2
cuba.dataSource.host = localhost
cuba.dataSource.port = 5432
 
fixicch2.fixServerType = all
 
fixicch2.prometheus.host = localhost
 
fixicch2.consulEnabled=false

• The following actions must be performed to connect to FIXEdge Java or FIXEdge C++ and FIXEye-Agent:
  • Run FIXICC H2 and log in.
  • Navigate to the Configuration → Show all servers in the left navigation menu. The Servers page will be opened.
  • Click the Add button. The Server editor page will be opened.

  • Enter Server Name, Type, IP, Admin Port and FIX Port for the Server and IP and Port for FIXEye Agent. Click the OK button.

FIXEdge Java configuration

The following properties must be defined in the fixedge.properties file:

service.discovery.enabled=false
 
server.useFixicch2ConfigManager=true
 
fixicch2.enable=true
 
# Fixicch2 REST API to load fix session and schedules configs and to subscribe on session and schedules changes
fixicch2.url=<fixicc_h2_url>

FIXEdge C++ configuration

The following properties must be defined in the FIXEdge.properties file:

Components.Service.FIXICCH2 = configuration-service
Components.Service.FIXICCH2.Host = <host>
Components.Service.FIXICCH2.Port = 8080
Components.Service.FIXICCH2.ReconnectInterval = <some_interval>
Components.Service.FIXICCH2.HeartBeatIntervalS = <optional, otherwise default 30 seconds: the interval at which FIXICC H2 expects to receive heartbeat messages from FIXEdge C++. Set this value to '0' to disable heartbeats.>
 
Components.Component.Configuration = FIXICCH2

FIXEye Agent configuration

The Consul.Enabled property must be set to 'false' in the fixeye-agent.properties file:

Consul.Enabled = false

FIXICC H2 settings

You should choose a directory on your workstation for FIXICC H2 files.

The FIXICC H2 instance is in the app.jar file. To complete the configuration, please create a local.app.properties file.

You can place the app.jar file for the FIXICC H2 application and local.app.properties (FIXICC H2 properties file) in the same directory, or store them separately.

Before you start your work, please set the database type for data storage.

The FIXICC H2 is compatible with PostgreSQL databases.

Please configure the FIXICC H2 according to the instance of the local.app.properties in your FIXICC H2 package, and set the following properties:

Configuration example:

cuba.dbmsType = postgres
cuba.dataSourceProvider = application
cuba.dataSource.username = C##CUBA
cuba.dataSource.password =cuba
cuba.dataSource.dbName = PTGSDB 
cuba.dataSource.host = 10.68.21.182
cuba.dataSource.port =1521
fixicch2.consul.encrypted_connection =true
fixicch2.consul.port =8501
fixicch2.consul.insecure_connection_enabled =false
fixicch2.fixServerType = FIXEdge CPP
fixicch2.prometheus.port = localhost
fixicch2.prometheus.port = 9090
fixicch2.prometheus.pollInterval = 5
fixicch2.metrics.support.fe = false
fixicch2.metrics.support.fej = true
fixicch2.unknownServer.autoRegistration = true

The following optional properties can also be configurated on the Application Properties page via FIXICC H2:

Logging configuration

To configure the logging level for the FIXICC H2 application, please create the logback.xml file and put it in the directory where the local.app.properties file is stored.

The logback.xml file is not mandatory.

For additional information please refer to the link.

Example:

<?xml version="1.0" encoding="UTF-8"?>

<configuration debug="false" packagingData="true">

    <property name="logDir" value="${app.home}/logs"/>

    <appender name="File" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${logDir}/app.log</file>

        <filter class="ch.qos.logback.classic.filter.ThresholdFilter">
            <level>INFO</level>
        </filter>

        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <!-- daily rollover -->
            <fileNamePattern>${logDir}/app.%d{yyyy-MM-dd}.log</fileNamePattern>
            <!-- keep 30 days' worth of history -->
            <maxHistory>5</maxHistory>
            <cleanHistoryOnStart>true</cleanHistoryOnStart>
        </rollingPolicy>

        <encoder>
            <pattern>%d{yyyy-MM-dd HH:mm:ss.SSS} %-5level [%thread%X{cubaApp}%X{cubaUser}] %logger - %msg%n</pattern>
        </encoder>
    </appender>

    <root>
        <appender-ref ref="File"/>
    </root>
	
    <!-- Begin CUBA -->
    <logger name="com.haulmont.cuba" level="INFO"/>
    <logger name="com.haulmont.cuba.core.sys" level="INFO"/>
    <logger name="com.haulmont.cuba.core.sys.CubaDefaultListableBeanFactory" level="WARN"/>
    <logger name="com.haulmont.cuba.core.app.scheduling" level="INFO"/>
    <logger name="com.haulmont.cuba.web.sys" level="INFO"/>
    <logger name="com.haulmont.cuba.portal" level="INFO"/>
    <logger name="com.haulmont.restapi.sys" level="INFO"/>
    <logger name="com.haulmont.cuba.core.app.LockManager" level="INFO"/>
    <!-- End CUBA -->

    <logger name="eclipselink" level="WARN"/>
    <logger name="eclipselink.sql" level="INFO"/>
    <logger name="org.springframework" level="WARN"/>
    <logger name="com.vaadin" level="WARN"/>
    <logger name="org.atmosphere" level="WARN"/>
    <logger name="org.activiti" level="INFO"/>
    <logger name="org.jgroups" level="INFO"/>
    <logger name="freemarker" level="INFO"/>
    <logger name="org.thymeleaf.TemplateEngine" level="INFO"/>
    <logger name="com.zaxxer.hikari" level="INFO"/>
    <logger name="org.docx4j" level="WARN"/>
	<logger name="org.xlsx4j" level="WARN"/>
    <logger name="org.apache.fop.apps.FOUserAgent" level="WARN"/>
    <logger name="org.hibernate" level="WARN"/>
    <logger name="sun" level="INFO"/>
    <logger name="com.sun" level="INFO"/>
    <logger name="javax" level="INFO"/>
    <logger name="org.apache" level="INFO"/>
    <logger name="org.eclipse.jetty" level="INFO"/>
    <logger name="org.docx4j.utils.ResourceUtils" level="ERROR"/>
    <logger name="org.docx4j.Docx4jProperties" level="ERROR"/>
    <logger name="org.xlsx4j.jaxb.Context" level="ERROR"/>
    <logger name="org.docx4j.utils.XSLTUtils" level="ERROR"/>
    <logger name="org.docx4j.jaxb.JaxbValidationEventHandler" level="ERROR"/>
    <logger name="org.docx4j.TraversalUtil" level="ERROR"/>
    <logger name="org.docx4j.fonts" level="ERROR"/>

    <!-- Begin Perf4J  -->
    <appender name="PerfStatFile" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${logDir}/perfstat.log</file>
        <append>true</append>

        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${logDir}/perfstat.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>5</maxHistory>
            <cleanHistoryOnStart>true</cleanHistoryOnStart>
        </rollingPolicy>

        <encoder>
            <pattern>%msg%n</pattern>
        </encoder>
    </appender>

    <appender name="CoalescingStatistics" class="org.perf4j.logback.AsyncCoalescingStatisticsAppender">
        <param name="TimeSlice" value="60000"/>
        <appender-ref ref="PerfStatFile"/>
    </appender>

    <appender name="UIPerfStatFile" class="ch.qos.logback.core.rolling.RollingFileAppender">
        <file>${logDir}/perfstat-ui.log</file>
        <append>true</append>

        <rollingPolicy class="ch.qos.logback.core.rolling.TimeBasedRollingPolicy">
            <fileNamePattern>${logDir}/perfstat-ui.%d{yyyy-MM-dd}.log</fileNamePattern>
            <maxHistory>5</maxHistory>
            <cleanHistoryOnStart>true</cleanHistoryOnStart>
        </rollingPolicy>

        <encoder>
            <pattern>%msg%n</pattern>
        </encoder>
    </appender>

    <appender name="UICoalescingStatistics" class="org.perf4j.logback.AsyncCoalescingStatisticsAppender">
        <param name="TimeSlice" value="120000"/>
        <appender-ref ref="UIPerfStatFile"/>
    </appender>

    <logger name="org.perf4j.TimingLogger" additivity="false" level="INFO">
        <appender-ref ref="CoalescingStatistics"/>
    </logger>

    <logger name="com.haulmont.cuba.gui.logging.UIPerformanceLogger" additivity="false" level="INFO">
        <appender-ref ref="UICoalescingStatistics"/>
    </logger>
    <!-- End Perf4J  -->

</configuration>

HTTPS support

To run FIXICC H2 with HTTPS support you need to provide it with a key store and trust store in JKS format. For production installations, you need to create JKS from the certificate and private key provided by a trusted certificate authority.

For testing purposes, you can generate a self-signed certificate by yourself.

keytool -genkey                                                                     
    -noprompt                                                                       
    -alias jetty                                                                    
    -keyalg RSA                                                                     
    -dname 'CN=admin, OU=EPM-BFIX, O=EPAM Systems, L=Unknown, S=Unknown, C=Unknown' 
    -keystore keystore.jks                                                          
    -storepass fixicch2                                                             
    -keypass fixicch2

To run FIXICC H2 with HTTPS enabled, you need to provide the following parameters:

For more information please refer to the Jetty Documentation page (keyStorePath , keyStorePassword , keyManagerPassword , trustStorePath , and trustStorePassword properties).

For example, to start FIXICC H2 with the keys generated as above run the following command:

export FIXICC_H2_KEY_STORE_PASSWORD=fixicch2
export FIXICC_H2_KEY_MANAGER_PASSWORD=fixicch2
export FIXICC_H2_TRUST_STORE_PASSWORD=fixicch2
java -Dapp.home=/opt/fixicch2-home              
    -Dfixicch2.secure_http_port=8433            
    -Dfixicch2.key_store_path=keystore.jks      
    -Dfixicch2.trust_store_path=keystore.jks    
    -jar /opt/fixicch2/app.jar

Start application

Start the FIXICC H2 from the command line with the following command:

java -Dapp.home=/opt/fixicch2-home -jar /opt/fixicch2/app.jar

This will start FIXICC H2 on port 8080, you can access it by browsing http://fixicc-h2-machine:8080/app.

Where:

• "/opt/fixicch2-home" is the directory with the local.app.properties file, you should type the full path for the file.
• "/opt/fixicch2/" is the directory with the app.jar file, you should type the full path for the file.

Changing FIXICC H2 port

To run FIXICC H2 on another HTTP port you need to specify the fixicch2.http_port Java system property, e.g. to run FIXICC H2 on port 9090, you should start the FIXICC H2 from the command line with the following command:

java -Dapp.home=/opt/fixicch2-home -Dfixicch2.http_port=9090 -jar /opt/fixicch2/app.jar

FIX Log Viewer Settings

To configure the search in the FIX logs:

1. Deploy FIXEye Agent (version 2.3.0 or higher) by following instruction.

How to Configure and Use LDAP for FIXICC H2

Please refer to the LDAP Github page for more information.

Precondition: Configure your directory server before enabling the LDAP FIXICC H2 add-on.

1. Configure LDAP plugin and Connection in FIXICC H2 configuration file local.app.properties

1. Fill in the following mandatory parameters (values are samples and must be replaced):
   
   

   ldap.contextSourceUrl=ldap://adhost-or-ip:389
   ldap.contextSourceUserName=cn=ldapuser,cn=Users,dc=fixicch2,dc=local
   ldap.contextSourceBase=cn=Users,dc=fixicch2,dc=local
   ldap.contextSourcePassword=password
   ldap.addonEnabled=true

   To correctly specify the contextSourceUserName parameter, you need to use the user's Distinguished Name (DN). The DN typically includes the cn (common name) or uid (user ID), along with the domain components (dc).

   The easiest way to find the exact value is to use the ADSI Edit tool:

   • Open ADSI Edit
   • connect to your directory
   • navigate to the user object
   • right-click the user object and click Properties
   • In the opened pop-up window in the Attribute Editor tab find the distinguishedName parameter
   • Use in config file value of distinguishedName parameter

   

2. Save changes and start/restart FIXICC H2 application

 Check yourself

1. If the plugin is enabled in local.app.properties then in FIXICC H2 UI in the left navigation panel under the Administration section you should see the LDAP navigation tree:
   
   
   
   
2. If ldap Url, UserName, Base, and Password parameters are correct then you should be able to pass successfully connection test under: Administration->LDAP Config->Test Connection button:

2. Configure attributes that will be used for matching rules

1. In FIXICC H2 UI navigate to the Administration->LDAP->LDAP Config
2. In the Schema Settings section click the Create button, add the name of attribute, and click the OK button.
   

   E.g., add the “memberOf” parameter:

   

3. A new attribute will be added to the table, if required add additional attributes and then click the OK button:
   
   
   
   
4. Alternatively, provide correct values corresponding to LDAP configuration in AD (see "How to define the correct Schema Base" section below) to the Schema Settings fields and use Refresh LDAP Attributes button to receive all attributes at once:
   
   

3. Configure LDAP Matching Rules

1. In FIXICC H2 UI navigate to the Administration->LDAP->LDAP Matching Rules
2. Click the Create Matchin Rule button and select Create Simple Rule
3. Fill in the Description field – it will be the name of the rule, e.g., Admins
4. Under the Conditions section click the Create button, select the attribute (list of attributes will contain values defined in step 2.), enter a valid value, and click the OK button.
   

   E.g., for the memberOf parameter, we can use the name of securityGroup:
   
   

5. For Access Group select Company
6. In the Roles section click the Add button and select the appropriate role (e.g., in our case for admins we need to add a system-full-access role)
7. Click the OK button, then click the Apply button at the bottom of the Matching Rules tab, to confirm saving changes.

Check yourself

1. If the Matching Rule was correctly configured and changes saved then it should be visible under Administration->LDAP->LDAP Matching Rules in the top section table when re-open this tab or re-login to the application:
   
   
   
   
2. If all required matching rules are created, you can test them right from the LDAP Matching Rule tab (Administration->LDAP->LDAP Matching Rules). For this purpose, enter a user login in the User Login field and click the Test Rules button.
   After that, the applied matching rules, access groups, and roles are displayed in the corresponding fields and tables. This functionality is useful when you need to check the accuracy of a rule application.
   
   
   
   
3. If all rules and permissions are correctly set, then the user should be able to log in to the FIXICC H2 UI and have a specified level of permissions.
   
   
   
   

4. Disable local user login

1. Update local.app.properties file and cuba.web.standardAuthenticationUsers property as follows (leave empty value):
   
   

   cuba.web.standardAuthenticationUsers=

2. Start/Restart FIXICC H2 application

Check yourself

If the property was correctly set then when trying to log in with non-LDAP local user error will be shown (only LDAP users will be able to log in):

How to define the correct Schema Base

To determine the correct value for the Schema Base in an existing Active Directory (AD), you can follow these steps:

1) Using ADSI Edit

1. Open ADSI Edit:
• Press Win + R, type ADSIEdit.msc, and press Enter.
2. Connect to Schema:
• In the left pane, right-click on ADSI Edit and select Connect to.
• In the Connection Settings window, under "Select a well known Naming Context," choose Schema and click OK.
3. Locate Schema Base:
• In the left pane, expand the schema for your domain controller.
• Right-click on CN=Schema,CN=Configuration,DC=yourdomain,DC=com and select Properties.
• The distinguished name (DN) you see here is your Schema Base[1].

2) Using Command Prompt

1. Open Command Prompt:
• Press Win + R, type cmd, and press Enter.
2. Run DSQuery Command:

• Enter the following command:

  sh dsquery * "cn=schema,cn=configuration,dc=yourdomain,dc=com" -scope base -attr objectVersion

• This command will return the schema version and confirm the Schema Base DN.

3) Using PowerShell

1. Open PowerShell:
• Search for PowerShell in the Start menu and open it.
2. Run Get-ItemProperty Command:

• Enter the following command:

  powershell Get-ItemProperty 'AD:\\CN=Schema,CN=Configuration,DC=yourdomain,DC=com' -Name objectVersion

• This command retrieves the schema version and confirms the Schema Base DN.

LDAP Properties

The following properties are available in the local.app.properties file: