Version 22.0.8473

• Overview
• Connector Settings
  • Settings Tab
    • Configuration
    • Message Decoding
    • TLS Settings
  • Advanced Tab
    • Logging
    • Keep Alive
    • Other Settings
    • Miscellaneous
  • Server Tab
    • Trusted IP Addresses
• Connected and Disconnected Messages
• Sending Messages

TCP Server Connectors support hosting a generic endpoint for receiving arbitrary data over TCP.

Overview

Each TCP Server Connector listens on a specified port for incoming TCP traffic, either with SSL/TLS encryption or plaintext. The connector is intended for use when CData Arc needs to receive arbitrary data that does not necessarily fit into the constraints provided by other standard protocols.

Since TCP traffic is a constant stream that does not intrinsically have a ‘start’ or ‘end’ point, the connector must be configured to determine where one message ends and the next begins. The connector supports two approaches:

• A static string/character delimiter that ends the current message or begins the next message
• Reading a value in the incoming TCP data to determine how long the message should be

For the second approach, the connector requires an offset (how many bytes after the first byte to begin reading the message length) and a size (how many bytes to read, starting at the offset, to read the length value). If the length of the message is the first value in the ‘header’ for the message, the offset should be 0.

Once the delimiter or length is reached, the connector will push a message into the Arc Flow containing the raw data received over TCP.

The TCP Server Connector can also generate an Arc message when a client connects or disconnects, to alert other processes within the Flow. More information can be found in the Connected and Disconnected Messages section.

For information on sending responses back to TCP clients, please see the Sending Messages section.

Connector Settings

Settings Tab

Configuration

Settings related to the core configuration of the connector.

• Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
• Connector Description An optional field to provide free-form description of the connector and its role in the flow.
• Port The port on which to listen for incoming TCP connections.

Message Decoding

Settings related to distinguishing individual messages from the TCP stream.

• Message Start Delimiter The character or string indicating the start of a new message.
• Message End Delimiter The character or string indicating the end of the current message.
• Message Length Offset The number of bytes to skip before beginning to read the length of the message from the incoming data.
• Message Length Size The size in bytes of the length value within the incoming data.

TLS Settings

Settings related to SSL/TLS transport security.

• Enable TLS Whether clients must negotiate SSL/TLS encryption to connect to the TCP server.
• Server Certificate The SSL/TLS certificate that identifies the TCP server.
• Certificate Password The password to access the Server Certificate’s private key.

Advanced Tab

Logging

Settings that govern the creation and storage of logs.

• Log Level Specifies the type of information to log in the connector’s Logs directory:
  • None — Does not create any logs.
  • Error — Creates logs only when the connector encounters an error.
  • Warning — Creates logs only when the connector issues a warning.
  • Info — Logs general information about the workflow, including any errors and warnings (if applicable).
  • Debug — Logs detailed debugging information for both successful and failed workflows.
  • Trace — Logs detailed trace information for both successful and failed workflows.

  Please note that Debug and Trace may log sensitive information including message contents and SSL certificates. Although connection properties (such as passwords) are masked, please review logs of this level for sensitive information before sharing them outside of your organization.

• Log Subfolder Scheme Instructs the connector to group files in the Logs folder according to the selected interval. For example, the Weekly option instructs the connector to create a new subfolder each week and store all logs for the week in that folder. The blank setting tells the connector to save all logs directly in the Logs folder. For connectors that process many transactions, using subfolders can help keep logs organized and improve performance.
• Log Messages A toggle that instructs the connector to save a copy of the most recent message in the Logs directory. Note that the connector only keeps one message per subfolder, and the connector overrides the previously-saved message when it runs again.

Keep Alive

Settings related to keep-alive packets sent by the server to maintain an idle connection.

• Keep Alive Whether to send keep-alive packets periodically to ensure that idle connections are not closed due to inactivity.
• Keep Alive Time The length of inactivity that should elapse before sending the first keep-alive packet.
• Keep Alive Interval The interval between consecutive keep-alive packets.

Other Settings

Settings not included in the previous categories.

• Connected Messages Whether the connector should generate an Arc message when a client connects. More information can be found in the Connected and Disconnected Messages section.
• Disconnected Messages Whether the connector should generate an Arc message when a client disconnects. More information can be found in the Connected and Disconnected Messages section.
• Idle Timeout The length of time the server should wait for an idle client before disconnecting them due to inactivity.
• Local File Scheme A filemask for determining local file names as they are downloaded by the connector. The following macros may be used to reference contextual information:
  %ConnectorId%, %Filename%, %FilenameNoExt%, %Ext%, %ShortDate%, %LongDate%, %RegexFilename:%, %DateFormat:%.
  As an example: %FilenameNoExt%_%ShortDate%%Ext%
• Local Host The binding address of the local server, if not the default network interface.
• Log Level The level of detail included in logs generated for the connector.
• Max Connections The maximum number of concurrent connectors.
• Other An arbitrary set of advanced configuration settings.
• Parent Connector If set to another TCP Server Connector, this connector will inherit settings from that connector. Any local settings will override settings from the parent.
• Log Messages Whether logs from sent files will include a copy of the file itself.
• Save to Sent Folder Whether files sent by the connector should be copied to the Sent folder for the connector.
• SSL/TLS Enabled Protocols The list of SSL/TLS protocols supported when establishing outgoing connections. It is strongly recommended to only use TLS protocols. Some obsolete operating systems do not support TLS 1.2.

Miscellaneous

Settings for specific use cases.

• Other Settings Allows configuration of hidden connector settings in a semicolon-separated list, like setting1=value1;setting2=value2. Normal connector use cases and functionality should not require use of these settings.

Server Tab

Trusted IP Addresses

This section defines the IP addresses that are allowed to make connections. The following functions are available:

• Add Opens a modal to enter a new IP address range.
• Edit Opens a modal to modify the selected IP address range.
• Delete Deletes the selected IP address range from the list.

The following restrictions apply to this feature:

• localhost cannot be modified or removed from the list.
• Any IP addresses outside of the defined ranges will be rejected.
• Ranges are supported. For example, the entry 100.10.100.1-15 indicates that IP addresses between 100.10.100.1 and 100.10.100.15 are allowed.
• CIDR notation is supported. For example, the entry 100.10.100.0/24 indicates that IP addresses between 100.10.100.0 and 100.10.100.255 are allowed.
• Wildcard patterns are supported. For example, the entry 100.10.100.* indicates that IP addresses beginning with 100.10.100 are allowed.

Connected and Disconnected Messages

By default, the TCP Server Connector will only generate Arc messages when clients transfer data such that the connector recognizes a full message (according to the settings in the Message Decoding section). The connector can also generate Arc messages when a client connects to the server (if Connected Messages is enabled in the Advanced tab) or disconnects from the server (if Disconnected Messages is enabled in the Advanced tab).

When these special messages are generated, a special header is added to the Arc message:

x-tcpserver-event

This header is set to the value ‘connected’ when clients are connecting, and ‘disconnected’ when clients are disconnecting.

This header value must be checked by later connectors in the Flow to detect whether a message written to the output folder of a TCP Server Connector is one of these special messages.

Sending Messages

The TCP Server Connector also uses a special header value to send messages back to connected clients:

x-tcpserver-connectionid

This header is added to any output messages generated by the connector, set to a ‘Connection ID’ value that uniquely identifies one of the connected clients. Messages that should be sent back to this client must have this same header set to the same value in order to ensure that the message is sent to the appropriate client.

Since this header is already present on any messages written out by the connector, if the message passes through an Arc Flow and arrives back at the Send folder for the TCP Server Connector, it will still have the same ‘Connection ID’ value and will be returned to the same client that sent the original message. If the message cannot be directly routed back to the TCP Server Connector, then the ‘Connection ID’ value must be saved and applied as a header (with the same name listed above) to whatever new messages should be returned to the client.