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.
Example services.json configuration file
{
"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/",
"approvedCorsConnections": [ "https://faircom.github.io" ],
"pollingFrequencyMilliseconds": 1,
"requestMaxThreads": 1024,
"maxConnectionsPerIpAddress": 25,
"connectionInactiveTimeout": 30,
"connectionRequestTimeout": 10,
"maxDatabaseConnectionCount": 2048,
"connectionPoolFileIdleCloseSeconds": 10,
"mqtt": {
"authenticationMethods": [ "none", "password", "clientCertificate" ],
"defaultDowngradeQoS": false,
"defaultMaxInflightMessages": 20,
"defaultMaxDeliveryRatePerSecond": 0,
"statsRetentionUnit": "day",
"statsRetentionPeriod": 14,
"disableThroughputStats": false,
"historyRetentionUnit": "day",
"historyRetentionPeriod": 30,
"enableMqttLogging": false,
"defaultRetrySeconds": 20,
"statsCollectionFrequencySeconds": 12,
"statsPublishFrequencySeconds": 30,
"disablePersistence": "no",
"defaultMessageCommitFrequencyForQoS1": 100,
"defaultMillisecondCommitFrequencyForQoS1": 1000,
"defaultOptimizeForQoS2": false,
"enforceQos2DuringRecovery": true,
"eventuallyPersistDeliveryInfo": false,
"messageCommitFrequencyForQoS1": 1,
"millisecondCommitFrequencyForQoS1": 1,
"optimizeForQoS2": false,
"ownerName": "admin",
"defaultMqttPayloadType": "json",
"defaultValidateMqttPayload": true
},
"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
}
]
}
Enable and disable permanent sessions
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.
"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
},
Enable and disable web applications
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.
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
}
]
How to use services.json
This section outlines the properties included in services.json.
| Property | Description | Default | Type | Limits (inclusive) | ||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
apiRoot |
The "apiRoot" property specifies location of the API in relation to the FairCom server. |
Optional with default of |
string | No limit | ||||||||||||
apis |
The "apis" property describes and controls FairCom's jsonAction APIs. |
Optional with default of []
|
array of objects |
|
||||||||||||
applicationRoot |
The The default value of There is rarely a reason to change the For information on how to add your own web applications, which can use any of FairCom's jsonAction APIs, contact FairCom. |
Optional with default of
|
string | No limit | ||||||||||||
applications |
The 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 |
Optional with default of []
|
array of objects | 1 or more objects | ||||||||||||
|
applications .enabled |
The "enabled" property enables or disables a web application. |
Optional with default of false
|
Boolean |
|
||||||||||||
|
applications .folderName |
The Only when the
In this example, the web application will be stored in the
|
Required - No default value | string | 1 to 64 bytes | ||||||||||||
|
applications .serviceLibrary |
The Library files are located in the The full path includes the |
Optional with default of ""
|
string | 1 to 64 bytes | ||||||||||||
|
applications .serviceName |
The "serviceName" property specifies a friendly name for the web application. The FairCom server ignores this property. | Optional with default of ""
|
string | 1 to 64 bytes | ||||||||||||
|
applications .uriPath |
The "uriPath" property indicates the path where the "serviceLibrary" file is stored. If specified, this value is appended to the default <faircom>/server/web/ folder path. |
Optional with default of ""
|
string | 1 to 64 bytes | ||||||||||||
approvedCorsConnections |
The services.json example:
When FairCom's App server receives an API request that includes an Origin header with a URL that is in the
When an API call does not include an Origin header or the specified URL in the Origin header does not match a URL in this array, the server does not add these headers to the response. This denies the CORS request. |
Optional with default of []
|
array | 0 or more strings | ||||||||||||
authenticationMethods |
FairCom MQ and FairCom Edge let you enforce secure MQTT communications with the broker by letting you control how MQTT clients authenticate. Use the
Define the allowed MQTT authentication methods by including any combination of Examples To allow MQTT clients to connect with or without authentication, include To require MQTT clients to connect only with certificate authentication, include only To require MQTT clients to connect only with a username and password authentication, include only To require MQTT clients to connect with a client certificate or a password, include Best Security Practice Remove |
Optional with default of
|
array of objects |
|
||||||||||||
codeServices |
The "codeServices" property specifies which programming languages are available in the product. |
Optional with default of []
|
array of objects |
|
||||||||||||
|
codeServices .enabled |
The "enabled" property specifies whether or not the feature is enabled. |
Optional with default of true
|
Boolean |
|
||||||||||||
|
codeServices .serviceLibrary |
The Library files are located in the The full path includes the |
Optional with default of ""
|
string | |||||||||||||
|
codeServices .serviceName |
The The
In 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. |
Optional with default of "javascript"
|
string | |||||||||||||
connectionPoolFileIdleCloseSeconds |
The
|
Optional with default of 10
|
integer |
-1 to 2147483647
|
||||||||||||
defaultDatabaseName |
The "defaultDatabaseName" property defines the default value of the "databaseName" property. |
FairCom DB defaults to FairCom Edge defaults to FairCom MQ defaults to |
string | 1 to 64 bytes | ||||||||||||
defaultOwnerName |
The
|
Optional with default of the session's |
string | 1 to 64 bytes | ||||||||||||
integrationServices |
The
|
Optional with default of {}
|
object | |||||||||||||
jsonActionApiDefaults |
The default settings for the FairCom jsonAction APIs and browser-based applications are specified in the
Example 1. Default settings for jsonAction APIs
The property names and values in You can change the values of the properties in
Keeping
|
Optional with default of {}
|
object | |||||||||||||
listeners |
The
|
Optional with default of []
|
array of objects | |||||||||||||
|
listeners .tls |
The |
Optional with default of {}
|
object | |||||||||||||
|
listeners .tls .allowedCipherSuites |
The
|
Optional with default of ""
|
string | |||||||||||||
|
listeners .tls .caCertificateFilename |
The
|
Optional with default of ""
|
string | |||||||||||||
|
listeners .tls .clientCertificateFilename |
The
|
Optional with default of ""
|
string | |||||||||||||
|
listeners .tls .clientPrivateKeyFilename |
The
|
Optional with default of ""
|
string | |||||||||||||
|
listeners .tls .requireClientCertificate |
The
|
Optional with default of false
|
Boolean |
|
||||||||||||
maxConnectionsPerIpAddress |
The 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 A value of This property can be added to the top level of the 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. |
Optional with default of 25
|
integer | |||||||||||||
maxJsonApiSessions |
The The default value is the maximum number of JSON API connections allowed by the license. A value of This property is added to the |
The max number of JSON API connections allowed by the license | integer | |||||||||||||
maxJsonApiSessionsPerIpAddress |
The The maximum possible number of connections is determined by the license file. A value of This property is added to the 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. |
Optional with default of 50
|
integer | |||||||||||||
maxJsonApiSessionsPerUsername |
The The maximum possible number of connections is determined by the license file. A value of 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":
{
"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
} |
Optional with default of 50
|
integer | |||||||||||||
mqtt |
The "mqtt" property groups the MQTT default values together. |
Optional with default of {}
|
object | |||||||||||||
|
mqtt .authenticationMethods |
The The broker supports the following authentication techniques:
|
[ "none", "password", "clientCertificate" ] |
array | [ "none", "password", "clientCertificate" ] |
||||||||||||
|
mqtt .defaultDowngradeQoS |
The "defaultDowngradeQoS" property sets the default value of the "downgradeQoS" property in "configureTopic". 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. |
Optional with default of false
|
Boolean |
|
||||||||||||
|
mqtt .defaultMaxDeliveryRatePerSecond |
The "defaultMaxDeliveryRatePerSecond" property sets the default value of the "maxDeliveryRatePerSecond" property in "configureTopic".Setting this property to 0 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. |
Optional with default of 0
|
integer | |||||||||||||
|
mqtt .defaultMaxInflightMessages |
The "defaultMaxInflightMessages" property sets the default value of "maxInflightMessages" in "configureTopic". 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. |
Optional with default of 20
|
integer | |||||||||||||
|
mqtt .defaultMessageCommitFrequencyForQoS1 |
The When most messages are QoS 0 or 1, in When most messages are QoS 2, you can add |
Optional with default of 1000
|
integer | |||||||||||||
|
mqtt .defaultMillisecondCommitFrequencyForQoS1 |
The When most messages are QoS 0 or 1, in When most messages are QoS 2, you can add |
Optional with default of 1000
|
integer | |||||||||||||
|
mqtt .defaultMqttPayloadType
|
The "defaultMqttPayloadType" property defines the default type of MQTT message payloads published to all topics. |
Optional with default of "json"
|
string enum |
|
||||||||||||
|
mqtt .defaultOptimizeForQoS2 |
The "defaultOptimizeForQoS2" property sets the default value for the "optimizeForQoS2" property. Setting this property 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. |
Optional with default of false
|
Boolean |
|
||||||||||||
|
mqtt .defaultRetrySeconds |
The "defaultRetrySeconds" property sets the global default value of the "retrySeconds" property. |
Optional with default of 20
|
integer |
1 to 65535
|
||||||||||||
|
mqtt .defaultValidateMqttPayload
|
The "defaultValidateMqttPayload" property determines if the broker validates the mqtt payload by default. Setting this property to true causes the broker to validate the MQTT message payload published to all topics to verify it matches the type specified by the "defaultMqttPayloadType" or "mqttPayloadType" properties. |
Optional with default of true
|
Boolean |
|
||||||||||||
|
mqtt .disableThroughputStats |
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. |
Optional with default of false
|
Boolean |
|
||||||||||||
|
mqtt .enableMqttLogging |
The "enableMqttLogging" property controls whether or not MQTT logging is enabled. When true, the CTSTATUS.FCS file will contain MQTT status messages. |
Optional with default of false
|
Boolean |
|
||||||||||||
|
mqtt .enforceQos2DuringRecovery |
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. |
Optional with default of true
|
Boolean |
|
||||||||||||
|
mqtt .eventuallyPersistDeliveryInfo |
The Set it to 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. |
Optional with default of false
|
Boolean |
|
||||||||||||
|
mqtt .historyRetentionPeriod |
The |
Optional with default of 30
|
integer | |||||||||||||
|
mqtt .historyRetentionUnit |
The These records are in the following tables in the FairCom database:
You may set
|
Optional with default of "day"
|
string |
|
||||||||||||
|
mqtt .messageCommitFrequencyForQoS1 |
The When it is set to When the When the When a topic only supports QoS 0 and 1 messages, you may set the value to an integer number greater than The |
Optional with default of 1
|
integer | |||||||||||||
|
mqtt .millisecondCommitFrequencyforQoS1 |
The When it is set to When the When the When a topic only supports QoS 0 and 1 messages, you may set the value to an integer number greater than The |
Optional with default of 1
|
integer | |||||||||||||
|
mqtt .optimizeForQoS2 |
The When When When
QoS 0 messages are unaffected by this property and always run at maximum performance.
|
Optional with default of false
|
Boolean |
|
||||||||||||
|
mqtt .ownerName |
The "ownerName" property sets the account name that owns the tables created by the MQTT broker. 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. |
Optional with default of "admin"
|
string | |||||||||||||
|
mqtt .pollingFrequencyMilliseconds |
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. Setting this property to 1, 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. |
Optional with default of 1
|
integer | |||||||||||||
|
mqtt .statsCollectionFrequencySeconds |
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 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. |
Optional with default of 12
|
integer | |||||||||||||
|
mqtt .statsPublishFrequencySeconds |
The
|
Optional with default of 30
|
integer | |||||||||||||
|
mqtt .statsRetentionPeriod |
The See |
Optional with default of 14
|
integer | Any positive integer | ||||||||||||
|
mqtt .statsRetentionUnit |
The You may set it to:
|
Optional with default of "day"
|
string |
|
||||||||||||
otherServices |
The
|
The services connected when the server last started up. | array of objects | |||||||||||||
transformServices |
The
|
The services connected when the server last started up. | array of objects |