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.

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.

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

This section outlines the properties included in services.json.

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

"tls": { 
  "certificateFilename": "server.crt", 
  "privateKeyFilename": "server.key",
  "certificateAuthoritiesFilename": "ca.crt",
  "allowedCipherSuites": "AES256-SHA256"
}

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

"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": [
  {
    "serviceName": "dbnotify",
    "serviceLibrary": "./dbnotify/fcdbnotify.dll",
    "enabled": false
  }
],

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

"transformServices" [
  {
    "serviceName": "siemensUDT2JSON",
    "serviceLibrary": "siemensudtservice.dll",
    "enabled": true
  }
],

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.

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

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

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

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.

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.

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.

COMM_PROTOCOL  F_TCPIP

COMM_PROTOCOL  FSHAREMM

COMM_PROTOCOL  FETCPIP

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.

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.

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:

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