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">
  <snmp enabled="1" host="localhost"/>
  <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" next_hop_pc="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.

Syslog Configuration

The syslog top-level configuration Object defines the configuration for writing to the Linux Syslog. By default, Syslog writing is disabled. Only Events (NOTICE or WARNING) or Alarms (ALARM or CLEAR) 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:

SNMP Configuration

The snmp top-level configuration Object defines the configuration for sending Event and Alarm traps to an SNMP trap daemon. By default, SNMP trap delivery is disabled.

Only Events (NOTICE or WARNING) or Alarms (ALARM or CLEAR) will ever be delivered as SNMP traps.

DEBUG, DUMP and SPAM are never written as an SNMP trap.

The snmp configuration object supports the following attributes:

Note that this mechanism delivers only via UDP using an SNMPv2c/v3 trap encoding, and does not support any security mechanisms.

This is because the expected usage is to hand-off traps to a local snmptrapd over the secure localhost address. This local snmptrapd will then perform the off-platform forwarding to a downstream endpoint using one or more SNMPv3 security mechanisms.

Refer to the Alarms section of this technical guide for more detail regarding the SNMP trap fields.

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:

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:

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.

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-<idx> 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 element.

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

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

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

Each virtual configuration Object supports the following attributes:

Application Loadshare & Failover

Both the “Repeated Real Applications” (implicit virtuals) and the (explicit) “Virtual Application Configuration” provide a mechanism by which a single Virtual Application Handle is created which maps to multiple Real Applications.

At run-time, any service wishing to pass a request to Virtual App must determine which of the single Real apps will actually perform the processing.

There are two main reasons why this is done:

1. To load-share across more then one CPU core/thread.
2. To perform standby/fallback/disaster scenarios.

The scenario is typically this. One Application “A” will have a task which needs to be performed by a Virtual Application “B”. Examples of this scenario are:

• Application “A” is an inbound Server Application such as SigtranApp or RestServerApp.
• Application “A” is a processing application such as LogicApp or TesterApp.

Application “A” determines has a Virtual Application Handle which maps to multiple Real copies of Application “B”. At the time of making the request to Application B, our initiating Application will resolve the Virtual Handle to a Real Handle by selecting the “best” option.

The logic in determining “best” depends on the relative “availability” the various different real applications underlying Application “B”.

There are FOUR different “availability” factors to consider in this comparison.

Priority

Every real application has a priority which is one of:

• [0] DISASTER
• [1] FALLBACK
• [2] STANDBY
• [3] PRIMARY (default)

This is a static parameter configured by the priority attribute on the <application> definition element. It may also be changed at run-time via the GUI.

Access

Every real application has an access indicator which is one of:

• [0] SHUTDOWN
• [1] OFFLINE
• [2] QUIESCING
• [3] ONLINE

This is set dynamically. Each application is responsible for monitoring the state of its external connections and its internal processing capabilities, and regularly notifying other applications (via the IPC shared memory area) the access which it can offer for processing requests. This allows the other applications to make sensible preference decisions for the purpose of load-balancing and failover.

Load & Backlog

Every real application which offers a processing service to other applications should monitor its own processing load and backlog, and should notify other applications of the up-to-date status of these parameters. Again, these are notified via the IPC shared memory area.

The two parameters are are:

• The Load % (of maximum) the Application is currently operating under.
• The Backlog % (of maximum) the Application is currently operating under.

These are integer values from 0 to 100. The extreme values should be used strictly, e.g.

1. An application should only notify 0% load when the load is absolutely zero.
   
2. An application should only notify 100% load when the load is absolutely at maximum, and any further requests will be placed in the backlog queue.
   
3. An application should only notify 0% backlog when the backlog is absolutely zero and all current requests are actively being processed .
   
4. An application should only notify 100% backlog when the backlog is absolutely at maximum, and any further requests will likely be timed-out or rejected.

In all other cases, values in the range 1 through 99 should be used.

E.g. 0.2% load should be reported as 1% not 0%, and 99.6% backlog should be reported as 99% backlog, not 100%.

Each application will define its own criteria for computing percentage. This will typically consider the number of connections, the number of simultaneous outstanding requests permitted per connection.

For computing the “backlog”, this may be a queue-size as a percentage of some arbitrary limit, or it may be a time-based computation. For example if the application has a limit of 4 seconds processing before a request is timed-out, then “50% backlog” may represent an average processing time of 2.0 seconds. Alternatively, this may be sized-based according to some arbitrary backlog queue size configuration.

The key factor is that these numbers should be comparable between comparable applications, enabling sensible load-sharing comparisons.

Selection Logic

The following selection logic is used when selecting preference among applications for processing a new request.

1. New sessions will only be created towards Applications with access ONLINE.
2. When two applications have the same priority, the lowest load is preffered.
3. When two applications have the same priority and both have 100% load, the lowest backlog is preferred.
4. Otherwise, the following priority/load/backlog combinations are preferred in descending order.