Configure ports and services

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.

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.

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:

The optional "defaultOwnerName" property is is used by "createSession" and "alterSession" to specify the default owner of objects created by the session. Its value must be a valid username of an account. If it is omitted, null, or "", it defaults to the value of the session's "username" property.
 

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

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

• You must include "caCertificateFilename" to allow clients to use X509 certificates to authenticate with the server.
• The certificate authorities file contains the list of certificate authorities the server uses to validate X509 certificates that clients present as authentication credentials.
• In order for an X509 certificate to be accepted by the server, the certificate must be signed by a certificate authority that is present in the certificate authorities certificate file.

        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }

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.

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.

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

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:

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.

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.

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.

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.

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.

The "defaultRetrySeconds" property is an optional integer that sets the global default value of the "retrySeconds" property. This property defaults to 20 (seconds).

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.

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.

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

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

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

You may set "historyRetentionUnit" to:

See "historyRetentionPeriod".

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.

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.

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.

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.

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.

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

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

You may set it to:

See “statsRetentionPeriod”