configureBrokerConnection

Connect a FairCom Server to an external broker

The "configureBrokerConnection" creates or updates a reusable connection to an external broker, which may be another instance of FairCom MQ, FairCom Edge, or an MQTT broker from another vendor. It stores this information in the "mqtt_broker" table inside the embedded FairCom database. There is one record for each connection to an external MQTT broker.

  • The "brokerConnectionName" is a unique user-defined name for the connection. It may be up to 100 characters long. It is used in all subsequent references to the connection, such as when configuring a topic to subscribe or forward messages to an external broker or when altering or deleting a broker connection.
  • If the "brokerConnectionName" already exists, then when running "configureBrokerConnection" FairCom's servers update the record rather than creating it.
  • Care should be taken when editing an existing broker connection because multiple MQTT topics may use it.
  • If you do not wish to share a broker connection between multiple topics/integration tables (so you can control the broker connections independently), it is permissible to create multiple broker connections which all connect to the same external MQTT broker - giving each broker connection record a different "brokerConnectionName".

 

Request examples

Minimal

{
  "action": "configureBrokerConnection",
  "params": {
    "brokerConnectionName": "MqttBroker1",
    "brokerHostname": "mqtt.faircom.com"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

{
  "api": "mq",
  "apiVersion": "1.0",
  "requestId": "2",
  "action": "configureBrokerConnection",
  "params": {
    "brokerConnectionName": "MqttBroker1",
    "brokerHostname": "mqtt.faircom.com",
    "brokerPort": 1883,
    "brokerUserName": "admin",
    "brokerUserPassword": "admin",
    "reconnectFrequencySeconds": 20,
    "command": "disconnect",
    "tls": {
      "allowedCipherSuites": "",
      "certificateAuthoritiesFilename": "",
      "certificateFilename": "",
      "privateKeyFilename": ""
    },
    "metadata": {}
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Minimal

{
    "result": {},
    "errorCode": 0,
    "errorMessage": ""
}
 
 

Maximal

{
    "result": {},
    "requestId": "2",
    "errorCode": 0,
    "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

brokerConnectionName

The "brokerConnectionName" property specifies a unique user-defined name for the connection. 

  • The unique name defined in the "brokerConnectionName" property is used in all subsequent references to the connection, such as when configuring a topic to subscribe or forward messages to an external broker or when altering or deleting a broker connection.
  • If the "brokerConnectionName" already exists, FairCom's server will update the record rather than create it.
  • If you do not wish to share a broker connection between multiple topics/integration tables (so you can control the broker connections independently), you can create multiple broker connections which all connect to the same external MQTT broker - giving each broker connection record a different "brokerConnectionName".
 Optional with default of "" string 1 to 100 bytes

brokerHostname

The "brokerHostname" property specifies the hostname of the broker. It must not be a zero-length string or contain only whitespace. It has a maximum length of 255 characters.

When these rules are violated the following errors will be displayed:
  • When creating a new broker connection, FairCom's servers log an error stating, "Cannot create the broker connection named xxx because brokerHostname is empty."
  • When updating an existing broker connection, FairCom's servers log an error stating, "Cannot update the broker connection named xxx because the new "brokerHostname" is empty. The current brokerHostname xxx and brokerPort xxx remain unchanged."

Required - No default value

 string 1 to 255 bytes

brokerPort

The "brokerPort" property specifies the TCP/IP port. 

  • If present, it must be a number between 1 and 65535 inclusive.
  • If the port is already in use, FairCom's server will not be able to run.
  • When it is set to a non-numeric value, or is out of range, FairCom's servers log an error stating, “Cannot create the broker connection named xxx because the brokerPort property is missing or is set to an invalid value. It must be present and set to a number greater than zero and less than 65536.”
Optional with default of 1883 integer

2 to 65534

brokerUserName

The "brokerUsername" property specifies the login name to the external broker. This property is an optional string from 1 to 64 bytes. If omitted, it defaults to an empty string.

Note Unlike some other properties containing the "name", the "name" in "brokerUsername" is all lowercase.

  • A zero-length username is invalid.
  • It is VARCHAR(500).

Optional with default of ""

 string 1 to 64 bytes

brokerUserPassword

The "brokerUserPassword" property contains the login password to the external broker and information about how that password might be encrypted. It is VARCHAR(500). Additional specifications may be added in the future.

 

Example

{ 
  "encryption": "NONE", 
  "password": "myPassword" 
}

Optional with default of ""

 string 0 to 256 bytes

command

The "command" property specifies a preset action that modifies the broker connection. If set to a valid command string, it executes the command.

The following service commands are available:
  • "disconnect"
    • Tells the server to disconnect this broker connection.
  • "reconnect"
    • Tells the server to reconnect this broker connection..
  • "applySettingsNow"
    • Immediately applies the settings from this command.
  • "applySettingsWhenDisconnected"
    • Postpones the application of the settings within this command until the broker connection has been disconnected.

Optional with default of "applySettingsWhenDisconnected"

 string

"disconnect"

"reconnect"

"applySettingsNow"

"applySettingsWhenDisconnected"

metadata

 The "metadata" property contains user-defined properties that add keywords and tags about the code package. The server indexes this field with a full-text index so you can search for any word or phrase to find code packages. Optional with default of {} object 0 or more key/value pairs

reconnectFrequencySeconds

The "reconnectFrequencySeconds" property specifies the number of seconds that the broker waits between attempts to reconnect to an external broker. 

If it is set to 0, the broker does not attempt to reconnect when it loses a connection or fails to connect.

FairCom's servers attempt to connect to an external broker when it is configured as a subscriber to topics on an external broker or when it is configured to forward messages to an external broker.

To stop the reconnect process, send the "configureBrokerConnection" message with the command property set to "disconnect".

To restart the reconnect process, send the "configureBrokerConnection" message with the command property set to "reconnect".

 Optional with default of 15 int32

1 to 65535

tls

 The "tls" property 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.  Optional with default of {} object

"allowedCipherSuites"

"certificateAuthoritiesFilename"

"certificateFilename"

"privateKeyFilename"

tls

.allowedCipherSuites

The "allowedCiperSuites" property specifies an array of ciphers that the server will accept for communications with clients. It defaults to an empty string.

  • It specifies the encryption ciphers that are allowed to be used for encrypting a TLS (SSL) connection.
  • A client is allowed to connect to the server only if it uses one of the ciphers in this list.
  • The default setting of an empty string supports industry-standard secure connections.
  • The default value requires clients to use full AES 256-bit encryption when they talk to the server.
  • If a client cannot support AES 256-bit encryption, a lower encryption level should be added to the list.
    • This is undesirable because malicious users will attempt to connect at the lowest possible level so they can harm the system (for more information, see ciphers main page at OPENSSL.org.
  • Example settings:
    • Maximally secure example:
      • This example only allows clients to connect securely.
      • ["AES256-SHA256", "AES256-GCM-SHA384", "DHE-RSA-AES256-SHA256"]
    • Minimally secure example with the broadest client support:
      • ["!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
    • Insecure example allowing clients to connect using any level of security from none to the maximal:
      • ["ALL", "!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
  • Add @STRENGTH to the end of the list to force the server to prioritize the strongest algorithms first. 
  • Place an exclamation point before a cipher to disable it. 
 Optional with default of "" string No limits

tls

.certificateAuthoritiesFilename

 The "certificateAuthoritiesFilename" property specifies the name and optional path of the certificate authorities certificate file (such as "ca.pem"). Optional with default of "" string No limits

tls

.certificateFilename

 The "certificateFilename" property specifies the name and optional path of a server certificate file. Optional with default of "" string No limits

tls

.privateKeyFilename

 The "privateKeyFilename" property specifies the name and optional path of a server key file. Optional with default of "" string No limits

 

Was this article helpful?

Give feedback about this article

Related Articles