Navigation :

Configuration

Overview

At startup, the n2svcd binary reads its static configuration from its configuration file. This defaults to /etc/n2svcd/n2svcd.xml, but may be changed using the --config command-line parameter. This file defines the configuration for all of the N2SVCD applications.

Example Configuration File

The following is an example N2SVCD configuration file with three applications configured.

<?xml version="1.0" encoding="utf-8"?>
<n2svcd multi="1" overloaded_poll_ms="100" overloaded_active_ms="500">
  <syslog enabled="1" ident="n2svcd"/>
  <statsd>
    <host>stats.mysite.com</host>
    <port>8125</port>
    <prefix>n2svcd.myhost.</prefix>
  </statsd>

  <applications>
    <application name="Manage" module="ManageApp">
      <include>
        <lib>../apps/manage/lib</lib>
      </include>
    </application>

    <application name="SIGTRAN" module="SigtranApp">
      <include>
        <lib>../apps/sigtran/lib</lib>
      </include>
      <parameters>
        <parameter name="opc" value="4112"/>
        <parameter name="ossn" value="10"/>
      </parameters>
      <config>
        <connections>
          <connection name="Loopback" type="loopback"/>
          <connection name="telco-slc01" type="sua" sg_dpc="2058" traffic_mode="2">
            <remote_host>10.42.2.155</remote_host>
            <remote_port>14001</remote_port>
            <local_host>10.42.2.100</local_host>
            <local_port>15000</local_port>
          </connection>
        </connections>
        <routes>
          <route pc="4112" connection="Loopback"/>
          <route pc="2058" connection="telco-slc01"/>
        </routes>
      </config>
    </application>

    <application name="Tester" module="TesterApp">
      <include>
        <lib>../apps/tester/lib</lib>
      </include>
      <parameters>
        <parameter name="json_host" value="0.0.0.0"/>
        <parameter name="json_port" value="9009"/>
      </parameters>
    </application>
  </applications>
</n2svcd>

Parameters

The following top-level elements/attributes are supported.

Attribute	Type	Description
`multi`	Integer	Set this to `1` to enable multi-process service daemon, `0` to disable. The command-line flags `--multi` or `--no-multi` will override the configuration file value. (Default = `0`, use single-process service daemon)
`overloaded_poll_ms`	Integer	Set this to override the global default warning threshold ms before a warning is generated for an overloaded non active app. (Default = `100` ms)
`overloaded_active_ms`	Integer	Set this to override the global default warning threshold ms before a warning is generated for an overloaded active app. (Default = `500` ms)
`syslog`	Object	Container for system log configuration.
`statsd`	Object	Container for StatsD statistics relay configuration.
`polling`	Object	Container for polling configuration.
`applications`	Array	Container for one or more Applications.
`.application`	Object	Container for a single configured Application running within the Service Daemon. Refer to the specific Application configuration documentation for the additional configuration for each Application.
`virtuals`	Array	Container for one or more user-defined Virtual Application translations.
`.virtual`	Object	Container for a user-defined Virtual Application used for load-sharing or failover.

Syslog Configuration

The syslog top-level configuration Object defines the configuration for writing to the Linux Syslog. By default, Syslog writing is disabled. Only messages of level NOTICE, WARNING and ERROR will ever be written to the Syslog. DEBUG, DUMP and SPAM is never written to the Syslog.

The syslog configuration object supports the following attributes:

Attribute	Type	Description
`enabled`	Integer	Set this to `1` to enable writing to the Linux Syslog, `0` to disable. (Default = `0`, do not write to the Linux Syslog)
`ident`	String	The application Ident value written to every Syslog record. (Default = Main Program name, typically `n2svcd`)
`pid`	Integer	Specify `1` to include PID in Syslog records, `0` to exclude PID. (Default = `1`, include PID in Syslog records)

StatsD Configuration

The statsd top-level configuration Object is used to define a destination for the delivery of statistics counters. By default, statistics counter values are only stored in memory and will be lost when n2svcd is restarted. If you wish to maintain a permanent record of statistics counters then you must set up a STATSD server and configure it here.

The statsd configuration object supports the following attributes:

Attribute	Type	Description
`host`	String	IPv4 Host Name or A.B.C.D IPv4 Address for UDP StatsD host. (Default = Do not notify statistics to an external agent)
`port`	Integer	Port number for UDP StatsD daemon. (Default = `8125`)
`prefix`	String	Common prefix for UDP StatsD notifications. The generating Application Name will also form part of the statistics counter name. (Default = `n2svcd.`)

Polling Configuration

The polling top-level configuration Object is used to override the default timer loop settings for the polling logic. These settings will apply to all applications running within this n2svcd instance. Reducing the polling rest and sleep timers will increase application responsiveness at the cost of extra CPU usage.

The polling configuration object supports the following attributes:

`rest_ms`	Integer	The number of millseconds to pause between polling loops when the application has recently finished performing work. A lower value will improve response time under moderate load, but will increase CPU usage under light load. (Default = `5` milliseconds)
`sleep_ms`	Integer	The number of millseconds to sleep between polling loops when the application has not performed any activity for several rests. A lower value will improve response time under light load, but will increase CPU usage under light load. (Default = `20` milliseconds)
`rests_before_sleep`	Integer	The number of short "rest" periods that must elapse without activity before each application performs longer "sleep" periods. A higher value will improve response time under moderate load, but will increase the CPU usage under light load. (Default = `100` rests before sleep)

Application Configuration

The applications.application configuration object is used to define Real Applications. These Real Applications perform all of the work within n2svcd.

Each application object has its own class-specific configuration structure which is described in the separate, dedicated configuration page for that Application. However, there are some common attributes for each Application, as described here.

Note that there is a special case for the WatchdogApp. If you do not define an application instance of WatchdogApp in the applications list, then one will be created automatically.

Attribute	Type	Description
`disabled`	`0` / `1` / `yes` / `no`	Convenience flag for disabling applications when testing. (Default = `0`, application is not disabled)
`name`	String	[Required] A unique name for this application instance. This may include only the characters `[a-z0-9 _\-]`.
`module`	String	[Required] Value defines which Application class will be loaded.
`include`	Array	Array of library class paths to pre-load when instantiating the Application class.
`.lib`	String	[Required] Relative or Absolute directory path in which the Application class is found.
`parameters`	Array	Array of parameter configuration to configure the Application.
`.parameter`	Object	A parameter to be passed to the Application at configuration time.
`.name`	String	[Required] Name of the Application parameter. See per-Application class documentation.
`.value`	String	The parameter configuration value which will be passed to all Application instances, unless overridded using a per-instance `value-` override. This value may specified indirectly via an environment variable `${VARNAME}` or a shell command ` command `.
`.value-`	String	A parameter value specific to a single instance of a repeated Application. The first application override value key is `value-1`. See notes below concerning Repeated Applications.
`repeat`	Integer	Number of instances of this Application to construct. (Default = `1`)
`user_alloc`	Integer	Number of bytes in the "User Message" inter-application IPC receive queue. Applications operating under heavy load may require an explicitly higher value. A suffix of `k` or `m` indicates Kilobytes or Megabytes. Otherwise value is bytes. (Default = `1m`)
`admin_alloc`	Integer	Number of bytes in the "Admin Message" inter-application IPC receive queue. Complex Applications may require an explicitly higher value. A suffix of `k` or `m` indicates Kilobytes or Megabytes. Otherwise value is bytes. The ManageApp may require an explicitly higher value. (Default = `128k`)

Evaluated Parameters

The value or value-<idx> for a <parameter> entry in an application may be specified as the value of an environment variable by wrapping the environment variable name in ${ and }. For example, <parameter="local_ip" value="${PRIMARY_IP}"/> indicates that the parameter value for local_ip is value of the unix environment variable PRIMARY_IP.

Alternatively, a value or value-<idx> wrapped in backticks ` indicates a unix command shell that should be executed, and the returned STDOUT/STDERR value is the value of the parameter. For example, <parameter="local_ip" value="`hostname -s`"/> indicates that the parameter value for local_ip is the result of executing the unix command hostname -s .

Note that this command will be run as the unix user who is executing n2svcd. Hence the configuration file n2svcd.xml must be secured appropriately against write-access to avoid a privilege-elevation security breach.

Repeating Real Applications

The repeat attribute is a mechanism by which load-sharing can be easily configured when running n2svcd in multi-process mode on suitable hardware.

An application configured with repeat will result in the creation of multiple Real Application instances, each with a name formed by appending :1, :2, etc. onto the given name. The given name will then be instantiated as a Virtual Application which maps to all of the multiple Real Applications.

e.g. When configured with name = Scripter and repeat = 2 then the following will be created:

A Real Application Scripter:1.
A Real Application Scripter:2.
A Virtual Application Scripter which load-shares across Scripter:1, Scripter:2.

To configure separate parameters.parameter values for different repeated application instances, use the value- syntax.

The following example configuration creates three instances of RealApp1 with port numbers 4601, 4602, and 4603 respectively.

<n2svcd>
  <applications>
    <application name="RealApp1" repeat="3">
      ...
      <parameters>
        <parameter name="PortNumber" value="4601">
          <value-2>4602</value-2>
          <value-3>4603</value-3>
        </parameter>
      </parameters>
    </application>
  </applications>
</n2svcd>

Note that if n2svcd is running in the default single-process mode then there will be no performance gain by creating multiple Application instances.

Applications which need exclusive access to a single resource (such as a single local server port number) are not obvious candidates for multiple instances.

Virtual Application Configuration

Virtual Applications are the mechanism by which one Application Name can translate at run-time into multiple Real Application instances. This offers a mechanism for load-sharing and redundancy.

As described above, the repeat attribute on the application configuration object is the simplest way to construct a Virtual Application for load-sharing across two identical instances. The parameter per-instance value override mechanism should support most common configuration cases.

However, if that configuration mechanism does not provide sufficient configuration flexibility for your purposes (or if you wish to make the Virtual Application mechanism more explicit) then you may manually configure explicit Virtual Applications using the virtuals configuration Array.

<n2svcd>
  <virtuals>
    <virtual name="VirtualApp">
      <applications>
        <application name="RealApp1" promoted="1"/>
        <application name="RealApp2" promoted="0"/>
      </applications>
    </virtual>
  </virtuals>

  <applications>
    <application name="RealApp1">
      ...
    </application>

    <application name="RealApp2">
      ...
    </application>
  </applications>
</n2svcd>

Each virtual configuration Object supports the following attributes:

Attribute	Type	Description
`name`	String	[Required] Name for your Virtual Application. Must not conflict with any other defined Real or Virtual Application name.
`applications`	Array	Array of Real Applications.
`.application`	Object	Entry for a Real Application translation for the Virtual Application.
`.name`	String	[Required] Name of the Real Application. Must be a configured Application name.
`.standby`	Integer	Set this to `1` to indicate that this Application is consided a Standby within the configured applications. This means that even when the Application reports itself with Status higher than STATUS_STANDBY, the maximum Status used when translating a Virtual Application Handle will be STATUS_STANDBY.
`.promoted`	Non-Negative Integer	Setting this to value greater than `0` indicates that this Application should always be promoted when translating a Virtual Application Handle across two Applications which otherwise have the same current Status. (Default = `0`)

Handle Translation and Application Status

Both the “Repeated Real Applications” and “Virtual Application Configuration” provide a mechanism by which a single Application Handle is created, which at run-time is translated to exactly one Real Application (for the purpose of load-sharing and/or failover).

The key attribute for translating an Application Handle into a Real Application is the Availability Status of the available Real Applications, which is as follows:

8/STATUS_AVAILABLE - Application has connectivity, and is lightly loaded (or not loaded at all).
7/STATUS_BUSY - Application has connectivity, is active, but is not overloaded.
6/STATUS_STANDBY - Application is actually AVAILABLE/BUSY but is in STANDBY mode.
5/STATUS_LOADED - Application has connectivity, but is 100% loaded (or more).
4/STATUS_FALLBACK - Application is actually AVAILABLE/BUSY/LOADED but is in FALLBACK mode.
3/STATUS_OFFLINE - Application has lost connectivity, or is overloaded to the point of failure.
2/STATUS_UNKNOWN - Application is not currently reporting status correctly.
1/STATUS_QUIESCING - Application will not accept new user tasks, but will continue existing tasks.
0/STATUS_SHUTDOWN - Application is in startup or shutdown mode and cannot accept user tasks now.

Each Application implements its own logic to determine and update its status in real-time.

When translating a Handle into a Real Application, the following logic is used:

The Application with the highest current Application Status is always used.
Any Application marked standby is capped at STATUS_STANDBY for this tranlation.
Any Application marked fallback is capped at STATUS_FALLBACK for this tranlation.
For Applications with the same Status, the highest promoted Application is always used.
For Applications with the same Status and promoted value, Round-Robin is performed.

Note that the “Repeated Real Applications” convenience mechanism does not support the configuration of standby, fallback or promoted attributes. These are only available through the “Virtual Application Configuration” mechanism.

Note that when using standby or fallback flags with Virtual Application translation, the web-based ManageApp will show the full working status of the Real Application (e.g. STATUS_AVAILABLE, STATUS_BUSY) and not the “capped” status that a Virtual Application translation may decide to apply.