docs.intersystems.com
Home / Web Gateway Configuration Guide / Web Servers for UNIX, Linux, and macOS

Web Gateway Configuration Guide
Web Servers for UNIX, Linux, and macOS
Previous section           Next section
InterSystems: The power behind what matters   
Search:  


This section describes the web servers used with InterSystems IRIS™ running on UNIX®, Linux, and macOS. It contains the following sections:
Several connectivity options are available for Apache. The Apache Group provides support for extensions implemented as dynamically linked modules (DSOs). Extensions, written as Apache modules, can be built directly into the Apache core. This is the recommended option. Other, atypical, configuration options are in the appendix Alternative Configurations for UNIX, Linux, and macOS
Apache Servers
Apache is supplied by the Apache Group and can be downloaded free of charge from http://www.apache.org.
Pre-built kits are available for some UNIX systems which are, generally, a few builds behind the latest version. The complete source code to Apache is available for download together with clear instructions for building the Apache server. The freely available GNU C compiler (gcc) can be obtained for this purpose, though the Apache build procedure attempts to use the indigenous C compiler.
Many systems are shipped with Apache pre-installed, configured and ready to go. Most distributions of Linux include Apache. IBM distributes Apache with their UNIX implementation: AIX.
Note:
The build of Apache that IBM supplies with AIX is not compatible with the recommended Apache API modules. Follow the instructions in the appendix Building Apache for IBM AIX® to build a compatible version of Apache on AIX. The configurations using NSD do not require this step. For more information, see the appendix Alternative Configurations for UNIX, Linux, and macOS.
This guide refers to the directory that Web Gateway components are installed in as: /opt/webgateway/bin/. It refers to the directory that Apache is installed in as /usr/apache/. Your Apache install directory may be different. If the layout is different on your system, be sure to amend the configuration directives described in the following sections, as appropriate.
This section describes the recommended option for installing the Web Gateway.
  1. Everyone should follow the directions in the section Install Locations with Apache Servers on UNIX (All Options).
Install Locations Apache UNIX, Linux, Mac OS (Recommended Option)
This section describes directory locations for Web Gateway files and CSP static files. The installation directory is /iris.
  1. Dynamically-linked modules CSPa24.so for Apache Version 2.4.x.
    In order to avoid disrupting existing Web 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.
    /opt/webgateway/bin
    The original location (/iris/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.
  2. HyperEvents Components
    The default location for these files is:
    /iris/csp/broker
  3. Miscellaneous static resources used by the CSP Samples
    A number of static web resources (such as image files) are required by the CSP Samples. The default location for these files is:
    /iris/csp/samples
  4. Miscellaneous static resources used by the Management Portal.
    A number of static web resources (such as image files) are required by the Management Portal. The default location for these files is:
    /iris/csp/sys
Requirements for using Apache API Modules (Recommended Option and Alternative Option 1)
Before following instructions for either Recommended Option and Alternative Option 1, 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, refer to your Apache documentation and follow the procedure for rebuilding Apache to include this module.
Recommended Option: Apache API Module without NSD (CSPa24.so)
This option is used in the configuration of the Private Web Server in the Management Portal.
This connectivity option offers the best performance as well as being the easiest to configure.
Before using this option you should bear in mind that Apache v2.4 is partially multi-threaded, implemented as a hybrid multi-process and multi-threaded server. In practice, this means that there is one instance of the Web Gateway per Apache child process. This is not a problem in itself but this architecture makes it difficult to control the number of connections to InterSystems IRIS (and InterSystems IRIS processes) used by the Web Gateway since each instance of the Web Gateway independently manages its own pool of InterSystems IRIS connections.
State-aware connectivity (preserve mode 1) should not be used with these modules.
The modules CSPa24.so (Runtime) and CSPa24Sys.so (Web Gateway systems management) are dynamically linked modules (DSOs).
Configure the web server to recognize CSP requests (files of type .csp, .cls, and .zen) and pass them to the Web Gateway module for processing. Apache 2.4.x: Use modules CSPa24.so and CSPa24Sys.so.
The web server configuration file (httpd.conf) is in the following directory:
/usr/apache/conf
For Red Hat Linux, the runtime version of httpd.conf is found in:
/etc/httpd/conf
For Suse, the runtime version of httpd.conf is found in:
/etc/apache2/conf
  1. Apache 2.4.x: Add the section below to the end of httpd.conf.
    LoadModule csp_module_sa /opt/webgateway/bin/CSPa24.so
    CSPModulePath /opt/webgateway/bin/
    <Location "/csp/bin/Systems/">
    SetHandler cspsys-handler-sa
    </Location>
    <Location "/csp/bin/RunTime/">
    SetHandler csp-handler-sa
    </Location>
    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>
    </Directory>
  2. 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 
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
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> 
For example, all the following would be sent to CSP for processing:
/csp/ 
/csp/samples/menu.csp 
/csp/sys/ 
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 
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>
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> 
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
and
text/csp
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
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 CSP 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
To access the Web Gateway Management pages, point your browser to:
http://localhost:<port_no>/csp/bin/Systems/Module.cxw
Notice the use of the cxw file extension. This extension prevents Apache attempting to load and run these DLLs through the Apache Group ISAPI interface. Also, remember that URL paths and files names are case-sensitive under Apache.
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
If you see an Unauthorized User error message, refer to the section on security considerations.
Nginx Web Servers
Nginx is an Open Source product and the source code can be downloaded free of charge from:
http://nginx.org/
Some prebuilt kits are available for Linux which are, generally, a few builds behind the latest Nginx build. However, given that extensions must be compiled into the Nginx core, it is necessary to build the web server locally from the source code in order to include support for CSP.
This guide assumes that CSP/Web Gateway web server components are installed under the following directory:
/opt/webgateway/bin/
It assumes that InterSystems IRIS, if installed locally, is under:
/opt/iris/
It assumes that the web server is installed under:
/opt/nginx/
If the layout is different on your system, be sure to amend the various configuration directives described in the following sections, as appropriate.
Installation
The Web Gateway components and the CSP static files should be installed as follows:
  1. Dynamically linked Universal Web Gateway Modules
    The default location for these binaries is:
    The configuration file (CSP.ini) and Event Log (CSP.log) are written in this directory.
    The modules with Sys appended are special modules for accessing the CSP systems management suite. The runtime modules (that is, those without Sys) have no access to the systems management forms.
  2. HyperEvents Components
    The default location for these files is:
    If these files are to be served as static components directly by the web server they should be copied to the following location:
  3. Miscellaneous static resources used by the Management Portal
    A number of static web resources (such as image files) are required by the Management Portal. The default location for these files is:
    Copy these to the following location if they are to be served directly by the web server:
Building the Nginx Web Server for CSP
Most of the Web Gateway functionality is provided by the Universal Modules (CSPx[Sys].so). For CSP access, Nginx can be built and configured to communicate with these Universal Modules through a small compiled-in module:
ngx_http_csp_module_sa.c
The build instructions given here are based on the official documentation for building Nginx under UNIX systems:
http://nginx.org/en/docs/configure.html
The Nginx documentation stipulates that the following third party add-ons are also required:
However, it is possible to create a fully functional server without these components, provided the final installation doesn’t require the functionality that would otherwise be provided by them.
A typical configuration script for building Nginx, including all optional modules listed above, is as follows:
./configure --prefix=/opt/nginx --with-http_ssl_module
This results in a default Nginx build installed under: /opt/nginx
The build process can be modified to exclude optional modules:
Procedure for building Nginx for CSP
  1. Unpack the source distribution under a location of your choice. For example:
    After unpacking, if you specify /opt/, the source code distribution is under:
  2. Create a directory for the CSP extension:
  3. Copy the module source code (ngx_http_csp_module_sa.c and cspapi.h) to the directory created above.
  4. In that same directory, create a configuration file called config. This file should contain the following lines:
    ngx_addon_name=ngx_http_csp_module_sa
    HTTP_MODULES="$HTTP_MODULES ngx_http_csp_module_sa"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_csp_module_sa.c"
    CORE_LIBS="$CORE_LIBS -ldl"
  5. Working in /opt/nginx-n.n.n/, configure the Nginx build environment:
    ./configure --prefix=/opt/nginx \
    --with-http_ssl_module \
    --add-module=/opt/nginx-n.n.n/csp
    Alternatively, without the optional functionality provided by OpenSSL, ZLIB and PCRE:
     ./configure --prefix=/opt/nginx \
    --without-http_rewrite_module \
    --without-http_gzip_module \
    --add-module=/opt/nginx-n.n.n/csp
    Note the final line containing the instructions to include the CSP module.
  6. Compile Nginx:
    make
  7. Install Nginx:
    make install
    If successful, you should find the complete server installation under:
Using the Universal Web Gateway Modules (CSPx*.so)
The Universal Modules CSPx.so (Run-time) and CSPxSys.so (Web Gateway systems management) are dynamically linked modules that are designed to be loaded by a CSP-enabled Nginx installation.
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 module for processing
The web server configuration file (nginx.conf) is found in the following directory:
/opt/nginx/conf
The following configuration directives are provided for the CSP extension:
Place the following directive within the http configuration block:
CSPModulePath /opt/webgateway/bin/;
This directive enables Nginx to find the Universal Gateway Modules (CSPx[Sys].so) and the associated configuration (CSP.ini).
Nginx can now be configured to pass all requests for a certain path to CSP or just certain file types.
Using the Universal Web Gateway Modules (CSPx*.dll)
Enabling CSP for a Particular Path
Place the following section within the appropriate server configuration block:
location /csp {
CSP On;
}
Registering Specific File Types with CSP
Place the following section within the appropriate server configuration block:
location /csp {
CSPFileTypes  csp cls zen cxw;
}
Starting and Stopping Nginx
First, ensure that Nginx has read/write permissions to the location holding the Universal Gateway Modules (/opt/webgateway/bin/). This is the location where the Web Gateway configuration and Event Log files are maintained (CSP.ini and CSP.log).
To start Nginx:
/opt/nginx/sbin/nginx
To stop Nginx:
/opt/nginx/sbin/nginx –s stop
Operating and Managing the Web Gateway
To access the Web Gateway’s systems management suite, point your browser:
http://<ip_address>/csp/bin/Systems/Module.cxw
Notice the use of the cxw file extension.
The CSP engine is automatically invoked for requested files containing the .csp, .cls, or .zen extensions. For example:
http://<ip_address>/csp/samples/menu.csp
If you see an Unauthorized User error message, refer to the section on security considerations in this book.
Building Nginx to Work with the CSP NSD Component
Nginx can be built to work with the Web Gateway’s network service daemon component (CSPnsd[Sv].exe), as opposed to the Universal Modules (CSPx[Sys].dll). To do this, modify the build and configuration procedure as follows:
The usual reason for preferring to use the NSD component is to obtain full and reliable support for CSP state-aware mode (Preserve mode). However, in order to get the best results with Nginx, it is recommended that applications should be entirely stateless.


Previous section           Next section
Send us comments on this page
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-07-17 06:06:47