/
How to configure FIX Sessions with engine.properties file

How to configure FIX Sessions with engine.properties file

Owned by AntonA (Unlicensed)
Last updated: Feb 11, 2022

Overview

FIX sessions can be preconfigured via FIX Antenna properties file - engine.properties. Parameters defined in engine.properties will be used during the session creation process. 

To configure a session parameter just add the following line into the engine.properties file:

Session.<SessionName>.<Parameter> = <value>

<SessionName> - SessionCompID and TargetCompID separated by '/' symbol or "Default"

<Parameter>  - Configurable session parameter

<Value>  - desired session parameter value

Configure Defaults for All Sessions

In order to configure the default parameter value for all sessions, use Default as SessionName. See the example below for details.

engine.properties
Session.Default.UseBlockingSockets = true
Session.Default.DisableTCPBuffer = true
Session.Default.StorageType = persistentMM
Session.Default.Validation.IsEnabled = false

Configure Specific Session

In order to configure parameters for some specific session, use its SenderCompID/TargetCompID pair as SessionName. See the example below for details. 

engine.properties
Session.CLIENT1/EXECUTOR.UseBlockingSockets = true
Session.CLIENT1/EXECUTOR.DisableTCPBuffer = true
Session.CLIENT1/EXECUTOR.StorageType = persistentMM
Session.CLIENT1/EXECUTOR.Validation.IsEnabled = false

Prioritizing Rules

The engine uses properties for creating a session in the following order (If the property is not defined in the current step, then the value from the next step is used):

  1. Properties configured in the C++ code as Engine::SessionExtraParameters value before the session creation
  2. Session specific settings defined as properties with Session.SenderCompID/TargetCompID pair in the engine.properties
  3. Default session settings defined as Session.Default properties in the engine.properties
  4. Hardcoded FIX Antenna Engine defaults

List of Available Parameters

The full list can be found here:

Session Parameters

Property

Description

Valid valuesDefaults

CpuAffinity

Specifies affinity mask for dedicated threads of the session. It makes sense only for aggressive modes.

Mask should be presented in the decimal system.0

RecvCpuAffinity

Specifies affinity mask for dedicated receiving thread of session. It makes sense only for an aggressive receive mode.

Mask should be presented in the decimal system.0

SendCpuAffinity

Specifies affinity mask for dedicated sending thread of session. It makes sense only for an aggressive send mode.

Mask should be presented in the decimal system.0

Create pre-configured sessions from a properties file

FIX Antenna 2.25.1. introduces a mechanism that allows passing a session configuration through a file.

The scenario below describes the case when the application gets all configured sessions from the properties file and iterates over the sessions list and creates them.

With this scenario, all initiator sessions connect immediately to the counterparty.

FIX Antenna C++ code example

application.cpp 
/* FixAntenna initialization here */
//....
Engine::Application MyAppAcceptor;
Engine::Application MyAppIntiator;
//....
std::vector<Session*> sessionsVector;
FAProperties::ConfiguredSessionsMap sessions = FixEngine::singleton()->getProperties()->getConfiguredSessions();
for(FAProperties::ConfiguredSessionsMap::const_iterator it = sessions.begin(); it != sessions.end(): ++it)
{
    Session *pSsn;
    if(it->second.sessionRole_ == Engine::INITIATOR_SESSION_ROLE)
        pSsn = FixEngine::singleton()->createSession( &MyAppIntiator, it->first, NA, &it->second );
    else
        pSsn = FixEngine::singleton()->createSession( &MyAppAcceptor, it->first, NA, &it->second );
    pSsn->connect();
    sessionsVector.push_back(pSsn);
}
//....
for(std::vector<Session*>.const_iterator it = sessionsVector.begin(); it != sessionsVector.end(); ++it)
{
    it->release();
}
/* FixAntenna de-initialization here */

FIX Antenna .NET code example

application.cs 
/* FixAntenna initialization here */
// ....
List<Session> activeSessions;
Dictionary<SessionId, SessionExtraParameters> sessions = FixEngine.Instance.getConfiguredSessions(SessionRole.NA);
foreach (KeyValuePair<SessionId, SessionExtraParameters> session in sessions)
{
    Session ses = FixEngine.Instance.CreateSession(session.Key, FixVersion.NA, session.Value);
    ses.Connect();
	activeSessions.add(ses);
}
//....
foreach (Session session in activeSessions)
{
	sessions.Dispose();
}

/* FixAntenna de-initialization here */

Creating initiator and acceptor

engine.properties
######### CLIENT1/SRV1 session #########
Session.CLIENT1/SRV1.ParserVersion = FIX44
Session.CLIENT1/SRV1.Role = Initiator
Session.CLIENT1/SRV1.Host = 127.0.0.1
Session.CLIENT1/SRV1.Port = 9090
Session.CLIENT1/SRV1.HBI = 30
#Other required session properties if any


######### ESVR/CTG session #########
Session.ESVR/CTG.ParserVersion = FIX44
Session.ESVR/CTG.Role = Acceptor
#Other required session properties if any

Pass Custom Logon Message to initiator from properties file.

engine.properties
######### CLIENT1/SRV1 session #########
Session.CLIENT1/SRV1.ParserVersion = FIX44
Session.CLIENT1/SRV1.Role = Initiator
Session.CLIENT1/SRV1.Host = 127.0.0.1
Session.CLIENT1/SRV1.Port = 9090
Session.CLIENT1/SRV1.HBI = 30
Session.CLIENT1/SRV1.CustomLogonMessageFileName = Logon.msg

An example of Logon message (35=A): Logon.msg

Create SSL sessions with properties file

FIX Antenna 2.26.0. has updated SSL support, extending the variety of formats accepted and password protected certificates/keys support.

FIX Antenna support certificates in PEM, PFX and DER formats along with private keys in PEM and DER formats.

Password protected certificates/keys can be used as well. The password is specified within plain text in engine.properties.

The cases below demonstrate how to configure Initiator/acceptor sessions in order to make them SSL enabled.

SSL related properties are demonstrated only assuming that session is generally configured already.

Creating initiator and acceptor:

engine.properties
######### Engine wide properties #########
# Used for all acceptor sessions and as default values for Initiator sessions. if ListenSSLPort is specified and optional otherwise.
# Mandatory. Set protocols accepted by the engine.
SSLProtocols = TLSv1_2
# Optional. Engine default values used if omitted.
SSLCiphersList = AES+aRSA:AES+aECDH:AES+aECDSA:@STRENGTH
# mandatory. Certificate file to use.
SSLCertificate = mycert.pem
# Optional. Applicable if only certificates is password protected.
SSLCertificatePassword = mycertPassword
# Optionality is correlated with SSLCertificate.
# It means if no SSLCertificate  specified then this property becomes seamless. It becomes optional if private key is already contained inside SSLCertificate file.
# This is possible for PEM and PFX formats but not for DER!
SSLPrivateKey = mycertKey.pem
# Optional if private key is not password protected. Please pay attention to the fact the this password is used for private key stored within certificate file as well.
# So it has meaning even if SSLPrivateKey is empty in this case.
SSLPrivateKeyPassword = mycertKeyPassword
# Optional if no peer certificate validation is required. This is a path to the file containing CA certificates (all in one file on after another, PEM format only!).
# This certificates are used to build accepted certificates list sent to peer as well.
SSLCACertificate = CACerts.pem
# Optional. false by default. Setting this property to true requires SSL engine to validate counter-party's certificate against CAs provided. 
# If validation has failed or no certificate was provided by counter-party connection is terminated immediately.
# Set this to true in order to accept only connection verified with certificate.
SSLValidatePeerCertificate = true

######### CLIENT1/SRV1 Initiator session #########
# Enable SSL support for the session
Session.CLIENT1/SRV1.SSL = true
# Optional. Overrides engine wide SSLProtocols property for the session
Session.CLIENT1/SRV1.SSLProtocols = TLSv1_2
# Optional. Overrides engine wide SSLCiphersList property for the session
Session.CLIENT1/SRV1.SSLCiphersList = AES+aRSA:AES+aECDH:AES+aECDSA:@STRENGTH
# Optional for initiators. Certificate file to use if certificate based authentication is requested by peer.
Session.CLIENT1/SRV1.SSLCertificate = mycert.pem
# Optional. Applicable if only certificates is password protected.
Session.CLIENT1/SRV1.SSLCertificatePassword = mycertPassword
# Optionality is correlated with SSLCertificate.
# It means if no SSLCertificate  specified then this property becomes seamless. It becomes optional if private key is already contained inside SSLCertificate file.
# This is possible for PEM and PFX formats but not for DER!
Session.CLIENT1/SRV1.SSLPrivateKey = mycertKey.pem
# Optional if private key is not password protected. Please pay attention to the fact the this password is used for private key stored within certificate file as well.
# So it has meaning even if SSLPrivateKey is empty in this case.
Session.CLIENT1/SRV1.SSLPrivateKeyPassword = mycertKeyPassword
# Optional if no peer certificate validation is required. This is a path to the file containing CA certificates (all in one file on after another, PEM format only!).
Session.CLIENT1/SRV1.SSLCACertificate = CACerts.pem
# Optional. false by default. Setting this property to true requires SSL engine to validate counter-party's certificate against CAs provided. If validation has failed connection is terminated immediately.
# Set this to true in order to validate acceptors certificate.
Session.CLIENT1/SRV1.ValidatePeerCertificate = true


######### ESVR/CTG Acceptor session #########
# Restricts the session to accept connections from SSL listener only.
Session.ESVR/CTG.SSL = true
# All remaining properties are engine wide for the acceptors and can't be specified on per-session basis.
# So they are configured with engine wide properties.


Configure FIX sessions with dedicated ports 

Accept sessions on a dedicated port 

The feature is introduced in FIX Antenna 2.28.0.

FIX Antenna C++ provides few ways to define listening ports for incoming FIX sessions:

  • by configuring a port per single session
  • by configuring a port per multiple sessions
  • by defining a single not secure port via API
  • by defining multiple listening ports via API (both SSL and non-SSL)

FIX Antenna-based products allows you to allocate a separate port for each acceptor session. Such a configuration enhances the usability and security of the solution.

The port can be shared between multiple sessions. However, the connection type should be the same, see more information in the "Limitations..." section.

When the last session bound to a particular port is terminated or not useful anymore, for example, according to the schedule, the Engine stops listening to connections on the given port. 

engine.properties
#defaults
Session.Default.StorageType = persistentMM
Session.Default.Validation.IsEnabled = false
Session.Default.ReconnectMaxTries = -1
Session.Default.ReconnectInterval = 60000

# acceptor #1
Session.FIXServer/Client42.Role = Acceptor
Session.FIXServer/Client42.ParserVersion = FIX42
Session.FIXServer/Client42.ReconnectInterval = 30000
Session.FIXServer/Client42.ListenPort = 9001
Session.FIXServer/Client42.ListenAddress = 127.0.0.1

# acceptor #2
Session.FIXServer/Client44.Role = Acceptor
Session.FIXServer/Client44.ParserVersion = FIX44
Session.FIXServer/Client44.ReconnectInterval = 30000
Session.FIXServer/Client44.ListenPort = 9002
Session.FIXServer/Client44.ListenAddress = 127.0.0.1

Similar configuration in QuickFIX:

acceptor.cfg
[DEFAULT]
FileStorePath=store
FileLogPath=log
ConnectionType=acceptor
SenderCompID=FIXServer

[SESSION]
BeginString=FIX.4.2
TargetCompID=Client42
ReconnectInterval=30
HeartBtInt=30
SocketAcceptPort=9001
SocketAcceptHost=127.0.0.1
DataDictionary=..\spec\fix\FIX42.xml

[SESSION]
BeginString=FIX.4.4
TargetCompID=Client44
ReconnectInterval=30
HeartBtInt=30
SocketAcceptPort=9002
SocketAcceptHost=127.0.0.1
DataDictionary=..\spec\fix\FIX44.xml

The TCP socket option SO_REUSEADDR is always enabled for listening ports.

Limitations across parameters and combinations

Sessions parameters have priority over session default parameters and global parameters.

If unregistered sessions are allowed, they will be accepted on listening ports of global level only.

Same SSL context across multiple sessions

  1. The same listening SSL port (i.e. SSL context) cannot be shared between two and more sessions if their SSL parameters are not the same.
  2. Secure and non-secure connections can't share the same port.

In case of the SSL context for multiple sessions is different or if a secure and insecure session are configured for using the same port, then the corresponding error will be logged. The session under conflict will not be created.


Example

engine.properties 
# SSL acceptor #1
Session.FIXServer/TLS12_Client42.Role = Acceptor
Session.FIXServer/TLS12_Client42.ParserVersion = FIX42
Session.FIXServer/TLS12_Client42.ListenPort = 9001
Session.FIXServer/TLS12_Client42.ListenAddress = 127.0.0.1
Session.FIXServer/TLS12_Client42.SSLValidatePeerCertificate = true
Session.FIXServer/TLS12_Client42.SSLCertificate = cert.pem
Session.FIXServer/TLS12_Client42.SSLPrivateKey = cert.pem
Session.FIXServer/TLS12_Client42.SSLCACertificate = certCA.pem
Session.FIXServer/TLS12_Client42.SSLProtocols = TLSv1_2

# SSL acceptor #2
Session.FIXServer/TLS12_Client44.Role = Acceptor
Session.FIXServer/TLS12_Client44.ParserVersion = FIX44
Session.FIXServer/TLS12_Client44.ListenPort = 9001
Session.FIXServer/TLS12_Client44.ListenAddress = 127.0.0.1
Session.FIXServer/TLS12_Client44.SSLValidatePeerCertificate = true
Session.FIXServer/TLS12_Client44.SSLCertificate = cert.pem
Session.FIXServer/TLS12_Client44.SSLPrivateKey = cert.pem
Session.FIXServer/TLS12_Client44.SSLCACertificate = certCA.pem
Session.FIXServer/TLS12_Client44.SSLProtocols = TLSv1_2

# SSL acceptor #3 with different TLS version => must use a different port.
Session.FIXServer/TLS10_Client44.Role = Acceptor
Session.FIXServer/TLS10_Client44.ParserVersion = FIX44
Session.FIXServer/TLS10_Client44.ReconnectInterval = 30000
Session.FIXServer/TLS10_Client44.ListenPort = 9002
Session.FIXServer/TLS10_Client44.ListenAddress = 127.0.0.1
Session.FIXServer/TLS10_Client44.SSLValidatePeerCertificate = true
Session.FIXServer/TLS10_Client44.SSLCertificate = cert2.pem
Session.FIXServer/TLS10_Client44.SSLPrivateKey = cert2.pem
Session.FIXServer/TLS10_Client44.SSLProtocols = TLSv1_0

# Non secure acceptor #4 => must use a different port.
Session.FIXServer/NonSecure_Client44.Role = Acceptor
Session.FIXServer/NonSecure_Client44.ParserVersion = FIX44
Session.FIXServer/NonSecure_Client44.ReconnectInterval = 30000
Session.FIXServer/NonSecure_Client44.ListenPort = 9003
Session.FIXServer/NonSecure_Client44.ListenAddress = 127.0.0.1
Session.FIXServer/NonSecure_Client44.SSLValidatePeerCertificate = true
Session.FIXServer/NonSecure_Client44.SSLCertificate = cert2.pem
Session.FIXServer/NonSecure_Client44.SSLPrivateKey = cert2.pem
Session.FIXServer/NonSecure_Client44.SSLProtocols = TLSv1_0

If the session connects to the listening port and SenderCompID does not match TargetCompID, the session will not be accepted and the corresponding error will be logged:

Session.FIXServer/NonSecure_Client44.ListenPort = 9003

Interaction with the stopListeningIncomingConnections function

The API call Engine::FixEngine::stopListeningIncomingConnections() stops listening and closes all the ports (global and sessions ones).

Configuring ListenPort session parameters via FIXICC

FIXICC 2.11.2 does not support the following session parameters configuration yet:

  • ListenPort
  • ListenAddress

Configure Administrative sessions with dedicated ports

The feature is available since FIX Antenna 2.29.0.

The administrative session has a configurable listen port as a FIX session.

FIX Antenna C++ provides a few ways to configure listening ports for administrative FIX sessions.

To configure listen port per single administrative FIX session:

  • Enable monitoring feature Monitoring.Enable in the engine.properties file.
  • Configure Monitoring.ListenAddress and Monitoring.ListenPort parameters exclusively for an administrative FIX session.
  • Specify administrative FIX session in engine.properties file.

To configure listen port per multiple sessions (administrative FIX session and another FIX session):

  • Enable monitoring feature Monitoring.Enable in the engine.properties file.
  • Configure Monitoring.ListenAddress and Monitoring.ListenPort parameters non-exclusively for an administrative FIX session.
  • Share Monitoring.ListenPort parameter with other FIX sessions.
  • Specify administrative FIX session in engine.properties file.

For multiple administrative sessions, specify all required sessions in session Monitoring.AdminSessionNames list with own sets of parameters.

If the parameters do not exist or are empty, the global engine's parameters Listen Address and Listen Port are used the same way as for ordinary FIX sessions.

Monitoring.ListenPort does not support a secure connection. 

To enable SSL for administrative sessions, the port number must be also added to ListenSSLPort.

More examples 

Parameters priority

The session parameters have priority over default session parameters.

If the listening port is defined for a default session, it will be used for the sessions, if the listening port for a specific session is not defined. If the listening port is not defined for a specific session and for a default session, the session will be listened to on the global ports.

engine.properties
# The session parameters has the highest priority
Session.FIXServer/TLS12_Client42.ListenPort = 9001
Session.FIXServer/TLS12_Client42.ListenAddress = 127.0.0.1

# defines defaults if session's parameters are not set
Session.Default.ListenPort = 9105
Session.Default.ListenAddress = 0.0.0.0

# defines default Engine level parameters if session's parameters are not set
ListenPort = 9105
ListenAddress = 0.0.0.0

Session.Default.ListenPort and Session.Default.ListenAddress parameters are used for an acceptor session, if ListenPort and ListenAddress parameters for a session level are not set.

Dedicated session

engine.properties
# defines local endpoint for Acceptor session that will be created on demand.
# Incoming connections from other endpoints will be filtered out
Session.<SenderId>/<TargetId>.ListenPort = 9105
Session.<SenderId>/<TargetId>.ListenAddress = 0.0.0.0

Disabled listening

To disable listening to incoming connections, a user should comment or remove a value for all ListenPort parameters. 

engine.properties
Session.<SenderId>/<TargetId>.ListenPort = 
ListenPort = 
ListenSSLPort =
Monitoring.ListenPort =

Setting listening ports via API 

To configure a listening address for a session use the field: Engine::SessionExtraParameters::listenAddress_

To configure listening ports for a session use the field: Engine::SessionExtraParameters::listenPort_.

To set an SSL port or several non-secure listening ports for a session via API, you need to use listenEndpoints (the list of structures where ListenAddress and listenSocketEndpoint parameters are defined). The listenSocketEndpoint parameter defines the listening port and sslCtx which sets parameters of the listening port (whether this port supports SSL or not).

By using API, any combination of listening ports for acceptor sessions can be defined.