Configure protocols, ports, and services using services.json
Services are configured at startup using the services.json
file (previously called cthttpd.json
).
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.
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.
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.
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 |
| The insecure HTTP protocol can be mapped to the Browser Apps, the jsonAction APIs, and the REST API. | |||
HTTPS |
| 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 inctsrvr.cfg
. Since the ISAM protocol uses shared memory or TCP/IP, it too is configured only inctsrvr.cfg
.
{ "listeners": [ { "serviceName": "mqtt1883", "description": "Port 1883 using insecure MQTT protocol for the MQTT broker on all TCP/IP addresses bound to this computer", "enabled": true, "port": 1883, "bindAddresses": [ "0.0.0.0" ], "protocol": "mqtt", "services": [ { "serviceName": "MQTT", "enabled": true, "uriPath": "/mqtt", "settingsFile": "", "mqttOverloadProtection": { "rate": 2000, "burstSize": 4000 }, "mqttVersions": [ "3.1", "3.1.1", "5" ] }, { "serviceName": "db", "enabled": true, "uriPath": "/json_nav" } ] }, { "serviceName": "mqtts8883", "description": "Port 8883 using TLS-secured MQTTS protocol for the MQTT broker on all TCP/IP addresses bound to this computer", "enabled": true, "port": 8883, "bindAddresses": [ "0.0.0.0" ], "protocol": "mqtts", "tls": { "certificateFilename": "cert.pem", "privateKeyFilename": "key.pem", "allowedCipherSuites": [ "AES256-SHA256" ], "certificateAuthoritiesFilename": "ca.pem" } }, { "serviceName": "mqttws1884", "description": "Port 1884 using WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this computer", "enabled": true, "port": 1884, "bindAddresses": [ "0.0.0.0" ], "protocol": "ws", "services": [ { "serviceName": "MQTT", "enabled": true, "uriPath": "/mqtt", "mqttOverloadProtection": { "rate": 2000, "burstSize": 4000 }, "mqttVersions": [ "3.1", "3.1.1", "5" ] }, { "serviceName": "jsonAction APIs API", "enabled": true, "uriPath": "/json_nav" } ] }, { "serviceName": "mqtwss8884", "description": "Port 8884 using TLS-secured WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this computer", "port": 8884, "bindAddresses": [ "0.0.0.0" ], "protocol": "wss", "enabled": true, "services": [ { "serviceName": "mq", "enabled": true, "uriPath": "/mqtt" }, { "serviceName": "db", "enabled": true, "uriPath": "/json_nav" } ] }, { "serviceName": "http8080", "description": "Port 8080 using insecure HTTP protocol for REST and Web Apps on all TCP/IP addresses bound to this computer", "port": 8080, "bindAddresses": [ "0.0.0.0" ], "protocol": "http", "enabled": true, "services": [ { "serviceName": "REST API", "uriPath": "/rest", "serviceLibrary": "ctrest.dll", "enabled": true }, { "serviceName": "Ace Monitor", "enabled": true }, { "serviceName": "Data Explorer", "enabled": true }, { "serviceName": "ISAM Explorer", "enabled": true }, { "serviceName": "MQ Explorer", "enabled": true }, { "serviceName": "Replication Mgr", "enabled": true } ] }, { "serviceName": "https8443", "description": "Port 8443 using TLS-secured HTTPS protocol for REST and Web Apps on all TCP/IP addresses bound to this computer", "port": 8443, "bindAddresses": [ "0.0.0.0" ], "protocol": "https", "enabled": true, "tls": { "certificateFilename": "cert.pem", "privateKeyFilename": "key.pem", "allowedCipherSuites": [ "AES256-SHA256" ], "certificateAuthoritiesFilename": "ca.pem" }, "services": [ { "serviceName": "CTREE REST API", "uriPath": "/ctree", "serviceLibrary": "ctrest.dll", "enabled": true }, { "serviceName": "REST API", "uriPath": "/rest", "serviceLibrary": "ctrest.dll", "enabled": true }, { "serviceName": "Ace Monitor", "enabled": true }, { "serviceName": "Data Explorer", "enabled": true }, { "serviceName": "ISAM Explorer", "enabled": true }, { "serviceName": "MQ Explorer", "enabled": true }, { "serviceName": "Replication Mgr", "enabled": true } ] } ], "app_Root": "./web/apps/", "apiRoot": "./api/", "applications": [ { "serviceName": "Ace Monitor", "enabled": true, "uriPath": "/AceMonitor", "serviceLibrary": "ctmonitor.dll" }, { "serviceName": "Data Explorer", "enabled": true, "uriPath": "/DataExplorer", "serviceLibrary": "ctsqlexplorer.dll" }, { "serviceName": "ISAM Explorer", "enabled": true, "uriPath": "/ISAMExplorer", "serviceLibrary": "ctisamexplorer.dll" } ], "apis": [ { "serviceName": "hub", "enabled": true }, { "serviceName": "mq", "enabled": true }, { "serviceName": "db", "enabled": true }, { "serviceName": "rest", "enabled": true } ], "integrationServices": [ { "serviceName": "opcua", "serviceLibrary": "opcservice.dll", "enabled": true }, { "serviceName": "snmp", "serviceLibrary": "snmp.dll", "enabled": false }, { "serviceName": "thingworx", "serviceLibrary": "thingworx.dll", "enabled": false }, { "serviceName": "siemensUDT2JSON", "serviceLibrary": "udt.dll", "enabled": false } ] }
The "listeners"
property is an array of listener objects. Each listener object defines one port that the server listens to. It also maps the port to one protocol and one or more services.
Required "listeners"
properties
"listeners"
object must have:"port"
"protocol"
"services"
"listeners": [ { "description": "Port 1883 using MQTT for MQTT", "port": 1883, "protocol": "mqtt", "services": [ { "serviceName": "mqtt", "enabled": true } ], "enabled": true } ]
"listeners"
object property summariesProperty | Description | Default | Type | Limits (inclusive) | ||||||
---|---|---|---|---|---|---|---|---|---|---|
| contains a user-defined explanation of what function this listener performs | "" | string | |||||||
| defines the port this listener will use to watch for new connections | Required - No default value | integer | |||||||
| defines the protocol assigned to the listener | Required - No default value | string |
| ||||||
| specifies one or more services which will use this listener NoteIf no services are specified the listener is disabled because it cannot provide any service. | Required - No default value | array of service objects | |||||||
| enables or disables this listener NoteAfter the server starts, a service can be enabled or disabled by using the | Required - No default value | Boolean |
|
Optional "listeners"
properties
Each "listeners"
object may include optional properties, which vary by protocol.
{ "description": "Port 8883 using TLS Secure MQTTS for MQTT", "port": 8883, "bindAddresses": [ "0.0.0.0" ], "protocol": "mqtts", "tls": { "keystorePath": "filepath/of/keystore", "keystorePassword": "", "certificateFilename": "cert.pem", "privateKeyFilename": "key.pem", "allowedCipherSuites": [ "AES256-SHA256" ], "certificateAuthoritiesFilename": "ca.pem" }, "services": [ { "serviceName": "mqtt" } ] }
Property | Description | Default | Type | Limits (inclusive) |
---|---|---|---|---|
binds this listener to a specific address, which can be used to prevent the listener from using other network interfaces |
| array | ||
| defines the TSL (SSL) security settings and file names | { } | object | |
| contains the file name of the public server certificate file — such as, |
| string | |
| contains the file name of the private server key file — such as |
| string | |
| contains a list of ciphers that the client may use to connect to the server NoteA client is only allowed to connect to the server if it uses one of the listed ciphers. |
| array | |
contains the file name of the certificate authorities file |
| string |
The "bindAddresses"
property is an optional array of TCP/IP addresses on the local computer that can be used to receive connections. It defaults to [ "0.0.0.0" ]
.
The default
[ "0.0.0.0" ]
represents any TCP/IP address assigned to any network interface card (NIC) on the local computer.When the local computer has multiple network interface cards, it has multiple TCP/IP addresses.
Important
If the computer has multiple TCP/IP addresses, you should set
"bindAddresses"
to the specific TCP/IP address or addresses that you want to bind to the port.If you want the port to accept connections from any IP address bound to the local computer, you can set the
"bindAddresses"
property to[ "0.0.0.0" ]
.If you want to limit the port to accept only connections originating from within the local computer, you can set the
"bindAddresses"
property to[ "127.0.0.1" ]
.
The "certificateAuthoritiesFilename"
property is the filename of the certificate authorities file. It defaults to "./web/ca.pem"
The certificate authorities file contains the list of certificate authorities that the server uses to validate X509 certificates presented by clients 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 file. This approach supports self-signed certificates as long as the creator of the self-signed certificate is in the certificate authorities file.
One or more services per listener
A listener on a specific port and "bindAddress"
uses a specific protocol. Communications over that protocol may be mapped to one or more services. Each listener routes incoming traffic to a service depending on the service’s settings, such as its "uriPath"
. A service must be included in the "services"
property before the listener can route traffic to it. The example maps the secure WebSocket (WSS) protocol on port 8884 to an MQTT service and a jsonAction APIs service.
{ "description": "Port 1884 using WebSocket for MQTT", "port": 1884, "bindAddresses": [ "0.0.0.0" ], "protocol": "ws", "services": [ { "serviceName": "mqtt", "uriPath": "/mqtt", "serviceLibrary": "ctmqtt.dll", "mqttOverloadProtection": { "rate": 2000, "burstSize": 4000 }, "mqttVersions": [ "3.1", "3.1.1", "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.
To modify
cthttpd.json
, see Configuring the application server.To modify
ctsrvr.cfg
, see Configuring FairCom DB.
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", ] }
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" ] }
Service | Port | Config file | Setting | Examples/Notes | ||||
---|---|---|---|---|---|---|---|---|
FairCom Web Applications | 8443 |
|
|
| ||||
MQTT Explorer - SSL | 8443 |
|
|
| ||||
SQL Explorer - SSL | 8443 |
|
|
| ||||
ACE Monitor - SSL | 8443 |
|
|
| ||||
REST API - SSL | 8443 |
|
|
| ||||
Insecure 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 |
|
| FairCom’s Replication Manager web application | ||||
MQTT | 1883 |
|
| Publish and subscribe to MQTT messages | ||||
WebSocket for JSON NAV API & MQTT protocol | 8081 |
|
| Used by FairCom’s MQTT Explorer for MQTT messages | ||||
c-treeDB, FairCom DB ISAM, FairCom Low-Level APIs | 5597 |
|
| Used by FairCom’s client driver to communicate with the server | ||||
SQL API | 6597 |
|
| Used by FairCom’s Server for SQL communications Note
| ||||
Node‑RED | 1880 |
|
| Node-RED is an open-source project that can use the FairCom server. It is not a FairCom product. Its configuration file, CautionBy 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.
Files with the
.json
extension must follow the syntax rules of JSON files.Files with the
.cfg
extension are FairCom’s configuration files.One property per line
The property name is followed by white space and the property value.
A semi-colon at the beginning of the line comments out the line.
Note
As always, be security conscious of which database services are running and listening on ports. Less access is better. You can turn off services by disabling plug-ins.
Tip
If the localhost
domain name does not work, use the IP Address 127.0.0.1
.
The FairCom DB server for Windows is named ctreeace.exe (or ctsrvr.exe
). FairCom DB servers prior to, and including, V11.0 were distributed with support for the communication protocols listed in the Communications protocols table.
Protocol |
|
---|---|
TCP/IP | F_TCPIP |
TCP/IP (using an IPv6 socket) | F_TCPIPV6 |
Shared Memory | FSHAREMM |
TCP/IP (Data Camouflage support - Deprecated) | FETCPIP NoteFairCom 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
.
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.
The default settings for FairCom's jsonAction APIs and browser-based applications are specified in the services.json
file in the "jsonActionApis"
property.
"jsonActionApis": { "defaultApi": "db", "defaultBinaryFormat": "hex", "defaultDatabaseName": "faircom", "defaultDebug": "max", "defaultOwnerName": "admin", "defaultResponseOptions": { "binaryFormat": "hex", "dataFormat": "objects", "numberFormat": "number" }, "idleConnectionTimeoutSeconds": 3600, "idleCursorTimeoutSeconds": 600 }
The property names and values in "jsonActionApis"
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 "jsonActionApis"
are omitted from services.json
, the properties default to the values in Example 4, “Default settings for jsonAction APIs”.
Note
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 jsonAction APIs and browser-based applications.
SQL_DATABASE
and "jsonActionApis"
in syncctsrvr.cfg
SQL_DATABASE my_new_database
services.json
"jsonActionApis": { "defaultApi": "db", "defaultBinaryFormat": "hex", "defaultDatabaseName": "my_new_database", "defaultDebug": "max", "defaultOwnerName": "admin", "defaultResponseOptions": { "binaryFormat": "hex", "dataFormat": "objects", "numberFormat": "number" }, "idleConnectionTimeoutSeconds": 3600, "idleCursorTimeoutSeconds": 600 }
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_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 is5,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 is10
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:
Broadcast feature | Token |
---|---|
|
|
|
|
|
|
| FAIRCOM_SERVER |