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)
    --[no-]multi                    Run as multi-process (overrides XML config).
    --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.