☰
Navigation :

App Config (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)">
      <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"/>
        <parameter name="local_timeout" value="5"/>
        ...
        <!-- 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"/>
        ...
        <!-- SSL configuration for a simple SSL-encrypted server -->
        <parameter name="ssl" value="yes"/>
        <parameter name="ssl.SSL_cert_file" value="../etc/ssl/localhost.crt"/>
        <parameter name="ssl.SSL_key_file" value="../etc/ssl/localhost.key"/>
        ...
        <!-- SSL configuration for a simple SSL-encrypted client using self-generated CA -->
        <parameter name="ssl" value="yes"/>
        <parameter name="ssl.SSL_ca_file" value="../etc/ssl/localhost.crt"/>
      </parameters>
      <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>     
    </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 TCP 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 server listen or 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/TLS) or 0 (No SSL/TLS).
(Default = 0)
"ssl.SSL_verify_mode" 0 / 1 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).
(Server Default = 0, Client Default = 1)
"ssl.SSL_ca_file" String Attribute TCP Client or TCP Server.
Use the Certificate Authority certificates contained in the indicated file.
(Default = Use system default Certificate Authorities)
"ssl.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)
"ssl.SSL_cert_file" String Attribute TCP Client or TCP Server.
Use the certificate contained in this file.
(Server Default = Use system default certificate, Client Default = Do not present a certificate)
"ssl.SSL_key_file" String Attribute TCP Client or TCP Server.
Use the key contained in this file.
(Server Default = Use system default key, Client Default = Do not use a key file)
"ssl.SSL_server_name" String Attribute TCP Client.
Include a Server Name Indication (SNI) extension with this value in the SSL/TLS ClientHello message.
(Default = Do not include an SNI extension in the SSL/TLS ClientHello message.)
"num_client_connections" Positive Integer Attribute TCP Client only.
Number of simultaneous TCP client connections opened when socket_mode = connect.
(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.
Note that timeout checking is only performed every half-second.
(Default = 20)
"local_timeout" Positive Integer Attribute TCP Server only.
Number of seconds to wait for internal processing to complete before abandoning the request and returning an error to the client.
Note that timeout checking is only performed every half-second.
(Default = 5)
"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 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 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 rises to 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 simplest 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_connections element must be configured to define two or more client_connection elements.

A 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.
This 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.