Skip to main content
Previous sectionNext section

Alternative Configurations for UNIX, Linux, and macOS

This section describes how to configure atypical options for InterSystems IRIS on UNIX®, Linux, and macOS.

Using the NSD on UNIX, Linux, macOS

When to Use the NSD

Several of the options described in this book use the NSD. There are two 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. These are:

  • 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.

NSD Module Install Locations

The NSD Module, if required, is CSPnsd.

The default location for this module is:

/opt/webgateway/bin
Copy code to clipboard

The NSD should be run from within its home directory (above). The configuration file (CSP.ini) and Event Log (CSP.log) are written in this directory for NSD-based connectivity options.

Operating the NSD

To run the NSD:

  1. Change to the following directory:

    /opt/webgateway/bin

  2. 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 Event Log (CSP.log). This file is created and maintained in the NSD home directory (such as /opt/webgateway/bin). The configuration file CSP.ini also resides in this directory.

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
Copy code to clipboard

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.

Storing the NSD port number in the CSPnsd.ini file is inappropriate for 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. 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:

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>
Copy code to clipboard
Example 2:

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>
Copy code to clipboard

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 copy of the configuration and log files (CSP.ini and CSP.log). 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]
Copy code to clipboard

- 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
Copy code to clipboard

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
Copy code to clipboard

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.

Atypical Options for Apache for UNIX®, Linux, Mac OS

This section contains the following subsections. Read the first section for all atypical options. Then follow the directions in the option that applies to your installation.

  1. Install Locations Apache on UNIX, Linux, Mac OS (All Alternative Options)

  2. Atypical Option 1: Apache API Module with NSD (mod_csp24.so)

  3. Alternative Option 2: CGI Modules with NSD (nph-CSPcgi)

  4. Alternative Option 3: Built-in Apache API Module with NSD (mod_csp.c)

Install Locations Apache on UNIX, Linux, Mac OS (All Alternative Options)

This section describes directory locations for Web Gateway files and CSP static files.

  1. The NSD module is:

    CSPnsd
    Copy code to clipboard

    The default location of this module is:

    /opt/webgateway/bin
    Copy code to clipboard

    The NSD should be run from within its home directory /opt/webgateway/bin. The configuration file, CSP.ini, and the event log, CSP.log, are written in this directory.

    In order to avoid disrupting existing Gateway installations on upgrading InterSystems IRIS, the installation places the following modules in the common location /opt/webgateway/bin. This location is not related to a particular InterSystems IRIS instance.

  2. CGI and other dynamically-linked modules:

    • CSPcgi (Runtime module)

    • nph-CSPcgi (Copy of CSPcgi)

    • CSPcgiSys (Systems-Management module)

    • nph-CSPcgiSys (Copy of CSPcgiSys)

    • mod_csp24.so (Apache Version 2.4.x — Apache module as a DSO, if supplied)

    In order to avoid disrupting existing Gateway installations on upgrading InterSystems IRIS, the installation procedures place these modules in the following common location. This location is not related to a particular InterSystems IRIS instance.

    /usr/cspgateway/bin
    Copy code to clipboard

    The original location (install-dir/csp/bin) is used to hold the Web Gateway components required for serving the Management Portal for the specific instance of InterSystems IRIS.

    The modules with Sys appended access the Web Gateway Management pages. The runtime modules (that is, those without Sys) have no access to the Web Gateway Management pages.

  3. The default location for the HyperEvents components:

    • CSPBroker.js

    • CSPxmlhttp.js

    and miscellaneous static resources (such as image files) are required by the CSP Samples and the Management Portal is:

    install-dir\csp\broker

Requirements for using Apache API Modules (Recommended Option and Alternative Option 1)

Before following instructions for either the recommended option (“Recommended Option: NSAPI Modules (CSPn3.so)”) or atypical option 1 (“Alternative Option 1: Apache API Module with NSD (mod_csp24.so)”), check that your build of Apache includes the built-in module for managing shared objects (mod_so). To perform this check, run the following command which lists the modules currently available within Apache:

httpd -l
Copy code to clipboard

The shared object module (mod_so) should appear in the list of modules displayed. The following shows a typical module listing (with mod_so included):

Compiled in modules:
  core.c
  mod_access.c
  mod_auth.c
  mod_include.c
  mod_log_config.c
  mod_env.c
  mod_setenvif.c
  prefork.c
  http_core.c
  mod_mime.c
  mod_status.c
  mod_autoindex.c
  mod_asis.c
  mod_cgi.c
  mod_negotiation.c
  mod_dir.c
  mod_imap.c
  mod_actions.c
  mod_userdir.c
  mod_alias.c
  mod_so.c
Copy code to clipboard

If mod_so is not included in the list for your Apache installation, refer to your Apache documentation and follow the procedure for rebuilding Apache to include this module.

Atypical Option 1: Apache API Module with NSD (mod_csp24.so)

If the CSP module is supplied with your distribution as a pre-built shared object (mod_csp24.so), then proceed to the section on configuration. To build the shared object from the supplied source file mod_csp.c choose Method 1 or Method 2 below. Method 1 is preferred.

Be sure to read the following instructions regarding the creation of shared objects in conjunction with the specific documentation contained within your Apache distribution. Note that the instructions given here assume that the root directory for the Apache installation is /usr/apache. In practice, this directory name usually has the Apache version number appended to it.

Method 1: Building the CSP Module as Shared Object with apxs (APache eXtenSion) Tool

The following command builds and installs the shared library, mod_csp24.so, in the Apache /modules directory using the Apache extension tool, apxs. It also adds a directive to load the module to the Apache configuration file /conf/httpd.conf.

apxs –c –o mod_csp24.so mod_csp.c
Copy code to clipboard

Copy the shared object produced (mod_csp24.so) into the following directory: /opt/webgateway/bin.

Method 2: Building the CSP Module as Shared Object Manually

Perform the following steps to manually build the CSP module as a shared object:

  1. Install the module source file mod_csp.c in the following directory: /usr/apache/src/modules/extra

  2. Return to the /usr/apache/src directory and edit the Configuration file. Near the end of this file, locate the following line:

    # AddModule modules/example/mod_example.o
    

    After this line, add the following line:

    ShareModule modules/extra/mod_csp24.so
    
  3. Configure the build process using the following command:

    ./Configure
    Copy code to clipboard
  4. Build the shared object using the following command:

    make
    Copy code to clipboard

    To produce shared object mod_csp24.so in /usr/apache/src/modules/extra

Note:

For further information about the apxs tool, refer to the Apache documentation at https://httpd.apache.org/docs/2.4/programs/apxs.html.

Method 2 Examples

This section documents the compiler and linker commands you can use to build the Apache module on a range of popular UNIX systems.

  • DEC UNIX 5 (DEC Compiler)

    cc -c -DOSF1 -std1 -pthread -DIS_64 -ieee_with_inexact \
     –I/usr/apache/include mod_csp.c -o mod_csp.o
    ld -all -shared -expect_unresolved "*" -taso mod_csp24.o \
    -o mod_csp24.so
    Copy code to clipboard
  • FreeBSD (GNU Compiler)

    cc -c -DFREEBSD –I/usr/apache/include -o mod_csp24.o mod_csp.c
    ld -G -o mod_csp.so mod_csp24.o
    Copy code to clipboard
  • Linux: (GNU Compiler)

  • macOS: (macOS Compiler)

    gcc -c -fPIC -fno-common -DMACOSX -DDARWIN \
        -I/usr/apache/include mod_csp.c -o mod_csp24.o 
    gcc -bundle -flat_namespace -undefined suppress mod_csp24.o -o mod_csp24.so
    Copy code to clipboard
  • IBM AIX® (IBM Compiler)

    xlc_r -c -DAIX -DAIX5 -I/usr/apache/include mod_csp.c -o mod_csp.o
    xlc_r -G -H512 -T512 -bM:SRE mod_csp24.o -berok -bexpall \
        -bnoentry -lm -lc -o mod_csp24.so
    Copy code to clipboard
  • IBM AIX®: 64-bit (IBM Compiler)

    OBJECT_MODE=64
    export OBJECT_MODE
    xlc_r -c -DAIX -DAIX5 -I/usr/apache/include mod_csp.c -o mod_csp.o
    xlc_r -G -H512 -T512 -bM:SRE mod_csp24.o -berok -bexpall \
        -bnoentry -lm -lc -o mod_csp24.so
    Copy code to clipboard

Copy mod_csp24.so to: /opt/webgateway/bin.

Runtime Configuration

Edit the Apache configuration file httpd.conf. For the standard Apache distribution, this file is in:

/usr/apache/conf
Copy code to clipboard

For Red Hat Linux, the runtime version of httpd.conf is in:

/etc/httpd/conf
Copy code to clipboard

Assuming that you wish to invoke the CSP engine for requested files that contain a .csp, .cls, or .zen extension, add the following section to the end of httpd.conf.

The below configuration block relies on the Regular Expressions (regex) processor being available to the Apache environment. Sometimes this is not the case and CSP files are consequently not served (File not found errors are returned). To remedy this situation, replace the following lines in the configuration block:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    SetHandler csp-handler
</LocationMatch>
Copy code to clipboard

with:

CSPFileTypes csp-handler csp cls
Copy code to clipboard
LoadModule csp_module /opt/webgateway/bin/mod_csp24.so
<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
                SetHandler csp-handler
</LocationMatch>
Alias /csp/ /opt/webgateway/csp/
<Directory "/opt/webgateway/csp">
        AllowOverride None
        Options MultiViews FollowSymLinks ExecCGI
        Require all granted
        <FilesMatch "\.(log|ini|pid|exe)$">
                Require all denied
        </FilesMatch>
        <Files CSPnsd>
                Require all denied
        </Files>
</Directory>
ScriptAlias /csp-bin/ "/opt/webgateway/bin/"
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/opt/webgateway/bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/opt/webgateway/bin/nph-CSPcgi"
<Directory "/opt/webgateway/bin/">
        AllowOverride None
        Options None
        Require all granted
</Directory>
Copy code to clipboard

Restart Apache after making changes to httpd.conf.

Controlling Connection Pooling

The size of the connection pool can be controlled by the following Apache configuration parameter (specified in http.conf):

CSPMaxPooledNSDConnections <no> 
Copy code to clipboard

In the absence of this parameter, a default value of 32 is used internally – which is effectively:

CSPMaxPooledNSDConnections 32 
Copy code to clipboard

To switch-off connection pooling, set this parameter to zero:

CSPMaxPooledNSDConnections 0 
Copy code to clipboard

If, for any reason, it becomes necessary to use the legacy (asymmetric) mode of operation (whereby the Web Gateway notifies the end of response transmission by closing the connection on its side), set this parameter to minus 1:

CSPMaxPooledNSDConnections -1
Copy code to clipboard
Operating and Managing the Web Gateway with Apache API and NSD

This connectivity option depends on the Web Gateway’s network service daemon (NSD).

  1. Start the CSP NSD as described in the section “Operating the NSD”.

  2. Restart Apache after making changes to its configuration (httpd.conf).

    The order in which Apache and the NSD are started is unimportant.

  3. To access the Web Gateway Management pages, enter the following URL in your browser.

    http://localhost:<port_no>/csp-bin/nph-CSPcgiSys
    Copy code to clipboard

If you see an Unauthorized User error message, refer to the section on security considerations.

The CSP engine is automatically invoked for requested files that contain a .csp, .cls, or .zen extension. For example:

http://localhost:<port_no>/csp/samples/menu.csp
Copy code to clipboard

Registering Additional File Types with CSP

Apache API modules always recognize the following reserved file extensions:

.csp .cls .zen .cxw 
Copy code to clipboard

You may have other files that you want to send to CSP for processing. For example, if you need to serve other static files through the Web Gateway or need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, .css, and .js.

You can configure Apache to recognize what files to pass on to CSP in any of the following ways:

  • By CSP location directive

  • By file extension – CSPFileTypes directive

  • By MIME type

By CSP location directive

Use the CSP directive to request that all files within a certain location be processed by CSP. The following requests that all files and directories under the /csp path be processed by CSP.

<Location /csp>
   CSP On 
   SetHandler csp-handler-sa
</Location> 
Copy code to clipboard

For example, all the following would be sent to CSP for processing:

/csp/ 
/csp/samples/menu.csp 
/csp/sys/ 
Copy code to clipboard
By file extension – CSPFileTypes directive

The CSPFileTypes directive works for requests for files that have extensions (such as /csp/menu.csp). It does not work for requests for files that do not have file extensions (such as /csp/menu).

This parameter is processed by the Web Gateway’s Apache modules and can be globally defined at the server definition level (in httpd.conf) or restricted within the definition for a location or directory block.

By file type: The following directive requests that files of type xxx and yyy be processed by CSP.

CSPFileTypes xxx yyy 
Copy code to clipboard

By location: The following requests that files of type xxx and yyy be processed by CSP but only for locations under /csp (including subdirectories, such as /csp/samples and so on).

<Location /csp/> 
   CSPFileTypes xxx yyy
</Location>
Copy code to clipboard

Using the wildcard character, the following requests that all files under path /csp (and /csp/samples and so on) be processed by CSP.

<Location /csp/> 
   CSPFileTypes * 
</Location> 
Copy code to clipboard
By MIME type

In addition to recognizing the file extensions listed above, CSP can also recognize files for the following MIME types:

application/x-csp
Copy code to clipboard

and

text/csp
Copy code to clipboard

For example, to add the file extension xxx to the list of files processed by CSP, use:

LoadModule csp_module_sa /opt/webgateway/bin/CSPa24.so
AddType application/x-csp csp cls zen xxx
Copy code to clipboard

One of the problems with using MIME types to associate types of file with CSP is that Apache checks to ensure that the path to the resource (that is, the hosting directory) physically exists, and returns a file not found error if it does not. It does not, however, check to ensure that the file requested physically exists – which is appropriate for resources served by the CSP engine since they are served by InterSystems IRIS and are virtual as far as the web server is concerned. The “By MIME type” approach is therefore only suitable for cases where the application’s path structure can be replicated on the web server.

Alternative Option 2: CGI Modules with NSD (nph-CSPcgi)

The web server should be configured such that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the Web Gateway for processing.

The web server configuration file (httpd.conf) is found in the following directory:

/usr/apache/conf
Copy code to clipboard

For Red Hat Linux, the runtime version of httpd.conf is found in:

/etc/httpd/conf
Copy code to clipboard

Add the following section to the end of httpd.conf:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    AllowOverride None
    Options FollowSymLinks ExecCGI
    Require all granted
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/opt/webgateway/bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/opt/webgateway/bin/nph-CSPcgi"
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ "/opt/webgateway/bin/nph-CSPcgi"
Alias /csp/ instance-installation-directory
<Directory "instance-installation-directory">
    AllowOverride None
    Options MultiViews FollowSymLinks ExecCGI
   Require all granted
    <FilesMatch "\.(log|ini|pid|exe)$">
       Require all denied
    </FilesMatch>
    <Files CSPnsd>
       Require all denied
    </Files>
</Directory>
ScriptAlias /csp-bin/ "/opt/webgateway/bin/"
<Directory "/opt/webgateway/bin/">
    AllowOverride None
    Options None
    Require all granted
</Directory>
Copy code to clipboard

The above configuration block relies on the Regular Expressions (regex) processor being available to the Apache environment. Sometimes this is not the case and CSP files are consequently not served (File not found errors are returned). To remedy this situation you can associate the (virtual) root location of your web applications with the CGI module instead of making the association through the CSP file extensions. For example, your web applications are contained in /csp. To associate the CSP CGI module with files under /csp, replace the following configuration block:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    AllowOverride None
    Options FollowSymLinks ExecCGI
    Require all granted
</LocationMatch>
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ "/opt/webgateway/bin/nph-CSPcgi"
Copy code to clipboard

with:

<Location "/csp">
    AllowOverride None
    Options FollowSymLinks ExecCGI
   Require all granted
</Location>
ScriptAlias /csp "/opt/webgateway/bin/nph-CSPcgi"
Copy code to clipboard

These directives work for URLs of the form:

http://localhost:<port_no>/csp/*.csp
Copy code to clipboard

Duplicate the configuration block for other root Locations. For example, repeat the process for /myapps for URLs of the form:

http://localhost:<port_no>/myapps/*.csp
Copy code to clipboard

Another approach to avoiding the regex issue is to use an Action directive in conjunction with a CSP MIME type. However, it should be noted that Action is essentially a content filtering technique and, as such, requires that your CSP files are physically present on the web server host even if the InterSystems IRIS server is installed on a separate computer. If you wish to use this approach, first add a new MIME type to the end of the Apache mime.types file and associate it with file types representing CSP content. The mime.types file are found in the same directory as the httpd.conf file.

text/csp                csp cls
Copy code to clipboard

Now, add the Action directive to the end of the CGI configuration block in httpd.conf such that it reads:

Alias /csp/ /opt/webgateway/csp/
<Directory "/opt/webgateway/csp">
    AllowOverride None
    Options MultiViews FollowSymLinks ExecCGI
    Require all granted
<Files CSPnsd>
       Require all denied
    </Files>
<Files CSP.ini>
       Require all denied
    </Files>
<Files CSP.log>
       Require all denied
    </Files>
<Files CSPnsd.ini>
       Require all denied
    </Files>
<Files CSPnsd.pid>
       Require all denied
    </Files>
</Directory>
ScriptAlias /csp-bin/ "/opt/webgateway/bin/"
<Directory "/opt/webgateway/bin/">
    AllowOverride None
    Options None
    Require all granted
</Directory>
Action text/csp “/csp-bin/nph-CSPcgi”
Copy code to clipboard

Restart Apache after making changes to httpd.conf.

Finally, note that because CGI is an open standard, The CSP CGI modules work with any web server.

Registering Additional File Types with CSP

Apache API modules always recognize the following reserved file extensions:

.csp .cls .zen .cxw 
Copy code to clipboard

You may have other files that you want to send to CSP for processing. For example, if you need to serve other static files through the Web Gateway or need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, .css, and .js.

You can configure Apache to recognize what files to pass on to CSP in any of the following ways:

  • By CSP location directive

  • By file extension – CSPFileTypes directive

  • By MIME type

By CSP location directive

Use the CSP directive to request that all files within a certain location be processed by CSP. The following requests that all files and directories under the /csp path be processed by CSP.

<Location /csp>
   CSP On 
   SetHandler csp-handler-sa
</Location> 
Copy code to clipboard

For example, all the following would be sent to CSP for processing:

/csp/ 
/csp/samples/menu.csp 
/csp/sys/ 
Copy code to clipboard
By the CSPFileTypes directive

The CSPFileTypes directive works for requests for files that have extensions (such as /csp/menu.csp). It does not work for requests for files that do not have file extensions (such as /csp/menu).

This parameter is processed by the Web Gateway’s Apache modules and can be globally defined at the server definition level (in httpd.conf) or restricted within the definition for a location or directory block.

By file type: The following directive requests that files of type .xxx and .yyy be processed by CSP.

CSPFileTypes xxx yyy 
Copy code to clipboard

By location: The following requests that files of type .xxx and .yyy be processed by CSP but only for locations under /csp (including subdirectories, such as /csp/samples and so on).

<Location /csp/> 
   CSPFileTypes xxx yyy
</Location>
Copy code to clipboard

Using the wildcard character, the following requests that all files under path /csp (and /csp/samples and so on) be processed by CSP.

<Location /csp/> 
   CSPFileTypes * 
</Location> 
Copy code to clipboard
By MIME type

In addition to recognizing the file extensions listed above, CSP can also recognize files for the following MIME types:

application/x-csp
Copy code to clipboard

and

text/csp
Copy code to clipboard

For example, to add the file extension xxx to the list of files processed by CSP, use:

LoadModule csp_module_sa /opt/webgateway/bin/CSPa24.so
AddType application/x-csp csp cls zen xxx
Copy code to clipboard

One of the problems with using MIME types to associate types of file with CSP is that Apache checks to ensure that the path to the resource (that is, the hosting directory) physically exists, and returns a file not found error if it does not. It does not, however, check to ensure that the file requested physically exists – which is appropriate for resources served by the CSP engine since they are served by InterSystems IRIS and are virtual as far as the web server is concerned. The “By MIME type” approach is therefore only suitable for cases where the application’s path structure can be replicated on the web server.

Operating and Managing the Web Gateway with CGI and NSD

This connectivity option depends on the Web Gateway’s network service daemon (NSD).

  1. Start the CSP NSD as described in the section “Operating the NSD

  2. Restart Apache after making changes to its configuration (httpd.conf).

    The order in which Apache and the NSD are started is unimportant.

  3. To access the Web Gateway Management pages, enter one of the following URLs in your browser.

    http://localhost:<port_no>/csp/bin/Systems/Module.cxw 
    http://localhost:<port_no>/csp-bin/nph-CSPcgiSys
    Copy code to clipboard

If you see an Unauthorized User error message, refer to the section on security considerations.

The CSP engine is automatically invoked for requested files that contain a .csp, .cls, or .zen extension. For example:

http://localhost:<port_no>/csp/samples/menu.csp
Copy code to clipboard

Alternative Option 3: Built-in Apache API Module with NSD (mod_csp.c)

Before embarking on setting up this more complicated option you should bear in mind that, for most modern UNIX systems, the performance advantage in static linking over linking the module at runtime as a shared object (option 1) is minimal (if anything at all).

Be sure to read these instructions in conjunction with the specific documentation contained within your Apache distribution.

Build Apache to Include CSP Module Source Code

Refer to the Apache documentation for this step.

http://httpd.apache.org/

Check the Apache Binary Produced

Run the following command to check that the CSP module has been successfully included in the Apache core (this command lists all modules currently built-into Apache):

./httpd -l
Copy code to clipboard

For example:

Compiled in modules:
        core.c
        mod_access.c
        mod_auth.c
        mod_include.c
        mod_log_config.c
        mod_env.c
        mod_setenvif.c
        prefork.c
        http_core.c
        mod_mime.c
        mod_status.c
        mod_autoindex.c
        mod_asis.c
        mod_cgi.c
        mod_negotiation.c
        mod_dir.c
        mod_imap.c
        mod_actions.c
        mod_userdir.c
        mod_alias.c
        mod_csp.c
Copy code to clipboard

Runtime Configuration

Edit the Apache configuration file httpd.conf. For the standard Apache distribution this file is in:

/usr/apache/conf
Copy code to clipboard

For Red Hat Linux, the runtime version of httpd.conf is in:

/etc/httpd/conf
Copy code to clipboard

Assuming that you wish to invoke the CSP engine for requested files that contain a .csp, .cls, or .zen extension, add the following section to the end of httpd.conf:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
                SetHandler csp-handler
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/opt/webgateway/bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/opt/webgateway/bin/nph-CSPcgi"
Alias /csp/ /opt/webgateway/csp/
<Directory "/opt/webgateway/csp">
        AllowOverride None
        Options MultiViews FollowSymLinks ExecCGI
        Require all granted
        <FilesMatch "\.(log|ini|pid|exe)$">
                Require all denied
        </FilesMatch>
        <Files CSPnsd>
                Require all denied
        </Files>
</Directory>
ScriptAlias /csp-bin/ "/opt/webgateway/bin/"
<Directory "/opt/webgateway/bin/">
        AllowOverride None
        Options None
        Require all granted
</Directory>
Copy code to clipboard

The above configuration block relies on the Regular Expressions (regex) processor being available to the Apache environment. Sometimes this is not the case and CSP files are consequently not served (File not found errors are returned). To remedy this situation, replace the following configuration block:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
                SetHandler csp-handler
</LocationMatch>
Copy code to clipboard

with:

CSPFileTypes csp cls zen
Copy code to clipboard

Note that all requests to Apache are serviced by a set of modules invoked in a predefined sequence. The CSP module is one of the first modules invoked, provided its definition was added near the end of the Configuration file as suggested.

Restart Apache after making changes to httpd.conf.

Registering Additional File Types with CSP

Apache API modules always recognize the following reserved file extensions:

.csp .cls .zen .cxw 
Copy code to clipboard

You may have other files that you want to send to CSP for processing. For example, if you need to serve other static files through the Web Gateway or need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, .css, and .js.

You can configure Apache to recognize what files to pass on to CSP in any of the following ways:

  • By CSP location directive

  • By file extension

  • By CSPFileTypes directive

  • By MIME type

By CSP location directive

Use the CSP directive to request that all files within a certain location be processed by CSP. The following requests that all files and directories under the /csp path be processed by CSP.

<Location /csp>
   CSP On 
   SetHandler csp-handler-sa
</Location> 
Copy code to clipboard

For example, all the following would be sent to CSP for processing:

/csp/ 
/csp/samples/menu.csp 
/csp/sys/ 
Copy code to clipboard
By the CSPFileTypes directive

The CSPFileTypes directive works for requests for files that have extensions (such as /csp/menu.csp). It does not work for requests for files that do not have file extensions (such as /csp/menu).

This parameter is processed by the Web Gateway’s Apache modules and can be globally defined at the server definition level (in httpd.conf) or restricted within the definition for a location or directory block.

By file type: The following directive requests that files of type xxx and yyy be processed by CSP.

CSPFileTypes xxx yyy 
Copy code to clipboard

By location: The following requests that files of type xxx and yyy be processed by CSP but only for locations under /csp (including subdirectories, such as /csp/samples and so on).

<Location /csp/> 
   CSPFileTypes xxx yyy
</Location>
Copy code to clipboard

Using the wildcard character, the following requests that all files under path /csp (and /csp/samples and so on) be processed by CSP.

<Location /csp/> 
   CSPFileTypes * 
</Location> 
Copy code to clipboard
By MIME type

In addition to recognizing the file extensions listed above, CSP can also recognize files for the following MIME types:

application/x-csp
Copy code to clipboard

and

text/csp
Copy code to clipboard

For example, to add the file extension xxx to the list of files processed by CSP, use:

LoadModule csp_module_sa /opt/webgateway/bin/CSPa24.so
AddType application/x-csp csp cls zen xxx
Copy code to clipboard

One of the problems with using MIME types to associate types of file with CSP is that Apache checks to ensure that the path to the resource (that is, the hosting directory) physically exists, and returns a file not found error if it does not. It does not, however, check to ensure that the file requested physically exists – which is appropriate for resources served by the CSP engine since they are served by InterSystems IRIS and are virtual as far as the web server is concerned. The “By MIME type” approach is therefore only suitable for cases where the application’s path structure can be replicated on the web server.

Operating and Managing the Web Gateway with Apache API and NSD

This connectivity option depends on the Web Gateway’s network service daemon (NSD).

  1. Start the CSP NSD as described in the section “Operating the NSD”.

  2. Restart Apache after making changes to its configuration (httpd.conf).

    The order in which Apache and the NSD are started is unimportant.

  3. To access the Web Gateway Management pages, point your browser at one of the following locations.

    http://localhost:<port_no>/csp/bin/Systems/Module.cxw
    http://localhost:<port_no>/csp-bin/nph-CSPcgiSys
    Copy code to clipboard

If you see an Unauthorized User error message, refer to the section on security considerations.

The CSP engine is automatically invoked for requested files that contain a .csp, .cls, or .zen extension. For example:

http://localhost:<port_no>/csp/samples/menu.csp
Copy code to clipboard

Locked-down Apache for UNIX, Linux, and macOS

Occasionally Apache is locked down so that you cannot easily configure the server to access files outside the Apache file system. For example, this is the case for Security Enhanced Linux (SELinux).

For configurations locked down in this way, the Web Gateway configurations discussed in previous sections results in HTTP 403 Forbidden error codes being returned on attempting to access CSP resources. There are two strategies for dealing with this problem.

  • Modify the security context for the Web Gateway’s home directory so that Apache can access files held in this location.

  • Move the Web Gateway’s home directory to a location under the Apache root file system (which is pre-configured to be accessible to Apache in the SELinux setup).

First, modifying the SELinux security context for the Web Gateway’s home directory is usually straightforward and involves the following steps.

We use, as an example, a Web Gateway home directory of /opt/webgateway/bin, the InterSystems IRIS Superserver listening on port 51773and InterSystems IRIS installed in /usr/iris/.

The chcon command sets file context and takes effect immediately.

sudo chcon -R -t httpd_sys_content_t /usr/iris/csp
sudo chcon -R -t httpd_sys_content_t /opt/webgateway/bin/CSP.ini
sudo chcon -R -t httpd_sys_content_t /opt/webgateway/bin/CSP.log
sudo chcon -t httpd_modules_t /opt/webgateway/bin/CSPa2.so
sudo chcon -t httpd_modules_t /opt/webgateway/bin/CSPa2Sys.so
sudo chcon -t httpd_modules_t /opt/webgateway/bin/CSPa22.so
sudo chcon -t httpd_modules_t /opt/webgateway/bin/CSPa22Sys.so
sudo chcon -t httpd_modules_t /opt/webgateway/bin/CSPa24.so
sudo chcon -t httpd_modules_t /opt/webgateway/bin/CSPa24Sys.so
Copy code to clipboard

However, changes made by the chcon command are lost after the next relabeling; therefore it is necessary use the semanage fcontext facility in addition to chcon. Also, it is extremely important to properly set the context of the Superserver port. Otherwise, the Web Gateway will not be able to access it, resulting in "Server unavailable" errors.

sudo /usr/sbin/semanage fcontext -a -t httpd_sys_content_t \
    "/usr/iris/csp(/.*)?"
sudo /usr/sbin/semanage fcontext -a -t httpd_sys_content_t \
    "/opt/webgateway/bin/CSP.ini"
sudo /usr/sbin/semanage fcontext -a -t httpd_sys_content_t \
    "/opt/webgateway/bin/CSP.log"
sudo /usr/sbin/semanage fcontext -a -t httpd_modules_t \
    "/opt/webgateway/bin/CSPa2.so"
sudo /usr/sbin/semanage fcontext -a -t httpd_modules_t \
    "/opt/webgateway/bin/CSPa2Sys.so"
sudo /usr/sbin/semanage fcontext -a -t httpd_modules_t \
    "/opt/webgateway/bin/CSPa22.so"
sudo /usr/sbin/semanage fcontext -a -t httpd_modules_t \
    "/opt/webgateway/bin/CSPa22Sys.so"
sudo /usr/sbin/semanage fcontext -a -t httpd_modules_t \
    "/opt/webgateway/bin/CSPa24.so"
sudo /usr/sbin/semanage fcontext -a -t httpd_modules_t \
    "/opt/webgateway/bin/CSPa24Sys.so"
sudo /usr/sbin/semanage port -a -t http_port_t -p tcp 51773
Copy code to clipboard

These are the basic steps for granting the Web Gateway (operating in the context of the hosting Apache server) access to files in its home directory.

An alternative approach (and the one that should be used if the method suggested above is not acceptable) is to configure the Web Gateway to work within the pre-configured directories provided by Apache. The following commands assume that Apache is installed in /usr/apache.

  • CGI modules should be copied to: /usr/apache/cgi-bin/

    cp /usr/iris/csp/bin/*cgi* /usr/apache/cgi-bin/
    Copy code to clipboard
  • API modules should be copied to: /usr/apache/modules/

    cp /usr/iris/csp/bin/*.so /usr/apache/modules/
    Copy code to clipboard
  • Static files should be copied to locations under: /usr/apache/htdocs/

    cp /usr/iris/csp/samples/* /usr/apache/htdocs/csp/samples/
    cp /usr/iris/csp/broker/* /usr/apache/htdocs/csp/broker/
    cp /usr/iris/csp/sys/* /usr/apache/htdocs/csp/sys/
    Copy code to clipboard

    Also, copy any sub-directories held under the above locations.

Having moved the Web Gateway installation, the appropriate changes to the paths specified in the Apache configuration must be made.

Recommended Option: Apache API Modules (CSPa24.so)

LoadModule cspsys_module_sa /usr/apache/modules/CSPap24.so
CSPSYSModulePath /usr/apache/modules/
<Location "/csp/bin/Systems/">
    SetHandler cspsys-handler-sa
</Location>
<Location "/csp/bin/RunTime/">
    SetHandler csp-handler-sa
</Location>
CSPFileTypes csp cls zen cxw
Copy code to clipboard

Atypical Option 1: Apache API Module with NSD (mod_csp.so)

LoadModule csp_module /usr/apache/modules/mod_csp.so
<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
SetHandler csp-handler
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/usr/apache/cgi-bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/usr/apache/cgi-bin/nph-CSPcgi"
Copy code to clipboard

Atypical Option 2: CGI Modules with NSD (nph-CSPcgi)

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
AllowOverride None
Options FollowSymLinks ExecCGI
Require all granted
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/usr/apache/cgi-bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/usr/apache/cgi-bin/nph-CSPcgi"
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ "/usr/apache/cgi-bin/nph-CSPcgi"
Copy code to clipboard

Atypical Option 3: Built-in Apache API Module with NSD (mod_csp.c)

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
SetHandler csp-handler
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "/apache/cgi-bin/nph-CSPcgiSys" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "/usr/apache/cgi-bin/nph-CSPcgi"
Copy code to clipboard

Troubleshooting

If you are getting I/O errors when connecting via HTTPS to an Apache mod_ssl server with Microsoft Internet Explorer, you might try the following. This is an occasional issue caused by Apache introduced in an attempt to work around problems caused by earlier versions of IE. The following lines are in the SSL/TLS configuration for Apache:

BrowserMatch ".*MSIE.*" nokeepalive ssl-unclean-shutdown downgrade-1.0 force-response-1.0
Copy code to clipboard

Remove the section downgrade-1.0 force-response-1.0 and restart Apache. This prevents a downgrade of the HTTP headers from HTTP/1.1 to HTTP/1.0 to get around some issues that earlier versions of IE had with HTTP/1.1. This may solve your issue.