Skip to main content

Apache for UNIX®/Linux/macOS

Apache for UNIX®/Linux/macOS

The Apache HTTP web server is supplied by the Apache Group and can be downloaded free of charge from http://www.apache.orgOpens in a new tab. Many systems are shipped with Apache preinstalled, configured and ready to go. For guidance installing Apache on a supported UNIX® or Linux system, refer to this Developer Community article: in a new tab.


On macOS, the InterSystems IRIS installer cannot automatically configure the preinstalled version of Apache. However, it can automatically configure the version of Apache installed using Homebrew ( in a new tab).

This page describes how to deploy the Web Gateway in Apache with the dynamic module csp_module_sa, which InterSystems implements using Apache’s native API.

The csp_module_sa module implements the Web Gateway using two dynamic shared object (.so) files:

  • — the runtime binary.

  • — the Web Gateway management binary.

This is the recommended deployment option for Apache; it is effective for the vast majority of use cases.


State-aware connectivity (preserve mode 1) should not be used with this module.

If you are configuring the Web Gateway on a system which uses a security-restricted version of Apache (such as RHEL with SELinux), see Add the Web Gateway to a Locked-Down Apache Installation for supplementary instructions. Alternative Options for Apache describes other options for deploying the Web Gateway with Apache, including options which use the Network Service Daemon (NSD).

Apache Considerations provides some guidance for administering an Apache web server connected to a Web Gateway. For detailed guidance, consult the Apache documentation ( in a new tab).

Verify That Apache Can Manage Shared Object Modules

Before you attempt to add the Web Gateway to your Apache configuration using Apache’s proprietary API, 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 from the command line (select the command appropriate for your operating system):

httpd -l
apache2 -l

This command displays the list of modules included in your current Apache installation. If mod_so is not included in this list, follow the instructions provided within the Apache documentation ( in a new tab) to compile a new build of Apache that includes this module.

Add the Web Gateway Modules to Your Web Server Configuration

  1. Note the file system location of the Web Gateway module files. These instructions use the most common location, /opt/webgateway/bin.

  2. Open the Apache web server configuration file (httpd.conf) in a text editor. This file is located in your Apache installation directory, within the /conf subdirectory. The most common installation locations are:

  3. Append directives to the end of the file which add the Web Gateway module. These directives should accomplish the following:

    • Load the module using the LoadModule directive, providing the name of the module and the location of the .so file for the Web Gateway’s runtime functions.

    • Issue the CSPModulePath directive, providing the full path for the directory that contains the .so file for the Web Gateway’s runtime functions.

    • Issue the CSPConfigPath directive, providing the full path for the directory that contains the .so file for the Web Gateway management functions.

    • Configure access settings for the directory that contains the Web Gateway binaries. To do so, add a <Directory> directive block for that directory as follows (the example assumes the most common installation location):

      <Directory "/opt/webgateway/bin">
          AllowOverride None
          Options MultiViews FollowSymLinks ExecCGI
          Require all granted
          <FilesMatch "\.(log|ini|pid|exe)$">
              Require all denied 
  4. Optional: if you want the web server to serve static files for your web applications, append directives to map the appropriate /csp paths to file system locations accessible to your web server. The Apache Alias directive provides one such method to accomplish this.

    For example: if the application /dashboard is served by a remote InterSystems IRIS instance but you want to serve static files for the application from the directory C:\iris\csp\dashboard on the web server’s machine, you could add the following directive:

    Alias /dashboard/ "C:/iris/csp/dashboard"
  5. Issue directives which invoke the Web Gateway to handle requests intended for your InterSystems IRIS applications. InterSystems provides the following directives for this purpose:

    • CSPFileTypes, which invokes the Web Gateway for requests for the set of file types you specify. (Because REST API endpoints are often paths and not files, this directive is not sufficient to invoke requests for REST applications.)

    • CSP On and CSP Off, which enable or disable the Web Gateway as the handler for all requests.

    By issuing these directives within <Location> blocks, you can configure your web server in a granular way, invoking the Web Gateway only for those relative URL paths which correspond with your InterSystems IRIS web applications.

    The following location block would invoke the Web Gateway exclusively for requests directed to the Management Portal for an InterSystems IRIS instance named iris3:

    <Location "/iris3/csp/sys/">
        CSP On

    To access the management pages for a Web Gateway without access to an InterSystems IRIS instance, enable the Web Gateway for the /csp path.

  6. Save the httpd.conf file.

  7. Restart Apache to allow the configuration changes to take effect.

The installer employs this procedure when it automatically configures an Apache web server. See Automatic Configuration Example for an example.

FeedbackOpens in a new tab