n2svcd binary is installed into
executes as an
init.d process. The process starts up and runs continously.
At startup, the
n2svcd binary reads its static configuration from its
configuration file which defaults to
/etc/n2svcd/n2svcd.xml file defines the configuration for all of the
installed Applications. Example Applications are:
- The Management Application
- The SIGTRAN Application (TCAP via SUA, M3UA, Loopback)
- The Test Execution Application
- The PI+ (LUA Scripted Message Gateway) Application
- The Toll-Free SCP Application
- Other Protocol Gateways (PI, FOX, OSD, DIAMETER, SMPP, etc.)
The following is an example
/etc/n2svcd/n2svcd.xml configuration file with three
<?xml version="1.0" encoding="utf-8"?> <n2svcd> <applications> <syslog enabled="1" ident="n2svcd"/> <statsd> <host>stats.mysite.com</host> <port>8125</port> <prefix>n2svcd.myhost.</prefix> </statsd> <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"> <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>
The following top-level elements/attributes are supported.
Container for Syslog configuration.
See below for details.
Container for StatsD statistics relay configuration.
See below for details.
Container for one or more Applications.
A configured Application running within the Service Daemon.
See below for details, as well as the separate per-Application class configuration on other pages.
Container for one or more user-defined Virtual Application translations.
A user-defined Virtual Application used for load-sharing or failover.
See below for more details.
For further details, see the specific N2SVCD Configuration sub-topics for each Application.
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.
syslog configuration object supports the following attributes:
Set this to
1 to enable writing to the Linux Syslog,
0 to disable.
0, do not write to the Linux Syslog).
The application Ident value written to every Syslog record.
(Default = Main Program name, typically
1 to include PID in Syslog records,
0 to exclude PID.
1, include PID in Syslog records).
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.
statsd configuration object supports the following attributes:
IPv4 Host Name or A.B.C.D IPv4 Address for UDP StatsD host.
(Default = Do not notify statistics to an external agent).
Port number for UDP StatsD daemon.
Common prefix for UDP StatsD notifications.
The generating Application Name will also form part of the statistics counter name.
application configuration object is used to define Real Applications.
These Real Applications perform all of the work within n2svcd.
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.
[Required] A unique name for this application instance.
[Required] Value defines which Application class will be loaded.
Array of library class paths to pre-load when instantiating the Application class.
[Required] Relative or Absolute directory path in which the Application class is found.
Array of parameter configuration to configure the Application.
A parameter to be passed to the Application at configuration time.
[Required] Name of the Application parameter.
See per-Application class documentation.
The parameter configuration value which will be passed to all Application instances, unless
overridded using a per-instance
A parameter value specific to a single instance of a repeated Application.
The first application override value key is
See notes below concerning Repeated Applications.
Number of instances of this Application to construct.
Repeating Real Applications
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
:2, etc. onto 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
2 then the following will be created:
- A Real Application
- A Real Application
- A Virtual Application
Scripterwhich load-shares across
To configure separate
parameter values for different repeated application
instances, use the
The following example configuration creates three instances of RealApp1 with port numbers 4601, 4602, 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
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>
virtual configuration Object supports the following attributes:
[Required] Name for your Virtual Application.
Must not conflict with any other defined Real or Virtual Application name.
Array of Real Applications.
Entry for a Real Application translation for the Virtual Application.
[Required] Name of the Real Application. Must be a configured Application name.
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.
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.
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:
- STATUS_AVAILABLE - Application has connectivity, and is lightly loaded (or not loaded at all).
- STATUS_BUSY - Application has connectivity, is active, but is not overloaded.
- STATUS_STANDBY - Application is actually AVAILABLE/BUSY but is in STANDBY mode.
- STATUS_LOADED - Application has connectivity, but is 100% loaded (or more).
- STATUS_FALLBACK - Application is actually AVAILABLE/BUSY/LOADED but is in FALLBACK mode.
- STATUS_OFFLINE - Application has lost connectivity, or is overloaded to the point of failure.
- STATUS_UNKNOWN - Application is not currently reporting status correctly.
- 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
standbyhas is capped at STATUS_STANDBY for this tranlation.
- Any Application marked
fallbackhas is capped at STATUS_FALLBACK for this tranlation.
- For Applications with the same Status, the highest
promotedApplication is always used.
- For Applications with the same Status and
promotedvalue, Round-Robin is performed.
Note that the "Repeated Real Applications" convenience mechanism does not support the
promoted attributes. These are only available
through the "Virtual Application Configuration" mechanism.
Note that when using
fallback flags with Virtual Application translation,
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 Applicaiton
translation may decide to apply.