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

Assumptions

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

Recommended Option: Apache API Module without NSD (CSPa24.so)

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 CSPa24.so (Runtime) and CSPa24Sys.so (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 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 Ubuntu or SUSE, the runtime version of httpd.conf is found in:

/etc/apache2/conf

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

   LoadModule csp_module_sa /opt/webgateway/bin/CSPa24.so
   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 
            </FilesMatch>
   </Directory>
   

   

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.