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.
- Some applications (e.g.
RestClientApp
,SoapClientApp
,FoxApp
,MmlClientApp
) operate only in TCP client mode, and hence use only the client parameters. - Some applications (e.g.
RestServerApp
,SoapServerApp
) operate only in TCP server mode, and hence only use the TCP client parameters. - Other applications (e.g.
DiameterApp
,SMPPApp
) can operate in either TCP client mode or TCP server mode, according to the configuration of thesocket_mode
parameter.
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. (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. (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:
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.