Alternative Options for Apache (UNIX®/Linux/macOS)

Install Locations (All Atypical Options)

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

1. The NSD module is:

   CSPnsd
   

   

   The default location of this module is:

   /opt/webgateway/bin
   

   

   The NSD should be run from within its home directory /opt/webgateway/bin. The configuration and log files 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
   

   

   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: Apache API Module without NSD (CSPa24.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

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

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

Alternative 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 start at Runtime 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 the shared object produced (mod_csp24.so) into the following directory: /opt/webgateway/bin.

Runtime Configuration

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

/usr/apache/conf

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

/etc/httpd/conf

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.

LoadModule csp_module /opt/webgateway/bin/mod_csp24.so
CSPFileTypes csp cls zen cxw 
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>

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> 

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

CSPMaxPooledNSDConnections 32 

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

CSPMaxPooledNSDConnections 0 

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

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

   

   If you see an Unauthorized User error message, see Enabling Access from Additional Client Addresses.

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

The web server should be configured such that it recognizes InterSystems file types 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

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

/etc/httpd/conf

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>

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"

with:

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

These directives work for URLs of the form:

http://localhost:<port_no>/csp/*.csp

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

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

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”

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.

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.

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

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

Runtime Configuration

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

/usr/apache/conf

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

/etc/httpd/conf

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:

CSPFileTypes csp cls zen cxw 
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>

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.