listStreamingConnections

Return a list of streaming connections that match all specified filters

The "listStreamingConnections" action lists streaming connections. 

This action ANDs together all the filter properties to create the filter. Omit a filter property or set it to null to prevent it from filtering the results. Omit all filters to return all connections.

When a filter property value is a string, the server treats it as a partial match of each character in the property's value to the corresponding character in the definitions. The server does not process characters as wildcards.

The action returns the following metrics:

  • The "estimatedBacklogSeconds" property reports the approximate time, in seconds, needed by the FairCom MQ server to apply data changes from the source server.
  • The "incomingBytesPerSecond" property reports the data change throughput, in bytes per second, streamed from the source FairCom server to FairCom MQ.
  • The "appliedBytesPerSecond" property reports the data change throughput, in bytes per second, applied by FairCom MQ. The difference between the incoming and applied throughput indicates whether the backlog is increasing or decreasing.

Note There is no "describeStreamingConnections" action because a server will have too few connections to streaming servers.

 

Request examples

Minimal

This example returns all streaming connections.

{
  "action": "listStreamingConnections",
  "params": {},
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

This example returns only those streaming connections that match the filter criteria.

{
  "api": "admin",
  "action": "listStreamingConnections",
  "params": {
    "streamingConnectionNameFilter": "fmq",
    "sourceServerNameFilter": "FC",
    "sourceHostnameFilter": "10.70.13",
    "sourcePortFilter": 5597,
    "sourceUsernameFilter": "AD"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Maximal

{
  "authToken": "authToken",
  "result": {
    "streamingConnections": [
      {
        "streamingConnectionName": "db1",
        "estimatedBacklogSeconds": 100,
        "metadata": {
        },
        "maxSecondsBeforeConnectingToNextServer": 15,
        "streamParallelism": 4,
        "sourceServers": [
          {
            "purpose": "Primary Server",
            "sourceServerName": "FAIRCOMS",
            "sourceHostname": "10.70.13.112",
            "sourcePort": 5597,
            "sourceUsername": "ADMIN",
            "sourcePassword": "ADMIN",
            "tls": {
              "enabled": true,
              "caCertificateFilename": "ca.crt",
              "allowedCipherSuites": "",
              "clientCertificateEnabled": true,
              "clientCertificateFilename": "admin_client.crt",
              "clientPrivateKeyFilename": "admin_client.key"
            }
          },
          {
            "purpose": "Secondary Server",
            "sourceServerName": "FAIRCOMS2",
            "sourceHostname": "10.70.13.113",
            "sourcePort": 5597,
            "sourceUsername": "ADMIN",
            "sourcePassword": "ADMIN",
            "tls": {
              "enabled": true,
              "caCertificateFilename": "ca.crt",
              "allowedCipherSuites": "",
              "clientCertificateEnabled": true,
              "clientCertificateFilename": "admin_client.crt",
              "clientPrivateKeyFilename": "admin_client.key"
            }
          }
        ]
      }
    ]
  },
  "errorCode": 0,
  "errorMessage": ""
}
 
 

 

Properties

Request properties ("params")

Property Description Default Type Limits (inclusive)

sourceHostnameFilter

The "sourceHostnameFilter" property specifies a partial match for a hostname.

 Optional with default of null string 1 to 64 bytes

sourcePortFilter

The "sourcePortFilter" property specifies a complete match for a port number.

 Optional with default of null integer 1 to 65535

sourceServerNameFilter

The "sourceServerNameFilter" property specifies a partial match for a server name.

 Optional with default of null string 1 to 64 bytes

sourceUsernameFilter

The "sourceUsernameFilter" property specifies a partial match for a user name.

 Optional with default of null string 1 to 64 bytes

streamingConnectionNameFilter

The "streamingConnectionNameFilter" property specifies a partial match for a connection name.

 Optional with default of null string 1 to 64 bytes

 

Response properties ("result")

Property Description Type Limits (inclusive)

streamingConnections

The "streamingConnections" property lists the streaming connections that match the request filters as separate objects.

 array of objects

0 or more objects containing 1 or more of the following properties:

"estimatedBacklogSeconds"

"metadata"

"sourceServers"

"streamingConnectionName"

"streamParallelism"

streamingConnections

.estimatedBacklogSeconds

The "estimatedBacklogSeconds" property reports the approximate time, in seconds, needed by the FairCom MQ server to apply data changes from the source server.

 integer 0 to 4294967296

streamingConnections

.maxSecondsBeforeConnectingToNextServer

 The "maxSecondsBeforeConnectingToNextServer" property specifies the maximum number of seconds the server will attempt to reconnect to the existing server before it attempts to connect to the next server in the "sourceServers" list. int32 1 to 65535

streamingConnections

.metadata

The "metadata" field allows a customer to add a JSON value to an object such as a label or thing. It is typically a JSON object, but may be any JSON value. Its purpose is to provide additional metadata about the label, such as translations in multiple languages, historical value changes, etc. The "alterLabel" action can only replace this value with a new JSON value.

 JSON 0 to 65,500 bytes

streamingConnections

.sourceServers

 The "sourceServers" property contains a list of FairCom DB or RTG server connection objects. FairCom MQ attempts to connect to the first server in the list. If that fails, it attempts to connect to the next one. If it reaches the last server in the list, it attempts to connect to the first. array of server connection objects 
{
  "purpose": "Primary Server",
  "sourceServerName": "FAIRCOMS",
  "sourceHostname": "10.70.13.112",
  "sourcePort": 5597,
  "sourceUsername": "ADMIN",
  "sourcePassword": "ADMIN",
  "tls": {
    "enabled": true,
    "caCertificateFilename": "ca.crt",
    "allowedCipherSuites": "",
    "clientCertificateEnabled": true,
    "clientCertificateFilename": "admin_client.crt",
    "clientPrivateKeyFilename": "admin_client.key"
  }
}

streamingConnections

sourceServers

.purpose

The "purpose" property provides a short description of the specified server's purpose.

 

In the Thing API, the "purpose" property specifies the thing's purpose, which is a short description of why a thing is in use. A thing may have one purpose. 

 

This API uses the Label API to manage purposes.

  • It uses the label group, "faircom/edge/purpose". 
  • An API client can use the "listLabels" action to retrieve the purpose list. 
  • An API client can use the "alterLabel" action to rename a purpose label.
  • An API client can use the "createLabel" action to create a purpose label.
  • An API client can use the "changeLabel" action to delete a purpose label, but the API client must first use the "listThings" action with the "purposeFilter" property to ensure the label is unused.
 string 1 to 64 bytes

streamingConnections

sourceServers

.sourceHostname

 The "sourceHostname" property specifies a unique host name or TCP/IP address of a FairCom DB or RTG server. string 1 to 255 bytes

streamingConnections

sourceServers

.sourcePassword

 The "sourcePassword" property specifies the login password of a FairCom DB or RTG server. string 1 to 128 bytes

streamingConnections

sourceServers

.sourcePort

 The "sourcePort" property specifies the ISAM TCP/IP port of a FairCom DB or RTG server. int16 1 to 65535

streamingConnections

sourceServers

.sourceServerName

 The "sourceServerName" property specifies the server name of a FairCom DB or RTG server. It is the name specified by the SERVER_NAME keyword defined in the target server's configuration file, ctsrvr.cfg. The server name used by most FairCom DB and RTG servers is "FAIRCOMS". This property is required if the "sourceHostname" is not defined. string 1 to 255 bytes

streamingConnections

sourceServers

.sourceUsername

 The "sourceUsername" property specifies the name of a FairCom DB or RTG server. string 1 to 64 bytes

streamingConnections

sourceServers

.tls

The "tls" property is a JSON object that defines the public server certificate filename, the private key filename, the certificate authority filename, the allowed cipher suites, and whether the client certificate is required. 

 

"tls": { "serverCertificateFilename": "server.crt", "privateKeyFilename": "server.key", "caCertificateFilename": "ca.crt", "allowedCipherSuites": "AES256-SHA256" "requireClientCertificate": "true"
}
 object

"allowedCipherSuites"

"caCertificateFilename"

"certificateFilename"

"privateKeyFilename"

streamingConnections

sourceServers

tls

.allowedCipherSuites

The "allowedCiperSuites" property specifies an array of ciphers that the server will accept for communications with clients. 

  • 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:
      • ["ALL", "!aNULL", "!eNULL", "!SSLv2", "!LOW", "!EXP", "!RC4", "!MD5", "@STRENGTH"]
  • @STRENGTH at the end of the list will force the server to prioritize the strongest algorithms first. 
  • Place an exclamation point before a cipher to disable it. 
 string No limits

streamingConnections

sourceServers

tls

.caCertificateFilename

The "caCertificateFilename" property specifies the name and optional path of the CA certificate file (such as "ca.pem"). 

  • When included, allows 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 authority's certificate file.
        "tls": {
          "enabled": true,
          "caCertificateFilename": "ca.crt",
          "allowedCipherSuites": "",
          
          "clientCertificateEnabled": true,
          "clientCertificateFilename": "admin_client.crt",
          "clientPrivateKeyFilename": "admin_client.key"
        }
 string No limits

streamingConnections

sourceServers

tls

.clientCertificateEnabled

 The "clientCertificateEnabled" property enables client certificate authentication when set to true. The target FairCom DB or RTG server must be configured to accept client certificates. boolean

true

false

streamingConnections

sourceServers

tls

.clientCertificateFilename

The "clientCertificateFilename" property specifies the name of the client certificate file. 

 string The file name of a client certificate.

streamingConnections

sourceServers

tls

.clientPrivateKeyFilename

The "clientPrivateKeyFilename" property specifies the name of the client private key file. 

 string The file name of a client certificate private key file.

streamingConnections

sourceServers

tls

.enabled

The "enabled" property specifies whether or not the feature is enabled. The example below enables the TLS feature.

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

true

false

streamingConnections

.streamingConnectionName

 The "streamingConnectionName" property specifies a unique, user-defined name for a streaming connection. The API uses it to identify streaming connections and to connect a data change stream to a FairCom DB or RTG server. string 1 to 64 characters

streamingConnections

.streamParallelism

 The "streamParallelism" property specifies the number of parallel streams the server uses to deliver data changes to the FairCom MQ server. You typically use a number that does not exceed the number of cores on the FairCom MQ server. integer 1 to 65535

 

Was this article helpful?

Give feedback about this article

Related Articles