Skip to main content

Configure ports and services

Configure protocols, ports, and services

This section defines how to configure the services of a FairCom server. It shows how to configure services with specific protocols and ports.

The FairCom default configuration matches common industry settings for the protocols, ports, and services it offers. All additional services are also configured at startup using the services.json file (previously called cthttpd.json). The services.json file is located in the <faircom>\config folder.

You may want to change ports:
  • To avoid colliding with a port used by an existing application.

  • To avoid a port blocked by a firewall.

  • To run multiple instances of the FairCom server on the same computer.

Ports, Protocols, and Services can be configured in the services.json file

portsprotocolsservicesconfigurationsettingsservices.json

This section outlines the properties included in services.json.

Table 1. "result" property summaries

Property

Description

Default

Type

Limits (inclusive)

apiRoot

specifies the root URI for FairCom's jsonAction APIs

"./api"

Note

There is rarely a reason to change this.

string

apis

describes and controls FairCom's jsonAction APIs

[]

array of objects

applicationRoot

specifies the folder relative to <faircom>/server/ where FairCom's web applications are located on disk

"./web/apps/"

Note

There is rarely a reason to change this.

string

applications

contains specifications for the web applications that can run with the FairCom server

[]

array of objects

applications
.enabled

(optional) enables or disables a web application

false

Boolean

true
false
applications
.folderName

specifies the folder name where web application code is stored

Required - No default value

string

1 to 64 bytes

applications
.serviceLibrary

(optional) specifies the name of a dynamically loaded library that provides an API and background jobs for the application.

""

string

1 to 64 bytes

applications
.serviceName

(optional) specifies a friendly name for the web application. The FairCom server ignores this property

""

string

1 to 64 bytes

applications
.uriPath

(optional) specifies the folder that contains the serviceLibrary file.

""

string

1 to 64 bytes

authenticationMethods

specifies the allowed MQTT authentication methods

["none",
"password",
"clientCertificate"]

array of objects

["none",
"password",
"clientCertificate"]

codeServices

specifies which programming languages are available in the product

[]

array of objects

"serviceName"
"serviceLibrary"
"enabled"
codeServices
.enabled

specifies whether or not the "codeServices" property is enabled

true

Boolean

true
false
codeServices
.serviceLibrary

specifies the filename (on disk) of the app server's dynamic library

""

string

codeServices
.serviceName

specifies the name of the code service that provides the programming language runtime environment

"javascript"

string

defaultDatabaseName

defines the default value of the "databaseName" property

FairCom DB defaults to "ctreeSQL"
FairCom Edge defaults to "faircom"
FairCom MQ defaults to "faircom"

string

1 to 64 bytes

defaultOwnerName

specifies the initial value of the "defaultOwnerName" property used by JSON APIs and FairCom's web application

"admin"

string

1 to 64 bytes

integrationServices

describes and controls FairCom's integration services

{}

array of objects

listeners

describes and controls FairCom's listeners

{}

array of objects

listeners
.tls

(optional) specifies the filenames of the public server certificate, private key, and certificate authority. It also specifies allowed cipher suites and client certificate requirements

{}

object

listeners
.tls
.allowedCipherSuites

(optional) specifies the ciphers that the server will accept for communications with clients

""

string

listeners
.tls
.caCertificateFilename

(optional) specifies the name and optional path of the CA certificate file

""

string

listeners
.tls
.clientCertificateFilename

(optional) specifies the name of the client certificate file

""

string

listeners
.tls
.clientPrivateKeyFilename

(optional) specifies the name of the client private key file

""

string

listeners
.tls
.requireClientCertificate

(optional) specifies whether the client certificate is required

false

Boolean

true
false

maxConnectionsPerIpAddress

specifies the number of TCP/IP connections the app server will accept from a single TCP/IP address

25

integer

maxJsonApiSessions

specifies the total number of JSON API sessions the app server will accept

The max number of JSON API connections allowed by the license

integer

maxJsonApiSessionsPerIpAddress

specifies the number of JSON API sessions the app server will accept from the same client IP address

50

integer

maxJsonApiSessionsPerUsername

specifies the number of JSON API sessions the app server will accept with the same username

50

integer

mqtt

(optional) groups the MQTT default values together

{}

object

mqtt
.authenticationMethods

(optional) determines which authentication techniques are accepted by the MQTT broker

[ "none", "password", "clientCertificate" ]

array

"none"
"password"
"clientCertificate"
mqtt
.defaultDowngradeQoS

(optional) determines the value of the "downgradeQoS" property in "configureTopic"

false

Boolean

true
false
mqtt
.defaultMaxDeliveryRatePerSecond

(optional) determines the default value of the "maxDeliveryRatePerSecond" property in "configureTopic"

0

integer

mqtt
.defaultMaxInflightMessages

(optional) determines the value of the "maxInflightMessages" property in "configureTopic"

20

integer

mqtt
.defaultMessageCommitFrequencyForQoS1

(optional) specifies the default frequency for messages to be committed for QoS 1

1000

integer

mqtt
.defaultMillisecondCommitFrequencyForQoS1

(optional) specifies the default frequency in milliseconds to commit the delivery status for QoS 1

1000

integer

mqtt
.defaultOptimizeForQoS2

(optional) determines the default value for the "optimizeForQoS2" property

false

Boolean

true
false
mqtt
.disableThroughputStats

(optional) determines whether or not the MQTT broker will track the average number of inbound and outbound messages per second

false

Boolean

true
false
mqtt
.enforceQos2DuringRecovery

(optional) guarantees the MQTT broker will not publish a QoS 2 message a second time after a broker recovers from an unexpected downtime

true

Boolean

true
false
mqtt
.eventuallyPersistDeliveryInfo

(optional) when false, causes the server to persist the delivery status of each message to disk to allow for mission-critical QoS 2 messages even in the event of unplanned downtime

false

Boolean

true
false
mqtt
.historyRetentionPeriod

(optional) specifies how long the server stores records that contain MQTT history

30

integer

mqtt
.historyRetentionUnit

(optional) specifies how often the server purges records containing MQTT history

"day"

string

"minute"
"hour"
"day"
"week"
"month"
"year"
"forever"
mqtt
.messageCommitFrequencyForQoS1

(optional) specifies the maximum number of messages the MQTT broker will send before it commits the delivery status to disk

1

integer

mqtt
.millisecondCommitFrequencyforQoS1

(optional) specifies the maximum number of milliseconds the MQTT broker will wait before it commits the delivery status to disk

1

integer

mqtt
.optimizeForQoS2

(optional) ensures the specified topic either delivers maximum performance for QoS 1 messages when set to false or fully supports mission-critical QoS 2 messages when set to true

false

Boolean

true
false
mqtt
.ownerName

(optional) specifies the name of the account that owns the tables created by the MQTT broker

"admin"

string

mqtt
.pollingFrequencyMilliseconds

(optional) specifies the frequency in seconds for all incoming requests over MQTT, HTTP, HTTPS, WS and WSS to be polled

1

integer

mqtt
.statsCollectionFrequencySeconds

(optional) specifies the frequency in seconds for the MQTT broker to collect statistics in the mqtt_stats table

12

integer

mqtt
.statsPublishFrequencySeconds

(optional) specifies the frequency in seconds for the MQTT broker to publish MQTT messages containing statistics about connections, subscribers, and topics

30

integer

mqtt
.statsRetentionPeriod

(optional) specifies how long the server stores records that contain MQTT statistics

14

integer

mqtt
.statsRetentionUnit

(optional) specifies how often the server purges records containing MQTT statistics in the mqtt_stats table

"day"

string

"minute"
"hour"
"day"
"week"
"month"
"year"
"forever"

otherServices

 an optional array of objects that describes and controls FairCom's other services.

The services connected when the server last started up.

array of objects

transformServices

an optional array of objects that describes and controls FairCom's transform services.

The services connected when the server last started up.

array of objects



The "apis" property is an array of objects that describes and controls FairCom's jsonAction APIs. It defaults to an empty object.

Each API is a service provided by the FairCom server.

Do not change the settings of the object properties unless you disable an unused API.

The "applicationRoot" property is a string that specifies the location of web applications relative to <faircom>/server/ .

The default value of "./web/apps/" translates to the folder <faircom>/server/web/apps.

There is rarely a reason to change the "applicationRoot".

For information on how to add your own web applications, which can use any of FairCom's jsonAction APIs, contact FairCom.

The "applications" property is an array of objects that describes and controls web applications that can run with the FairCom server. It defaults to an empty array which means no applications are configured to run.

FairCom and other custom web applications are single-page, browser-based applications served from folders in the default <faircom>/server/web/apps/ folder.

An app server is a backend service used by one or more web applications. It listens to HTTP and/or WebSocket requests and then returns results.

Contact FairCom for information on how to build and add your own app servers using C or C++.

The following "applications" properties should be considered for each web app:

The "folderName" property specifies the folder within the "applicationRoot" folder that contains the code the FairCom web server delivers to the browser. This folder contains all code-related files such as HTML, CSS, JavaScript files, and so forth.

Only when the "enabled" property in the same object is true will the FairCom web server deliver the folder's code to the web browser, as shown in the following example for FairCom's ACE Monitor application.

{
  "serviceName": "Ace Monitor",
  "folderName": "AceMonitor",
  "serviceLibrary": "ctmonitor.dll",
  "enabled": true
},

In this example, the web application will be stored in the <faircom>/server/web/apps/AceMonitor/ folder.

Tip

Set the "enabled" property to false for each application you want to disable. In addition, the FairCom web server will not deliver any application if the "applications" property is missing or all application objects set "enabled" to false.

Warning

You may change the "enabled" setting to false or true for the FairCom built-in web applications but do not change the other settings.

FairCom MQ and FairCom Edge let you enforce secure MQTT communications with the broker by letting you control how MQTT clients authenticate.

Use the "authenticationMethods" property in the services.json configuration file to control MQTT authentication.

"mqtt": {
  "authenticationMethods": ["none", "password", "clientCertificate"]
  }

Define the allowed MQTT authentication methods by including any combination of "none", "password", and "clientCertificate" in the "authenticationMethods" property. 

Examples

To allow MQTT clients to connect with or without authentication, include "none", "password", and "clientCertificate" in the list. This is the default setting in services.json.

To require MQTT clients to connect only with certificate authentication, include only "clientCertificate" in the list.

To require MQTT clients to connect only with a username and password authentication, include only "password" in the list.

To require MQTT clients to connect with a client certificate or a password, include "clientCertificate", and "password" in the list.

Best Security Practice

Remove "none" from the list to prevent non-authenticated clients from connecting.

The "serviceName" property is a case insensitive, optional property that defaults to "javascript".  It specifies the name of the code service that provides the programming language runtime environment.

The "serviceName"  property maps to a section in the services.json file called "codeServices" that defines which programming languages are available in the product.

"codeServices": [
  {
    "serviceName": "javascript",
    "serviceLibrary": "v8transformservice.dll",
    "enabled": true
  }
],

In services.json, multiple code language services can be created with different "serviceName" properties, such as "javascript", "javascript2023", and "javascript2027". This allows the developer of a code package to do things like use "javascript" to specify the latest version of the JavaScript code service or target a specific version of the JavaScript engine using a more specific "serviceName".

Each service may use the same or different dynamic libraries (.dll, .so, or .dylib) to provide the programming language runtime. The same dynamic library may also be reused in other services, such as transform services.

The "databaseName" property is an optional string that specifies the database that contains the tables. It defaults to the database name supplied at login.

Note

In the API Explorer, "defaultDatabaseName" is set to "ctreeSQL" in the "createSession" action that happens at login.

  • A zero-length "databaseName" is invalid.

  • Its limits are from 0 to 64 bytes.

  • If the "databaseName" property is omitted or set to null, the server will use the default database name specified at login.

  • If no default database is specified during "createSession", "defaultDatabaseName" will be set to the "defaultDatabaseName" value that is specified in the services.json file.

The "defaultOwnerName" property is an optional string that is supplied at "createSession". It is used by the "ownerName" property which specifies the owner account name. It defaults to the "username". When "ownerName" is omitted, the server sets "ownerName" to the value of "defaultOwnerName". However, if "defaultOwnerName" is set to the empty string, then the "ownerName" is set to the empty string.

  • See Object owner in the JSON DB Concepts section for an explanation of how to use the "defaultOwnerName" property to specify the owner of objects created in the session

  • When "ownerName" is omitted the server uses the "defaultOwnerName" property value set during login.

  • In "createSession" and "alterSession" when "defaultOwnerName" is omitted or set to null:

    • In the JSON DB API, the server sets "defaultOwnerName" to the "username" of the logged-in user. Thus, by default, the logged-in account owns the objects it creates.

    • In the JSON Hub API and JSON MQ API, the server sets "defaultOwnerName" to "admin" allowing the server to own the objects it creates.

  • Actions that create objects, such as "createTable" and "createIntegrationTable", can omit the "ownerName" property making the server set "ownerName" to the value of "defaultOwnerName".

  • When an action that creates an object sets the "ownerName" property to a valid account name, the specified account owns the created object and an account that owns an object has full management rights over the object. You can use object ownership as a simple way to control access to objects.

  • When "ownerName" is set to the empty string, then no account owns the object. Unowned objects can be managed by administrator accounts and by accounts assigned to roles that grant access rights to the object making it useful when you want to prevent an account from owning an object and inheriting full management rights to that object.

The "integrationServices" property is an array of objects that describes and controls FairCom's integration services. It defaults to an empty array.

  • An integration service is a connector that uses a protocol to collect information from devices and/or deliver information to devices — for example, FairCom Edge includes connectors that collect data from Modbus and OPC UA.

  • For information on how to build and add your own connectors using C or C++, contact FairCom.

  • Do not change the settings of the object properties unless disabling an unused connector.

The "listeners" property is an array of objects that describes and controls FairCom's listeners. It defaults to an empty array.

  • A listener is a service that listens on a specified TCP/IP port for a specified protocol.

  • FairCom servers provide listeners for the protocols:

    • "http"

    • "https"

    • "mqtt"

    • "mqtts"

    • "mqttws"

    • "mqttwss"

  • Each protocol is hardwired to a specific set of backend services:

    • The HTTP and HTTPS protocols are hardwired to support the jsonAction APIs and web applications. 

    • The MQTT and MQTTS protocols are hardwired to support MQTT protocols 3.1.1 and 5.0 over TCP/IP.

    • The MQTTWS and MQTTWSS protocols are hardwired to support MQTT protocols 3.1.1 and 5.0 over WebSocket.

  • For information on how to build and add your own listeners using C or C++, contact FairCom.

  • Do not change the object property settings unless disabling an unused listener.

  • Each protocol can listen with TLS authentication for secure communications.

The "tls" property is a JSON object that defines the public server certificate filename, the private key filename, the certificate authority filename, the cipher suites that are allowed, and whether the client certificate is required. This property is optional. It defaults to an empty object. 

Example

"tls": { "serverCertificateFilename": "server.crt", "privateKeyFilename": "server.key", "caCertificateFilename": "ca.crt", "allowedCipherSuites": "AES256-SHA256" "requireClientCertificate": "true"
}

The "maxConnectionsPerIpAddress" property is the number of TCP/IP connections the app server will accept from a single TCP/IP address.

This feature is implemented at the FairCom App Server level to prevent the app server from being overwhelmed by a DoS attack. It protects against simultaneous DoS attacks across multiple protocols: HTTP, HTTPS, MQTT, MQTTS, WS, and WSS.

The default is 25 connections.

A value of 0 disables this protection.

This property can be added to the top level of the services.json file and/or to each listener object in the "listeners" array. At the top level, the property applies to all listeners. Within a listener, it applies only to that listener.

In the case that your connections are routed through a firewall or load balancer, you may need to disable this feature since the connections will come from the same IP address.

Example

{
  "maxConnectionsPerIpAddress": 5,
    "listeners": [
    {
      "serviceName": "https8443",
      "description": "Port 8443 using TLS-secured HTTPS protocol for REST and Web Apps on all TCP/IP addresses bound to this server",
      "port": 8443,
      "protocol": "https",
      "enabled": true,
      "maxConnectionsPerIpAddress": 5,
      "tls": {
        "certificateFilename": "./web/fccert.pem"
      }
    }
  ]
}

The "maxJsonApiSessions" property is the total number of JSON API sessions the app server will accept. This setting ensures the server does not consume so many resources that it becomes unstable.

The default value is the maximum number of JSON API connections allowed by the license.

A value of 0 disables this protection and allows JSON API sessions up to the maximum number of connections allowed by the license file.

This property is added to the "jsonActionApiDefaults" object.

The "maxJsonApiSessionsPerIpAddress" property is the number of JSON API sessions the app server will accept from the same client IP Address.

The default value is 50.

The maximum possible number of connections is determined by the license file.

A value of 0 disables this protection and allows JSON API sessions with the same IP Address up to the maximum number of connections allowed by the license file.

This property is added to the "jsonActionApiDefaults" object.

In the case that your connections are routed through a firewall or load balancer, you may need to disable this feature since the connections will come from the same IP address.

The "maxJsonApiSessionsPerUsername" property is the number of JSON API sessions the app server will accept with the same username. Because of this, an application may use a different account for each JSON API session.

The default value is 50.

The maximum possible number of connections is determined by the license file.

A value of 0 disables this protection and allows unlimited sessions with the same username up to the maximum number of connections allowed by the license file.

If your application uses one account for all JSON API sessions, this feature will need to be disabled.

This property is added to the "jsonActionApiDefaults" object. See the example below.

Example

"jsonActionApiDefaults":
{
  "maxJsonApiSessions": 500,
  "maxJsonApiSessionsPerIpAddress": 20,
  "maxJsonApiSessionsPerUsername": 20,
    "defaultApi": "hub",
  "defaultBinaryFormat": "hex",
  "defaultDatabaseName": "faircom",
  "defaultDebug": "max",
  "defaultOwnerName": "admin",
  "defaultResponseOptions":
  {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "idleConnectionTimeoutSeconds": 3600,
  "idleCursorTimeoutSeconds": 600,
  "defaultRetentionPolicy": "autoPurge",
  "defaultRetentionUnit": "week",
  "defaultRetentionPeriod": 4
}

The "mqtt" property is an optional object that defaults to {} and groups the MQTT default values together.

The "authenticationMethods" property defines which authentication techniques are accepted by the MQTT broker. To enable an authentication technique, include it in the list. To disable an authentication technique, remove it from the list. For example, remove "none" and "password" from the list to require all clients to authenticate using only client certificates. The default value is "authenticationMethods": [ "none", "password", "clientCertificate" ], which causes the broker to accept all client authentication techniques.

The broker supports the following authentication techniques:

  • "none" allows clients to connect without authentication.

  • "password" enables clients to connect using a username and password.

  • "clientCertificate" supports clients sending an X.509 client certificate to the broker for authentication. The certificate must include the username in the certificate's Common Name (CN) field.

The "defaultDowngradeQoS" property sets the default value of the "downgradeQoS" property in "configureTopic". It is optional and defaults to false. The MQTT broker uses this value when a topic does not include the "downgradeQoS" property. Use the "downgradeQoS" property to set each topic to a different setting. When false, it enables FairCom MQ's unique ability to deliver messages using the QoS requested by subscribers regardless of the QoS provided by publishers. When true, the MQTT broker lowers the quality of service (QoS) of outgoing MQTT messages to match the QoS of incoming messages.

The "defaultMaxDeliveryRatePerSecond" property sets the default value of the "maxDeliveryRatePerSecond" property in "configureTopic". It is optional and defaults to 0, which causes the broker to send messages as fast as possible. A value between 1 and 1000 helps keep a client from being overwhelmed with too many messages sent too quickly. It must be a value between 0 and 2147483647. The MQTT broker uses this value when a topic does not include the "maxDeliveryRatePerSecond" property. Use the "maxDeliveryRatePerSecond" property to set each topic to a different setting.

The "defaultMaxInflightMessages" property sets the default value of "maxInflightMessages" in "configureTopic". It is optional and defaults to 20. It causes the broker to send up to 20 messages without waiting for subscribers to acknowledge published packets. Setting this property to a larger number increases performance but may overwhelm some subscribers. The MQTT broker uses this value when a topic does not include the "maxInflightMessages" property. Use the "maxInflightMessages" property to set each topic to a different setting.

The "defaultMessageCommitFrequencyForQoS1" property specifies the default frequency for messages to be committed for QoS 1. The default value is 1000 to deliver all messages as quickly as possible. The "optimizeForQoS2" property automatically uses the value of this property to set the default value of the "messageCommitFrequencyForQoS1" property in the "configureTopic" action, which you can optionally assign to each topic. 

When most messages are QoS 0 or 1, in services.json, you can set "defaultMessageCommitFrequencyForQoS1" to a number greater than 0, such as 1000. It delays committing the delivery status to disk by the specified number of messages, which causes the MQTT broker to use volatile RAM to track delivery status. Delaying the persistence of delivery status increases delivery speed, but when the MQTT broker encounters unexpected downtime, the broker resends messages up to the number specified in this property, which is a problem for QoS 2 messages but not for QoS 0 and QoS 1 messages. When you need a specific topic to support QoS 2, use the "configureTopic" action to set the "MessageCommitFrequencyForQoS1": 0 to ensure previously sent QoS 2 messages are not resent while the server recovers from unplanned downtime. 

When most messages are QoS 2, you can add "defaultMessageCommitFrequencyForQoS1": 0 to services.json. This setting causes the server to commit each message's delivery status to disk, which ensures previously sent QoS 2 messages are not resent while the server recovers from unplanned downtime. When you need a specific topic to support QoS 0 or 1 for maximum performance, use the "configureTopic" action to set "MessageCommitFrequencyForQoS1" to a number greater than 0, such as 1000.

The "defaultMillisecondCommitFrequencyForQoS1" property specifies the default frequency in milliseconds to commit the delivery status for QoS 1. The "optimizeForQoS2" property automatically uses the value of this property to set the default value of the "MillisecondCommitFrequencyForQoS1" property in the "configureTopic" action, which you can optionally assign to each topic. The default value is 1000 to deliver all messages as quickly as possible. 

When most messages are QoS 0 or 1, in services.json, you can set "defaultMillisecondCommitFrequencyForQoS1" to a number greater than 0, such as 1000. It delays committing the delivery status to disk by the specified number of milliseconds, which causes the MQTT broker to use volatile RAM to track delivery status. Delaying the persistence of delivery status increases delivery speed, but when the MQTT broker encounters unexpected downtime, the broker resends messages, which is a problem for QoS 2 messages but not for QoS 0 and QoS 1 messages. When you need a specific topic to support QoS 2, use the "configureTopic" action to set the "millisecondCommitFrequencyForQoS1": 0 to ensure previously sent QoS 2 messages are not resent while the server recovers from unplanned downtime. 

When most messages are QoS 2, you can add "defaultMillisecondCommitFrequencyForQoS1": 0 to services.json. This setting causes the server to commit each message's delivery status to disk, which ensures previously sent QoS 2 messages are not resent while the server recovers from unplanned downtime. When you need a specific topic to support QoS 0 or 1 for maximum performance, use the "configureTopic" action to set "MillisecondCommitFrequencyForQoS1" to a number greater than 0, such as 1000.

The "defaultOptimizeForQoS2" property sets the default value for the "optimizeForQoS2" property. It defaults to false for maximum performance. Set to false in the "mqtt" section of the services.json file when you expect most messages to use QoS 1 for the fastest performance. Set to true in the "mqtt" section of the services.json file when you expect most messages to use QoS 2, which is appropriate for mission-critical applications that cannot receive messages more than once, such as MQTT command messages and the data change messages from FairCom DB Notify. You can override this default value in each topic by using the "configureTopic" action to assign a different value to the "optimizeForQoS2" property. QoS 0 messages are unaffected by this property and always run at maximum performance.

The "disableThroughputStats" property controls how the MQTT broker tracks the number of inbound and outbound messages per second. Set to true to stop the MQTT Broker from tracking the average number of inbound and outbound messages per second. It defaults to false. When set to false, the broker tracks the throughput of all incoming and outgoing messages, which is helpful in troubleshooting usage spikes. Throughput tracking slightly slows down MQTT performance. Disable throughput tracking by omitting the property or setting it to null or false.

The "enforceQos2DuringRecovery" property guarantees the MQTT broker will not publish a QoS 2 message a second time after a broker recovers from an unexpected downtime. To do this, the broker must persist the packet transfer state of each QoS 2 message, which slows the speed of message delivery to QoS 2 subscribers. This feature works at the broker level. It is configured once for the broker and applies to all topics and subscribers. The default value is false.

Warning

Changing to true may cause you to lose QoS 1 and 2 messages. It also prevents you from implementing high availability. FairCom does not recommend using true.

Warning

Do not change this setting if you want to preserve your settings in FairCom MQ and FairCom Edge. To change this setting, you must shut down the FairCom server, delete the faircom xdatabase, change the setting's value, and restart the server to rebuild its delivery tracking tables.

The "eventuallyPersistDeliveryInfo" property determines whether the server will persist the delivery status of each message to disk. It defaults to false,  which causes the server to persist the delivery status of each message to disk. FairCom recommends false because it allows FairCom's MQTT broker to support mission-critical QoS 2 messages – even when the server is recovering from unplanned downtime.

Set it to true for faster message delivery when you only want to support QoS 0 and 1. Setting it to true prevents FairCom's MQTT broker from supporting mission-critical QoS 2 messages because when the server is recovering from an unplanned downtime, it may resend QoS 2 messages, which violates the MQTT specification. 

In more technical terms, this setting controls whether the broker commits the delivery status of MQTT packets to the transaction log on disk or commits delivery status to volatile RAM using FairCom's PREIMG technology, where the server eventually writes the changes to disk.

The "historyRetentionPeriod" property controls how long the server stores records that contain MQTT history. It is a positive integer number. For example, when you set "historyRetentionPeriod" to 5 and "historyRetentionUnit" to "day", the server retains records for five days, and, at the beginning of each day, the server removes records older than five days.

See "historyRetentionUnit".

The "historyRetentionUnit" property controls how often the server purges records containing MQTT history.

These records are in the following tables in the FairCom database:

  • mqtt_connection_topic_history

  • mqtt_connection_history

  • mqtt_command_history

  • mqtt_subscription_history

You may set "historyRetentionUnit" to:

  • "minute"

  • "hour"

  • "day"

  • "week"

  • "month"

  • "year"

  • "forever"

See "historyRetentionPeriod".

The "messageCommitFrequencyForQoS1" property sets the maximum number of messages the MQTT broker will send before it commits the delivery status to disk. A larger number increases the time between committed messages, which improves performance, but during recovery from unplanned downtime, it allows the broker to resend packets it has already sent. A non-zero number is a problem for QoS 2 messages, which should be sent only once.

When it is set to 1 or less, the delivery information for each message is committed when the message is delivered, and the "millisecondCommitFrequencyForQoS1" property is set to 0 to disable the timer because it is not needed.

When the "optimizeForQoS2" property is true, it sets the value of this property to 0 to support Qos 2 messages. This setting ensures the MQTT broker does not resend previously sent QoS 2 messages while recovering from unplanned downtime. Command and data change messages typically require QoS 2 because they must be delivered only once.

When the "optimizeForQoS2" property is false, it sets the value of this property to "defaultMessageCommitFrequencyForQoS1" unless you assign a value to the "messageCommitFrequencyForQoS1" property.

When a topic only supports QoS 0 and 1 messages, you may set the value to an integer number greater than 0, such as 1000. It delays committing the delivery status to disk by the specified number of messages, which causes the MQTT broker to use volatile RAM to track delivery status for faster message delivery. Many messages, such as telemetry, status, queries, birth notice, and death notice, use QoS 0 or 1 when the client can tolerate receiving the same message more than once.

The "messageCommitFrequencyForQoS1" and "millisecondCommitFrequencyForQoS1" properties work together to ensure no more than the maximum number of messages and milliseconds occur before the server commits the delivery status to disk.

The "millisecondCommitFrequencyForQoS1" property sets the maximum number of milliseconds the MQTT broker will wait before it commits the delivery status to disk. A larger number increases the time between committed messages, which improves performance, but during recovery from unplanned downtime, it allows the broker to resend packets it has already sent. A non-zero number is a problem for QoS 2 messages, which should be sent only once.

When the "optimizeForQoS2" property is true, it sets the value of this property to 0 to support QoS 2 messages. This setting ensures the MQTT broker does not resend previously sent QoS 2 messages while recovering from unplanned downtime. Command and data change messages typically require QoS 2 because they must be delivered only once.

When the "optimizeForQoS2" property is false, it sets the value of this property to "defaultMillisecondCommitFrequencyForQoS1" unless you assign a value to the "millisecondCommitFrequencyForQoS1" property.

When a topic only supports QoS 0 and 1 messages, you may set the value to an integer greater than 0, such as 1000. It delays committing the delivery status to disk by the specified number of milliseconds, which causes the MQTT broker to use volatile RAM to track delivery status for faster message delivery. Many messages, such as telemetry, status, queries, birth notice, and death notice, use QoS 0 or 1 when the client can tolerate receiving the same message more than once.

The "messageCommitFrequencyForQoS1" and "millisecondCommitFrequencyForQoS1" properties work together to ensure no more than the maximum number of messages and milliseconds occur before the server commits the delivery status to disk.

The "optimizeForQoS2" property ensures the specified topic either delivers maximum performance for QoS 1 messages when set to false or fully supports mission-critical QoS 2 messages when set to true. It defaults to false for maximum performance.

When false, the topic uses the value you specify in "MessageCommitFrequencyForQoS1". If omitted, "MessageCommitFrequencyForQoS1" is set to "defaultMessageCommitFrequencyForQoS1".

When false, the topic uses the value you specify in "MillisecondCommitFrequencyForQoS1". If omitted, "MillisecondCommitFrequencyForQoS1" is set to "defaultMillisecondCommitFrequencyForQoS1".

When true, it assigns the following property values to the topic and ignores any values you apply to these properties:

"MessageCommitFrequencyForQoS1": 1

"MillisecondCommitFrequencyForQoS1": 0

QoS 0 messages are unaffected by this property and always run at maximum performance.

Note

When true, this setting causes the server to persist additional two-phase commit information for each sent message. This information is required for the server to know if it has already sent a message. Persisting this extra information slows message delivery but ensures the server correctly handles duplicate messages during a server restart after an unplanned downtime.

The "ownerName" property sets the account name that owns the tables created by the MQTT broker. It defaults to "admin". You can set it to any valid account name. It is a security best practice to set the owner name to an account with limited privileges.

The "pollingFrequencyMilliseconds" property controls the polling frequency of all incoming requests over MQTT, HTTP,  HTTPS, WS, and WSS. Thus, it affects the latency and throughput of all MQTT, JSON action APIs, and Web applications. It defaults to 1, which causes the server to poll for an incoming event every millisecond. This setting provides the lowest latency and maximum throughput performance. This setting works well on all but the slowest computers, such as old Raspberry PI computers. A higher number decreases CPU usage and power consumption and increases the latency for detecting incoming messages and API requests.

The "statsCollectionFrequencySeconds" property sets the frequency in seconds for the MQTT broker to collect statistics in the mqtt_stats table, which is required for the MQ Dashboard to work. The default value is 12 seconds. The following values turn off the insertion of statistics records into the mqtt_stats table: omitting the property, setting it to null, or setting it to a value <= 0. A smaller value increases the accuracy of the MQ Explorer dashboard, but it slightly slows down the overall performance of the MQTT broker.

The "statsPublishFrequencySeconds" property sets the frequency in seconds for the MQTT broker to publish MQTT messages containing statistics about connections, subscribers, and topics. Each message is a JSON object that includes extensive information about the current state of the MQTT broker. Do the following to turn off publishing these messages: omit the property, set it to null, or set it to a value <= 0. A smaller value increases the number of messages sent per second and slightly slows down the overall performance of the MQTT broker.

  • The MQTT broker publishes these statistic messages to the topic names specified in "connectionStatsTopicName", "subscriberStatsTopicName", and "topicStatsTopicName"

  • The MQTT broker also stores the messages for each statistic topic in an integration table. The broker stores the message in the "source_payload" field. The broker derives the name of an integration table from its corresponding MQTT topic name. For example, a topic named "faircomAdmin/connections" causes a table to be created and named mqtt_msg_faircomadmin_connections.

The "statsRetentionPeriod" property controls how long the server stores records that contain MQTT statistics. It is a positive integer number. For example, when you set "statsRetentionPeriod" to 5 and "statsRetentionUnit" to "day", the server retains records for five days, and, at the beginning of each day, the server removes records older than five days.

This property applies to the mqtt_stats table and the integration tables created by the "connectionStatsTopicName", "subscriberStatsTopicName", and "topicStatsTopicName" properties.

See "statsRetentionUnit".

The "statsRetentionUnit" property controls how often the server purges records containing MQTT statistics in the mqtt_stats table.

You may set it to:

  • "minute"

  • "hour"

  • "day"

  • "week"

  • "month"

  • "year"

  • "forever"

See "statsRetentionPeriod"

The "otherServices" property is an optional array of objects that describes and controls FairCom's other services. It defaults to the services connected when the server last started up.

"otherServices": [
  {
    "serviceName": "dbnotify",
    "serviceLibrary": "./dbnotify/fcdbnotify.dll",
    "enabled": false
  }
],

The "transformServices" property is an optional array of objects that describes and controls FairCom's transform services. It defaults to the services connected when the server last started up.

"transformServices" [
  {
    "serviceName": "siemensUDT2JSON",
    "serviceLibrary": "siemensudtservice.dll",
    "enabled": true
  }
],
{
  "maxConnectionsPerIpAddress": 5,
  "listeners": [
  {
    "serviceName": "http8080",
    "description": "Port 8080 using insecure HTTP protocol for REST and Web Apps on all TCP/IP addresses bound to this server",
    "port": 8080,
    "protocol": "http",
    "enabled": false
  },
  {
    "serviceName": "https8443",
    "description": "Port 8443 using TLS-secured HTTPS protocol for REST and Web Apps on all TCP/IP addresses bound to this server",
    "port": 8443,
    "protocol": "https",
    "enabled": true,
    "tls": {
      "serverCertificateFilename": "./web/fccert.pem",
      "allowedCipherSuites": "",
      "caCertificateFilename": "",
      "clientCertificateFilename": "",
      "clientPrivateKeyFilename": "",
      "requireClientCertificate": false
    }
  },
  {
    "serviceName": "mqtt1883",
    "description": "Port 1883 using insecure MQTT protocol for the MQTT broker on all TCP/IP addresses bound to this server",
    "port": 1883,
    "protocol": "mqtt",
    "enabled": true
  },
  {
    "serviceName": "mqtts8883",
    "description": "Port 8883 using TLS-secured MQTTS protocol for the MQTT broker on all TCP/IP addresses bound to this server",
    "port": 8883,
    "protocol": "mqtts",
    "enabled": true,
    "tls": {
      "serverCertificateFilename": "./web/fccert.pem"
    }
  },
  {
    "serviceName": "mqttws9001",
    "description": "Port 9001 using WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this server",
    "port": 9001,
    "protocol": "mqttws",
    "enabled": true
  },
  {
    "serviceName": "mqttwss9002",
    "description": "Port 9002 using TLS-secured WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this server",
    "port": 9002,
    "protocol": "mqttwss",
    "enabled": true,
    "tls": {
      "serverCertificateFilename": "./web/fccert.pem"
    }
  }

  ],

  "jsonActionApiDefaults":
  {
    "defaultApi": "hub",
    "defaultBinaryFormat": "hex",
    "defaultDatabaseName": "faircom",
    "defaultDebug": "max",
    "defaultOwnerName": "admin",
    "defaultResponseOptions":
    {
      "binaryFormat": "hex",
      "dataFormat": "objects",
      "numberFormat": "number"
    },
    "idleConnectionTimeoutSeconds": 3600,
    "idleCursorTimeoutSeconds": 600,
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4,
    "maxJsonApiSessions": 1024,
    "maxJsonApiSessionsPerIpAddress": 50,
    "maxJsonApiSessionsPerUsername": 50,
    "enablePermanentJsonApiSessions": true
  },

  "applicationRoot": "./web/apps/",
  "pollingFrequencyMilliseconds": 1,
  "requestMaxThreads": 1024,
  "maxConnectionsPerIpAddress": 25,
  "connInactiveTimeout": 30,
  "connRequestTimeout": 10,
  "maxDBconnCount": 2048,

  "mqtt": {
    "authenticationMethods": [ "none", "password", "clientCertificate" ],

    "defaultDowngradeQoS": false,
    "defaultMaxInflightMessages": 20,
    "defaultMaxDeliveryRatePerSecond": 0,

    "statsRetentionUnit": "day",
    "statsRetentionPeriod": 14,
    "disableThroughputStats": false,

    "historyRetentionUnit": "day",
    "historyRetentionPeriod": 30,

    "enableMqttLogging": false,

    "statsCollectionFrequencySeconds": 12,
    "statsPublishFrequencySeconds": 30,

    "disablePersistence": "no",
    "defaultMessageCommitFrequencyForQoS1": 100,
    "defaultMillisecondCommitFrequencyForQoS1": 1000,
    "defaultOptimizeForQoS2": false,
    "enforceQos2DuringRecovery": true,
    "eventuallyPersistDeliveryInfo": false,
    "messageCommitFrequencyForQoS1": 1,
    "millisecondCommitFrequencyForQoS1": 1,
    "optimizeForQoS2": false,
    "ownerName": "admin"
  },

  "storeAndForward":
  {
    "controlSentPosition": false,
    "transactionLog": true
  },

  "applications": [
  {
    "serviceName": "Ace Monitor",
    "uriPath": "AceMonitor",
    "serviceLibrary": "ctmonitor.dll",
    "enabled": true
  },
  {
    "serviceName": "Data Explorer",
    "uriPath": "SQLExplorer",
    "serviceLibrary": "ctsqlexplorer.dll",
    "enabled": true
  },
  {
    "serviceName": "ISAM Explorer",
    "uriPath": "ISAMExplorer",
    "serviceLibrary": "ctisamexplorer.dll",
    "enabled": true
  }
  
  ],

  "apiRoot": "./api",

  "apis": [
  {
    "serviceName": "hub",
    "enabled": true
  },
  {
    "serviceName": "mq",
    "enabled": true
  },
  {
    "serviceName": "db",
    "enabled": true
  },
  {
    "serviceName": "transform",
    "enabled": true
  }
  ],

  "integrationServices": [
  {
    "serviceName": "opcua",
    "serviceLibrary": "opcservice.dll",
    "schemaName": "opcua",
    "enabled": true
  },
  {
    "serviceName": "modbus",
    "serviceLibrary": "modbusservice.dll",
    "schemaName": "modbus",
    "enabled": true
  },
  {
    "serviceName": "ab",
    "serviceLibrary": "abservice.dll",
    "schemaName": "ab",
    "enabled": true
  },
  {
    "serviceName": "siemensS7",
    "serviceLibrary": "siemenss7service.dll",
    "schemaName": "siemensS7",
    "enabled": true
  },
  {
    "serviceName": "rest",
    "serviceLibrary": "restservice.dll",
    "schemaName": "rest",
    "enabled": true
  }
  ],

  "transformServices": [
  {
    "serviceName": "siemensUDT2JSON",
    "serviceLibrary": "siemensudtservice.dll",
    "enabled": false
  },
  {
    "serviceName": "v8TransformService",
    "serviceLibrary": "v8transformservice.dll",
    "enabled": false
  }
  ],

  "codeServices": [
  {
    "serviceName": "javascript",
    "serviceLibrary": "v8transformservice.dll",
    "enabled": true
  }
  ],

  "otherServices": [
  {
    "serviceName": "dbnotify",
    "serviceLibrary": "./dbnotify/fcdbnotify.dll",
    "enabled": false
  },
  {
    "serviceName": "ctagent",
    "serviceLibrary": "./agent/ctagent.dll",
    "enabled": false
  },
  {
    "serviceName": "thingworx",
    "serviceLibrary": "./thingworx/ctthingworx.dll",
    "enabled": false
  },
  {
    "serviceName": "aggregation",
    "serviceLibrary": "./aggregation/cttimestamp.dll",
    "enabled": false
  }
  ]
}

The table shows FairCom’s default mapping of each protocol to a TCP/IP port and one or more services. It is common for multiple services to share the same port.

Only services that require the server to listen for client connections are included in the table. Services, such as OPC UA and Modbus, are not listed because they require the server to pull data from other systems. Services, such as ThingWorx, are also not listed because they require the server to push data into other systems.

For maximum flexibility in any network environment, you can configure how FairCom servers map ports to specific protocols. The main constraint is that you can assign a port to only one protocol. Thus, a port can support only one protocol. However, you can assign any port to any protocol and you can assign different ports to the same protocol. You can also choose not to assign a protocol to any port, which disables the protocol and minimizes the attack footprint of the server. You can easily disable any port and service assigned to that port.

A FairCom server creates a listener each time a protocol is mapped to a port. For each listener, it sends communications over that protocol to one or more services.

You can map each protocol to one or more compatible services, such as mapping the Secure WebSocket (WSS) protocol to the MQTT service. The table shows which protocols and services can be mapped directly to each other.

Table 3. Protocols and services that can be directly mapped to each other

Protocol

Compatibility services

Description

MQTT

MQTT

The insecure MQTT protocol can only be mapped to the MQTT service.

MQTTS

MQTT

The secure MQTT protocol can only be mapped to the MQTT service.

MQTTWS

MQTT

The insecure MQTT protocol over WebSocket can only be mapped to the MQTT service.

MQTTWSS

jsonAction APIs

The secure MQTT protocol over WebSocket can only be mapped to the MQTT service.

WS

jsonAction APIs

The insecure WebSocket protocol can be mapped only to jsonAction APIs.

WSS

jsonAction APIs

The secure WebSocket protocol can be mapped only to jsonAction APIs.

HTTP

jsonAction APIs
REST
Browser Apps

The insecure HTTP protocol can be mapped to the Browser Apps, the jsonAction APIs, and the REST API.

HTTPS

jsonAction APIs
REST
Browser Apps

The secure HTTP protocol can be mapped to the Browser Apps, the jsonAction APIs, and the REST API.

ISAM

ISAM

FairCom’s proprietary ISAM communication protocol over TCP/IP can only be mapped to the ISAM service.

SQL

SQL

FairCom’s proprietary SQL communication protocol over TCP/IP can only be mapped to the SQL service.



Note

  • Some protocols have limitations that prevent them from being directly mapped to a service — for example, you cannot map the HTTP protocol to an MQTT service because they are fundamentally incompatible. When you want to bridge across two incompatible protocols, you can create integrations in FairCom Edge that bridge any input service to any output service.

  • Shared Memory is not a TCP/IP protocol. Thus, it is not configured in services.json. Instead, it is configured in ctsrvr.cfg. Since the ISAM protocol uses shared memory or TCP/IP, it too is configured only in ctsrvr.cfg.

Versions 12 through 12.5 of the FairCom DB server used the cthttpd.json file to manage ports. This section explains how that configuration file works. Newer versions of FairCom services use the services.json configuration file.

Modifying
Example 1. Version 12 of cthttpd.json
{
  "listening_http_port": 8080,
  "listening_https_port": 8443,
  "ssl_certificate": "./web/fccert.pem",
  "document_root": "./web/apps",


  "applications": [
    "ctree;ctrest.dll",
    "AceMonitor;ctmonitor.dll",
    "SQLExplorer;ctsqlexplorer.dll",
    "ISAMExplorer;ctisamexplorer.dll",
  ]
}


Example 2. Version 12.5 of cthttpd.json
{
	"tls_certificate": "./web/fccert.pem",

	"http_port": 8080,
	"http_enabled": true,

	"https_port": 8443,
	"https_enabled": true,

	"websocket_port": 8081,
	"websocket_tls_connections_only": true,
	"websocket_enabled": true,

	"mqtt_port": 1883,
	"mqtt_tls_connections_only": false,
	"mqtt_enabled": true,

	"app_root": "./web/apps",

	"http_url_to_appserver_map": [
		"mqtt;ctmqtt.dll",
		"ctree;ctrest.dll",
		"AceMonitor;ctmonitor.dll",
		"SQLExplorer;ctsqlexplorer.dll",
		"ISAMExplorer;ctisamexplorer.dll"
	],

	"websocket_url_to_appserver_map": [
		"json_nav;json_nav.dll"
	]
}


Table 4. Port descriptions

Service

Port

Config file

Setting

Examples/Notes

FairCom Web Applications

8443

services.json

V12.5: "https_port": 8443
V12: "listening_https_port": 8443

https://localhost:8443/

MQTT Explorer - SSL

8443

services.json

V12.5: "https_port": 8443
V12: "listening_https_port": 8443
https://localhost:8443/mq/
https://localhost:8443/mqttexplorer/

SQL Explorer - SSL

8443

services.json

V12.5: "https_port": 8443
V12: "listening_https_port": 8443
https://localhost:8443/sql/
https://localhost:8443/sqlexplorer/

ACE Monitor - SSL

8443

services.json

V12.5: "https_port": 8443
V12: "listening_https_port": 8443
https://localhost:8443/monitor/
https://localhost:8443/acemonitor/

REST API - SSL

8443

services.json

V12.5: "https_port": 8443
V12: "listening_https_port": 8443

https://localhost:8443/ctree/api/v1/openapi

Insecure HTTP Port

8080

services.json

V12.5: "http_port": 8080
V12: "listening_http_port": 8080

The apps and REST API above can use this port when a secure connection is NOT required — for example, in a development lab

Replication Manager

7000

ctagent.json

"memphis_sql_port": 7000

FairCom’s Replication Manager web application

MQTT

1883

services.json

V12.5: "mqtt_port": 1883
V12: "mqtt_listening_port": 1883

Publish and subscribe to MQTT messages

WebSocket for JSON NAV API & MQTT protocol

8081

services.json

V12.5: "websocket_port": 8081
V12: "mqtt_websocket_port": 8081

Used by FairCom’s MQTT Explorer for MQTT messages

c-treeDB, FairCom DB ISAM, FairCom Low-Level APIs

5597

ctsrvr.cfg

SERVER_PORT 5597

Used by FairCom’s client driver to communicate with the server

SQL API

6597

ctsrvr.cfg

SQL_PORT 6597

Used by FairCom’s Server for SQL communications

Note

  • This port must be unused and available or you may see "SQL subsystem initialization failed" in the CTSTATUS.FCS file. You may edit the SQL port to a different value.

  • Be sure to verify that the server is not trying to set up an IPv6 port when it should be using an IPv4 port (see IPv6 Support).

Node‑RED

1880

settings.js

"uiPort": 1883

Node-RED is an open-source project that can use the FairCom server. It is not a FairCom product. Its configuration file, settings.js, is located in the folder where you installed Node-RED. 

Caution

By default, Node-RED communicates passwords in the clear. Node-RED can be secured.



FairCom ports are configured in configuration files located in <faircom>/config. You can change them using any text editor.

Rules:
  • Files with the .json extension must follow the syntax rules of JSON files.

  • Files with the .cfg extension are FairCom’s configuration files.

    • One property per line

    • The property name is followed by white space and the property value.

    • A semi-colon at the beginning of the line comments out the line.

Note

As always, be security conscious of which database services are running and listening on ports. Less access is better. You can turn off services by disabling plug-ins.

Tip

If the localhost domain name does not work, use the IP Address 127.0.0.1.

The FairCom DB server for Windows is named ctreeace.exe (or ctsrvr.exe). FairCom DB servers prior to and including V11.0 were distributed with support for the communication protocols listed in the Communications protocols table.

Table 5. Communication protocols

Protocol

COMM_PROTOCOL keyword

TCP/IP

F_TCPIP

TCP/IP (using an IPv6 socket)

F_TCPIPV6

Shared Memory

FSHAREMM

TCP/IP (Data Camouflage support - Deprecated)

FETCPIP



The FairCom server for Windows defaults to the TCP/IP protocol. To activate any other protocol, use the COMM_PROTOCOL keyword in a ctsrvr.cfg file, discussed in Advanced configuration keywords. Use the name shown in the table above under COMM_PROTOCOL keyword as the token following the COMM_PROTOCOL keyword in ctsrvr.cfg.

Note

The COMM_PROTOCOL option specifies the protocol used for ISAM connections. By default, local SQL connections use shared memory unless the SQL_OPTION NO_SHARED_MEMORY keyword is specified. See the COMM_PROTOCOL for more information about the communication protocol for SQL connections.

The COMM_PROTOCOL keyword disables the default protocol, so if you want to load the default and another protocol, each must have a COMM_PROTOCOL entry in ctsrvr.cfg.

Example 3. Load all supported communication protocols for the FairCom server on Windows
COMM_PROTOCOL  F_TCPIP

COMM_PROTOCOL  FSHAREMM

COMM_PROTOCOL  FETCPIP


Note

If COMM_PROTOCOL is specified for one protocol, all protocols to be used must be specified. If no COMM_PROTOCOL is specified, the FairCom server uses the default, F_TCPIP.

The shared memory protocol eliminates the overhead of the TCP/IP protocol stack resulting in very fast communications. The only drawback is the client and server must reside in the same physical memory space. For client server applications running on the same machine, this can result in communications performance increases of almost 500% over TCP/IP in some instances.

Important

The following information increases security risk.

It is possible for your vendor to create client applications that listen for an available FairCom server without knowing the server name in advance. A FairCom server can be configured to broadcast its server name and IP address over a TCP/IP port.

With this method, it is possible for a client to detect the various FairCom servers operating on the network and obtain their server names, including IP addresses.

These server keywords support the broadcast features BROADCAST_PORT, BROADCAST_INTERVAL, and BROADCAST_DATA. See the examples in FairCom DB configuration options.

Broadcast features:
  • BROADCAST_PORT specifies the TCP/IP port used for the broadcast.

    The default value is 0, which means the broadcast is off.

    If DEFAULT is specified, this means that the broadcast is on and the default port is used, which is 5,595.

    Any valid four-byte integer greater than 5000 that is not in use by another process may be specified. This should NOT be the port for the FairCom server, which is displayed at startup and is based on the server name, see examples.

  • BROADCAST_INTERVAL determines the number of seconds between broadcasts. The default is 10 seconds, otherwise the token should be a number.

    Important

    If the number is negative, each broadcast is also sent to the FairCom server standard output.

    To prevent unreasonable values, the maximum value allowed is set to 86,400 seconds, which is once per day.

  • BROADCAST_DATA specifies a token to be broadcast following the server name. The token must not contain spaces. The server name will be followed by a vertical bar character, "|", which is followed by the token. There is no default token.

Using the following sample keywords and assuming the host IP address was 127.0.0.1, the FairCom server broadcasts “SAMPLE | 127.0.0.1 | 5451| FAIRCOM_SERVER” on port 6329 every 90 seconds:

Table 6. Sample keywords

Broadcast feature

Token

SERVER_NAME

SAMPLE

BROADCAST_PORT

6329

BROADCAST_INTERVAL

90

BROADCAST_DATA

FAIRCOM_SERVER



To enable permanent sessions under "jsonActionApiDefaults" add "enablePermanentJsonApiSessions": true.

To disable permanent sessions under "jsonActionApiDefaults" add "enablePermanentJsonApiSessions": false or omit this property because it defaults to false.

Example

"jsonActionApiDefaults":
{
  "defaultApi": "hub",
  "defaultBinaryFormat": "hex",
  "defaultDatabaseName": "faircom",
  "defaultDebug": "max",
  "defaultOwnerName": "admin",
  "defaultResponseOptions":
  {
    "binaryFormat": "hex",
    "dataFormat": "objects",
    "numberFormat": "number"
  },
  "idleConnectionTimeoutSeconds": 3600,
  "idleCursorTimeoutSeconds": 600,
  "defaultRetentionPolicy": "autoPurge",
  "defaultRetentionUnit": "week",
  "defaultRetentionPeriod": 4,
  "maxJsonApiSessions": 1024,
  "maxJsonApiSessionsPerIpAddress": 50,
  "maxJsonApiSessionsPerUsername": 50,
  "enablePermanentJsonApiSessions": true
},

Edit the <faircom>/config/services.json file to enable or disable the FairCom server from running all web applications or specific web applications.

All applications

 

To enable all web applications to run, set the "applicationRoot" property value to <faircom>/server/web/apps.

To disable all web applications from running set the "applicationRoot" property to an empty string (""), null, or omit it from services.json.

Examples 

Allow applications to run

"applicationRoot": "<faircom>/server/web/apps",

"applications": []

Do not allow any applications to run

"applicationRoot": "",

"applications": []

Specific applications

Use the "applications" property in services.json to control when the FairCom server allows specific web applications to run. The FairCom server rejects all HTML page requests for an application unless it is properly enabled and configured in the "applications" property.

Note

The "applicationRoot" property value must also be set to enable web applications.

If these conditions are met, the FairCom server will return files found in the designated folder and its subfolders.

Examples 

Allow the Ace Monitor application to run.

"applications":[
  {
    "serviceName": "Ace Monitor",
    "folderName": "AceMonitor",
    "uriPath": "AceMonitor",
    "serviceLibrary": "ctmonitor.dll",
    "enabled": true
  }
]

Do not allow the Ace Monitor application to run.

"applications": [
  {
    "serviceName": "Ace Monitor",
    "folderName": "AceMonitor",
    "uriPath": "AceMonitor",
    "serviceLibrary": "ctmonitor.dll",
    "enabled": false
  }
]