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>
  </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 Trap 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.

Refer to the Alarms section for more detail regarding the SNMP trap fields.

If one or more SNMP Applications are specified and the SNMP version is 3, those applications will be used to deliver SNMP traps. If the version is 2 or SNMP applications are not configured and specified within the snmp section, SNMP traps will be sent directly from each component as required. In both cases, the snmp top-level configuration is used unless overridden by application-specific parameters.

Note that:

• All SNMP traps are only sent over UDP.
• The only security model supported for SNMP v3 is USM.

An example configuration might be:

<?xml version="1.0" encoding="utf-8"?>
<n2svcd multi="1">
    ...
    <snmp enabled="1" version="3">
        <auth_username>user1</auth_username>
        <auth_alg>md5</auth_alg>
        <auth_key>0183c5b0eefb85b6dd3181a787219bc5</auth_key>
        <privacy_alg>des</privacy_alg>
        <privacy_key>0183c5b0eefb85b6dd3181a787219bc5</privacy_key>
  	</snmp>
  	...
</n2svcd>

The available configuration for SNMP traps depends on the version selected. All SNMP configuration items may be set as N2SVCD evaluated parameters.

Common SNMP Trap Configuration

The snmp configuration object supports the following attributes for all SNMP versions:

SNMP v2 Trap Configuration

The snmp configuration object supports the following additional attributes for SNMP v2:

SNMP v3 Trap Configuration

The snmp configuration object supports the following additional attributes for SNMP v3:

Note that:

• The required privacy_key length is 16 characters (128 bits) for DES encryption rather than the usual 8 characters (64 bits). This is due to the requirements for encryption given in RFC 3114.
• Using auth_password or privacy_password is not allowable for strict compliance with RFC 3414. The N2SVCD system will therefore issue notices at startup giving the localised keys that can be used instead for auth_key and privacy_key, respectively.
• Each comma-separated snmp_apps value is treated as an independent parameter for N2SVCD evaluated parameter lookups.

SNMP v3 Engine IDs

When SNMP v3 is used, each N2SVCD application (including instances of repeated applications) identifies itself with an SNMP engine ID when sending SNMP traps, either as an authoritative engine (at the message layer) or as a context engine (within the message PDU).

SNMP engine IDs are generated in the following manner, depending on configuration:

1. If id_literal is configured, the entire SNMP engine ID is set using it and no other configuration applies.
2. The first four octets are set by the id_iana_pem value.
3. The first bit is set by id_v3_format as either 1 or 0.
4. If id_v3_format is true, the fifth octet is set according to id_value_format.
5. The remaining octets are set according to id_value. If no explicit configuration exists for this parameter, the format used is as follows:

<hostname>.<configured application name[:application iteration]>

Note that:

• The application iteration will only be present if the application is repeated.
• The hostname and the application name will be trimmed from the front in order to fit the length requirements of RFC 3411.
• Only the ID value format 4 (text) will be treated as text when encoded. Other values must ensure that the configured value is a hexadecimal string.

As an example, given the following configured values:

• iana_pen => (not set)
• id_v3_format => true
• id_value_format => 4
• id_value => Fred

… the generated SNMP engine ID would be 80:00:DC:DC:04:46:72:65:64 (colons added for legibility), where:

• 80:00:DC:DC contains the default IANA PEN 56540 with the first bit set,
• 04 sets the value format as “text”, and
• 46:72:65:64 is the encoding of the ID value.

Note that with this configuration, the maximum allowable ID value length would be 27.

Refer to RFC 3411 for full details of SNMP engine ID formats and their usage within SNMP messages.

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.

Repeating 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 :0, :1, etc. onto the given name. The given name will then be instantiated as a Virtual Application Pool which maps to all of the multiple configuration names (each with one or more real applications).

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

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

Note that in all cases, non-repeated applications will be internally referred to with the suffix :0.

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. Note that indexes are zero-based.

<n2svcd>
  <applications>
    <application name="RealApp1" repeat="3">
      ...
      <parameters>
        <parameter name="PortNumber" value="4601">
          <value-1>4602</value-1>
          <value-2>4603</value-2>
        </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.

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.

Virtual Application Pool Configuration

A Virtual Application Pool definition is a mechanism by which more then one Config Name can be grouped into a shared resource pool for the purpose of load-sharing/failover.

a. You have multiple services but they need slightly different config, so you are going to use different configuration (two different config name pools), but you then want to combine them all as a single pool for load-sharing/failover.

b. You have two pairs of real application processes and sometimes you want to share/fail among a pair, and sometimes you want to share/fail among all four.

As described above, the repeat attribute on the application configuration object creates a load-sharing/failover pool across multiple real-processes for a single config-name. A virtual application configuration simply groups multiple config-name entries into a single virtual pool as a collective load-sharing/failover application label.

<n2svcd>
  <virtuals>
    <virtual name="VirtualApp">
      <applications>
        <application name="ConfigName1"/>
        <application name="ConfigName2"/>
      </applications>
    </virtual>
  </virtuals>

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

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

Each virtual configuration Object supports the following attributes:

Application Loadshare & Failover

Both the “Repeated Real Applications” and the “Virtual Application Pool Configuration” provide a mechanism by which a single application label maps to one or more “real applications” for the purpose of accepting internal messages containing information for processing.

When one application wishes to invoke another application for a task, it does so by sending a message over the Inter Process Communication (IPC) mechanism under which n2svcd is running, which may be either single-process objects (IPC = none) shared memory (IPC = shm) or TCP sockets (IPC = sockets).

The sending application must be configured with an application label, which is either:

• A specific “config name” matching an <application name="???"…/> label, or
• A “virtual name” associated with a virtual pool of “config name” values as above.

The sending application will then request a “handle” for the label. The n2svcd framework will consider all of the real applications which are associated with the label. The determination of the real applications associated with each application config name (or virtual pool of config names) is a discovery task performed at application startup, as part of the application’s “prepare” phase. In a dynamic environment like kubernetes, each application may periodically re-perform discovery.

When a hangle is requested, the sending application will consider all of the known “real” applications associated with the requested application label, and will chose the “best” real application to perform the processing. This determination is made by considering the availability of the real applications.

There are four different “availability” factors to consider in this comparison - Priority, Access, Load Percentage, and Loading Indicator.

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.

Loading

Every real application which offers a processing service to other applications is responsible to monitor its own processing load, and should notify other applications of the up-to-date status using the two loading parameters which are published to other applications via the IPC shared memory area.

The two load-related parameters are:

• The Load Percentage (of maximum).
• The Loading Indicator.

The load percentage is an integer values from 0 to 100. The extreme values should be used strictly:

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 at the absolute maximum and additional requests are expected to fail.

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, or the number of running instances or sessions, or a limit of transactions initiated per second. This percentage should also be adjusted to allow for any internal backlog/queuing capability.

The loading indicator is one of:

• [0] NORMAL
• [1] HIGH
• [2] OVERLOAD

A loading indicator of HIGH is set when the loading percentage has reached the configured value as per the high_load_pc application configuration parameter.

A loading indicator of OVERLOAD is set when an application is forced to discard inbound processing requests because it has reached a pre-set sizing limit or timeout parameter.

If an application loading indicator is marked as HIGH or OVERLOAD loading then that indicator will continue to report HIGH or OVERLOAD for as long as the corresponding alarm is active, being the number of seconds as configured for the alarm_clear_secs application configuration parameter after the associated loading condition has actually ended.

Application Preference

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.