Common Configuration (TCP)

Overview

Some Application instances contain TCP/IP functionality based on the TcpApp base class. In addition to the common Application configuration parameters and their application-specific attributes, these TCP Applications typically require TCP configuration as indicated below.

<?xml version="1.0" encoding="utf-8"?>
<n2svcd>
  ...
  <applications>
    ...
    <application name="<name>" module="<module>" overloaded_poll_ms="100" overloaded_active_ms="500">
      <include><lib>/path/to/library</lib></include>
      <parameters>
        <!-- application-specific parameters -->
        ...
        <!-- TCP application parameters (server example) -->
        <parameter name="listen_queue" value="20"/>
        <parameter name="local_host" value="192.168.10.10"/>
        <parameter name="local_port" value="8118"/>
        ...
        <!-- TCP application parameters (client example, identical) -->
        <parameter name="num_client_connections" value="5"/>
        <parameter name="local_host" value="192.168.10.10"/>
        <parameter name="remote_host" value="192.168.10.44"/>
        <parameter name="remote_port" value="8080"/>
        <parameter name="reconnect_interval" value="60"/>
        <parameter name="backlog_timeout" value="2"/>
        <parameter name="server_timeout" value="5"/>
        ...
        <!-- TCP application parameters (client example, disparate) -->
        <parameter name="local_host" value="192.168.10.10"/>
        <parameter name="remote_host" value="prod-prim.telco.com"/>
        <parameter name="reconnect_interval" value="60"/>
        <parameter name="backlog_timeout" value="2"/>
        <parameter name="server_timeout" value="5"/>
        <config>
          <client_connections>
            <client_connection remote_port="8080"/>
            <client_connection remote_port="8081"/>
            <client_connection remote_port="8082"/>
            <client_connection remote_port="8080"
              remote_host="prod-sec.telco.com" local_host="192.168.11.10" priority="2"/>
          </client_connections>
        </config>
      </parameters>
    </application>
    ...
  </application>
  ...
</n2svcd>

These TCP parameters include both server-relevant and client-relevant configuration parameters.

Applications which can operate in either mode will use either the TCP server or TCP client parameters (but not both).

Note that the terms “client” and “server” can apply differently at different layers of the protocol stack. For example, an application can operate as a client at the TCP layer (it initiates) the outbound TCP connection, but once the connection is established, it can passively wait to receive inbound requests for processing. Hence it is a client at the TCP layer, but a server at the higher layer.

Configuration Details

The application element attributes for all Application instances are as below. For details of the various parameter types used, refer to Common Configuration.

Parameter Name Type XML Type Description
parameters Array Element [Required] As per Common Configuration Application parameters.
.socket_mode String Attribute This must be either listen (TCP Server) or connect (TCP Client).
(Default = connect if supported, or listen)
.listen_queue Integer Attribute TCP Server only.
Backlog of pending accepts on the listen socket when socket_mode is listen.
This value may need to be increased when operating under heavy load..
(Default = 10)
.local_host String Attribute TCP Server or TCP Client.
Local IPv4 Host Name or A.B.C.D IPv4 Address for the TCP client connection.
(Default = 0.0.0.0, all addresses)
.local_port Positive Integer Attribute TCP Server or TCP Client.
Local IPv4 Port Number.
Using this option in TCP Client mode will cause a port confict if num_client_connections is > 1.
(Default = application-specific or determined by OS TCP layer, generally a system-allocated ephemeral port)
.remote_host String Attribute TCP Client only.
IPv4 Host Name or A.B.C.D IPv4 Address to connect to.
[Required] for TCP Client unless using the client_connections configuration.
.remote_port Positive Integer Attribute TCP Client only.
IPv4 Port Number to connect to.
[Required] for TCP Client unless using the client_connections configuration.
.ssl Integer Attribute TCP Client or TCP Server.
Whether the Application should use SSL/TLS for its server connections.
1 (Use SSL/https) or 0 (No-SSL, use http).
(Default = 0)
.SSL_verify_mode Integer Attribute TCP Client or TCP Server.
Whether the Application should verify the Peer's certificate.
1 (Verify Server's Certificate) or 0 (Do not verify Server's Certificate).
(Default = 1)
.SSL_ca_file String Attribute TCP Client or TCP Server.
Use a Certificate Authority contained in the indicated file.
(Default = Use system default Certificate Authorities)
.SSL_ca_path String Attribute TCP Client or TCP Server.
Use all Certificate Authority files contained in the indicated directory.
Multiple directories may be delimited by the : character.
(Default = Use system default Certificate Authorities)
.num_client_connections Positive Integer Attribute TCP Client only.
Number of simultaneous TCP client connections opened when socket_mode = connect.
This (Default = 1)
.connection_backlog Positive Integer Attribute TCP Client or TCP Server.
Number of in-progress requests to allow on a connection when sending.
(Default = 10)
.backlog_timeout Positive Integer Attribute TCP Client or TCP Server.
Number of seconds to wait for a free connection before abandoning the request.
(Default = 10)
.server_timeout Positive Integer Attribute TCP Client or TCP Server.
Number of seconds to wait on a submitted request before abandoning the request.
(Default = 20)
.reconnect_interval Positive Integer Attribute TCP Client only.
Time in seconds between attempts to re-connect a failed connection.
(Default = 5)
.ping_interval Integer Attribute TCP Client or TCP Server.
Time in seconds between sending the Application's protocol-specific ping message to check each connection.
Note that not all applications support sending pings; this value will be ignored if so. A ping_interval of zero will disable ping connection checks.
(Default = 0)
.ping_always Boolean Attribute TCP Client or TCP Server.
Whether the the Application's protocol-specific ping message should always be sent, even when the connection is active with user messages.
(Default = false, send ping only when inactive)
.max_send_attempts Positive Integer Attribute TCP Client or TCP Server.
Maximum number of attempts for sending each each request. This includes the original attempt, plus none or more retries.
A value of 1 means do not retry messages on failed connections.
(Default = 2)
.warning_queue_above Positive Integer Attribute TCP Client or TCP Server.
Generate a warning if the number of backlog unqueued requests reaches this value.
(Default = 20)
.notice_queue_below Positive Integer Attribute TCP Client or TCP Server.
Generate a notice if the number of backlog unqueued requests falls below this value.
(Default = 15)
.report_queue_warning_period Positive Integer Attribute TCP Client or TCP Server.
The number of seconds between reporting on the queue warning state.
(Default = 30)
config Object Element TCP Client or TCP Server.
This is a container for extended configuration for the LogicApp.
.client_connections Array of client_connection Objects Element TCP Client or TCP Server.
Defines the configured static Client Connections for this App.
This mechanism is used when the client connections are NOT identical within an application, for example when a single TCP Client application is connecting to more than one different remote port and/or remote host.
.client_connection Object Element Defines a single TCP Client connection.

TCP Client Connection

In the simplist case, a TCP Client application will create a single client connection, or will create multiple identical client connections. In that case the parameters mechanism will suffice.

However there are cases where an TCP Client application wishes to connect to disparate remote hosts and/or ports. In this case the config.client_applications element must be configured to define two or more client_connection elements.

An client_connection entry within the config.client_connections element of a TCP Client application has the following attributes:

Parameter Name Type XML Type Description
.local_host String Attribute TCP Server or TCP Client.
Local IPv4 Host Name or A.B.C.D IPv4 Address for the TCP client connection.
(Default = 0.0.0.0 or the parameters default)
.local_port Positive Integer Attribute TCP Server or TCP Client.
Local IPv4 Port Number.
Using this option in TCP Client mode will cause a port confict if num_client_connections is > 1.
(Default = the parameters default)
.remote_host String Attribute TCP Client only.
IPv4 Host Name or A.B.C.D IPv4 Address to connect to.
(Default = the parameters default)
.remote_port Positive Integer Attribute TCP Client only.
IPv4 Port Number to connect to.
(Default = the parameters default)
.priority Integer 1 - 99 Attribute The priority of this connection compared to the other connections within this application.
his is an integer value from 1 (top priority) to 99 (lowest priority).
The use of this "priority" for connection selection will vary from application to application. Some applications (particularly those which use transient TCP connections) may ignore this priority value.
(Default = 1 best priority)

Note that the num_client_connections parameter is incompatible with config.client_connections.

Some applications (e.g. FoxApp) may also have the option to load TCP client connection information from other sources, e.g. from a database.