Skip to main content

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.

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

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

How to use services.json

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

Each "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
    }
  ]
Table 3. "listeners" object property summaries

Property

Description

Default

Type

Limits (inclusive)

"description"

contains a user-defined explanation of what function this listener performs

""

string

"port"

defines the port this listener will use to watch for new connections

Required - No default value

integer

"protocol"

defines the protocol assigned to the listener

Required - No default value

string

"mqtt"
"mqtts"
"ws"
"wss"
"http"
"https"

"services"

specifies one or more services which will use this listener

Note

If no services are specified the listener is disabled because it cannot provide any service.

Required - No default value

array of service objects

"enabled"

enables or disables this listener

Note

After the server starts, a service can be enabled or disabled by using the ctadmin CLI utility or by calling the "manageService" action in the JSON Admin API.

Required - No default value

Boolean

true
false


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"
    }
  ]
}
Table 4. Optional protocol property summaries

Property

Description

Default

Type

Limits (inclusive)

"bindAddresses"

binds this listener to a specific address, which can be used to prevent the listener from using other network interfaces

[ "0.0.0.0" ] 

array

"tls"

defines the TSL (SSL) security settings and file names

{ }

object

"certificateFileName"

contains the file name of the public server certificate file — such as, cert.pem

"./web/fccert.pem"

string

"privateKeyFilename"

contains the file name of the private server key file — such as key.pem

"key.pem"

string

"allowedCipherSuites"

contains a list of ciphers that the client may use to connect to the server

Note

A client is only allowed to connect to the server if it uses one of the listed ciphers.

[ "AES256-SHA256" ]

array

"certificateAuthoritiesFilename"

contains the file name of the certificate authorities file

"./web/ca.pem"

string



"bindAddresses"

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

Things to know:

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

"certificateAuthoritiesFilename"

The "certificateAuthoritiesFilename" property is the filename of the certificate authorities file. It defaults to "./web/ca.pem"

Things to know:

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

Ports in 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 5. 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 6. 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.

Set server-wide jsonAction defaults

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

Example 4. Default settings for jsonAction APIs
"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.

Example 5. Keeping SQL_DATABASE and "jsonActionApis" in sync

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


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

Broadcast feature

Token

SERVER_NAME

SAMPLE

BROADCAST_PORT

6329

BROADCAST_INTERVAL

90

BROADCAST_DATA

FAIRCOM_SERVER



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

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.

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.

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

tls

A server certificate is a certificate that a server computer uses to identify itself to client computers.