Skip to main content

Ports and services

Configure protocols, ports, and services

Abstract

Services are configured at startup using the services.json file (previously called cthttpd.json). The services.json file is located in the <faircom>\config folder.

Services are configured at startup using the services.json file (previously called cthttpd.json). The services.json file is located in the <faircom>\config folder.

All FairCom products provide multiple services that listen on TCP/IP ports. These services include web applications and APIs. The APIs support SQL, JSON commands, ISAM, and so forth.

Each service is provided by a plugin or a built-in library. A plugin is a dynamic library (dll, so, or dylib) that the FairCom server optionally loads at startup. For information about configuring plugins and the ports they use, see Plug-ins.

Built-ins are permanent core API services that also use dynamic libraries that are provided by the server. A plugin or a built-in can provide one or more services. Each service has a specific function, such as supporting an API like jsonAction APIs, connecting to a protocol like OPC UA, or transforming data.

The FairCom server maps protocols to ports and services. The server listens on many ports to a variety of protocols and sends incoming traffic to multiple services — for example, clients of the FairCom Edge server can use MQTT to communicate with each other while they each connect to the FairCom Edge server over different protocols, such as MQTT, MQTTS, WS, and WSS. Or clients using any FairCom server can use a variety of protocols to access the jsonAction APIs API, such as HTTP, HTTPS, WS, WSS, MQTT, and MQTTS.

Some services (such as SQL, jsonAction APIs, and ISAM) use the same communication pattern, such as the request/response pattern, and perform the same functions, such as querying, inserting, updating, and deleting records. Since these services work equally well across multiple communication protocols, like WS, WSS, HTTP, HTTPS, TCP/IP, and Shared Memory this makes choosing the communication protocol and the service a matter of client preference. Thus, the SQL, ISAM, and jsonAction APIs API can potentially run over any of these protocols — for example, in FairCom DB, the ISAM service is available over TCP/IP and Shared Memory.

This section defines how to configure the services of a FairCom server.  It shows how to map protocols to ports to services, as well as how to configure services. FairCom’s default configuration matches common industry settings for the protocols, ports, and services it offers. You can use the services.json file to configure less common combinations.

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.

Default protocols, ports, and services

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.

Map protocols, ports, and services

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

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"
    }
  },
  {
    "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/",
  "requestIterationMilliseconds": 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
  },

  "storeAndForward":
  {
    "controlSentPosition": false,
    "transactionLog": true,
    "defaultSubscriberMessageCommitFrequency": 100,
    "defaultSubscriberMessageCommitIntervalMSecs": 1000
  },

  "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
  }
  ]
}

How to use services.json

This section outlines the properties included in services.json.

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

defines the folder relative to the <faircomInstallation>/server folder (where FairCom's web applications are located on disk)

"./web/apps/"

Note

There is rarely a reason to change this.

string

"applications"

describes and controls FairCom's app servers

[]

array of objects

"authenticationMethods"

specifies the allowed MQTT authentication methods

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

array of objects

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

"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

Minimum length: 1
Maximum length: 64

defaultOwnerName

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

"admin"

string

Minimum length: 1
Maximum length: 64

integrationServices

describes and controls FairCom's integration services

{}

array of objects

listeners

describes and controls FairCom's listeners

{}

array of objects

"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



"apis"

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

Essential information

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

"applicationRoot"

The "applicationRoot" property is a string that defines the folder relative to the <faircomInstallation>/server folder (where FairCom's web applications are located on disk. Its default value is "./web/apps/".

Essential information

  • The default value of "./web/apps/" translates to the folder <faircom_installation>/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.

"applications"

The "applications" property is an array of objects that describes and controls FairCom's app servers. It defaults to an empty array which means no applications are configured to run.

Essential information

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

  • An app server is not a web application. FairCom's web applications are single-page, browser-based applications that are served out of folders in the <faircom_installation>/server/web/apps folder.

  • Each of FairCom's web applications call backend services from one or more app servers (contact FairCom for information on how to build and add your own app servers using C or C++).

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

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

"databaseName"

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.

Essential information

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

"defaultOwnerName"

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.

Essential information

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

"integrationServices"

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

Essential information

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

"listeners"

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

Essential information

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

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

Essential information

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"
      }
    }
  ]
}

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

Essential information

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.

"maxJsonApiSessionsPerIpAddress"

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

Essential information

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.

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

Essential information

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
}

"otherServices"

"transformServices"

Configure ports for FairCom DB server V12.0 through V12.5

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.

Configure ports for FairCom DB servers prior to version 10

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

Note

FairCom DB V11.5 and later support TLS/SSL - see Transport layer security secures data in transit between network FairCom DB clients and servers



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.

Configure ISAM ports for TCP/IP broadcast

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



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.

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
},

Transmission Control Protocol/Internet Protocol (TCP/IP) is the combination of a networking protocol (TCP) and computer addressing (IP) that makes it possible for computers to communicate across the Internet.

Internet protocols: hostname, HTTP, HTTPS, IP, IP Address, MQTT, MQTTS, MQTTWSS, protocol, TCP, TCP/IP, TLS, WebSocket

Structured Query Language (SQL) is a standardized programming language that is used to manage relational databases and perform various operations on the data in them.

FairCom's SQL engine is ANSI compliant and has almost all SQL features up through the SQL:2003 standard.

JavaScript Object Notation (JSON) is a simple format for representing data. It requires very little markup and is flexible enough to represent the majority of data structures. It is self-describing, which makes it ideal for schemaless applications and search. It can optionally be paired with a schema to define an expected structure.

Indexed Sequential Access Method (ISAM) is FairCom's primary ACE API. ISAM uses the Record Buffer Method, which gives the application full control over the contents of the entire record buffer to store structured or unstructured data.

FairCom's ISAM API provides full control over record processing. This allows developers to implement data processing algorithms that are tailored to precise application needs, and this allows an application to achieve unrivaled performance. FairCom's ISAM API works best in the C and C++ languages.

FairCom ACE APIs include ISAM, CTDB, and Low-level ACE API.

Open Platform Communications Unified Architecture (OPC UA) is a machine-to-machine communication protocol for industrial automation. OPC UA is the latest, easiest, and most robust protocol from the OPC Foundation.

The FairCom Edgeprovides a connector to OPC UA to bridge data from OPC UA devices to other protocols, including MQTT, JSON, and SQL.

Hypertext Transfer Protocol (HTTP) is a standard request-response protocol that works on top of TCP/IP. It allows a client computer to send a request to a server computer, which in turn, replies to the request. The purpose of HTTP is to allow software to ask questions and receive answers.

Secure Hypertext Transfer Protocol (HTTP) is the HTTP protocol running over TLS. It provides secure request-response communications between computers.

Secure Message Queueing Telemetry Transport (MQTTS) is the MQTT protocol running over TLS. It provides secure messaging between computers.

Shared Memory

Transport Layer Security (TLS) is a secure way for computers to communicate. It uses encryption, a certificate file , and a private key file to create secure communications between computers. TLS was formerly called Secure Sockets Layer (SSL). FairCom products support TLS 1.3, which is the latest version.

MQTTWS

WebSocket (WS) is a standard communication protocol for bidirectional exchange of data between computers, see RFC 6455. It works over TCP/IP and HTTP. It is often used by single page web applications because web browsers have built in support for WebSocket. It is also used by applications and servers that want to push messages to other computers in additional to using the request-response provided by HTTP.

A database is a set of data that is managed by a database server. A database contains data that is organized into tables, records, and fields. A database is a huge composite data type that represents a group of interconnected objects. A database allows records to be joined together for querying, searching, and processing by users, applications, and services.

A database is a security container that controls which accounts have permissions to access specific data.