Alternative Options for Apache (UNIX®/Linux/macOS)
This page describes additional possible Apache configurations for use with the InterSystems Web Gateway on UNIX®, Linux, and macOS (apart from a locked-down Apache, discussed separately). To get started with all these configurations, read the first section. Then follow the directions in the section that applies to your configuration.
Install Locations (All Atypical Options)
This section describes directory locations for Web Gateway files and CSP static files.
-
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 CSP.ini configuration file and the CSP.log file 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.
-
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.
-
-
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 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.
Method 2: Building the CSP Module as Shared Object Manually
Perform the following steps to manually build the CSP module as a shared object:
-
Install the module source file mod_csp.c in the following directory: /usr/apache/src/modules/extra
-
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
-
Configure the build process using the following command:
./Configure
-
Build the shared object using the following command:
make
To produce shared object mod_csp24.so in /usr/apache/src/modules/extra
For further information about the apxs tool, see the Apache documentation at https://httpd.apache.org/docs/2.4/programs/apxs.htmlOpens in a new tab.
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).
-
Start the CSP NSD as described in Operating the NSD.
-
Restart Apache after making changes to its configuration (httpd.conf).
The order in which Apache and the NSD are started is unimportant.
-
To access the Web Gateway management pages, enter the following URL in your browser.
http://<hostname>:<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 following form, using the <baseURL> for your instance:
http://<baseURL>/csp/*.csp
Duplicate the configuration block for other root Locations. For example, repeat the process for /myapps for URLs of the form:
http://<baseURL>/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.
Operating and Managing the Web Gateway with CGI and NSD
This connectivity option depends on the Web Gateway’s network service daemon (NSD).
-
Start the CSP NSD as described in Operating the NSD
-
Restart Apache after making changes to its configuration (httpd.conf).
The order in which Apache and the NSD are started is unimportant.
-
To access the Web Gateway management pages, enter one of the following URLs in your browser.
http://<hostname>:<port_no>/csp/bin/Systems/Module.cxw http://<hostname>:<port_no>/csp-bin/nph-CSPcgiSys
If you see an Unauthorized User error message, see Enabling Access from Additional Client Addresses.
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.
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.
Operating and Managing the Web Gateway with Apache API and NSD
This connectivity option depends on the Web Gateway’s network service daemon (NSD).
-
Start the CSP NSD as described in Operating the NSD.
-
Restart Apache after making changes to its configuration (httpd.conf).
The order in which Apache and the NSD are started is unimportant.
-
To access the Web Gateway management pages, point your browser at one of the following locations.
http://<hostname>:<port_no>/csp/bin/Systems/Module.cxw http://<hostname>:<port_no>/csp-bin/nph-CSPcgiSys
If you see an Unauthorized User error message, see Enabling Access from Additional Client Addresses.