N2SVCD
Overview
The n2svcd
binary program executes the process or processes which encapsulate
the Applications described in this documentation. The default installation
location for this binary is /usr/share/n2svcd/bin/n2svcd
.
In a production environment, the n2svcd
binary will typically run as a system
service (details and management depending on your particular operating system).
Running n2svcd --help
will show the program usage.
usage: n2svcd
--config <file> Default = '/etc/n2svcd/n2svcd.xml'.
--trace <0|1|2|3> (request n2svcd to return debug traces)
--debug (--trace_level = 1)
--dump (--trace_level = 2)
--spam (--trace_level = 3)
--nodename Override the configured 'nodename' in XML.
--multi Run as multi-process (1 per Application)
--shm-path <path in /dev/shm> Default = '/n2svcd'
--clean Forcibly remove the IPC shared memory area.
--single-app <app-name> Used when master n2svcd forks children.
--help Show this usage information.
Parameter: --config
The --config
parameter specifies an alternative configuration file for the service.
The default configuration file is /etc/n2svcd/n2svcd.xml
.
Parameter: --trace
The --trace
parameter specifies a global trace level. The default global trace level is 0
which means that ERROR, WARNING, and NOTICE are logged to STDERR (in addition to any
other destinations such as syslog, or in-memory tracing).
Higher global trace levels of 1
(DEBUG), 2
(DUMP), 3
(SPAM) will
cause increasing levels of global trace output to be written to STDERR.
The parameters --debug
, --dump
, --spam
are shorthand alternatives for
--trace 1
, --trace 2
, --trace 3
.
Enabling global trace above zero should be used for development and problem-solving only, and should not be enabled for a platform that is expected to handle production traffic levels.
Parameter: --nodename
This overrides the node name of record, which is used for generating instance GID (global ID) strings, and is also used by the EdrApp as a prefix on all generated EDR files.
Specifying a command line value will override the value configured in n2svcd.xml
.
The fallback is the system hostname.
Flags: --multi
/ --no-multi
By default, or when the --no-multi
flag is specified, n2svcd
will execute all
applications within a single process, and all message-passing between applications
will be performed directly from one object to another using private memory queues.
Specifying --multi
requests that the service daemon execute each Application within
a dedicated process, allowing the system to use more than one core, and increasing the
overall capacity of the service daemon.
Communication between processes is performed using IPC Shared Memory circular buffers
for message queues, and IPC Semaphores for ensuring restricting access to the message
queues. This IPC Shared Memory can be seen by using the ls
command in the virtual
file-system for /dev/shm
.
$ ls /dev/shm/n2svcd
The master process in the service daemon runs the WatchdogApp
application, and forks
off a child process for each other application. Each child process attached to this
common shared memory application.
Parameter: --shm-path
For the purpose of testing, you may occasionally wish to run more than one multi-process service daemon at the same time on a single machine.
In order to do this, you must specify an alternative pathname for the IPC Shared Memory
area for the second service daemon. This path must start with a forward slash (/
).
Parameter: --clean
By default, when specifying --multi
, the service daemon master process will handle
SIGINT by first performing a managed shutdown of all non-Watchdog application sub
processes. It will then delete the IPC Shared Memory area containing the cyclic
message queues and semaphores used by that service daemon.
However, if the watchdog exits or is forcibly terminated without completing the shutdown sequence, the IPC Shared Memory are will be left in place, and it will not be possible to re-start the service daemon until it is cleaned up.
In this case you must clean-up manually before re-starting the master service deamon process, specifically:
- Ensure that all old child processes have terminated (kill -9 may be required).
- Run
n2svcd
with--multi --clean
to remove the old IPC Shared Memory.
If you are using a non-standard IPC Shared Memory path, you will also need to specify
the appropriate value using --shm-path
.
Parameter: --single-app
When the master process of the service daemon forks and executes child processes, it
uses the --single-app
on the command line to indicate that the child process should
implement only this single named application.
You should never need to use this parameter when running manual n2svcd
command lines.