☰
Navigation :

Common Configuration

Overview

All applications that run in the Service Daemon have common configuration options that can be applied to them. These options should be configured at the same level as the individual application parameters, i.e.:

<?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 -->
      </parameters>
    </application>
    ...
  </application>
  ...
</n2svcd>

Parameter Types

N2SVCD Applications support a variety of configuration parameter types, some with defined ranges of possible inputs.

Parameter Type Description
String A string containing any characters, e.g. abc.
Hex String A string containing hexadecimal characters, e.g. 123abc.
Integer A signed whole number, e.g. -1, 0, 1, etc.
Unsigned Integer An unsigned whole number, e.g. 0, 1, 2, etc.
Enumeration As for Unsigned Integer, but within a defined range.
Positive Integer An unsigned positive number, e.g. 1, 2, 3, etc.
Number A number with any sign and optionally a fractional component, e.g. 1.0, 2.5, etc.
Boolean A binary value, represented as any of the case-insensitive possible pairs 1/0, Y/N, YES/NO, ON/OFF, T/F, or TRUE/FALSE.
Array An ordered list of other parameter values of the same type.
Object A container for other arbitrary parameter values.

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.

Attribute Type Description
name String [Required] A unique name for this application instance.
module String [Required] The internal name for the type of the application. Refer to the application-specific configuration for the appropriate value to use.
include Array [Required] An array of directories containing the required application-specific libraries.
lib String [Required] An individual included application library directory. Refer to the application-specific configuration for which libraries are required.
parameters Array [Required] Array of name = value Parameters for this Application instance.
.trace_level Enumeration Attempt to enable in-memory tracing for all instances running inside this application, subject to the limitations of the trace_per_second configuration throttle. Tracing levels above debug should be used with care in production systems. Possible values are:
  • 0 = none
  • 1 = debug
  • 2 = dump
  • 3 = spam
(Default = 0)
.trace_level_max Enumeration This is a hard cap for trace level enabled dynamically during operation, e.g. via tracing traps or via dynamic change to trace_level using the administration GUI. This is intended to protect production systems from excessive tracing overheads. It is determined at startup time and cannot be modified. Possible values are:
  • 0 = none
  • 1 = debug
  • 2 = dump
  • 3 = spam
(Default = one level higher than the initial value of trace_level)
.trace_per_second Positive Integer The maximum number of instances for this application which may have their instance trace log enabled in any given second. If this value is reached, then subsequent requests to activate tracing will be ignored until the start of a new clock second. Values above 1 should be used with care in production systems.
(Default = 1)
.retention_count Positive Integer The number of most-recent traced dialogs to retain in-memory for monitoring.
(Default = 50)
.edr_enabled Boolean Whether writing of EDR files should be enabled or not. Note that not all applications support EDRs; this value will be ignored if so.
(Default = NO, do not write EDR files)
.edr_directory String Directory where EDR files will be written.
(Default = /var/lib/n2svcd/edrs)
.edr_prefix String Prefix for EDR filenames.
(Default = Set Per-Application)
.edr_hostname String Hostname for EDR filenames.
(Default = Determined from System Configuration)
.edr_retry_interval Positive Integer Number of seconds to wait before retrying to create a new EDR output file after an attempt to create a new file has failed.
(Default = 30)
.edr_report_interval Positive Integer Number of seconds between the EDR Writer child process reporting the current file size and EDR count back to the parent process for Management purposes.
(Default = 5)
.edr_num_files_shown Positive Integer How many recent EDR files the application displays in the Management Interface.
(Default = 20)
.edr_max_file_edrs Positive Integer How many EDRs can be written to an EDR file before the file is closed and a new file is started.
(Default = 2000)
.edr_max_file_secs Positive Integer How long an EDR file can be open before the file is closed and a new file is started.
(Default = 300)
.edr_max_flush_edrs Positive Integer How many EDRs can be written to an EDR file before a disk I/O flush is performed on the file.
(Default = 20)
.edr_max_flush_secs Positive Integer How long an EDR file can be open for before a disk I/O flush is performed on the file.
(Default = 5)

TCP Configuration Details

Some Application instances contain TCP/IP functionality. In addition to the common Application configuration parameters, such Applications may also include the below. For details of the various parameter types used, refer to Common Configuration.

Attribute Type Description
parameters Array [Required] As per Common Configuration Application parameters.
.socket_mode String This must be either listen (TCP Server) or connect (TCP Client).
(Default = connect)
.listen_queue Integer 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 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 Local IPv4 Port Number for the TCP client connection. Using this option 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 [Conditional] IPv4 Host Name or A.B.C.D IPv4 Address to connect to. Must be provided when socket_mode = connect.
.remote_port Positive Integer [Conditional] IPv4 Port Number to connect to. Must be provided when socket_mode = connect.
.ssl Integer 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 Wheter the Application should verify the Server Peer's certificate.
1 (Verify Server's Certificate) or 0 (Do not verify Server's Certificate).
(Default = 1)
.SSL_ca_file String Use a Certificate Authority contained in the indicated file.
(Default = Use system default Certificate Authorities)
.SSL_ca_path String 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 Number of simultaneous TCP client connections opened when socket_mode = connect. (Default = 1)
.pool Positive Integer [Deprecated] Alias for num_client_connections.
.connection_backlog Positive Integer Number of in-progress requests to allow on a connection.
(Default = 10)
.backlog_timeout Positive Integer Number of seconds to wait for a free connection before abandoning the request.
(Default = 10)
.server_timeout Positive Integer Number of seconds to wait on a submitted request before abandoning the request.
(Default = 20)
.reconnect_interval Positive Integer Time in seconds between attempts to re-connect a failed connection.
(Default = 5)
.ping_interval Integer 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 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 Maximum number of attempts for sending each each request in the case where the connection dies while the message is in transit. A value of 1 means do not retry messages on failed connections.
(Default = 2)
.warning_queue_above Positive Integer Generate a warning if the number of unqueued messages reaches this value.
(Default = 20)
.notice_queue_below Positive Integer Generate a notice if the number of unqueued messages falls below this value.
(Default = 15)
.report_queue_warning_period Positive Integer The number of seconds between reporting on the queue warning state.
(Default = 30)

Message Handling

All applications use the following messages: