Skip to main content

This documentation is for an older version of this product. See the latest version of this content.Opens in a new tab

Alternative Options for Apache (Windows)

This page contains information for installations with Apache web servers on Microsoft Windows, for use with the InterSystems Web Gateway. Read the sections that apply to your installation.

This page describes additional Apache configurations for Microsoft Windows. To get started with all these configurations, read the first section. Then follow the directions in the section that applies to your installation.

Install Locations (All Atypical Options)

The following modules are installed:

  • CSPcgi.exe (Runtime module)

  • nph-CSPcgi.exe (Copy of CSPcgi.exe)

  • CSPcgiSys.exe (Systems-Management module)

  • nph-CSPcgiSys.exe (Copy of CSPcgiSys.exe)

Note:

There are separate binaries for Apache Version 2.4.x are shown below:

  • mod_csp24.dll (Apache built-in module as a DLL, if supplied)

  • CSPa24.dll (Runtime module, if supplied)

  • CSPa24Sys.dll (Web Gateway Systems Management module, if supplied)

The default location for these binaries is:

C:\Program Files\Apache Group\Apache\WebGateway\bin

The original location (install-dir\csp\bin) is used to hold the Web Gateway components required for serving the Management Portal for the specific instance of InterSystems IRIS.

The configuration and log file are written in this directory for non NSD-based connectivity options.

The modules with Sys appended are special modules for accessing the Web Gateway systems management suite. The runtime modules (that is, those without Sys) have no access to the systems management forms.

Alternative Option 1: Apache and CGI Modules with NSD (nph-CSPcgi.exe)

Configure the web server such that it recognizes InterSystems file types and passes them to the Web Gateway for processing.

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

C:\Program Files\Apache Group\Apache\conf

Add the following section to the end of httpd.conf:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    AllowOverride None
    Options FollowSymLinks ExecCGI
    Require all granted
</LocationMatch>
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ "c:/iris/csp/bin/nph-CSPcgi.exe"
Alias /csp/ c:/iris/csp/
<Directory "c:/iris/csp">
    AllowOverride None
    Options MultiViews FollowSymLinks ExecCGI
    Require all granted
    <FilesMatch "\.(log|ini|pid|exe)$">
        Require all denied
    </FilesMatch>
</Directory>
ScriptAlias /csp-bin/ "c:/iris/csp/bin/"
ScriptAliasMatch /csp/bin/Systems/Module.cxw "c:/iris/csp/bin/nph-CSPcgiSys.exe"
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "c:/iris/csp/bin/nph-CSPcgi.exe"
<Directory "c:/iris/csp/bin/">
    AllowOverride None
    Options None
    Require all granted
    <FilesMatch "\.(exe)$">
        Allow from all
    </FilesMatch>
</Directory>

The above configuration block relies on the Regular Expressions (regex) processor being available to the Apache environment. Sometimes this is not the case, particularly with Windows systems, and CSP files are consequently not served (File not found errors are returned). To remedy this situation, associate the (virtual) root location of your web applications with the CGI module instead of making the association through the CSP file extensions. For example, your web applications are in /csp. To associate the CSP CGI module with files under /csp, replace the following configuration block:

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    AllowOverride None
    Options FollowSymLinks ExecCGI
    Require all granted
</LocationMatch>
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ 
      "c:/iris/csp/bin/nph-CSPcgi.exe"

with

<Location "/csp">
    AllowOverride None
    Options FollowSymLinks ExecCGI
    Require all granted
</Location>
ScriptAlias /csp "c:/iris/csp/bin/nph-CSPcgi.exe"

These directives work for URLs of the form:

http://localhost:<port_no>/csp/*.csp

Duplicate this configuration block for other root locations. For example, repeat the process for /myapps for URLs of the form:

http://localhost:<port_no>/myapps/*.csp

Another approach to avoiding the regex issue is to use an Action directive in conjunction with a CSP MIME type. However, note that Action is a content filtering technique and, as such, requires that your CSP files are physically present on the web server host even if the InterSystems IRIS server is installed on a separate computer.

To use this approach:

  1. Add a new MIME type to the end of the Apache mime.types file and associate it with the InterSystems file types that represent classes: .csp, .cls, and .zen. The mime.types file is in the same directory as the httpd.conf file:

    text/csp                csp cls

  2. Add the Action directive to the end of the CGI configuration block in httpd.conf such that it reads:

    Alias /csp/ c:/iris/csp/
<Directory "c:/iris/csp">
    AllowOverride None
    Options MultiViews FollowSymLinks ExecCGI
    Require all granted
<Files CSPnsd.exe>
       Require all denied
    </Files>
<Files CSP.ini>
       Require all denied
    </Files>
<Files CSP.log>
       Require all denied
    </Files>
<Files CSPnsd.ini>
       Require all denied
    </Files>
<Files CSPnsd.pid>
       Require all denied
    </Files>
    <FilesMatch "\.(log|ini|pid|exe)$">
       Require all denied
    </FilesMatch>
</Directory>
ScriptAlias /csp-bin/ "c:/iris/csp/bin/"
<Directory "c:/iris/csp/bin/">
    AllowOverride None
    Options None
    Require all granted
</Directory>
Action text/csp “/csp-bin/nph-CSPcgi.exe”

    Finally, note that because CGI is an open standard, the CSP CGI modules work with any web server.

  3. Restart Apache after making changes to httpd.conf.

Mapping Additional File Types

Apache API modules always recognize InterSystems file types. For other file extensions, see Configuring Apache to Pass Additional File Types.

Operating and Managing the Web Gateway with Apache NSD

This connectivity option depends on the Web Gateway’s network service daemon (NSD).

  1. Start the CSP NSD as described in Operating the NSD.

  2. Restart Apache after making changes to its configuration (httpd.conf).

    The order in which Apache and the NSD are started is unimportant.

  3. To access the Web Gateway management pages, point your browser at one of the following locations:

    http://localhost:<port_no>/csp/bin/Systems/Module.cxw
http://localhost:<port_no>/csp-bin/nph-CSPcgiSys

    If you see an Unauthorized User error message, see Enabling Access from Additional Client Addresses.

Alternative Option 2: Apache API Module with NSD (mod_csp24.dll)

Note:

This connectivity option is not used as often as the stand-alone API modules described in Option 1; however, it can be used if you need to use the NSD. The CSP module, built as a DLL (mod_csp24.dll – for Apache 2.4), performs better than the CGI-based solution (Option 2).

  1. Edit the Apache configuration file httpd.conf. For the standard Apache distribution this file is in:

    C:\Program Files\Apache Group\Apache\conf

    To invoke CSP for files with the .csp, .cls, and .zen extensions, add the following section to the end of httpd.conf. For Apache v2.4.x, specify mod_csp24.dll. 

    LoadModule csp_module c:/iris/csp/bin/mod_csp24.dll
CSPFileTypes csp cls zen cxw 
Alias /csp/ /iris/csp/
<Directory "c:/iris/csp">
        AllowOverride None
        Options MultiViews FollowSymLinks ExecCGI
        Require all granted
        <FilesMatch "\.(log|ini|pid|exe)$">
                Require all denied
        </FilesMatch>
        <Files CSPnsd>
                Require all denied
        </Files>
</Directory>
ScriptAlias /csp-bin/ "c:/iris/csp/bin/"
ScriptAliasMatch /csp/bin/Systems/Module.cxw
              "c:/iris/csp/bin/nph-CSPcgiSys.exe" 
ScriptAliasMatch /csp/bin/RunTime/Module.cxw
              "c:/iris/csp/bin/nph-CSPcgi.exe"
<Directory "c:/iris/csp/bin/">
        AllowOverride None
        Options None
        Require all granted
</Directory>

  2. Restart Apache after making changes to httpd.conf.

Mapping Additional File Types

To configure additional file types to be processed by the CSP engine, include the new file extension(s) in the list of usual file extensions (.csp, .cls, .zen) to be processed by the CGI module. For example, add them to the following line:

ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$  "C:/iris/csp/bin/nph-CSPcgi.exe"

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, .svg, .css, and .js.

The following directive can be used to map requests for all files to InterSystems IRIS (specifically by the CSP engine) for a given path.

ScriptAliasMatch ^/csp/*/.* "C:/iris/csp/bin/nph-CSPcgi.exe"

Therefore, a basic configuration block for mapping requests for all files in the /csp path would be:

ScriptAliasMatch ^/csp/*/.* "C:/iris/csp/bin/nph-CSPcgi.exe"
<Directory "/iris/csp/bin/">
   AllowOverride None    
   Options None
   Require all granted
</Directory>

Operating and Managing the Web Gateway with Apache API and NSD

This connectivity option depends on the Web Gateway’s network service daemon (NSD).

  1. Start the CSP NSD as described in Operating the NSD.

  2. Restart Apache after making changes to its configuration (httpd.conf).

    The order in which Apache and the NSD are started is unimportant.

  3. To access the Web Gateway management pages, point your browser at one of the following locations.

    http://localhost:<port_no>/csp/bin/Systems/Module.cxw 
http://localhost:<port_no>/csp-bin/nph-CSPcgiSys.exe

    If you see an Unauthorized User error message, see Enabling Access from Additional Client Addresses.

Locked-down Apache Environments for Microsoft Windows

Occasionally Apache is locked-down such that you cannot easily configure the server to access files outside the Apache file system.

For configurations locked down in this way, the Web Gateway configurations discussed in previous sections result in HTTP 403 Forbidden error codes being returned when you try to access CSP resources. To work with these secure configurations, copy the file system under: install-dir\csp\

to a location under the Apache root:

C:\Program Files\Apache Group\Apache\

Specify appropriate changes to the paths specified in the Apache configuration.

An alternative approach is to configure the Web Gateway to work within the pre-configured directories provided by Apache.

  1. Copy CGI modules to: C:\Program Files\Apache Group\Apache\cgi-bin\ as follows:

    copy c:\iris\csp\bin\*cgi*.exe C:\Program Files\Apache Group\Apache\cgi-bin\

  2. Copy API modules to C:\Program Files\Apache Group\Apache\modules:

    copy c:\iris\csp\bin\*.dll C:\Program Files\Apache Group\Apache\modules\

  3. Copy static files (and their subdirectories) to locations under C:\Program Files\Apache Group\Apache\htdocs\csp\samples.

    copy c:\iris\csp\samples\*.*
  C:\Program Files\Apache Group\Apache\htdocs\csp\samples\ 
copy c:\iris\csp\broker\*.*
  C:\Program Files\Apache Group\Apache\htdocs\csp\broker\
copy c:\iris\csp\sys\*.*
  C:\Program Files\Apache Group\Apache\htdocs\csp\sys\

  4. Install the NSD component (if required) in C:\Program Files\Apache Group\Apache\nsd.

Using the pre-configured directories in Apache simplifies the Web Gateway configuration in httpd.conf. Modified configuration blocks are shown below.

Configuration for Recommended Option: Apache API Modules (CSPa24.dll)

LoadModule csp_module_sa
    C:/Program Files/Apache Group/Apache/modules/CSPa24.dll
CSPFileTypes csp cls zen cxw

Configuration for Alternative Option 2: CGI Modules with NSD (nph-CSPcgi.exe)

<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
AllowOverride None
Options FollowSymLinks ExecCGI
Require all granted
</LocationMatch>
ScriptAliasMatch /csp/bin/Systems/Module.cxw "C:/Program Files/Apache Group/Apache/cgi-bin/nph-CSPcgiSys.exe"
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "C:/Program Files/Apache Group/Apache/cgi-bin/nph-CSPcgi.exe"
ScriptAliasMatch /*\.([Cc][Ss][Pp]|[Cc][Ll][Ss])$ "C:/Program Files/Apache Group/Apache/cgi-bin/nph-CSPcgi.exe"

Configuration for Alternative Option 3: Apache API Module with NSD (mod_csp24.dll)

LoadModule csp_module
           C:/Program Files/Apache Group/Apache/modules/mod_csp24.dll
CSPFileTypes csp cls zen cxw 
ScriptAliasMatch /csp/bin/Systems/Module.cxw "C:/Program Files/Apache Group/Apache/cgi-bin/nph-CSPcgiSys.exe"
ScriptAliasMatch /csp/bin/RunTime/Module.cxw "C:/Program Files/Apache Group/Apache/cgi-bin/nph-CSPcgi.exe"

Configuration for Alternative Option 4: ISAPI Modules (CSPms.dll)

Legacy only

AddHandler isapi-isa dll
AddHandler isapi-isa csp
AddHandler isapi-isa cls
AddHandler isapi-isa zen
AddHandler isapi-isa cxw
Alias /csp/bin/Systems/Module.cxw /csp/bin/CSPmsSys.dll
Using the NSD (UNIX®/Linux/macOS)Next section
Previous sectionAlternative Options for IIS 7 or Later (Windows)
FeedbackOpens in a new tab