Skip to main content

Configuring Apache to Work With the Web Gateway (UNIX®/Linux/macOS)

This page describes how to configure an Apache web server for use with the InterSystems Web Gateway on UNIX®, Linux, or macOS. (On these operating systems, the other option is Nginx; options are different on other operating systems.)

Several connectivity options are available for Apache. Apache is supplied by the Apache Group and can be downloaded free of charge from http://www.apache.orgOpens in a new tab. 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 options are the NSD, locked-down Apache web server, and several other atypical Apache configurations.

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.


In certain cases, the macOS and AIX preinstalled versions of Apache may not be suitable for use with InterSystems IRIS: see Using the NSD for UNIX®, Linux, and macOS for an alternative deployment option.

This section describes the recommended option for installing the Web Gateway.

  1. For all configurations, follow the directions in Install Locations for Apache on UNIX®, Linux, and macOS.

  2. Then follow the directions in Recommended Option: Apache API Module without NSD (

    Or for less common scenarios, see Locked-Down Apache Web Server, and other Atypical Apache Configurations.


This page assumes that:

  • The Web Gateway components are installed in /opt/webgateway/bin/

  • Apache is installed in /usr/apache/

If the layout is different on your system, modify the configuration directives as appropriate.

Install Locations for Apache for UNIX®, Linux, macOS (Recommended Option)

This section describes directory locations for Web Gateway files and CSP static files. The installation directory is /iris.

  1. Dynamically-linked modules 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.


    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:

  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:

  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:


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 on Red Hat Linux, issue the following command:

httpd -l

To perform this check on Ubuntu or SUSE, issue the following command:

apache2 -l

These commands display the list of modules currently available within Apache. The shared object module (mod_so) should appear on this list. The following shows a typical module listing (with mod_so included):

Compiled in modules:

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.

Recommended Option: Apache API Module without NSD (

This option is used in the configuration of the Private Web Server used by 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 because 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 (Runtime) and (Web Gateway systems management) are dynamically linked modules (DSOs).

Configure the web server to recognize InterSystems file types and pass them to the Web Gateway module for processing. Apache 2.4.x: Use modules and

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


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


For Ubuntu or SUSE, the runtime version of httpd.conf is found in:

  1. Apache 2.4.x: Add the following to the end of httpd.conf.

    LoadModule csp_module_sa /opt/webgateway/bin/
    CSPModulePath /opt/webgateway/bin/
    CSPFileTypes csp cls zen cxw 
    Alias /csp/ /opt/webgateway/bin/
    <Directory "/opt/webgateway/bin">
             AllowOverride None
             Options MultiViews FollowSymLinks ExecCGI
             Require all granted
             <FilesMatch "\.(log|ini|pid|exe)$">
             Require all denied 
  2. Restart Apache after making changes to httpd.conf.

  3. See Configuring Apache to Pass Additional File Types.

Now you can use the Web Gateway management pages to further configure the Web Gateway.

FeedbackOpens in a new tab