Skip to main content

Web Servers for UNIX, Linux, and macOS

This section describes the web servers used with InterSystems IRIS® running on UNIX®, Linux, and macOS.

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 preinstalled, configured and ready to go. Most distributions of Linux include Apache. IBM distributes Apache with their UNIX implementation, AIX.

Note:

The macOS and AIX preinstalled versions of Apache may not be suitable for use with InterSystems IRIS:

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

  • For versions of macOS starting with 10.14 and ending with 10.14.3, the Web Gateway is incompatible with the preinstalled Apache web server. Therefore, InterSystems recommends one of these alternatives:

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)”.

  2. Then follow the directions in the section “Recommended Option: Apache API Module without NSD (CSPa24.so)”. Or, if you are using an atypical option, see the appendix “Alternative Configurations for UNIX, Linux, and Mac OS.

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

    • CSPBroker.js

    • CSPxmlhttp.js

    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

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

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. Web Gateway Network Service Daemon (NSD)

    • CSPnsd

    The default location for this binary is:

    /opt/webgateway/bin/

  2. HyperEvents Components

    CSPBroker.js

    CSPxmlhttp.js

    The default location for these files is:

    /opt/iris/csp/broker

    If these files are to be served as static components directly by the web server they should be copied to the following location:

    /opt/nginx/html/csp/broker

  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:

    /opt/iris/csp/sys

    Copy these to the following location if they are to be served directly by the web server:

    /opt/nginx/html/csp/sys

Building the Nginx Web Server for CSP

Most of the Web Gateway functionality is provided by the NSD (CSPnsd). For CSP access, Nginx can be built and configured to communicate with the NSD through a small compiled-in module:

ngx_http_csp_module.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:

  • OpenSSL - Remove SSL/TLS capability:

    Remove directive: --with-http_ssl_module

  • Zlib - Remove GZIP capability:

    Add directive: --without-http_gzip_module

  • PCRE - Remove HTTP rewrite capability:

    Add directive: --without-http_rewrite_module

Procedure for building Nginx for CSP

  1. Unpack the source distribution under a location of your choice. For example:

    /opt/

    After unpacking, if you specify /opt/, the source code distribution is under:

    /opt/nginx-n.n.n/

  2. Create a directory for the CSP extension:

    /opt/nginx-n.n.n/csp/

  3. Copy the module source code (ngx_http_csp_module.c) 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
    HTTP_MODULES="$HTTP_MODULES ngx_http_csp_module"
    NGX_ADDON_SRCS="$NGX_ADDON_SRCS $ngx_addon_dir/ngx_http_csp_module.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:

    /opt/nginx/

Using the NSD with Nginx

The web server should be configured such that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the NSD 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:

Syntax: CSP on|off;

Default: CSP off;

Context: location, if in location

Whether CSP is enabled for all requests to a particular path.

Syntax: CSPFileTypes [filetype ... ];

Default: —

Context: location, if in location

The file types for which CSP is enabled. To enable CSP for particular file types such as .csp or .cls, use the following directive.

CSPFileTypes csp cls;

To enable CSP for all file types, use *.

CSPFileTypes *;

Syntax: CSPNSD_pass hostname:port;

Default: —

Context: location, if in location

The hostname/IP and port where the NSD is listening. By default, the NSD listens at 127.0.0.1:7038. This directive is required.

Syntax: CSPNSD_response_headers_maxsize size ;

Default: CSPNSD_response_headers_maxsize 8k;

Context: location, if in location

The maximum size of the HTTP headers in a response. An error is returned to the web client if the response headers exceed this size.

Syntax: CSPNSD_connect_timeout time;

Default: CSPNSD_connect_timeout 300s ;

Context: location, if in location

Timeout for connecting to the NSD when a request is received from the web client.

Syntax: CSPNSD_send_timeout time ;

Default: CSPNSD_send_timeout 300s;

Context: location, if in location

Timeout for a single send operation to the NSD when sending a request. The timeout is set only between two successive write operations, not for the transmission of the whole request.

Syntax: CSPNSD_read_timeout time ;

Default: CSPNSD_read_timeout 300s;

Context: location, if in location

Timeout for a single read operation from the NSD when reading a response. The timeout is set only between two successive read operations, not for the transmission of the whole response.

Enabling CSP for a Particular Path

Place the following section within the appropriate server configuration block:

location /csp {
CSP On;
CSPNSD_pass localhost:7038;
}

Registering Specific File Types with CSP

Place the following section within the appropriate server configuration block:

location /csp {
CSPFileTypes  csp cls zen cxw;
CSPNSD_pass localhost:7038;
}

Starting and Stopping Nginx and the NSD

To start Nginx:

/opt/nginx/sbin/nginx

To stop Nginx:

/opt/nginx/sbin/nginx –s stop

See Operating the NSD for instructions on how to operate the NSD.

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.

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 Universal Modules CSPx.so (Run-time) and CSPxSys.so (Web Gateway systems management). The Universal Modules are dynamically linked modules that can be loaded by a CSP-enabled Nginx installation. Use of the Universal Modules is now deprecated and not recommended due to stability issues. Everyone using the Universal Modules should rebuild and reconfigure Nginx to use the NSD instead. The following instructions serve as a reference only for existing installations. To build Nginx to work with the Universal Modules, modify the build and configuration procedure as follows:

  • In step 3, copy the module source code ngx_http_csp_module_sa.c, cspapi.h, and ngx_http_csp_common.hinstead of ngx_http_csp_module_sa.c.

  • In step 4, the configuration file for CSP (/opt/nginx-n.n.n/csp/config) should read as follows:

    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"
  • Add the CSPModulePath directive from the http configuration block to specify the path to the Universal Gateway Modules.

    CSPModulePath /opt/webgateway/bin;
  • The following directives are not supported:

    • CSPNSD_pass

    • CSPNSD_response_headers_maxsize

    • CSPNSD_connect_timeout

    • CSPNSD_send_timeout

    • CSPNSD_read_timeout

  • The following directives are supported:

    • CSP

    • CSPFileTypes

Feedback