How to change web service ports and settings (services.json)

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 "./api"

 
string No limit

apis

The "apis" property describes and controls FairCom's jsonAction APIs. Optional with default of [] array of objects

"serviceName"

"enabled"

applicationRoot

The "applicationRoot" property 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.

Optional with default of "./web/apps/"

 

string No limit

applications

The "applications" property describes and controls web applications that can run with the FairCom server. 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:

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

true

false

applications

.folderName

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.

 

Note 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.

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

 

Required - No default value string 1 to 64 bytes

applications

.serviceLibrary

The "serviceLibrary" property specifies the filename of a dynamic library that provides the API used by the web application.

Library files are located in the <faircom>/server/web/ folder.

The full path includes the "serviceLibrary" value — for example, the Monitor app has a "serviceLibrary" name of ctmonitor.dll, and its full path in the file system is <faircom>/server/web/ctmonitor.dll.

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 "approvedCorsConnections" property lists the external URLs that are approved to make cross-origin API requests.

services.json example:

{
	"applicationRoot": "./web/apps/",
	"approvedCorsConnections": [ "https://faircom.github.io" ]
}

When FairCom's App server receives an API request that includes an Origin header with a URL that is in the "approvedCorsConnections" array, the server adds the following HTTP headers to the response. This approves the CORS (Cross-Origin Resource Sharing) request.

Access-Control-Allow-Origin: https://faircom.github.io
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: Content-Type
Content-Type: application/json

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 "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.

Optional with default of ["none",

"password",

"clientCertificate"]

array of objects

["none",

"password",

"clientCertificate"]

codeServices

The "codeServices" property specifies which programming languages are available in the product. Optional with default of [] array of objects

"serviceName"

"serviceLibrary"

"enabled"

codeServices

.enabled

The "enabled" property specifies whether or not the feature is enabled.  Optional with default of true Boolean

true

false

codeServices

.serviceLibrary

The "serviceLibrary" property specifies the filename of a dynamic library that provides the API used by the web application.

Library files are located in the <faircom>/server/web/ folder.

The full path includes the "serviceLibrary" value — for example, the Monitor app has a "serviceLibrary" name of ctmonitor.dll, and its full path in the file system is <faircom>/server/web/ctmonitor.dll.

Optional with default of "" string  

codeServices

.serviceName

The "serviceName" property 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.

Optional with default of "javascript" string  

connectionPoolFileIdleCloseSeconds

The "connectionPoolFileIdleCloseSeconds" property specifies how long in seconds a table remains open in the connection pool used by the MQTT and REST API after the operation completes. This value must be an integer between -1 and 2147483647. When this property is set to a value of -1, the tables in the connection pool stay open indefinitely.

FairCom recommends using the REST API to make changes to tables and indexes because it is rarely affected by file block errors caused by open files in the connection pool. 

Error code Description Cause
-17008 CT - File open failed due to conflicting file access modes (exclusive/shared). Occurs when a SQL, ISAM or CTDB operation requires exclusive access (e.g., to alter a table or modify indexes), but the table is held open (in shared mode) by the MQTT or JSON REST APIs.
798 File is blocked, retry later. Occurs when a SQL, ISAM, or CTDB operation attempts to access a table, but another process (like the REST API) has forced an exclusive lock on the table (usually during an alteration operation).
799 File block cleared, close/reopen file. Occurs when another process has forced an exclusive lock on a table, causing the file to be closed in your session. You must reopen the file in your session to continue using it.

When the REST API alters a table (including adding or deleting its indexes), it uses the ctFILBLKX function to force the table to close in all other sessions. This action is the root cause for Errors -17008, 798, 799 in concurrent REST, SQL, ISAM, or CTDB operations. 

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 "ctreeSQL"

FairCom Edge defaults to "faircom"

FairCom MQ defaults to "faircom"

string 1 to 64 bytes

defaultOwnerName

The "defaultOwnerName" property is used by "createSession" and "alterSession" to specify the default owner of objects created by the session. Its value must be a valid username of an account. 

  • See Object owner in the JSON DB Concepts section for an explanation of how to use the "defaultOwnerName" and "ownername" properties to specify the owner of objects.
  • 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.

Optional with default of the session's "username" property.

string 1 to 64 bytes

integrationServices

The "integrationServices" property describes and controls FairCom's integration services.

  • 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.
Optional with default of {} object  

jsonActionApiDefaults

The default settings for the FairCom jsonAction APIs and browser-based applications are specified in the services.json file in the "jsonActionApiDefaults" property.

Use the Google Chrome browser for FairCom browser-based tools. Other browsers may cause unexpected behavior.

Example 1. Default settings for jsonAction APIs

"jsonActionApiDefaults": {
    "defaultApi": "db",
    "defaultBinaryFormat": "hex",
    "defaultVariantFormat": "json",
    "defaultDatabaseName": "faircom",
    "defaultDebug": "max",
    "defaultOwnerName": "admin",
    "defaultResponseOptions": 
    {
      "binaryFormat": "hex",
      "variantFormat": "json",
      "dataFormat": "objects",
      "numberFormat": "number"
    },
    "idleConnectionTimeoutSeconds": 3600,
    "idleCursorTimeoutSeconds": 600,
    "defaultRetentionPolicy":"autoPurge",
    "defaultRetentionPeriod":"4",
    "defaultRetentionUnit":"week"
  }

The property names and values in "jsonActionApiDefaults" are identical to those in the "params" property of "createSession", "alterSession", and "describeSessions". Each FairCom product ships with different default settings that make sense for that product — for example, in FairCom DB, the "defaultAPI" property is set to "db", in FairCom MQ it is set to "mq", and in FairCom Edge it is set to "hub".

You can change the values of the properties in services.json, and all jsonAction APIs and browser-based user interfaces will use these properties as their default. If any of the properties in "jsonActionApiDefaults" are omitted from services.json, the property values may vary depending on the JSON action performed.

FairCom's core configuration file, ctsrvr.cfg, contains a SQL_DATABASE setting. You can set SQL_DATABASE to the name of a database and when the FairCom server starts, it creates a database with that name if it does not already exist.

By default, ctsrvr.cfg sets SQL_DATABASE to "ctreeSQL". If you change SQL_DATABASE to use another database name, it is a good practice to put the same name in the "defaultDatabaseName" property in services.json. This makes your newly created database the default database in all of FairCom's jsonActionAPIs and browser-based applications.

Keeping SQL_DATABASE and "jsonActionApiDefaults" in sync
ctsrvr.cfg 

SQL_DATABASE my_new_database

services.json 

"": {
    "defaultApi": "db",
    "defaultBinaryFormat": "hex",
    "defaultDatabaseName": "my_new_database",
    "defaultDebug": "max",
    "defaultOwnerName": "admin",
    "defaultResponseOptions": 
    {
      "binaryFormat": "hex",
      "dataFormat": "objects",
      "numberFormat": "number"
    },
    "idleConnectionTimeoutSeconds": 3600,
    "idleCursorTimeoutSeconds": 600,
    "defaultRetentionPolicy":"autoPurge",
    "defaultRetentionPeriod":"4",
    "defaultRetentionUnit":"week"
  }
Optional with default of {} object  

listeners

The "listeners" property describes and controls FairCom's listeners.

  • 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.
Optional with default of [] array of objects  

listeners

.tls

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. 

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

listeners

.tls

.allowedCipherSuites

The "allowedCiperSuites" property specifies an array of ciphers that the server will accept for communications with clients. 

  • It specifies the encryption ciphers that are allowed to be used for encrypting a TLS (SSL) connection.
  • A client is allowed to connect to the server only if it uses one of the ciphers in this list.
  • The default setting of an empty string supports industry-standard secure connections.
  • The default value requires clients to use full AES 256-bit encryption when they talk to the server.
  • If a client cannot support AES 256-bit encryption, a lower encryption level should be added to the list.
    • This is undesirable because malicious users will attempt to connect at the lowest possible level so they can harm the system (for more information, see ciphers main page at OPENSSL.org.
  • Example settings:
    • Only allows clients to connect securely.
    • Maximally secure example:
["AES256-SHA256", "AES256-GCM-SHA384", "DHE-RSA-AES256-SHA256"]
  • Minimally secure example with the broadest client support:
["!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
  • Insecure example allowing clients to connect using any level of security from none to the maximal:
["ALL", "!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
  • Add @STRENGTH to the end of the list to force the server to prioritize the strongest algorithms first.
  • Place an exclamation point before a cipher to disable it.
Optional with default of "" string  

listeners

.tls

.caCertificateFilename

The "caCertificateFilename" property specifies the name and optional path of the CA certificate file (such as "ca.pem").

  • You must include "caCertificateFilename" to allow clients to use X509 certificates to authenticate with the server.
  • The certificate authorities file contains the list of certificate authorities the server uses to validate X509 certificates that clients present as authentication credentials.
  • In order for an X509 certificate to be accepted by the server, the certificate must be signed by a certificate authority that is present in the certificate authorities certificate file.
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
Optional with default of "" string  

listeners

.tls

.clientCertificateFilename

The "clientCertificateFilename" property specifies the name of the client certificate file.

        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
Optional with default of "" string  

listeners

.tls

.clientPrivateKeyFilename

The "clientPrivateKeyFilename" property specifies the name of the client private key file. 

        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
Optional with default of "" string  

listeners

.tls

.requireClientCertificate

The "requireClientCertificate" property determines if a client certificate is required. If present, it must be set to true or false.

  • When "requireClientCertificate” is true, the listener prompts the client for a client certificate. If the client does not provide one or provides an incorrect certificate, the server refuses to connect to the client. When the server requires a client to authenticate using a client certificate, "requireClientCertificate” must be set to true.
  • When "requireClientCertificate” is false, the listener does not prompt the client for a client certificate. This prevents the server from using a client certificate to authenticate a client.
Optional with default of false Boolean

true

false

maxConnectionsPerIpAddress

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.

{
  "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"
      }
    }
  ]
}
Optional with default of 25 integer  

maxJsonApiSessions

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 max number of JSON API connections allowed by the license integer  

maxJsonApiSessionsPerIpAddress

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

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.

Optional with default of 50 integer  

maxJsonApiSessionsPerUsername

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 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.

"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 "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.
[ "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

true

false

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 "defaultMessageCommitFrequencyForQoS1" property specifies the default frequency for messages to be committed for QoS 1. Setting this property to 1000 delivers 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.

Optional with default of 1000 integer  

mqtt

.defaultMillisecondCommitFrequencyForQoS1

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. Setting this property to 1000 delivers 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.

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

"json"

"xml"

"binary"

"jpeg"

"siemensUdt"

"utf8"

"variantObject"

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

true

false

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

true

false

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

true

false

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

true

false

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

true

false

mqtt

.eventuallyPersistDeliveryInfo

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.

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. When set to false, the server to persists 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.

Optional with default of false Boolean

true

false

mqtt

.historyRetentionPeriod

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".

Optional with default of 30 integer  

mqtt

.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".

Optional with default of "day" string

"minute"

"hour"

"day"

"week"

"month"

"year"

"forever"

mqtt

.messageCommitFrequencyForQoS1

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.

Optional with default of 1 integer  

mqtt

.millisecondCommitFrequencyforQoS1

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.

Optional with default of 1 integer  

mqtt

.optimizeForQoS2

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.

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.

Optional with default of false Boolean

true

false

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 "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 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.
Optional with default of 30 integer  

mqtt

.statsRetentionPeriod

The "statsRetentionPeriod" property controls how long the server stores records that contain MQTT statistics. 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.

See "statsRetentionUnit".

Optional with default of 14 integer Any positive integer

mqtt

.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"

Optional with default of "day" string

"minute"

"hour"

"day"

"week"

"month"

"year"

"forever"

otherServices

The "otherServices" property describes and controls FairCom's other services.

"otherServices": [
  {
    "serviceName": "dbnotify",
    "serviceLibrary": "./dbnotify/fcdbnotify.dll",
    "enabled": false
  }
],
The services connected when the server last started up. array of objects  

transformServices

The "transformServices" property describes and controls FairCom's transform services.

"transformServices" [
  {
    "serviceName": "siemensUDT2JSON",
    "serviceLibrary": "siemensudtservice.dll",
    "enabled": true
  }
],
The services connected when the server last started up. array of objects