Skip to main content

Advanced Install

Instructions for advanced setup, installation, and administration of FairCom servers

This section provides guidance and instructions for configuring FairCom for maximum performance and specialized functionality.

Instructions for advanced setup, installation, and administration of FairCom servers

Advanced Install
setup
installation
administration
FairCom servers
configuring
performance
specialized functionality

Change admin password

Set the password for the ADMIN user

The ADMIN user and members of the ADMIN group have full control over all operations in the FairCom server. They are also the only users who can stop the server.

Important

Changing the ADMIN password on all servers is critical to secure your data from malicious attackers.

  • The default administrator user ID is admin.

    • FairCom user IDs are NOT case-sensitive.

  • The default password: ADMIN

    • FairCom passwords ARE case-sensitive.

Set or change the password for the ADMIN account on FairCom servers

ADMIN accountset passwordchange admin passwordset admin passwordAdmin password

Use sa_admin to change a password

sa_admin is a command-line interface (CLI) program designed to be embedded into scripts. It changes a user password using command line parameters.

The following example changes the admin user password to NewPassword:

sa_admin -aADMIN -pADMIN -f"" -sFAIRCOMS -oup admin NewPassword

  • The -a parameter specifies the current value of the admin username, which is ADMIN unless you previously changed it.

  • The -p parameter specifies the current value of he admin user password, which initially is ADMIN.

  • The -f parameter is the file password, which is typically "".

  • The -s parameter is the connection name of the FairCom database, which is "FAIRCOMS" unless you previously changed it.

  • The -oup parameter tells the program to change the password.

Use ctadmn to change a password

Change a FairCom user password

ctadmn is an interactive tool you run from the command line, such as the DOS command prompt or the Linux BASH shell. It prompts you for information to change a user password.

This example authenticates the admin user as an authorized administrator, then changes the admin user password.

  1. Open a command prompt.

  2. Move to the <faircom>/tools folder.

  3. Run ctadmn.

    ctadmn1.png

  4. When prompted, enter admin for the user ID and press ENTER.

  5. Enter ADMIN for the password and press ENTER.

    1. By default, FairCom products set the admin password to ADMIN, which is all uppercase characters.

  6. Press ENTER for the next two prompts unless you have changed the File Password or Server Name.

  7. Press 1 and ENTER to open the User Operations menu.

    ctadmn2.png

  8. Press 4 and ENTER to change a user password.

    ctadmn3.png

  9. When prompted, enter admin for the User ID and press ENTER.

    ctadmn4.png

  10. Enter a new password and press ENTER.

  11. Enter the same new password again and press ENTER.

  12. Press ENTER.

  13. To quit

    1. Press q then ENTER

    2. Press q then ENTER again.

Server configuration

Configure the settings of FairCom server products

You can manage the behavior of your FairCom product by configuring settings in the <faircom>/config/ folder. The most important configuration files include services.json and ctsrvr.cfg .

Introduction

The following are introductions to configuration options for the FairCom server:

Section

Description

Automatic data aggregationData aggregation

Automatic data aggregation simplifies the task of performing simple processing on timestamped data.

LinuxLinux

The default operating system settings on Unix-style operating systems, such as Linux, Raspbian, Android IoT, AIX, and Solaris, are adequate for running a typical FairCom server. To customize the server to meet larger (or smaller) needs, you can change the operating system limits.

Memory usage

Memory usage in the FairCom server can be adjusted to match the capabilities of your hardware.

Ports and services

The section, FairCom ports, lists the default c-tree ports and provides information about how to change them. FairCom recommends using the defaults until you are familiar with the FairCom server.

Unix

Systems based on Unix (including AIX, Solaris, and Linux) may have configuration requirements. In addition to configuring the FairCom server, the operating system itself may need to be configured.

Windows

This section covers configuring installed features using FairComConfig.exe, the FairCom server as a Windows service, and the Tool Tray Interface on Windows.

This section provides a brief introduction to the settings that are most important when configuring your product for the first time

configureFairCom productsfirst time configurationconfiguration guideconfigure memory usageconfigure portsconfigure settings

Memory usage

Configure memory usage in a FairCom server

Memory usage in a FairCom server can be adjusted to match the capabilities of your hardware.

The defaults are 100 MB Data Cache, 100 MB of Index Cache, 100 MB of Sort Cache, 1024 maximum files (tables plus indexes), and 32 simultaneous connections. This configuration is designed for medium-sized environments, such as edge gateways.

Increasing the values for files, connections, and caches causes the FairCom server to use additional RAM. Conversely, decreasing these values reduces the RAM consumed.

The number of connections and files is the greatest factor in determining RAM because each connection consumes RAM for each file that is opened.

See Server Memory Calculations to help estimate your memory footprint for a given configuration.

Default memory settings

You can manage the RAM consumed by the FairCom server by changing the settings in the ctsrvr.cfg file. The following default settings consume approximately 8 GB RAM when all connections and files are open.

Table 1. Default memory settings

Setting

RAM

CONNECTIONS

32

FILES

1024

DAT_MEMORY

100 MB

IDX_MEMORY

100 MB

SORT_MEMORY

100 MB



Example 1. Small device example

On a small device, you can reduce RAM usage to a maximum of around 60 MB using the following settings:

Table 2. Small device example

Setting

RAM

CONNECTIONS

5

FILES

60

DAT_MEMORY

10 MB

IDX_MEMORY

10 MB

SORT_MEMORY

10 MB





Example 2. Large hub example

On a large computer, you can increase the settings to handle many more tables, indexes, and concurrent connections. The settings below are an example for a larger integration hub that consumes a maximum of around 30 GB RAM when all connections and files are open:

Table 3. Large hub example

Setting

RAM

CONNECTIONS

300

FILES

600

DAT_MEMORY

500 MB

IDX_MEMORY

500 MB

SORT_MEMORY

500 MB





Example 3. Large data center example

On a high-end server, you can increase the settings to handle very large numbers of tables, indexes, concurrent connections, and cache. The upper limits are 1 million files and 4096 connections.

The settings below are an example for a huge server that consumes a maximum of around 2 TB RAM when all connections and files are open:

Table 4. Large data center example

Setting

RAM

CONNECTIONS

1000

FILES

2500

DAT_MEMORY

50000 MB

IDX_MEMORY

50000 MB

SORT_MEMORY

50000 MB





To learn more about these settings, see:

In addition to the number of files and users, many parameters, such as those that affect cache sizes, can be adjusted to further tailor the FairCom Server to your needs.

For more details, see Caching and data integrity recommendations.

Memory usage in the FairCom server can be adjusted to match the capabilities of your hardware

memory usage settingsmemoryRAMmemory allocationdefault memory settings

Server memory calculations

This document provides information about the memory that the FairCom Server uses, including formulas to calculate the server's expected memory use based on the configuration options and usage patterns.

Note

The FairCom Knowledgebase has a memory use calculator spreadsheet that can help you evaluate the best memory usage.

Baseline server memory use

The FairCom Server startup memory requirements are calculated using the following equation:

Baseline Memory = 
  Server binary size + 
  Data cache size + 
  Index cache size + 
  System file control blocks + 
  Lock wait-for graph + 
  Global array sizes

Server binary size:

Calculate the server binary size by adding the size of the executable on disk and the sizes of all the shared libraries that the server process loads.

Data cache size:

The data cache size is set using the DAT_MEMORY configuration option. It defaults to 100 MB.

Index cache size:

The data cache size is set using the IDX_MEMORY configuration option. It defaults to 100 MB.

System file control blocks:

At startup, the server allocates an array of pointers to hold the system file control blocks. The number of entries in the array is set to the FILES configuration option. Each time a file uses a previously unused system file number, the server allocates a system file control block for that system file number and memory use increases by the size of the system file control block structure (CTFILE).

Initial allocation size:

FILES * sizeof(CTFILE *)

Size when fully used:

FILES * sizeof(CTFILE *) + FILES * (sizeof(CTFILE) + alignment)

Example structure size for 64-bit Windows server:

sizeof(CTFILE) + alignment = 4720

Lock wait-for graph:

The server allocates a two-dimensional array that it uses to detect that a blocking lock request would cause a deadlock. The array uses two bits per entry and uses the maximum number of connections set by the CONNECTIONS configuration option for both dimensions of the array.

Allocation size in bytes:

CONNECTIONS * CONNECTIONS / 4

Global array sizes:

The server allocates a number of global arrays. Many of these arrays are sized based on the maximum number of supported connections that is set in the server binary at compile time. This value, MXU2, is currently set to 10287 for a 64-bit server and to 4143 for a 32-bit server.

Some of the sizes of the global arrays depend on the CACHE_LINE configuration option, since this option causes those array elements to be aligned on a multiple of the specified cache line size. Supported CACHE_LINE values are: 1, 2, 4, 8, 16, 32, 64, 128, 256, 512, and 1024. If an invalid CACHE_LINE option is specified in the configuration file, the server logs a warning message to CTSTATUS.FCS and uses the default value.

The total global array size for a 64-bit server is approximately 74 MB when using the default CACHE_LINE size of 128.

Memory use for each ISAM connection

Base memory use for each ISAM connection is approximated as follows. <fils> is the fils parameter value specified by the client when connecting to the server.

Thread stack size + 
Communication buffer size + 
Record compression buffer size + 
Schema conversion buffer size + 
Connection level state information + 
ISAM level state information + 
Block encryption buffer + 
User file control blocks + 
Transaction mark list buffer + 
Preimage space hash bins + 
ISAM context hash bins + 
ISAM context state + 
User level lock hash bins+ 
Preimage space entries + 
Lock table entries

Thread stack size:

Each thread allocates a stack. The thread stack size is set as follows:

On Windows systems:

  • For ISAM threads, the stack size is set to 64 KB and cannot be changed.

  • For SQL threads, the stack size defaults to 1 MB for servers that don't support Unicode and to 1.5 MB for servers that support Unicode.

  • The stack size for SQL threads can be changed by using the server configuration option

    SETENV DH_THREAD_STACK_SZ_KB=<stack_size_in_kilobytes>

On Unix systems:

  • For ISAM threads, the stack size defaults to 64 KB.

  • For SQL threads, the stack size defaults to 1.5 MB for servers that don't support Unicode and to 3.5 MB for servers that support Unicode.

  • The stack size for ISAM and SQL threads can be changed by using the server configuration option 

    SETENV DH_THREAD_STACK_SZ_KB=<stacksize_in_kilobytes>

Communication buffer size:

The communication buffer is initially 4 KB. When the client reads or writes a record that exceeds the current communication buffer size, the server allocates a sufficiently-sized communication buffer to hold the record. The communication buffer remains allocated at that larger size until the client disconnects.

Note

The server configuration option TRIM_USER_MEMORY YES can be used to cause the server to periodically check if the communication buffer exceeds 1 MB, and if so it reduces the communication buffer to its default size of 4 KB.

Record compression buffer size:

A connection that reads or writes records that use data record compression allocates a buffer to hold the uncompressed record image. This buffer remains allocated until the client disconnects.

Note

The server configuration option TRIM_USER_MEMORY YES can be used to cause the server to periodically check if the communication buffer exceeds 1 MB, and if so it reduces the communication buffer to its default size of 4 KB.

Schema conversion buffer size:

A connection that reads records from a table that has had a hot alter operation performed on it might need to convert records from an older version of the record schema to the current schema version. As a performance enhancement, the server allocates a schema conversion buffer to hold the converted record image. This buffer remains allocated until the client disconnects.

Note

The server configuration option TRIM_USER_MEMORY YES can be used to cause the server to periodically check if the communication buffer exceeds 1 MB, and if so it reduces the communication buffer to its default size of 4 KB.

Connection level state information:

The server allocates memory to hold connection level state information in the format of a CTGV structure.

Example CTGV structure size for 64-bit Windows: 14736 bytes

ISAM level state information:

The server allocates memory to hold ISAM state information. The amount of memory depends on the sizes of the CTIS, CTIS1, and CTIS2 structures, the size of the FILNO data type, and the maximum number of files requested by the client when it connects to the server. The server automatically increases the file number limit as needed when the client requests using a file number that exceeds the current file number limit, up to the MAX_FILES_PER_USER server configuration option.

The formula for calculating ISAM memory use is as follows, where <fils> is the maximum number of files requested by the client:

sizeof(CTIS) +
<fils> * sizeof(CTIS1) +
<fils> * sizeof(CTIS2 *) +
2 * <fils> * sizeof(FILNO *) +
<fils> * MAX_KEY_SEG * sizeof(CTIS2) +
2 * <fils> * MAX_DAT_KEY * sizeof(FILNO)

Typical values for 64-bit Windows are:

sizeof(CTIS) = 3160
sizeof(CTIS1) = 80
sizeof(CTIS2 *) = 8
sizeof(FILNO) = 4
sizeof(CTIS2) = 12
MAX_KEY_SEG = 16
MAX_DAT_KEY = 64

Block encryption buffer:

For each connection the server allocates a buffer for encrypting data in blocks of size 32768 rounded up to a multiple of the LOG_PAGE_SIZE server configuration option (which defaults to 8192).

User file control blocks:

The server allocates memory to hold connection level state information about each file that a connection has opened. The amount of memory depends on the size of the FUSR structure and the maximum number of files requested by the client when it connects to the server. The server automatically increases the file number limit as needed when the client requests using a file number that exceeds the current file number limit, up to the MAX_FILES_PER_USER server configuration option, which defaults to 32767.

The formula for calculating user file control block memory use is as follows, where <fils> is the maximum number of files requested by the client:

<fils> * sizeof(FUSR)

A typical value for 64-bit Windows is:

sizeof(FUSR) = 504

Transaction mark list buffer:

The server allocates a buffer to manage transaction marks in index nodes. The buffer size is given by the following formula:

PAGE_SIZE / 128 * 16 * 6

PAGE_SIZE defaults to 32768.

Preimage space hash bins:

The server allocates hash bins for efficiently searching preimage space. The memory use is given by the following formula:

PREIMAGE_HASH * sizeof(SHADLST *)

PREIMAGE_HASH defaults to 128.

sizeof(SHALST *) is 8 for 64-bit systems and 4 for 32-bit systems.

ISAM context hash bins:

The server allocates hash bins for efficiently searching ISAM contexts. The memory use is given by the following formula:

CONTEXT_HASH * sizeof(ctICON *)

CONTEXT_HASH defaults to 6.

sizeof(ctICON *) is 8 for 64-bit systems and 4 for 32-bit systems.

ISAM context state:

Each ISAM context allocates memory for each index whose state is stored in the ISAM context. The formula to calculate the memory use is as follows:

(sizeof(ctCONBUF) + key length) rounded up to multiple of sizeof(ctCONBUF)

sizeof(ctCONBUF) is 24 for 64-bit systems and 16 for 32-bit systems.

User level lock hash bins:

The server allocates hash bins for efficiently searching the user lock table. The memory use is given by the following formula:

LOCK_HASH * sizeof(ULOKHSH)

LOCK_HASH defaults to 16.

sizeof(ULOKHSH) is 16 for 64-bit systems and 8 for 32-bit systems.

Preimage space entries:

Each operation on a transaction controlled file creates a preimage space entry, which contains information about the operation. This information can include a data record image or a key value.

Memory used for each preimage space entry:

sizeof(SHADLST) + data length

data length is the size of the record image or a key value

Example structure size for 64-bit Windows server:

sizeof(SHADLST) = 128

Lock table entries:

Each record that is locked has a system lock table entry (RECLOK). Each record lock request creates a user lock table entry (LOKS). Because more than one read lock can be held on a particular record, when using read locks more than one user level lock entry can exist for a system lock table entry.

Table read locks and table write locks can be used to reduce memory use by locking the entire table rather than locking a large number of individual records.

Memory used for each record that is locked:

sizeof(RECLOK) + alignment

Memory used for each record lock that a connection has acquired:

sizeof(LOKS) + alignment

Example sizes for 64-bit Windows server:

sizeof(RECLOK) + alignment = 88

sizeof(LOKS) + alignment = 40

Configure ports and services

Configure protocols, ports, and services

This section defines how to configure the services of a FairCom server. It shows how to configure services with specific protocols and ports.

The FairCom default configuration matches common industry settings for the protocols, ports, and services it offers. All additional services are also configured at startup using the services.json file (previously called cthttpd.json). The services.json file is located in the <faircom>\config folder.

You may want to change ports:

  • To avoid colliding with a port used by an existing application.

  • To avoid a port blocked by a firewall.

  • To run multiple instances of the FairCom server on the same computer.

Note

See also:

Ports, Protocols, and Services can be configured in the services.json file

portsprotocolsservicesconfigurationsettingsservices.json

How to use services.json

This section outlines the properties included in services.json.

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

specifies the folder relative to <faircom>/server/ where FairCom's web applications are located on disk

"./web/apps/"

Note

There is rarely a reason to change this.

string

applications

contains specifications for the web applications that can run with the FairCom server

[]

array of objects

applications
.enabled

(optional) enables or disables a web application

false

Boolean

true
false
applications
.folderName

specifies the folder name where web application code is stored

Required - No default value

string

1 to 64 bytes

applications
.serviceLibrary

(optional) specifies the name of a dynamically loaded library that provides an API and background jobs for the application.

""

string

1 to 64 bytes

applications
.serviceName

(optional) specifies a friendly name for the web application. The FairCom server ignores this property

""

string

1 to 64 bytes

applications
.uriPath

(optional) specifies the folder that contains the serviceLibrary file.

""

string

1 to 64 bytes

authenticationMethods

specifies the allowed MQTT authentication methods

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

array of objects

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

codeServices

specifies which programming languages are available in the product

[]

array of objects

"serviceName"
"serviceLibrary"
"enabled"
codeServices
.enabled

specifies whether or not the feature is enabled

true

Boolean

true
false
codeServices
.serviceLibrary

specifies the filename (on disk) of the app server's dynamic library

""

string

codeServices
.serviceName

specifies the name of the code service that provides the programming language runtime environment

"javascript"

string

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

1 to 64 bytes

defaultOwnerName

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

"admin"

string

1 to 64 bytes

integrationServices

describes and controls FairCom's integration services

{}

array of objects

listeners

describes and controls FairCom's listeners

{}

array of objects

listeners
.tls

(optional) specifies the filenames of the public server certificate, private key, and certificate authority. It also specifies allowed cipher suites and client certificate requirements

{}

object

listeners
.tls
.allowedCipherSuites

(optional) specifies the ciphers that the server will accept for communications with clients

""

string

listeners
.tls
.caCertificateFilename

(optional) specifies the name and optional path of the CA certificate file

""

string

listeners
.tls
.clientCertificateFilename

(optional) specifies the name of the client certificate file

""

string

listeners
.tls
.clientPrivateKeyFilename

(optional) specifies the name of the client private key file

""

string

listeners
.tls
.requireClientCertificate

(optional) specifies whether the client certificate is required

false

Boolean

true
false

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

mqtt

(optional) groups the MQTT default values together

{}

object

mqtt
.authenticationMethods

(optional) determines which authentication techniques are accepted by the MQTT broker

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

array

"none"
"password"
"clientCertificate"
mqtt
.defaultDowngradeQoS

(optional) determines the value of the "downgradeQoS" property in "configureTopic"

false

Boolean

true
false
mqtt
.defaultMaxDeliveryRatePerSecond

(optional) determines the default value of the "maxDeliveryRatePerSecond" property in "configureTopic"

0

integer

mqtt
.defaultMaxInflightMessages

(optional) determines the value of the "maxInflightMessages" property in "configureTopic"

20

integer

mqtt
.defaultMessageCommitFrequencyForQoS1

(optional) specifies the default frequency for messages to be committed for QoS 1

1000

integer

mqtt
.defaultMillisecondCommitFrequencyForQoS1

(optional) specifies the default frequency in milliseconds to commit the delivery status for QoS 1

1000

integer

mqtt
.defaultOptimizeForQoS2

(optional) determines the default value for the "optimizeForQoS2" property

false

Boolean

true
false
mqtt
.disableThroughputStats

(optional) determines whether or not the MQTT broker will track the average number of inbound and outbound messages per second

false

Boolean

true
false
mqtt
.enforceQos2DuringRecovery

(optional) guarantees the MQTT broker will not publish a QoS 2 message a second time after a broker recovers from an unexpected downtime

true

Boolean

true
false
mqtt
.eventuallyPersistDeliveryInfo

(optional) when false, causes the server to persist the delivery status of each message to disk to allow for mission-critical QoS 2 messages even in the event of unplanned downtime

false

Boolean

true
false
mqtt
.historyRetentionPeriod

(optional) specifies how long the server stores records that contain MQTT history

30

integer

mqtt
.historyRetentionUnit

(optional) specifies how often the server purges records containing MQTT history

"day"

string

"minute"
"hour"
"day"
"week"
"month"
"year"
"forever"
mqtt
.messageCommitFrequencyForQoS1

(optional) specifies the maximum number of messages the MQTT broker will send before it commits the delivery status to disk

1

integer

mqtt
.millisecondCommitFrequencyforQoS1

(optional) specifies the maximum number of milliseconds the MQTT broker will wait before it commits the delivery status to disk

1

integer

mqtt
.optimizeForQoS2

(optional) ensures the specified topic either delivers maximum performance for QoS 1 messages when set to false or fully supports mission-critical QoS 2 messages when set to true

false

Boolean

true
false
mqtt
.ownerName

(optional) specifies the name of the account that owns the tables created by the MQTT broker

"admin"

string

mqtt
.pollingFrequencyMilliseconds

(optional) specifies the frequency in seconds for all incoming requests over MQTT, HTTP, HTTPS, WS and WSS to be polled

1

integer

mqtt
.statsCollectionFrequencySeconds

(optional) specifies the frequency in seconds for the MQTT broker to collect statistics in the mqtt_stats table

12

integer

mqtt
.statsPublishFrequencySeconds

(optional) specifies the frequency in seconds for the MQTT broker to publish MQTT messages containing statistics about connections, subscribers, and topics

30

integer

mqtt
.statsRetentionPeriod

(optional) specifies how long the server stores records that contain MQTT statistics

14

integer

mqtt
.statsRetentionUnit

(optional) specifies how often the server purges records containing MQTT statistics in the mqtt_stats table

"day"

string

"minute"
"hour"
"day"
"week"
"month"
"year"
"forever"

otherServices

 an optional array of objects that describes and controls FairCom's other services.

The services connected when the server last started up.

array of objects

transformServices

an optional array of objects that describes and controls FairCom's transform services.

The services connected when the server last started up.

array of objects



"apis"

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

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 specifies the location of web applications relative to <faircom>/server/ .

The default value of "./web/apps/" translates to the folder <faircom>/server/web/apps.

There is rarely a reason to change the "applicationRoot".

For information on how to add your own web applications, which can use any of FairCom's jsonAction APIs, contact FairCom.

"applications"

The "applications" property is an array of objects that describes and controls web applications that can run with the FairCom server. It defaults to an empty array which means no applications are configured to run.

FairCom and other custom web applications are single-page, browser-based applications served from folders in the default <faircom>/server/web/apps/ folder.

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

Contact FairCom for information on how to build and add your own app servers using C or C++.

The following "applications" properties should be considered for each web app:

"applications"."folderName"

The "folderName" property specifies the folder within the "applicationRoot" folder that contains the code the FairCom web server delivers to the browser. This folder contains all code-related files such as HTML, CSS, JavaScript files, and so forth.

Only when the "enabled" property in the same object is true will the FairCom web server deliver the folder's code to the web browser, as shown in the following example for FairCom's ACE Monitor application.

{
  "serviceName": "Ace Monitor",
  "folderName": "AceMonitor",
  "serviceLibrary": "ctmonitor.dll",
  "enabled": true
},

In this example, the web application will be stored in the <faircom>/server/web/apps/AceMonitor/ folder.

Tip

Set the "enabled" property to false for each application you want to disable. In addition, the FairCom web server will not deliver any application if the "applications" property is missing or all application objects set "enabled" to false.

Warning

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

"applications"."serviceLibrary"
"applications"."uriPath"
"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.

"codeServices"."enabled"

The "enabled" property is an optional Boolean that specifies whether or not the feature is enabled.

"codeServices"."serviceLibrary"
"codeServices"."serviceName"

The "serviceName" property is a case insensitive, optional property that defaults to "javascript".  It specifies the name of the code service that provides the programming language runtime environment.

The "serviceName"  property maps to a section in the services.json file called "codeServices" that defines which programming languages are available in the product.

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

In services.json, multiple code language services can be created with different "serviceName" properties, such as "javascript", "javascript2023", and "javascript2027". This allows the developer of a code package to do things like use "javascript" to specify the latest version of the JavaScript code service or target a specific version of the JavaScript engine using a more specific "serviceName".

Each service may use the same or different dynamic libraries (.dll, .so, or .dylib) to provide the programming language runtime. The same dynamic library may also be reused in other services, such as transform services.

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

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

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

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

  • A listener is a service that listens on a specified TCP/IP port for a specified protocol.

  • FairCom servers provide listeners for the protocols:

    • "http"

    • "https"

    • "mqtt"

    • "mqtts"

    • "mqttws"

    • "mqttwss"

  • Each protocol is hardwired to a specific set of backend services:

    • The HTTP and HTTPS protocols are hardwired to support the jsonAction APIs and web applications. 

    • The MQTT and MQTTS protocols are hardwired to support MQTT protocols 3.1.1 and 5.0 over TCP/IP.

    • The MQTTWS and MQTTWSS protocols are hardwired to support MQTT protocols 3.1.1 and 5.0 over WebSocket.

  • For information on how to build and add your own listeners using C or C++, contact FairCom.

  • Do not change the object property settings unless disabling an unused listener.

  • Each protocol can listen with TLS authentication for secure communications.

"listeners"."tls"

The "tls" property is a JSON object that defines the public server certificate filename, the private key filename, the certificate authority filename, the cipher suites that are allowed, and whether the client certificate is required. This property is optional. It defaults to an empty object. 

Example
"tls": { "serverCertificateFilename": "server.crt", "privateKeyFilename": "server.key", "caCertificateFilename": "ca.crt", "allowedCipherSuites": "AES256-SHA256" "requireClientCertificate": "true"
}
"listeners"."tls"."allowedCipherSuites"
"listeners"."tls"."caCertificateFilename"
"listeners"."tls"."clientCertificateFilename"
"listeners"."tls"."clientPrivateKeyFilename"
"listeners"."tls"."requireClientCertificate"
"maxConnectionsPerIpAddress"

The "maxConnectionsPerIpAddress" property is the number of TCP/IP connections the app server will accept from a single TCP/IP address.

This feature is implemented at the FairCom App Server level to prevent the app server from being overwhelmed by a DoS attack. It protects against simultaneous DoS attacks across multiple protocols: HTTP, HTTPS, MQTT, MQTTS, WS, and WSS.

The default is 25 connections.

A value of 0 disables this protection.

This property can be added to the top level of the services.json file and/or to each listener object in the "listeners" array. At the top level, the property applies to all listeners. Within a listener, it applies only to that listener.

In the case that your connections are routed through a firewall or load balancer, you may need to disable this feature since the connections will come from the same IP address.

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.

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.

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.

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

The "mqtt" property is an optional object that defaults to {} and groups the MQTT default values together.

"mqtt"."authenticationMethods"

The "authenticationMethods" property defines which authentication techniques are accepted by the MQTT broker. To enable an authentication technique, include it in the list. To disable an authentication technique, remove it from the list. For example, remove "none" and "password" from the list to require all clients to authenticate using only client certificates. The default value is "authenticationMethods": [ "none", "password", "clientCertificate" ], which causes the broker to accept all client authentication techniques.

The broker supports the following authentication techniques:

  • "none" allows clients to connect without authentication.

  • "password" enables clients to connect using a username and password.

  • "clientCertificate" supports clients sending an X.509 client certificate to the broker for authentication. The certificate must include the username in the certificate's Common Name (CN) field.

"mqtt"."defaultDowngradeQoS"

The "defaultDowngradeQoS" property sets the default value of the "downgradeQoS" property in "configureTopic". It is optional and defaults to false. The MQTT broker uses this value when a topic does not include the "downgradeQoS" property. Use the "downgradeQoS" property to set each topic to a different setting. When false, it enables FairCom MQ's unique ability to deliver messages using the QoS requested by subscribers regardless of the QoS provided by publishers. When true, the MQTT broker lowers the quality of service (QoS) of outgoing MQTT messages to match the QoS of incoming messages.

"mqtt"."defaultMaxDeliveryRatePerSecond"

The "defaultMaxDeliveryRatePerSecond" property sets the default value of the "maxDeliveryRatePerSecond" property in "configureTopic". It is optional and defaults to 0, which causes the broker to send messages as fast as possible. A value between 1 and 1000 helps keep a client from being overwhelmed with too many messages sent too quickly. It must be a value between 0 and 2147483647. The MQTT broker uses this value when a topic does not include the "maxDeliveryRatePerSecond" property. Use the "maxDeliveryRatePerSecond" property to set each topic to a different setting.

"mqtt"."defaultMaxInflightMessages"

The "defaultMaxInflightMessages" property sets the default value of "maxInflightMessages" in "configureTopic". It is optional and defaults to 20. It causes the broker to send up to 20 messages without waiting for subscribers to acknowledge published packets. Setting this property to a larger number increases performance but may overwhelm some subscribers. The MQTT broker uses this value when a topic does not include the "maxInflightMessages" property. Use the "maxInflightMessages" property to set each topic to a different setting.

"mqtt"."defaultMessageCommitFrequencyForQoS1"

The "defaultMessageCommitFrequencyForQoS1" property specifies the default frequency for messages to be committed for QoS 1. The default value is 1000 to deliver all messages as quickly as possible. The "optimizeForQoS2" property automatically uses the value of this property to set the default value of the "messageCommitFrequencyForQoS1" property in the "configureTopic" action, which you can optionally assign to each topic. 

When most messages are QoS 0 or 1, in services.json, you can set "defaultMessageCommitFrequencyForQoS1" to a number greater than 0, such as 1000. It delays committing the delivery status to disk by the specified number of messages, which causes the MQTT broker to use volatile RAM to track delivery status. Delaying the persistence of delivery status increases delivery speed, but when the MQTT broker encounters unexpected downtime, the broker resends messages up to the number specified in this property, which is a problem for QoS 2 messages but not for QoS 0 and QoS 1 messages. When you need a specific topic to support QoS 2, use the "configureTopic" action to set the "MessageCommitFrequencyForQoS1": 0 to ensure previously sent QoS 2 messages are not resent while the server recovers from unplanned downtime. 

When most messages are QoS 2, you can add "defaultMessageCommitFrequencyForQoS1": 0 to services.json. This setting causes the server to commit each message's delivery status to disk, which ensures previously sent QoS 2 messages are not resent while the server recovers from unplanned downtime. When you need a specific topic to support QoS 0 or 1 for maximum performance, use the "configureTopic" action to set "MessageCommitFrequencyForQoS1" to a number greater than 0, such as 1000.

"mqtt"."defaultMillisecondCommitFrequencyForQoS1"

The "defaultMillisecondCommitFrequencyForQoS1" property specifies the default frequency in milliseconds to commit the delivery status for QoS 1. The "optimizeForQoS2" property automatically uses the value of this property to set the default value of the "MillisecondCommitFrequencyForQoS1" property in the "configureTopic" action, which you can optionally assign to each topic. The default value is 1000 to deliver all messages as quickly as possible. 

When most messages are QoS 0 or 1, in services.json, you can set "defaultMillisecondCommitFrequencyForQoS1" to a number greater than 0, such as 1000. It delays committing the delivery status to disk by the specified number of milliseconds, which causes the MQTT broker to use volatile RAM to track delivery status. Delaying the persistence of delivery status increases delivery speed, but when the MQTT broker encounters unexpected downtime, the broker resends messages, which is a problem for QoS 2 messages but not for QoS 0 and QoS 1 messages. When you need a specific topic to support QoS 2, use the "configureTopic" action to set the "millisecondCommitFrequencyForQoS1": 0 to ensure previously sent QoS 2 messages are not resent while the server recovers from unplanned downtime. 

When most messages are QoS 2, you can add "defaultMillisecondCommitFrequencyForQoS1": 0 to services.json. This setting causes the server to commit each message's delivery status to disk, which ensures previously sent QoS 2 messages are not resent while the server recovers from unplanned downtime. When you need a specific topic to support QoS 0 or 1 for maximum performance, use the "configureTopic" action to set "MillisecondCommitFrequencyForQoS1" to a number greater than 0, such as 1000.

"mqtt"."defaultOptimizeForQoS2"

The "defaultOptimizeForQoS2" property sets the default value for the "optimizeForQoS2" property. It defaults to false for maximum performance. Set to false in the "mqtt" section of the services.json file when you expect most messages to use QoS 1 for the fastest performance. Set to true in the "mqtt" section of the services.json file when you expect most messages to use QoS 2, which is appropriate for mission-critical applications that cannot receive messages more than once, such as MQTT command messages and the data change messages from FairCom DB Notify. You can override this default value in each topic by using the "configureTopic" action to assign a different value to the "optimizeForQoS2" property. QoS 0 messages are unaffected by this property and always run at maximum performance.

"mqtt"."disableThroughputStats"

The "disableThroughputStats" property controls how the MQTT broker tracks the number of inbound and outbound messages per second. Set to true to stop the MQTT Broker from tracking the average number of inbound and outbound messages per second. It defaults to false. When set to false, the broker tracks the throughput of all incoming and outgoing messages, which is helpful in troubleshooting usage spikes. Throughput tracking slightly slows down MQTT performance. Disable throughput tracking by omitting the property or setting it to null or false.

"mqtt"."enforceQos2DuringRecovery"

The "enforceQos2DuringRecovery" property guarantees the MQTT broker will not publish a QoS 2 message a second time after a broker recovers from an unexpected downtime. To do this, the broker must persist the packet transfer state of each QoS 2 message, which slows the speed of message delivery to QoS 2 subscribers. This feature works at the broker level. It is configured once for the broker and applies to all topics and subscribers. The default value is false.

"mqtt"."eventuallyPersistDeliveryInfo"

Warning

Changing to true may cause you to lose QoS 1 and 2 messages. It also prevents you from implementing high availability. FairCom does not recommend using true.

Warning

Do not change this setting if you want to preserve your settings in FairCom MQ and FairCom Edge. To change this setting, you must shut down the FairCom server, delete the faircom xdatabase, change the setting's value, and restart the server to rebuild its delivery tracking tables.

The "eventuallyPersistDeliveryInfo" property determines whether the server will persist the delivery status of each message to disk. It defaults to false,  which causes the server to persist the delivery status of each message to disk. FairCom recommends false because it allows FairCom's MQTT broker to support mission-critical QoS 2 messages – even when the server is recovering from unplanned downtime.

Set it to true for faster message delivery when you only want to support QoS 0 and 1. Setting it to true prevents FairCom's MQTT broker from supporting mission-critical QoS 2 messages because when the server is recovering from an unplanned downtime, it may resend QoS 2 messages, which violates the MQTT specification. 

In more technical terms, this setting controls whether the broker commits the delivery status of MQTT packets to the transaction log on disk or commits delivery status to volatile RAM using FairCom's PREIMG technology, where the server eventually writes the changes to disk.

"mqtt"."historyRetentionPeriod"

The "historyRetentionPeriod" property controls how long the server stores records that contain MQTT history. It is a positive integer number. For example, when you set "historyRetentionPeriod" to 5 and "historyRetentionUnit" to "day", the server retains records for five days, and, at the beginning of each day, the server removes records older than five days.

See "historyRetentionUnit".

"mqtt"."historyRetentionUnit"

The "historyRetentionUnit" property controls how often the server purges records containing MQTT history.

These records are in the following tables in the FairCom database:

  • mqtt_connection_topic_history

  • mqtt_connection_history

  • mqtt_command_history

  • mqtt_subscription_history

You may set "historyRetentionUnit" to:

  • "minute"

  • "hour"

  • "day"

  • "week"

  • "month"

  • "year"

  • "forever"

See "historyRetentionPeriod".

"mqtt"."messageCommitFrequencyForQoS1"

The "messageCommitFrequencyForQoS1" property sets the maximum number of messages the MQTT broker will send before it commits the delivery status to disk. A larger number increases the time between committed messages, which improves performance, but during recovery from unplanned downtime, it allows the broker to resend packets it has already sent. A non-zero number is a problem for QoS 2 messages, which should be sent only once.

When it is set to 1 or less, the delivery information for each message is committed when the message is delivered, and the "millisecondCommitFrequencyForQoS1" property is set to 0 to disable the timer because it is not needed.

When the "optimizeForQoS2" property is true, it sets the value of this property to 0 to support Qos 2 messages. This setting ensures the MQTT broker does not resend previously sent QoS 2 messages while recovering from unplanned downtime. Command and data change messages typically require QoS 2 because they must be delivered only once.

When the "optimizeForQoS2" property is false, it sets the value of this property to "defaultMessageCommitFrequencyForQoS1" unless you assign a value to the "messageCommitFrequencyForQoS1" property.

When a topic only supports QoS 0 and 1 messages, you may set the value to an integer number greater than 0, such as 1000. It delays committing the delivery status to disk by the specified number of messages, which causes the MQTT broker to use volatile RAM to track delivery status for faster message delivery. Many messages, such as telemetry, status, queries, birth notice, and death notice, use QoS 0 or 1 when the client can tolerate receiving the same message more than once.

The "messageCommitFrequencyForQoS1" and "millisecondCommitFrequencyForQoS1" properties work together to ensure no more than the maximum number of messages and milliseconds occur before the server commits the delivery status to disk.

"mqtt"."millisecondCommitFrequencyForQoS1"

The "millisecondCommitFrequencyForQoS1" property sets the maximum number of milliseconds the MQTT broker will wait before it commits the delivery status to disk. A larger number increases the time between committed messages, which improves performance, but during recovery from unplanned downtime, it allows the broker to resend packets it has already sent. A non-zero number is a problem for QoS 2 messages, which should be sent only once.

When the "optimizeForQoS2" property is true, it sets the value of this property to 0 to support QoS 2 messages. This setting ensures the MQTT broker does not resend previously sent QoS 2 messages while recovering from unplanned downtime. Command and data change messages typically require QoS 2 because they must be delivered only once.

When the "optimizeForQoS2" property is false, it sets the value of this property to "defaultMillisecondCommitFrequencyForQoS1" unless you assign a value to the "millisecondCommitFrequencyForQoS1" property.

When a topic only supports QoS 0 and 1 messages, you may set the value to an integer greater than 0, such as 1000. It delays committing the delivery status to disk by the specified number of milliseconds, which causes the MQTT broker to use volatile RAM to track delivery status for faster message delivery. Many messages, such as telemetry, status, queries, birth notice, and death notice, use QoS 0 or 1 when the client can tolerate receiving the same message more than once.

The "messageCommitFrequencyForQoS1" and "millisecondCommitFrequencyForQoS1" properties work together to ensure no more than the maximum number of messages and milliseconds occur before the server commits the delivery status to disk.

"mqtt"."optimizeForQoS2"

The "optimizeForQoS2" property ensures the specified topic either delivers maximum performance for QoS 1 messages when set to false or fully supports mission-critical QoS 2 messages when set to true. It defaults to false for maximum performance.

When false, the topic uses the value you specify in "MessageCommitFrequencyForQoS1". If omitted, "MessageCommitFrequencyForQoS1" is set to "defaultMessageCommitFrequencyForQoS1".

When false, the topic uses the value you specify in "MillisecondCommitFrequencyForQoS1". If omitted, "MillisecondCommitFrequencyForQoS1" is set to "defaultMillisecondCommitFrequencyForQoS1".

When true, it assigns the following property values to the topic and ignores any values you apply to these properties:

"MessageCommitFrequencyForQoS1": 1

"MillisecondCommitFrequencyForQoS1": 0

QoS 0 messages are unaffected by this property and always run at maximum performance.

Note

When true, this setting causes the server to persist additional two-phase commit information for each sent message. This information is required for the server to know if it has already sent a message. Persisting this extra information slows message delivery but ensures the server correctly handles duplicate messages during a server restart after an unplanned downtime.

"mqtt"."ownerName"

The "ownerName" property sets the account name that owns the tables created by the MQTT broker. It defaults to "admin". You can set it to any valid account name. It is a security best practice to set the owner name to an account with limited privileges.

"mqtt"."pollingFrequencyMilliseconds"

The "pollingFrequencyMilliseconds" property controls the polling frequency of all incoming requests over MQTT, HTTP,  HTTPS, WS, and WSS. Thus, it affects the latency and throughput of all MQTT, JSON action APIs, and Web applications. It defaults to 1, which causes the server to poll for an incoming event every millisecond. This setting provides the lowest latency and maximum throughput performance. This setting works well on all but the slowest computers, such as old Raspberry PI computers. A higher number decreases CPU usage and power consumption and increases the latency for detecting incoming messages and API requests.

"mqtt"."statsCollectionFrequencySeconds"

The "statsCollectionFrequencySeconds" property sets the frequency in seconds for the MQTT broker to collect statistics in the mqtt_stats table, which is required for the MQ Dashboard to work. The default value is 12 seconds. The following values turn off the insertion of statistics records into the mqtt_stats table: omitting the property, setting it to null, or setting it to a value <= 0. A smaller value increases the accuracy of the MQ Explorer dashboard, but it slightly slows down the overall performance of the MQTT broker.

"mqtt"."statsPublishFrequencySeconds"

The "statsPublishFrequencySeconds" property sets the frequency in seconds for the MQTT broker to publish MQTT messages containing statistics about connections, subscribers, and topics. Each message is a JSON object that includes extensive information about the current state of the MQTT broker. Do the following to turn off publishing these messages: omit the property, set it to null, or set it to a value <= 0. A smaller value increases the number of messages sent per second and slightly slows down the overall performance of the MQTT broker.

  • The MQTT broker publishes these statistic messages to the topic names specified in "connectionStatsTopicName", "subscriberStatsTopicName", and "topicStatsTopicName". 

  • The MQTT broker also stores the messages for each statistic topic in an integration table. The broker stores the message in the "source_payload" field. The broker derives the name of an integration table from its corresponding MQTT topic name. For example, a topic named "faircomAdmin/connections" causes a table to be created and named mqtt_msg_faircomadmin_connections.

"mqtt"."statsRetentionPeriod"

The "statsRetentionPeriod" property controls how long the server stores records that contain MQTT statistics. It is a positive integer number. For example, when you set "statsRetentionPeriod" to 5 and "statsRetentionUnit" to "day", the server retains records for five days, and, at the beginning of each day, the server removes records older than five days.

This property applies to the mqtt_stats table and the integration tables created by the "connectionStatsTopicName", "subscriberStatsTopicName", and "topicStatsTopicName" properties.

See "statsRetentionUnit".

"mqtt"."statsRetentionUnit"

The "statsRetentionUnit" property controls how often the server purges records containing MQTT statistics in the mqtt_stats table.

You may set it to:

  • "minute"

  • "hour"

  • "day"

  • "week"

  • "month"

  • "year"

  • "forever"

See "statsRetentionPeriod"

"otherServices"

The "otherServices" property is an optional array of objects that describes and controls FairCom's other services. It defaults to the services connected when the server last started up.

"otherServices": [
  {
    "serviceName": "dbnotify",
    "serviceLibrary": "./dbnotify/fcdbnotify.dll",
    "enabled": false
  }
],
"transformServices"

The "transformServices" property is an optional array of objects that describes and controls FairCom's transform services. It defaults to the services connected when the server last started up.

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

Example services.json configuration file

{
  "maxConnectionsPerIpAddress": 5,
  "listeners": [
  {
    "serviceName": "http8080",
    "description": "Port 8080 using insecure HTTP protocol for REST and Web Apps on all TCP/IP addresses bound to this server",
    "port": 8080,
    "protocol": "http",
    "enabled": false
  },
  {
    "serviceName": "https8443",
    "description": "Port 8443 using TLS-secured HTTPS protocol for REST and Web Apps on all TCP/IP addresses bound to this server",
    "port": 8443,
    "protocol": "https",
    "enabled": true,
    "tls": {
      "serverCertificateFilename": "./web/fccert.pem",
      "allowedCipherSuites": "",
      "caCertificateFilename": "",
      "clientCertificateFilename": "",
      "clientPrivateKeyFilename": "",
      "requireClientCertificate": false
    }
  },
  {
    "serviceName": "mqtt1883",
    "description": "Port 1883 using insecure MQTT protocol for the MQTT broker on all TCP/IP addresses bound to this server",
    "port": 1883,
    "protocol": "mqtt",
    "enabled": true
  },
  {
    "serviceName": "mqtts8883",
    "description": "Port 8883 using TLS-secured MQTTS protocol for the MQTT broker on all TCP/IP addresses bound to this server",
    "port": 8883,
    "protocol": "mqtts",
    "enabled": true,
    "tls": {
      "serverCertificateFilename": "./web/fccert.pem"
    }
  },
  {
    "serviceName": "mqttws9001",
    "description": "Port 9001 using WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this server",
    "port": 9001,
    "protocol": "mqttws",
    "enabled": true
  },
  {
    "serviceName": "mqttwss9002",
    "description": "Port 9002 using TLS-secured WebSocket protocol for the MQTT broker on all TCP/IP addresses bound to this server",
    "port": 9002,
    "protocol": "mqttwss",
    "enabled": true,
    "tls": {
      "serverCertificateFilename": "./web/fccert.pem"
    }
  }

  ],

  "jsonActionApiDefaults":
  {
    "defaultApi": "hub",
    "defaultBinaryFormat": "hex",
    "defaultDatabaseName": "faircom",
    "defaultDebug": "max",
    "defaultOwnerName": "admin",
    "defaultResponseOptions":
    {
      "binaryFormat": "hex",
      "dataFormat": "objects",
      "numberFormat": "number"
    },
    "idleConnectionTimeoutSeconds": 3600,
    "idleCursorTimeoutSeconds": 600,
    "defaultRetentionPolicy": "autoPurge",
    "defaultRetentionUnit": "week",
    "defaultRetentionPeriod": 4,
    "maxJsonApiSessions": 1024,
    "maxJsonApiSessionsPerIpAddress": 50,
    "maxJsonApiSessionsPerUsername": 50,
    "enablePermanentJsonApiSessions": true
  },

  "applicationRoot": "./web/apps/",
  "pollingFrequencyMilliseconds": 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,

    "disablePersistence": "no",
    "defaultMessageCommitFrequencyForQoS1": 100,
    "defaultMillisecondCommitFrequencyForQoS1": 1000,
    "defaultOptimizeForQoS2": false,
    "enforceQos2DuringRecovery": true,
    "eventuallyPersistDeliveryInfo": false,
    "messageCommitFrequencyForQoS1": 1,
    "millisecondCommitFrequencyForQoS1": 1,
    "optimizeForQoS2": false,
    "ownerName": "admin"
  },

  "storeAndForward":
  {
    "controlSentPosition": false,
    "transactionLog": true
  },

  "applications": [
  {
    "serviceName": "Ace Monitor",
    "uriPath": "AceMonitor",
    "serviceLibrary": "ctmonitor.dll",
    "enabled": true
  },
  {
    "serviceName": "Data Explorer",
    "uriPath": "SQLExplorer",
    "serviceLibrary": "ctsqlexplorer.dll",
    "enabled": true
  },
  {
    "serviceName": "ISAM Explorer",
    "uriPath": "ISAMExplorer",
    "serviceLibrary": "ctisamexplorer.dll",
    "enabled": true
  }
  
  ],

  "apiRoot": "./api",

  "apis": [
  {
    "serviceName": "hub",
    "enabled": true
  },
  {
    "serviceName": "mq",
    "enabled": true
  },
  {
    "serviceName": "db",
    "enabled": true
  },
  {
    "serviceName": "transform",
    "enabled": true
  }
  ],

  "integrationServices": [
  {
    "serviceName": "opcua",
    "serviceLibrary": "opcservice.dll",
    "schemaName": "opcua",
    "enabled": true
  },
  {
    "serviceName": "modbus",
    "serviceLibrary": "modbusservice.dll",
    "schemaName": "modbus",
    "enabled": true
  },
  {
    "serviceName": "ab",
    "serviceLibrary": "abservice.dll",
    "schemaName": "ab",
    "enabled": true
  },
  {
    "serviceName": "siemensS7",
    "serviceLibrary": "siemenss7service.dll",
    "schemaName": "siemensS7",
    "enabled": true
  },
  {
    "serviceName": "rest",
    "serviceLibrary": "restservice.dll",
    "schemaName": "rest",
    "enabled": true
  }
  ],

  "transformServices": [
  {
    "serviceName": "siemensUDT2JSON",
    "serviceLibrary": "siemensudtservice.dll",
    "enabled": false
  },
  {
    "serviceName": "v8TransformService",
    "serviceLibrary": "v8transformservice.dll",
    "enabled": false
  }
  ],

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

  "otherServices": [
  {
    "serviceName": "dbnotify",
    "serviceLibrary": "./dbnotify/fcdbnotify.dll",
    "enabled": false
  },
  {
    "serviceName": "ctagent",
    "serviceLibrary": "./agent/ctagent.dll",
    "enabled": false
  },
  {
    "serviceName": "thingworx",
    "serviceLibrary": "./thingworx/ctthingworx.dll",
    "enabled": false
  },
  {
    "serviceName": "aggregation",
    "serviceLibrary": "./aggregation/cttimestamp.dll",
    "enabled": false
  }
  ]
}

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

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

Enable and disable web applications

Edit the <faircom>/config/services.json file to enable or disable the FairCom server from running all web applications or specific web applications.

All applications

 

To enable all web applications to run, set the "applicationRoot" property value to <faircom>/server/web/apps.

To disable all web applications from running set the "applicationRoot" property to an empty string (""), null, or omit it from services.json.

Examples 

Allow applications to run

"applicationRoot": "<faircom>/server/web/apps",

"applications": []

Do not allow any applications to run

"applicationRoot": "",

"applications": []
Specific applications

Use the "applications" property in services.json to control when the FairCom server allows specific web applications to run. The FairCom server rejects all HTML page requests for an application unless it is properly enabled and configured in the "applications" property.

Note

The "applicationRoot" property value must also be set to enable web applications.

If these conditions are met, the FairCom server will return files found in the designated folder and its subfolders.

Examples 

Allow the Ace Monitor application to run.

"applications":[
  {
    "serviceName": "Ace Monitor",
    "folderName": "AceMonitor",
    "uriPath": "AceMonitor",
    "serviceLibrary": "ctmonitor.dll",
    "enabled": true
  }
]

Do not allow the Ace Monitor application to run.

"applications": [
  {
    "serviceName": "Ace Monitor",
    "folderName": "AceMonitor",
    "uriPath": "AceMonitor",
    "serviceLibrary": "ctmonitor.dll",
    "enabled": false
  }
]

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 9. 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 4. 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 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 5. 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 6. 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 10. 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.

jsonAction defaults

Set server-wide defaults for jsonAction APIs

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

Note

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

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


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

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

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 jsonActionAPIs and browser-based applications.

Example 8. Keeping SQL_DATABASE and "jsonActionApiDefaults" in sync

ctsrvr.cfg 

SQL_DATABASE my_new_database

services.json 

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


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

jsonAction defaultsjsonAction APIservices.jsonjsonActionApiDefaultsdefault settingsjson action defaults

Manage FairCom DB plug-ins

Plug-Ins and Callbacks Extend the FairCom Database Engine

Beginning with FairCom V12 a new ability to extend functionality with advanced modular capabilities is provided. Using a new plug‑in architecture, advanced features can be quickly dropped in using independently configured plug-ins that are provided as a shared object with companion configuration file entries. Each plug-in is usually self-contained in its own folder. All plug-in configurations are stored in the <faircom>\config folder.

Several plug‑ins are provided by default. The following plug-ins are provided beginning with V12:

  1. HTTP web services

  2. MQTT message services

  3. REST API services

  4. OPC communication protocols for Industrial IoT (IIoT) services

  5. UA communication interface for IIoT services

  6. PTC ThingsWorx® IIoT integration

  7. PTC ThingWorx® AlwaysOn IIoT protocols

Most of the provided plug-ins are not enabled by default to maximize security and minimize memory usage. FairCom plug‑ins are securely implemented but they can increase the attack surface by possibly opening additional network ports and listening across alternative communication protocols.

Plug-ins are enabled as needed in the standard FairCom ctsrvr.cfg and services.json files. Each plug-in is individually enabled using a configuration line that includes its configured name and shared object location.

Example

; Plugins
PLUGIN cthttpd;./web/cthttpd.dll
PLUGIN ctagent;./agent/ctagent.dll

The ctsrvr.cfg configuration file is now located in <faircom>\server\config (this location is optional and existing locations are supported for full backward compatibility).

Dynamic plug-ins

Interface for Managing Plug-ins on the fly

Beginning with V13, FairCom plug-in support has been enhanced by providing multiple interfaces for loading, starting, and stopping FairCom plug-ins on the fly. Previously, all plug-ins had to be configured and enabled at server launch. Now plug-ins can be loaded, started, and stopped on demand without restarting the server.

Loading, starting, and stopping plug-ins can be accomplished by either uncommenting them in the ctsrvr.cfg server configuration file, using the ctadmn command-line utility, or calling C API functions. A plug-in must first be loaded then it can be started and stopped.

Command-Line Administrator Utility

You can call ctadmn as a command-line utility to start and stop a plug-in using the following syntax:  

ctadmn -s <server name> -u <user name> -p <password> -c "<command>"

where the <command> is enclosed in quotes as in the following format:

"plugin <plug-in name> start|stop"

ctadmn can execute any generic operation from the plug-in using the following syntax:

ctadmn -s <server> -u <user> -p <password> -c "plugin <plug-in name> <command> <arguments>"

Example 1 - Execute the ctadmn command-line utility with direct arguments and start the web services plug-in:

ctadmn -s FAIRCOMS -u ADMIN -p ADMIN -c "plugin cthttpd start"

Example 2 - Execute the ctadmn command-line utility interactively using option 10 to load and start the web services plug-in:

  1. Execute the ctadmn utility.

  2. Select option 10 - "Change Server Settings."

  3. Again select option 10 - "Change the specified configuration option."

  4. Enter the configuration option and its value:

    >> PLUGIN cthttpd;./web/cthttpd.dll       
Successfully changed the configuration option.

Example 3 – Use the ctadmn command-line utility to restart the OPC/UA plug-in after changing the settings:

  1. Edit the ctopc.json file to add a device or change the connection details to a device.

  2. Stop the OPC plug-in via ctadmn: ctadmn -s FAIRCOMS -u ADMIN -p ADMIN -c "plugin ctopc stop"

  3. Restart the plug-in via ctadmn: &gt;ctadmn -s FAIRCOMS -u ADMIN -p ADMIN -c "plugin ctopc start"

  4. The OPC/UA plug-in will now load the modified configuration file and use the new settings.

Control plug-ins using C API functions

Control plug-ins using the ctSETCFG() and ctPlugin() functions. Use ctSETCFG() to load a plug-in, and use ctPlugin() to start or stop a loaded plug-in.

Example 1 - Load the web services plug-in:

ctSETCFG(setcfgCONFIG_OPTION, "PLUGIN cthttpd;./web/cthttpd.dll");

Where:

  • setcfgCONFIG_OPTION is a general-purpose option used for passing a string value.

  • "PLUGIN cthttpd;./web/cthttpd.dll" (in quotes) is a string containing the same plug-in name and path as shown in your ctsrvr.cfg server configuration file.

Example 2 - Start the web services plug-in:

NINT ctPlugin(ctPLUGIN_COMMAND command, pTEXT inputBuffer, pTEXT outputBuffer, pVRLEN pOutputBufferSize);

Where:

  • command: currently, the options are ctPLUGIN_START or ctPLUGIN_STOP (defined by the ctPLUGIN_COMMAND enum type)

  • inputBuffer is flexible; currently, it expects only the plug-in name (loaded in the server by the PLUGIN keyword in ctsrvr.cfg)

  • outputBuffer: Starting and stopping plug-ins does not have any output, so this is unused. Pass a pointer to a TEXT string.

  • pOutputBufferSize: Starting and stopping plug-ins does not have any output, so this is unused. Pass a pointer to a VRLEN number set to the length of the string passed to outputBuffer.

Example 3 - Stop the web services plug-in:

ctPlugin(ctPLUGIN_STOP, " cthttpd ",outBuff,&outBuffLen);

Manage FairCom DB plug-ins

FairCom DBplug-insmanage plug-inscustomize plug-insconfigure plug-ins

Windows

Configure FairCom product settings in Windows-based systems

Section

Description

Configure installed features using FairComConfig.exe

This section describes the capabilities and modes of FairComConfig.exe, a Windows application that configures the FairCom server on Windows.

Configure the FairCom server as a Windows service

This section contains a procedure to set the two configurable properties using the Windows Services Control Panel applet.

Configure the Tool Tray Interface on Windows

When the server configuration file contains the CONSOLE TOOL_TRAY keyword, it displays a FairCom icon in the Windows tool tray, making it easy to see that the server is running and to shut it down.

Configure FairCom product settings in Windows-based systems

configureWindowsconfigure settingsWindows configurationconfigure tool tray

Configure installed features using FairComConfig.exe

FairComConfig.exe is a Windows application that configures the FairCom server on Windows. This utility is named FairComConfig.exe and is included with the download package in the <faircom>\tools\SetUp\ folder.

FairComConfig.exe capabilities

  • It can install the Visual C++ Redistributable, which is used by the FairCom server on Windows.

  • It can install drivers for ADO.NET, ODBC, and Java Stored Procedures.

  • It can configure Windows firewall exceptions and Windows Start Menu items.

  • It can configure or unconfigure the FairCom server as a Windows service.

    • Installing as a service is useful when you unzip and run the FairCom server manually instead of using the Windows MSI installer.

    • Running the FairCom server as a Windows service is a best practice in a production setting because the FairCom server runs automatically when the computer starts. It also makes it easy for administrators to manage and monitor the service.

    • FairComConfig.exe is the easiest way to remove the FairCom server as a Windows service along with all its dependent features.

This utility has two modes: Configure and Remove

  • Remove: When items have been previously configured, FairComConfig.exe is in the Remove state. Click Remove to unconfigure all FairCom features. The utility then reverts to the Configure state where you can choose which features you want to configure. The Remove button is safe. It does NOT uninstall the FairCom server or delete any data files.

  • Configure: When no items have been previously configured, FairComConfig.exe is in the Configured state. Check the boxes you want to configure and click Configure.

FairComConfig.exe Windows Utility in Config Mode

FairComConfig.exe in Configure mode

FairComConfig.exe Windows Utility in Remove Mode

FairComConfig.exe in Remove mode

For tips on troubleshooting your installation, see Troubleshoot.

Configure the FairCom server as a Windows service

When you install the FairCom server using the Windows Installer, it is automatically configured to run as a Windows Service. If you install it manually by unzipping it into a folder, you need to manually register the FairCom server to run as a service (see Install as a Windows service).

The FairCom service has two configurable properties:

  1. Startup Type

  2. Logon User

These options can be set using the Windows Services Control Panel applet by performing this procedure:

  1. Open the Windows Control Panel by clicking Start > Settings > Control Panel.

  2. Select the Services applet. You will be presented with a list of the installed services.

    services_window.png

    Services applet in the Windows Control Panel

  3. Select the FairCom service, then double-click it or right-click and choose Properties.

  4. The Windows Service configuration options window will appear.

    1. Set the Startup Type on the General tab.

    2. Set the Logon User on the Log On tab.

      svcproperties_vista.png

      Windows service configuration options window

Note

The Microsoft Windows Services control Panel applet is an easy, safe, visual method for managing the FairCom server as a Windows service. You can use it to define how and when the service starts. You can change the logon user. And you can also manually start, stop, pause, and resume the server. You can also do all these things using Microsoft’s command-line utility, sc, which is the preferred way to create automated scripts to manage Windows services.

Use the tool tray on Windows

By default, when a FairCom server runs on Windows as an executable, it puts an icon (RunningIcon.png) in the task tray. Double-clicking the task tray icon opens the FairCom Status window.

FairCom Status window features:

  • Shutdown the FairCom server.

  • View the version of the FairCom server.

  • View the FairCom startup configuration.

Hide the task tray icon:

  1. Navigate to and open the ctsrvr.cfg file within the config folder.

  2. Update the CONSOLE setting to ;CONSOLE.

    Note

    The CONSOLE setting does nothing when the FairCom server runs as a Windows service.

    ;CONSOLE TOOL_TRAY

  3. Select Shutdown from the Control dropdown menu.

    ControlMenuShutdown.png

  4. Restart the FairCom server.

System limits

Limits of FairCom DB attributes

FairCom JSON API actions use required and optional parameters to complete specific operations. The following table shows the limits of these parameters.

Table 11. System attribute limits

Attribute

Description

Limits

disk read/write

Size of disk reads and writes

Limited on Windows

file ID

The file ID number

1 to 4294963200

file size

Size of a file

1 to 16 Exabytes

fixed-length record

Size of a fixed length record.

1 to 64KB

group

Number of users in a group

0 to 16 per user

indices

Number of indices per data file.

0 to 64 (default)

memory files

Memory file limitations

See Memory File Limitations

open files

Number of concurrently opened files

1 to 32767

password

Password limitations

1 to 64 bytes

records per file

Number of records per file

No limit

segments

Number of segments per index

1 to 16 (default)

SQL CHECK constraint clause

Length of a FairCom DB SQL CHECK constraint clause

20000 bytes

SQL column (NATIONAL CHARACTER)

Length of a FairCom DB SQL column for VARBINARY and VARCHAR specifying the character set designated as NATIONAL CHARACTER

1 to 3275 bytes

SQL column (standard)

Length of a FairCom DB SQL column for standard data types.

0 to 65500 bytes

SQL connection string

Length of a FairCom DB SQL connection string

0 to 100 bytes

SQL default value

FairCom DB SQL default value specification

0 to 8192 bytes

SQL error message

Length of a FairCom DB SQL error message

0 to 511 bytes

SQL identifier

Length of a FairCom DB SQL identifier

1 to 32 bytes

SQL nesting levels

Number of FairCom DB SQL nesting levels for view references

0 to 25

SQL procedure arguments

Number of arguments in a FairCom DB SQL CALL statement

0 to 50

SQL recursion level

Number of FairCom DB SQL recursion levels for stored procedures

0 to 10

SQL statement input parameters

Number of input parameters in a FairCom DB SQL statement

0 to 512

SQL statement length

Length of a FairCom DB SQL statement

1 to 32MB (prior to V10.2, the limit was 35,000 characters)

SQL statement nesting levels

Number of nesting levels in a FairCom DB SQL statement

0 to 25

SQL statement outer references

Number of or outer references in a FairCom DB SQL statement

0 to 25

SQL statement table references

Number of table references in a FairCom DB SQL statement

1 to 250

SQL storage attribute

Length of a FairCom DB storage_attribute

1 to 2000 bytes

SQL table check constraints

Number of check constraints in a FairCom DB SQL table

0 to 4000

SQL table columns

Number of FairCom DB columns in a SQL table

1 to 2500

SQL table foreign constraints

Number of foreign constraints in a FairCom DB SQL table

0 to 4000

SQL table index components

Number of index components for all indexes on a FairCom DB SQL table

0 to 2048 (configurable)

SQL view definition

Length of a FairCom DB SQL view definition

1 to 65000 bytes

table name

Length of a table name

1 to 64 bytes

UNIFRMAT

Support for UNIFRMAT files

Available only for non-transaction processed files.

user name

Length of a FairCom DB user name

1 to 31 bytes POSIX standard

variable-length record

Size of a variable length record

1 to 2GB



Disk reads/writes

A large variable-length record read or write operation could fail with Windows error 1450. To avoid this Windows error see  Enforce Maximum Disk Read/Write Sizes on Windows to set the maximum read/write size.

File ID

The file ID number of a transaction-controlled file is incremented each time the file is opened. If error 534, Pending File ID overflow: 534 is written to CTSTATUS.FCS see File ID Overflow.

File size

The file size limit is 16 Exabytes (18 million terabytes). See File Size and Operating System Limits for more information.

Group

The System Administrator can create one or more Groups. Each group is assigned a unique Group ID that is a 32-byte ASCIIZ string.

To provide a convenient way for users with related needs to share information, each user is assigned membership in one to 16 groups. The Administrator adds the groups to the system and assigns users to them. Each user has a default group, which counts as one of the user’s 16 groups. If a user is not assigned to a group, the user’s default group is the GUEST group.

When an application program logs on to the FairCom Server with one of the extended functions, it sends a User ID and user password to the FairCom Server. Logging on with one of the equivalent standard functions or sending a NULL User ID with one of the extended functions automatically assigns the User ID of GUEST and membership in the GUEST group. If a User ID or password that does not exist is sent, the initiating call to the FairCom Server returns an error code and the program is not connected to the FairCom Server.

Indice

The indice limit defaults to 64 but can be increased using MAX_DAT_KEY in ctsrvr.cfg to a theoretical limit of 32767, although a practical limit exists well before this value.

Password

Each User can have an optional user password. The password limit is 64 bytes. For more information about passwords, see Automatically Enforce Password Strength.

Segment

The segment limit defaults to 16 but can be increased using MAX_KEY_SEG in ctsrvr.cfg to a theoretical limit of 32767, although a practical limit exists well before this value.

SQL Table index component

The limits of the table index components are configurable in ctsrvr.cfg by MAX_DAT_KEY (default 64) and MAX_KEY_SEG (default 32).

Table name

Table names must meet the following requirements:

  • Must be 64 bytes or less in length

  • Must start with an upper or lowercase letter

  • Must not contain special characters other than underscore "_"

  • Can include a mix of upper-lower case characters but are treated as case-insensitive.

Note

Actions that take a “tableName” will return an Error 4054 if the table name does not meet these requirements. If this error is returned by "createTable", "createIntegrationTable", "createInput", or "createTransform", check the supplied "tableName" property to ensure it meets requirements.

UNIFRMAT

UNIFRMAT support is only available for non-transaction processed files. See Limitations for more information.

User

A user name, user ID, or account name is a 32-byte null-terminated ASCII string, which implies 31 bytes are available. The following characters are allowed in the name:

  • ABCDEFGHIJKLMNOPQRSTUVWXYZ

  • abcdefghijklmnopqrstuvwxyz

  • 0123456789

  • ._-

  • A hyphen character (-) cannot be used as the first character.

The server ignores the case of the ASCII characters. Therefore, the server considers TEST_1.FairCom-4 to be the same as test_1.faircom-4.

Note

FairCom based these limitations on the POSIX standard for the Portable Filename Character Set.

Connect

Connect to the FairCom server

The FairCom server provides services over TCP/IP ports and shared memory. These services include APIs and browser-based applications for managing and exploring the server. The following tables contain common connection strings and ports.

To connect to FairCom’s Web applications and APIs, use port 8443 with either the FairCom server hostname or IP address, such as localhost:8443.

You must use a certificate to connect securely to a FairCom server. FairCom provides a solution for creating, managing, and using certificates for secure communications.

Table 13. FairCom DB default connection strings

Protocol

Connection string

ADO.NET

User ID=ADMIN;Password=ADMIN;database=ctreeSQL;server=localhost;port=6597

Apps

http://localhost:8080

Apps secure

https://localhost:8443

ISAM

FAIRCOMS@localhost:5597

iSQL

isql -u ADMIN -p ADMIN 6597@localhost:ctreeSQL

iSQL secure

isql -u ADMIN -p ADMIN ssl:6597@localhost:ctreesql

JDBC

getConnection("jdbc:ctree://localhost:6597/ctreeSQL", "ADMIN", "ADMIN")

JSON APIs

POST a JSON document to http://localhost:8080/api"

JSON APIs secure

POST a JSON document to https://localhost:8443/api"

PHP SQL

ctsql_connect(":6597@localhost:ctreeSQL", "ADMIN", "ADMIN")

Python SQL

pyctree.connect(user='ADMIN',password='ADMIN',database='ctreeSQL',host='localhost',port='6597')



Table 14. FairCom Edge and FairCom MQ default connection strings

Protocol

Connection string

ADO.NET

User ID=ADMIN;Password=ADMIN;database=faircom;server=localhost;port=6597

Apps

http://localhost:8080

Apps secure

https://localhost:8443

ISAM

FairCom Edge: FAIRCOMS@localhost:5597 and FairCom MQ: FCEDGEMQ@localhost:5597

iSQL

isql -u ADMIN -p ADMIN 6597@localhost:faircom

iSQL secure

isql -u ADMIN -p ADMIN ssl:6597@localhost:faircom

JDBC

getConnection("jdbc:ctree://localhost:6597/faircom", "ADMIN", "ADMIN")

JSON APIs

POST a JSON document to http://localhost:8080/api"

JSON APIs secure

POST a JSON document to https://localhost:8443/api"

PHP SQL

ctsql_connect(":6597@localhost:faircom", "ADMIN", "ADMIN")

Python SQL

pyctree.connect(user='ADMIN',password='ADMIN',database='faircom',host='localhost',port='6597')



See also:

Troubleshoot Connections

If the port is not working, check the following:

  1. Ensure the FairCom server is running.

  2. Ensure your firewall is not blocking the port.

  3. Check to see if another application is already using the port.

Tip

If the localhost domain name does not work, use the IP Address 127.0.0.1.

Note

FairCom's JSON APIs and its browser applications run on ports 8080 and 8443.

If Google Chrome requires that the FairCom server needs a valid certificate, see Solve certificate security problems in Google Chrome.

Connect to the browser applications using http://localhost:8080/ or https://localhost:8443/.

Connect to JSON APIs using http://localhost:8080/api or https://localhost:8443/api.

connect to FairCom's Web applications and APIs by specifying connection strings and ports with a valid certificate

ConnectWeb applicationsconnection stringsportconnect to serverconnect to API

Docker or Podman

Use a Docker or Podman image with the FairCom server

There are two ways to use the FairCom products inside a Docker container:

  • Use the gzipped image provided by FairCom

    or

  • Create a Docker image out of a regular package.

 The creation of a Docker image can be done through the Docker creation script provided by FairCom or by manually defining your own Docker image.

Tip

To install FairCom products into a Docker or Podman container, expand the FairCom product gzipped tarball on Linux systems or a .zip file on Windows into the container.

Note

This document uses Docker as the main target of this document. However, Docker and Podman commands are interchangeable by simply replacing references to "docker" with "podman". For example, the following command stops a Docker container:

# docker container stop edge

And the following command stops a Podman container: 

# podman container stop edge

tips and best practices to create Docker or Podman containers with FairCom products

DockerPodmancreate containercreate docker containercreate podman container

Use the provided image

Use the Docker image provided by FairCom

FairCom provides a Docker image containing the essentials to run the server. This image uses the following naming convention:

FairCom-DB.linux.x64.64bit.v4.1.3.71.240201.DockerImage.tar.gz
FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.DockerImage.tar.gz
FairCom-RTG.linux.x64.64bit.v4.1.3.71.240201.DockerImage.tar.gz

In order to add the provided image to your host repository, you can use the Docker load command. 

# docker load < FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.DockerImage.tar.gz

The FairCom-provided image uses the FairCom product version as the product tag. Optionally, you can tag the imported image with the “latest” tag in order to avoid specifying the entire version tag every time you invoke the image.

# docker tag faircomedge:v4.1.3.71 faircomedge:latest

Use the Docker image provided by FairCom

Docker imageFairComservernaming conventionFairCom DBFairCom EdgeFairCom RTGDocker loadproduct tagdocker tag

Create an image

Create a Docker or Podman image

When using Docker or Podman containers, some users desire to create their own containers from scratch. This section provides a few tips and best practices to create Docker or Podman containers with FairCom products.

Adding FairCom technology into an image is fairly straightforward. However, FairCom provides a script to facilitate the creation of an essential image identical to the one provided as a gzipped Docker image.

Note

This section uses the FairCom default ports. If you want to use different ports, you can change them in the services.json or ctsrvr.cfg file located in the <faircom>/config folder. Consider changing the image exposed ports accordingly.

Use the Docker image creation script

FairCom's provided script named create_image.sh helps the end user to create a Docker image starting from a regular FairCom distribution package (gizpped tarball).

Currently create_image.sh supports x64 and ARM64 Linux flavors.

The create_image.sh script depends on some files named Dockerfile* that must reside in the same directory as the script named create_image.sh.

The create_image.sh script requires Docker or Podman. Starting with Docker version 24, you may also need to install the Docker buildx plugin in order to correctly support the docker image creation. Refer to your Docker distribution to know how to correctly install it. 

The create_image.sh script takes the following parameters in this order:

FAIRCOM_BUNDLE: this is the first and the only mandatory parameter. This specifies the FairCom gzipped tarball to use as base to create the docker image. The create_image.sh script will take care to select the requested components needed to run the server inside a container based on the image.

LICENSE: here the end user can pass a FairCom license file to replace the default license included in the FAIRCOM_BUNDLE. The parameter is optional, if any of the following parameters needs to be passed please specify an empty string “”. Please refer to the samples below.

quiet: By default the create_image.sh script creates a backup copy of the configuration folder before creating the image: the quiet parameter will force the create_image.sh script to skip all the questions related to configuration files backup and proceed with the image creation without asking questions. No file will be backed up if the quiet parameter is used.

remove: By default the create_image.sh creates a docker image in your local docker instance and saves a copy of it as a gzipped image in the current directory. The remove parameter will force create_image.sh to remove the image from the docker instance and leave only the gzipped image on disk. The gzipped image can be imported in any other docker instance using the docker load command. (Please refer to the “Use provided image section” above to know how to load a gzipped image)

create_image.sh usage examples

The following command will create a simple image starting from a FairCom distribution package:

# ./create_image.sh FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.tar.gzThe following command will create an image and will replace the default license file with the specified as second parameter:# ./create_image.sh FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.tar.gz ctsrvr39481103.lic

The following command will create an image with the default license and will skip any question about the save of the config files:

# ./create_image.sh FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.tar.gz “” quiet

The following command will create an image, replace the license with the specified one and will remove the image from the local docker instance:

# ./create_image.sh FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.tar.gz ctsrvr39481103.lic “” remove

The following command will create the image with the default license and will remove the image from the local docker instance:

# ./create_image.sh FairCom-Edge.linux.x64.64bit.v4.1.3.71.240201.tar.gz “” “” remove

FairCom generated images details

As FairCom uses create_image.sh to generate the provided docker images all the images generated with create_image.sh have similar characteristics.

The create_image.sh script takes the following directories from the specified FairCom bundle and puts them in the generated image:

config/

data/

server/

tools/

tranlogs/

Depending on the input package flavor the script chooses between the provided Dockerfiles to make sure the correct default TCP ports are exposed by the image. The Dockerfile takes care to select the proper operating system image to host and run the server and to install the required dependencies; of course it also specifies to start the server when a container based on the image is spawned.

Despite the fact that FairCom’s designed container images have a default place for configuration, data and tranlogs inside the container it’s a very good idea to take advantage of the volume mounts/maps to make sure configuration, data and tranlogs are produced outside the running containers to facilitate the upgrade of the image version in case is needed, please refer to Mapping external folders into Docker section to know how to do this.

FairCom chose as base operating system image the following images:

For X64 platforms (x86_64): Red Hat 8 universal base image For ARM64 platforms: Ubuntu 24.04

Create your own Docker image

Some FairCom users prefer to create their own Docker image for various reasons. The most common reason is that complex applications may depend on other software components, which need to be part of the Docker image.

You can create your own Docker image by starting with any image on the Docker hub or using a FairCom-provided image. A FairCom-provided image must be loaded on the Docker host used to generate the new image.

Regardless of the selected base image, the user creating the image will probably want to define the image through a Dockerfile. Dockerfiles, together with FairCom’s create_image.sh script, can be used as a starting point to create your own Dockerfile that best covers your application needs. 

Usually, a FairCom bundle includes the following:

  • <faircom>/config

  • <faircom>/data

  • <faircom>/server

  • <faircom>/tranlogs

Note

  • We discuss best practices for storing the config, data, and tranlogs folders in the Copying files into and out of a Docker container and Mapping external folders into Docker sections. As data, transaction logs, and configuration locations depend on your configuration, you might need to change your Dockerfile definition to define and include the correct locations. Map your data, transaction logs, and configuration locations out of Docker containers to facilitate the server binaries updates.

  • Consider adding the ctadmn (administration tool) and ctstop (scriptable command line tool for stopping the FairCom server) into this container. These are both found in the <faircom>/tools folder. FairCom prebuilt Docker images include the entire /tools FairCom distribution folder.

  • In order to take advantage of record compression, the FairCom server must be able to load the zlib library as libz.so. Many Linux base images distribute zlib as libz.so.1. Make sure your custom image creates a symbolic link to libz.so.1 named libz.so in the same directory where libz.so.1 is hosted so that libz.so.1 is loaded correctly as libz.so,. This can be done with a RUN command in your Dockerfile.

    RUN ln -s /usr/lib64/libz.so.1 /usr/lib64/libz.soRUN ln -s /lib/aarch64-linux-gnu/libz.so.1 /lib/aarch64-linux-gnu/libz.so

    Refer to your base image distribution to understand the name and the path of zlib.

For best performance, include the FairCom client side in the same container with the FairCom server application (faircom). It is possible to host the server and client components in separate containers. However, keep in mind you will experience about a 10-15% performance penalty. This overhead is present if both containers are running on the same machine and using the shared memory communication protocol. If the containers are not on the same machine, and therefore TCP/IP communication is in use, the overhead will be even greater.

Start a Docker container

Simply start the Docker container like any other container using the docker run command, or script starting the database server engine (faircom.exe on Windows, faircom on Linux/Unix).

Stop a Docker container

If executing FairCom’s ctstop command does not terminate the Docker container, you can stop the Docker container with the following command:

sudo docker container stop edge

Warning

It is best to stop the FairCom server by executing FairCom’s ctstop command. If this does not work, and the FairCom COMPATIBILITY TERMINATE_ON_SIGNAL keyword is active in ctsrvr.cfg, then using Docker’s stop command works by sending a SIGTERM signal to FairCom server to shut down cleanly. It gives the server ten seconds to shut down. If this is not enough time, the server will be terminated prematurely. This should not result in data loss if your files are under transaction processing control (file mode TRNLOG), but the best practice is to use ctstop.

Kill a Docker container

If all other means of stopping the FairCom container fail, you can kill the Docker container with the following command:

sudo docker kill edge

Warning

The warning above in Stopping a Docker container also applies to killing a Docker container.

Copy files into and out of a Docker container

The FairCom server uses various configuration files. It is recommended to copy these configuration files (from <your FairCom installation folder>/config) to a folder outside the Docker container. This ensures changes to these files are preserved when you replace the current container with a new version of the FairCom Server.

You can use the following techniques to copy any file inside the container to a folder outside the container:

  1. Before copying files, shut down the Docker container using the following command (adjust your paths accordingly):

    sudo docker exec -it edge /opt/faircom/tools/ctstop -auto

  2. Then run the following docker cp command to copy the config folder to the /tmp folder:

    sudo docker cp edge:/opt/faircom/config /tmp

    Docker copies data out of the container into the folder you specify. The command above creates one new folder on your Linux operating system named /tmp/config and copies the container files into it.

  3. After Docker copies these files, the Linux root owns them. If you want to see and work with these files without being root, you need to change the owner.

    Run the following command in the folder that contains these files, which in this case is /tmp. It changes the owner to desired_owner_name. Replace desired_owner_name with your login name or another login name that you want to own these files.

    sudo chown -R desired_owner_name config

  4. To use the new config folder along with any mapped data and tranlogs folders (Mapping external folders into Docker), you must remove the current container and run a new Docker container. Use the following commands to do this:

    sudo docker container rm edge
sudo docker run -d -p 1883:1883 -p 5597:5597 -p 6597:6597 -p 8080:8080 -p 8081:8081 -p 8443:8443 -v /tmp/:/opt/faircom/data -v /tmp/:/opt/faircom/tranlogs -v /tmp/config/:/opt/faircom/config --name edge faircomedge:v3.0.1.206

    The previous command uses these folders on your operating system as the source for config, data, and tranlogs. This ensures your configuration, data, and logs are not lost when you update the Docker container to a new image.

It is a best practice to map another folder besides /tmp to hold your config, data, and tranlogs. The section, Mapping external folders into Docker, shows you how to do this.

Map External Folders into Docker

This section describes best practices for mapping Linux folders into a Docker container.

Warning

Do not run the examples in this section without first reading the entire section and thinking about which Linux folders you want to use to hold your data. Then modify the commands to use your chosen folders

FairCom stores your data in three folders called data, tranlogs, and config. As recommended in this guide, these folders are located inside the Docker container in a folder named /opt/faircom/.

  • Data files are stored in /opt/faircom/data

  • Transaction Logs are in /opt/faircom/tranlogs

  • Configuration files are in /opt/faircom/config

Note

Storing data inside a Docker container is not a good practice because updating or deleting the Docker container destroys these files. Further, Docker’s internal file system slows down greatly when its files change often.

You should map operating system folders into the Docker container. This stores your data in those mapped folders and preserves your data when you update the Docker image. Use the -v switch in the Docker run command to map operating system folders into Docker’s internal folders.

Example 10. The following command maps the operating system folder named /tmp/data/ into the folder inside the Docker container named /opt/faircom/data/
sudo docker run -d -p 1883:1883 -p 5597:5597 -p 6597:6597 -p 8080:8080 -p 8081:8081 -p 8443:8443 -v /tmp/data/:/opt/faircom/data/ --name edge faircomedge:v3.0.1.206


The -v outside_folder:inside_folder option maps an operating system folder into a Docker container folder. Docker will create the operating system folder if it does not exist. After the command runs, the files and folders in the operating system folder are the only ones visible inside the mapped Docker container folder. Preexisting files and folders stored inside the Docker container’s folder are no longer visible to the applications running inside the Docker container.

FairCom recommends you create your own folders for data, logs, and config files outside the container. After creating these "external" folders, you need to ensure the Docker process has access to these folders. You may need to modify the ownership of these folders to give Docker permission to access them.

sudo chown -R desired_owner_name folder_name
The following folders are possibilities:

  • /var/lib/faircom/data

  • /var/lib/faircom/tranlogs

  • /var/lib/faircom/config

When creating your own folder for config files, you need to copy a set of FairCom’s config files into /var/lib/faircom/config because the FairCom server will not run without them. For an example of how to do this, see the section, Copying files into and out of a Docker container.

Once these operating system folders are created and the config folder contains FairCom’s config files, you can modify the docker run command with new -v mappings to use those folders. The command below is an example:

sudo docker run -d -p 1883:1883 -p 5597:5597 -p 6597:6597 -p 8080:8080 -p 8081:8081 -p 8443:8443 -v /var/lib/faircom/data/:/opt/faircom/data -v /var/lib/faircom/tranlogs/:/opt/faircom/tranlogs  -v /var/lib/faircom/config/:/opt/faircom/config --name edge faircomedge:v3.0.1.206

Warning

Do not configure two Docker containers to use the same operating system folders for data and tranlogs. If you do, the two instances of the FairCom server will write to the same data files. This can irrecoverably corrupt the data.

Troubleshoot TCP/IP port conflicts

If you cannot connect to the FairCom server over TCP/IP, you may have port conflicts. Perform the following checks to troubleshoot:

  1. When the FairCom server is not running, run the following command to list the ports currently in use on Linux.

    netstat – an

    Note

    The netstat command is part of net-tools. If it is not already installed, you can install it using the following command:

    sudo yum install net-tools

  2. Compare the output of netstat to the list provided in FairCom ports.

    If any of these ports are being used by other applications, then the FairCom server will not run properly.

    You can configure FairCom to use another port by modifying its configuration files. These ports and files are documented in FairCom ports used by FairCom technology.

  3. If you have copied the config folder outside the container and mapped that folder back into the container, you can directly edit the config files using your favorite editor, see Copying files into and out of a Docker container and Mapping external folders into Docker.

  4. If you have not mapped an operating system folder to the config folder, you use the nano text editor that is built into the Docker container. The config files are located inside the Docker container in the folder /opt/faircom/config. You can use a command like the following to edit a config file. Change some_config_file to the name of the actual file, such as ctsrvr.cfg.

    sudo docker exec -it edge nano /opt/faircom/config/some_config_file

  5. After you change one or more ports in FairCom’s config files, you must stop the FairCom server and remove the container. You can use the following commands to do this. But first modify the run command by changing the appropriate -p option to properly map the new port.

    sudo docker exec -it edge /opt/faircom/tools/ctstop -auto

sudo docker container rm edge


sudo docker run -d -p 1883:1883 -p 5597:5597 -p 6597:6597 -p 8080:8080 -p 8081:8081 -p 8443:8443 -v /tmp/:/opt/faircom/data -v /tmp/:/opt/faircom/tranlogs -v /tmp/config/:/opt/faircom/config --name edge faircomedge:v3.0.1.206

Run a container using -P

If you cannot connect to the FairCom server over TCP/IP, you may have run the Docker container with the -P (upper case P) switch. This switch causes Docker to map the fixed ports inside the Docker container to randomly available ports on the outside of the container.

Example 11. Running a Docker with the -P switch
sudo docker run -d -P --name edge faircomedge:v3.0.1.206


Note

If you use the -P switch, you must use Docker’s dynamically assigned port numbers to connect to the FairCom server. This is a convenient way to quickly run multiple containers of the FairCom server on the same computer without port conflicts. On the other hand, it makes it more complicated to connect to FairCom services.

You can run the following command to get the port mappings of a Docker container:

sudo docker port edge

After executing the Docker run command with the -P (uppercase P) example shown above, the Docker container returns port mappings like the following. The results shown the mapping of ports from inside of the Docker container to the outside.

Example 12. Return

Inside to outside

1883/tcp -> :::55005

5597/tcp -> :::55004

6597/tcp -> :::55003

8080/tcp -> :::55002

8081/tcp -> :::55001

8443/tcp -> :::55000


For example, FairCom uses TCP/IP ports for the following protocols.

  • MQTT uses port 1883 by default.

    In the -P example above, Docker maps it to 55005.

  • Browser-based apps uses port 8443 by default.

    In the -P example above, Docker maps it to 55000.

  • MQTT WebSocket uses port 8081 by default.

    In the -P example above, Docker maps it to 55001.

  • SQL ODBC uses port 6597 by default.

    In the -P example above, Docker maps it to 55003.

  • ISAM, CTDB, and NAV APIs use port 5597 by default.

    In the -P example above, Docker maps it to 55004.

  • Port 8080 is the insecure HTTP port. Use port 8443 instead.

    In the -P example above, Docker maps it to 55002.

You can use FairCom’s config files to change the default ports.

Connect to FairCom’s browser-based applications

Note

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

To connect to FairCom’s browser-based applications, use a URL like the following in your web browser:

https://localhost:8443/

Putting this URL in the web browser brings up the landing page for FairCom’s browser-based applications. On this landing page, you can click on the links to run MQTT Explorer, SQL Explorer, and Monitor.

If there are issues:

  • Try changing localhost in the URL to the hostname or IP address of the computer running the Docker container containing FairCom. You may also consider using the following URL if localhost is not working:

    https://127.0.0.1:8443/

  • Tyr changing 8443 in the URL to the port number that Docker maps to port 8443. In the -P example above, the Docker container maps 8443 to 55000.

Note

SQL Explorer and Monitor applications work properly when using their default ports. Do not change these ports to Docker’s newly mapped ports.

When you launch MQTT Explorer (available in FairCom EDGE), it opens a connection page where you can specify ports for connecting to the application. If you use the -p switch (lowercase p) to run the Docker container, the default ports work without change.

If you use -P switch (uppercase P) to run the Docker container, you need to determine the port that Docker assigned to port 8081, which is the WebSocket port used by MQTT Explorer. In  Running a container using -P, its example shows that Docker assigned the external port 55001 to FairCom’s internal MQTT/WS port of 8081. When you log into MQTT Explorer, you must use Docker’s newly assigned external port for the MQTT/WS Port. Do not change the default value for the SQL port.

83138.png

  • For the field named MQTT/WS Port, use the port number that the Docker container maps to 8081. This is FairCom’s MQTT WebSocket port, which allows a web browser to send and receive MQTT messages. In the -P example above, Docker maps this port to 55001.

  • Do not change the SQL Port, which defaults to 6597. This port is used inside the Docker container by FairCom’s app server to connect to the Database Server. Because FairCom’s app server and database server run inside the container, they communicate using their original internal port numbers.

Install into production

Install FairCom products into production

Establishing secure connections is necessary to maintain safe communications among FairCom servers and data collection devices. The following process for establishing TLS connections is recommended when deploying FairCom servers.

Security

  1. Create a valid certificate for each FairCom Edge server.

  2. Configure the certificate for HTTPS connections only.

  3. Turn on file encryption.

  4. Change the ADMIN password to a secure password.

  5. Add additional user accounts for applications and end users.

    Note

    Do not allow application and end-user accounts to have admin access or to know the ADMIN password. Ensure each account has a secure password.

Configuration settings

  1. Update the settings in the ctsrvr.cfg file to fit production needs.

    Note

    Increase the default topic settings for FairCom Edge and FairCom MQ. There needs to be 62*number of expected topics. If the persistence settings were changed it will be (retentionPeriod+1)*2.

  2. Verify that the system files limit is at least as high as the FILES settings from Step 1.

  3. Increase the DAT_MEMORY and IDX_MEMORY settings to allow caching as much of the data you expect to access as possible.

    Note

    Keep this within the footprint of the physical RAM the hardware has available.

  4. Store the data, index, and tranlog folders on fast local SSD storage.

    Note

    Using a shared or network volume to store these files will dramatically slow down performance.

This page describes how to install FairCom products into production

install FairCom productsconfigurationinstall to productionproductionsecurity

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.

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

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.

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.

MQTTWS