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.
Attribute | Type | Description |
---|---|---|
nodename
|
String |
The node name of record for the purpose of generating instance IDs and the construction of EDR filenames. (Default = determined from the hostname) |
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 Syslog configuration. |
snmp
|
Object | Container for SNMP trap 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 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:
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)
|
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:
Attribute | Type | Description |
---|---|---|
enabled
|
Integer |
Set this to 1 to enable delivery of SNMP traps, 0 to disable.(Default = 0 , do not deliver SNMP traps)
|
host
|
String |
The name or IPv4 address of the host to receive SNMP traps. Only one host may be specified. Typically this is a local `snmptrapd` instance, which can be configured to forward traps to one or more remote SNMP trap daemons. (Default = localhost )
|
port
|
Integer |
The UDP port number for the SNMP trap daemon to which we will deliver. (Default = 162 )
|
location
|
String | The system location, as per RFC 3418. (Default = system hostname) |
community
|
String |
The SNMP community string to use.
(Default = n2svcd )
|
send_alarms
|
Integer |
Whether to send SNMP Alarms, i.e. ERROR and CLEAR SNMP traps.
Set this to 1 to enable delivery of SNMP Alarms, 0 to disable.
Note that this has no effect if enabled is not 1 (Default = 1 , deliver SNMP ERROR and CLEAR alarm traps)
|
send_events
|
Integer |
Whether to send SNMP Events, i.e. NOTICE and WARNING SNMP traps.
Set this to 1 to enable delivery of SNMP Events, 0 to disable.
Note that this has no effect if enabled is not 1 (Default = 1 , deliver SNMP NOTICE and WARNING alarm traps)
|
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:
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 _\-] .
|
priority
|
primary / standby / fallback / disaster
|
Adjusts the relative priority of applications e.g. when choosing among Database Apps,
REST Client Apps, or other service apps which may be instantiated more than once. (Default = primary )
|
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-<idx> override.
This value may specified indirectly via an environment variable ${VARNAME} or a shell command `command` .
|
.value-<idx>
|
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 acrossScripter: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:
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. |
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.
When configuring a downstream Application name, either a single Real Application name may be specified, or a Virtual Application name may be specified which for each use will be evaluated to choose from one of the underlying Real Application names.
There are two main reasons why this is done:
- To load-share across more then one CPU core/thread.
- 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
orRestServerApp
. - Application “A” is a processing application such as
LogicApp
orTesterApp
.
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, 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:
- An application should only notify
0%
load when the load is absolutely zero. - 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.
- New sessions will only be created towards Applications with access
ONLINE
. - When two applications have the same priority, the lowest load is preffered.
- When two applications have the same priority and both have
100%
load, the lowest backlog is preferred. - Otherwise, the following priority/load/backlog combinations are preferred in descending order.
Priority | Loading | Note |
---|---|---|
PRIMARY
|
NORMAL
|
|
STANDBY
|
NORMAL
|
Standby is a load-backup which activates once the primary hits full load. |
PRIMARY
|
HIGH < 100%
|
|
STANDBY
|
HIGH < 100%
|
|
FALLBACK
|
NORMAL
|
Fallback is a load-backup which activates once the primary and standby hits high load. |
FALLBACK
|
HIGH < 100%
|
|
PRIMARY
|
OVERLOAD or >= 100%
|
|
STANDBY
|
OVERLOAD or >= 100%
|
|
FALLBACK
|
OVERLOAD or >= 100%
|
|
DISASTER
|
(any) |
Disaster is only used when all other higher priorities have access which is not ONLINE .
|