alterStreamingConnection

Update a streaming connection

The "alterStreamingConnection" action alters a streaming connection from a source FairCom server to a FairCom MQ server. Use it to modify connection settings, such as changing a password or the logging level. After you alter a connection, the FairCom MQ server immediately uses the new connection settings to connect to the FairCom DB or RTG server. 

If you change a connection to point to a different FairCom DB or RTG server, it forces FairCom MQ to fail all data change streams from the original FairCom DB or RTG server and restart them from the new one.

You can change the streaming connection name only when no data change streams use it.

 

Request examples

Minimal

{
  "action": "alterStreamingConnection",
  "params": {

    "streamingConnectionName": "db1",

    "sourceHostname": "10.70.13.112",
    "sourcePort": 5597,
    "sourceUsername": "ADMIN",
    "sourcePassword": "ADMIN"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

Maximal

This example configures a connection to multiple source servers. The FairCom MQ server attempts to connect to the servers in the list in the order they are listed. If a connection fails, it connects to the next server in the list. If the connection to the last server in the list fails, it attempts to connect to the first one.

{
  "api": "admin",
  "action": "createStreamingConnection",
  "params": {
    "streamingConnectionName": "db1",
    "logLevel": "error",
    "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"
        }
      }
      
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}
 
 

 

Response examples

Maximal

{
  "authToken": "authToken",
  "result": {

    "streamingConnectionName": "db1",
    "logLevel": "error",
    "metadata": {},
    "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",
        
        "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)

logLevel

 The "logLevel" property defines what type of messages the replication agent will log. Optional with default of "warning" string enum

"off" - no messages logged

"debug" - logs debug, info, warning, and error messages

"info" - logs info, warning, and error messages

"warning" - logs warning and error messages

"error" - logs error messages

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. Optional with default of 30 int32 1 to 65535

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

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. Required - No default value 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"
  }
}

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. 

 

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

Optional with default of "". Defaults to

"unknown" in the Thing API 

 string 1 to 64 bytes

sourceServers

.sourceHostname

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

sourceServers

.sourcePassword

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

sourceServers

.sourcePort

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

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". Required if "sourceHostname" is not defined - No default value string 1 to 255 bytes

sourceServers

.sourceUsername

The "sourceUsername" property specifies the source account to be cloned.

Note See System limits for user name and other system properties requirements.

 Required - No default value string 1 to 31 bytes

sourceServers

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

sourceServers

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

sourceServers

tls

.caCertificateFilename

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

  • 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.
 Optional with default of "" string No limits

sourceServers

tls

.clientCertificateEnabled

 The "clientCertificateEnabled" property enables client certificate authentication if true. The target FairCom DB or RTG server must be configured to accept client certificates. Optional with default of false boolean

true

false

sourceServers

tls

.clientCertificateFilename

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

 Required - No default value string No limits

sourceServers

tls

.clientPrivateKeyFilename

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

 Required - No default value string No limits

sourceServers

tls

.enabled

The "enabled" property determines whether or not the specified 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"
        }
 Optional with default of true Boolean

true

false

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. Required - No default value string 1 to 64 characters

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. Optional with default of 8 integer 1 to 65535

 

Response properties ("result")

Property Description Type Limits (inclusive)

logLevel

 The "logLevel" property defines what type of messages the replication agent will log. string enum

"off" - no messages logged

"debug" - logs debug, info, warning, and error messages

"info" - logs info, warning, and error messages

"warning" - logs warning and error messages

"error" - logs error messages

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. object 0 or more key/value pairs

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

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. 

 

The Thing 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

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

sourceServers

.sourcePassword

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

sourceServers

.sourcePort

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

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". string 1 to 255 bytes

sourceServers

.sourceUsername

The "sourceUsername" property specifies the source account to be cloned.

Note See System limits for user name and other system properties requirements.

 string 1 to 31 bytes

sourceServers

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

"allowedCipherSuites"

"certificateAuthoritiesFilename"

"certificateFilename"

"privateKeyFilename"

sourceServers

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. 
 string No limits

sourceServers

tls

.caCertificateFilename

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

  • 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.
 string No limits

sourceServers

tls

.clientCertificateEnabled

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

true

false

sourceServers

tls

.clientCertificateFilename

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

 string No limits

sourceServers

tls

.clientPrivateKeyFilename

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

 string No limits

sourceServers

tls

.enabled

The "enabled" property determines whether or not the specified 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

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

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