Using the NSD (UNIX®/Linux/macOS)
This page describes how to use the Network Service Daemon (NSD) or use with the Web Gateway on UNIX®, Linux, or macOS. This is not the typical installation but is appropriate in some cases.
When to Use the NSD
There are three situations in which you might choose to use the NSD to separate the Web Gateway from the web server so that you can manage the Web Gateway independently of the web server:
-
If your web server distributes its load over multiple server processes, an instance of the Web Gateway is then attached to each web server process.
-
If you have a very large web server installation for which CSP is only a small part; for example, a web server that serves php, static content, .NET, and .ASP applications, as well as web applications.
-
If you are using the Nginx web server.
NSD Module Install Locations
The NSD Module, if required, is CSPnsd.
The default location for this module is:
/opt/webgateway/bin
The NSD should be run from within its home directory (above). The configuration file and log file are written in this directory for NSD-based connectivity options.
Operating the NSD
To run the NSD:
-
Change to the following directory:
/opt/webgateway/bin
-
Enter the following command to start the NSD:
./CSPnsd
Before retiring to the background, the NSD displays a banner indicating its running configuration. It shows the TCP port number dedicated to this service, which is, by default, port number 7038.
You can suppress all startup messages for this command using the -s qualifier. For example, to start the NSD from a script invoked at system boot, use:
/opt/webgateway/bin/CSPnsd –s
Other common startup options:
-
Display help information.
./CSPnsd -h
-
Pause the operation of the NSD. This command sends a stop signal (SIGSTOP) to the NSD process.
./CSPnsd -pause
-
Continue the operation of the NSD (after a pause). This command sends a continue signal (SIGCONT) to the NSD process.
./CSPnsd -cont
-
Give permission to others to run the NSD. Administrators of the NSD (CSPnsd) component can give permission to a group or others to start/stop the NSD using CSPnsd —m=s where s is a startup option.
s can be one of
-
u for the current user (default)
-
g for the current group
-
o for others
-
a for everyone (m=ugo)
Example: CPSnsd -m=ug gives permissions to the group (the Administrator group) to run the NSD. This command gives the CPSnsd.pid permissions of: -rw-rw–--
When the command to stop the CSPnsd is issued, it tries to signal the CSPnsd parent process to shut down as before. If this is not possible because the service was started by a different user, a flag is written to the CSPnsd.ini file and the service gracefully closes itself down when it acknowledges this flag. This process takes up to 20 seconds to complete.
-
To close down the NSD, enter:
./CSPnsd -stop
Alternatively:
kill –TERM `cat /opt/webgateway/bin/CSPnsd.pid`
These commands close down the NSD in an orderly manner – it gracefully terminates all open connections to InterSystems IRIS and releases all its system resources before terminating. Do not use the kill –9 command to terminate the NSD.
All errors are reported in the Web Gateway Event Log.
Starting the NSD on Alternative TCP Port
By default, the NSD listens for incoming requests on TCP port 7038. You can override this by starting the service as follows, where port_no is the TCP port number of your choice.
./CSPnsd [port_no]
Or:
./CSPnsd -p=[port_no]
On startup, the NSD creates the following file:
/opt/webgateway/bin/CSPnsd.ini
Typically, this file contains the following lines:
[SYSTEM]
Ip_Address=127.0.0.1
TCP_Port=7038
In this context, the clients are the Web Gateway module contained within, or dynamically linked to, the web server and/or the Web Gateway CGI modules invoked by the server. It is, therefore, essential that this file is not deleted or moved. It is also important that the web server processes can read this file. Set the privileges accordingly, bearing in mind the UNIX® username under which your web server is operating. The NSD clients attempt to find this file in the following locations:
/opt/webgateway/bin
/etc
If the NSD is operating in a different directory, you have to move the CSPnsd.ini file to one of the locations listed.
It is inappropriate to store the NSD port number in the CSPnsd.ini file in situations in which multiple instances of the NSD are running. For Apache servers, there is a much better mechanism for communicating the TCP port number of the NSD to its clients. Specifically, set the following environment variables in the Apache configuration to indicate the address and port of the target NSD installation.
-
CSP_NSD_NAME — This is the IP address of the NSD. Only use this parameter if the NSD is operating on a remote computer.
-
CSP_NSD_PORT — This is the TCP port of the NSD.
The values specified in these environment variables take precedence over any values found in the CSPnsd.ini file.
Example 1: Two Apache Virtual Hosts
To distribute the load for two Apache virtual hosts (123.123.1.1 and 123.123.1.2) between two independent NSD installations (listening on TCP port 7038 and 7039), add the following directives to the Apache configuration (httpd.conf):
<VirtualHost 123.123.1.1>
ServerName 123.123.1.1
SetEnv CSP_NSD_PORT 7038
</VirtualHost>
<VirtualHost 123.123.1.2>
ServerName 123.123.1.2
SetEnv CSP_NSD_PORT 7039
</VirtualHost>
Example 2: Two Web Applications
To distribute the load for two web applications (/csp1 and /csp2) between two independent NSD installations (listening on TCP port 7038 and 7039), add the following directives to the Apache configuration (httpd.conf):
<Location /csp1>
SetEnv CSP_NSD_PORT 7038
</Location>
<Location /csp2>
SetEnv CSP_NSD_PORT 7039
</Location>
Restart Apache after making changes to its configuration.
In cases where multiple instances of the NSD are running, it is recommended that the separate instances be installed in separate directories, each maintaining its own copies of the configuration file and log file. The Web Gateway management pages for each instance can easily be accessed by using the NSD's internal HTTP server. For example:
http://localhost:7038/csp/bin/Systems/Module.cxw
http://localhost:7039/csp/bin/Systems/Module.cxw
Spreading the Load over Multiple NSD Processes
By default, the NSD operates in a two-process mode of operation (one parent and one child worker).
However, there are limits to the number of threads that a single UNIX® process can start. If the concurrent load of the web application is resulting in requests queuing for available threads, consider raising the number of processes used by the NSD.
./CSPnsd –c=[no_processes]
- where no_processes is the number of child (or worker) processes to start.
It should be noted that there are even advantages in setting the number of child processes to one.
./CSPnsd –c=1
Under these circumstances, the NSD actually starts two processes: a parent and one child worker process. The presence of the parent processes when using the ‘–c’ directive improves the resilience of the NSD because if a fault develops in one of the worker processes the parent can replace the process. For the single, multi-threaded architecture, the NSD cannot always recover from serious internal error conditions.
State-aware connectivity (preserve mode 1) should not be used in cases where the number of worker processes exceeds one.
Granting Administrator Rights to the NSD
Administrators of the NSD (CSPnsd) component can have some control over the user (or group) permitted to start/stop this service.
In the default scenario, the CSPnsd master process ID (PID) file (CSPnsd) is created such that only the user who started the service can subsequently close it down.
Administrators can now choose, for example, to allow all users belonging to the current UNIX® group to manage the service. This is the group to which the administrating user belongs.
NSD start-up option: [-m=s] Define the user(s) permitted to manage this service where 's' is: 'u' for the current user (the default), 'g' for the current group, 'o' for others, 'a' for everyone (m=ugo),
Example:
./CSPnsd -m=ug
This allows the current user and all others in the current user's group to manage the NSD.
When the command to stop the NSD is issued, it first tries to signal the CSPnsd parent process to shut down as before. If this is not possible due to the service having been started by a different user, a flag is written to the CSPnsd.ini file and the service gracefully closes itself down when it acknowledges this flag. This process takes up to 20 seconds to complete.