docs.intersystems.com
InterSystems IRIS Data Platform 2019.2  /  Web Gateway Configuration Guide

Web Gateway Configuration Guide
Alternative Configurations for Microsoft Windows
Previous section           Next section
InterSystems: The power behind what matters   
Search:  


This section describes how to set up atypical configurations for InterSystems IRIS™ on Microsoft Windows. You should read the first sections to see if they apply to your configuration. Then select one of the configuration options. This section contains the following sections:
These atypical configurations may require some of the following modules. Refer to the sections describing each option to see which are actually required.
These modules are placed in the following common location:
C:\Inetpub\CSPGateway
The configuration file (CSP.ini) and Event Log (CSP.log) are written in this directory for non NSD-based connectivity options.
Using the Network Service Daemon (NSD)
When to Use the NSD
Several of the options described in this book use the NSD. There are two situations in which you might choose to use the NSD to separate the Web Gateway from the web server so that you can manage the Web Gateway independently of the web server. These are:
NSD Module Install Locations
If the you use the NSD Module in Microsoft Windows, you install the following two utilities:
On an IIS installation, these are installed in this location:
C:\Inetpub\CSPGateway\nsd
On an Apache installation, these are installed in this location:
C:\Program Files\Apache Group\Apache\WebGateway\nsd
Run the NSD from within its home directory, C:\Inetpub\CSPGateway\nsd. The configuration file (CSP.ini) and Event Log (CSP.log) are written in this directory for NSD-based connectivity options.
Operating the NSD
Use the following procedure to start the NSD.
  1. Change to the NSD home directory, such as:
    C:\Inetpub\CSPGateway\nsd
  2. Start the NSD with:
    CSPnsd
    The NSD starts as a Windows service (CSPnsdSv.exe). Once registered as a service, you can manage the NSD entirely through the Windows Service Manager.
  3. Close down the NSD, by issuing the following command:
    CSPnsd -stop
Alternatively, you can enter:
CSPnsd
This shows the status of the NSD’s Windows Service and allows you to perform one of the following actions:
Alternatively, you can use the Windows Service Manager to manage the NSD. The NSD can be identified in the Service Manager by the description:
Cache Server Pages – Network Service Daemon
All errors are reported in the CSP event log (that is, CSP.log). This file is created and maintained in the install-dir\csp directory. The CSP configuration file CSP.ini also resides in this directory.
Other Startup Options
  1. Display help information.
    CSPnsd -h
  2. Run the NSD interactively in a command window as opposed to as a Windows service. You must use this mode of operation if you are running multiple instances of the NSD.
    CSPnsd -v
Starting NSD on Alternative TCP Port
By default, the NSD listens for incoming requests on TCP port 7038. You can override this by starting the service as follows:
CSPnsd –v [port_no]
Or:
CSPnsd –v -p[port_no]
- where port_no is the TCP port number of your choice.
On startup, the NSD creates the following file:
CSPnsd.ini
Typically, this file contains the following lines:
[SYSTEM]
Ip_Address=127.0.0.1
TCP_Port=7038
In this context, the clients are the Web Gateway modules contained within, or dynamically linked to, the web server and/or the CSP CGI modules invoked by the server. It is, therefore, essential that this file is not deleted or moved. It is also important that the web server processes can read this file. Set the privileges accordingly, bearing in mind the Windows user under which your web server is operating. The NSD clients attempt to find this file in a location contained within the Windows PATH variable. For example:
C:\Windows
The CSPnsd.ini file must be moved to this location before starting the web server
Clearly, storing the NSD port number in the CSPnsd.ini file is inappropriate for situations in which multiple instances of the NSD are running. For Apache servers, there is a much better mechanism for communicating the TCP port number of the NSD to its clients.
Set the following environment variables in the Apache configuration to indicate the address and port of the target NSD installation. The values specified in these environment variables take precedence over any values found in the CSPnsd.ini file.
CSP_NSD_NAME — This is the IP address of the NSD. Only use this parameter if the NSD is operating on a remote computer.
CSP_NSD_PORT — This is the TCP port of the NSD.
Example 1:
Distribute the load for two Apache virtual hosts (say, 123.123.1.1 and 123.123.1.2) between two independent NSD installations (listening on TCP port 7038 and 7039).
Add the following directives to the Apache configuration (httpd.conf):
<VirtualHost 123.123.1.1>
    ServerName 123.123.1.1
    SetEnv CSP_NSD_PORT 7038
</VirtualHost>
<VirtualHost 123.123.1.2>
    ServerName 123.123.1.2
    SetEnv CSP_NSD_PORT 7039
</VirtualHost>
Example 2:
Distribute the load for two web applications (say, /csp1 and /csp2) between two independent NSD installations (listening on TCP port 7038 and 7039).
  1. Add the following directives to the Apache configuration (httpd.conf):
    <Location /csp1>
        SetEnv CSP_NSD_PORT 7038
    </Location>
    <Location /csp2>
        SetEnv CSP_NSD_PORT 7039
    </Location>
  2. Restart Apache after making changes to its configuration.
In cases where multiple instances of the NSD are running, it is recommended that the separate instances be installed in separate directories, each maintaining its own copy of the configuration and log files (CSP.ini and CSP.log). The Web Gateway Management pages for each instance can easily be accessed by using the NSD internal HTTP server. For example:
http://localhost:7038/csp/bin/Systems/Module.cxw
http://localhost:7039/csp/bin/Systems/Module.cxw
Alternative Options for IIS 7 or Later
This appendix contains instructions for configuring atypical options for IIS 7. To configure one of these options:
  1. Follow the steps in the section Microsoft IIS All Versions.
  2. Install ISAPI and GCI services, as described in the section Installing the ISAPI and CGI Services.
  3. Select one of the following 4 options and follow the directions in that section:
Installing the ISAPI and CGI Services
IIS 7 does not, by default, run ISAPI extension, ISAPI filters, or CGI modules. For all the atypical options for IIS 7, you must install these services.
Note that, with the ISAPI extensions service installed, all versions of the Web Gateway work with IIS 7.
Install these legacy services through the Windows Control Panel.
  1. Open the Windows Control Panel.
  2. Select Programs and Features and select Turn Windows Features on or off.
  3. Navigate to Internet Information Services and expand World Wide Web Services and Application Development Features.
    Select ISAPI Extensions. Also select ISAPI Filters and CGI, if these additional services are required. Select OK.
  4. In the Windows Control Panel, open Administrative Tools and Internet Information Services (IIS) Manager.
  5. In the left panel, highlight [MACHINE_NAME] ([machine_name]\[user_name])
  6. In the middle panel, double-click the Modules icon.
  7. In the right panel, select Add Native Module.
  8. In the left panel, expand the top level, expand Web Sites and expand Default Web Site
    [MACHINE_NAME] ([machine_name]\[user_name])
                  Web Sites
                         Default Web Site
  9. In the middle panel, double-click Handler Mappings.
  10. In the middle panel, highlight the ISAPI-dll handler.
  11. In the right panel, select Edit Handler Permissions.
  12. Select Execute and select OK. This allows ISAPI extensions to be invoked through direct calls to the name of the ISAPI DLL.
Alternative Option 1: Using the ISAPI Modules (CSPms*.dll)
Use this option if your Web Gateway DLLs are unable to support the Native Module interface (the Recommended Option). This is the default (and best performing) solution that was supplied for earlier versions of IIS.
IIS 7 does not, by default, run ISAPI extensions, ISAPI filters or CGI modules. This option requires the ISAPI extensions service.
Follow the instructions in the section Installing the ISAPI and CGI Services (If Required) for installing and configuring the ISAPI extensions service.
The web server should be configured such that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the Web Gateway for processing.
Enabling the ISAPI Extensions
DLLs: CSPms.dll and CSPmsSys.dll
Before these extensions can be used they must be registered with IIS as being “Allowed” applications. This is done in the Internet Information Services (IIS) Manager control panel.
  1. Open the Internet Information Services (IIS) Manager window.
  2. In the left panel, highlight [MACHINE_NAME] ([machine_name]\[user_name]).
  3. In the middle panel, double-click ISAPI and CGI Restrictions.
  4. In the right panel, select Add.
  5. In the Add ISAPI or CGI Restriction dialogue, enter the following details:
    ISAPI or CGI Path: C:\Inetpub\CSPGateway\CSPms.dll
    Description: WebGatewayRunTime
    Allow extension path to execute: Select
    Select OK
Mapping the CSP File Extensions
Choose one of the following configuration methods:
  1. Serve all content (including static content) from InterSystems IRIS. Map * to the Web Gateway. Follow the file map procedure in the section “Registering Additional File Types with CSP” in this book.
  2. Serve static content from the web server. Map only files of type .csp, .cls, .zen, .cxw to the Web Gateway.
If you are serving static files from the web server, map the CSP file extensions to the Web Gateway ISAPI extensions as follows:
Extension Binary
*.csp C:\Inetpub\CSPGateway\CSPms.dll
*.cls C:\Inetpub\CSPGateway\CSPms.dll
*.zen C:\Inetpub\CSPGateway\CSPms.dll
*.cxw C:\Inetpub\CSPGateway\CSPms.dll
  1. Open the Internet Information Services (IIS) Manager window.
  2. In the left panel expand the top level to reveal the Web Sites section, then the Default Web Site section. Highlight the Default Web Site section:
    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
    Note:
    This activates CSP for the whole web site. To restrict the use of CSP to specific virtual sub-directories (such as /csp/) focus control on the appropriate subdirectory (under Default Web Site) before creating the mappings. Repeat the process for each virtual subdirectory from which CSP content is to be served.
  3. In the middle panel, double-click the Handler Mappings icon.
  4. In the right panel, select Add Script Map.
  5. In the Add Script Map dialogue, enter:
    Request Path: *.csp
    Executable: C:\Inetpub\CSPGateway\CSPms.dll
    Name: WebGateway_csp
  6. Select Request Restrictions.
    Clear: Invoke handler only if request is mapped to
    Select OK to return to Add Script Map dialogue.
    Select OK.
  7. At this point you may be prompted as follows:
    “Would you like to enable this ISAPI extension? If yes, we add your extension as an “Allowed” entry in the ISAPI and CGI Restrictions list. If the extension already exists we allow it.”
    Select Yes.
    You can later find the list of allowed applications as follows:
    In the left panel, highlight:
    [MACHINE_NAME] ([machine_name]\[user_name])
    In the middle panel, double-click ISAPI and CGI Restrictions.
    If the Web Gateway ISAPI components are not included in the list of allowed applications, add them.
    You can add text of your own choice in the Description field. For example:
    WebGatewayManagement for CSPmsSys.dll
    WebGatewayRunTime for CSPms.dll
  8. Repeat the above process: Use the Add Script Map dialogue to enter the following two mappings:
    Request Path: *.cls
    Executable: C:\Inetpub\CSPGateway\CSPms.dll
    Name: WebGateway_cls
    Request Path: *.zen
    Executable: C:\Inetpub\CSPGateway\CSPms.dll
    Name: WebGateway_zen
    Request Path: *.cxw
    Executable: C:\Inetpub\CSPGateway\CSPms.dll
    Name: WebGatewayManagement
Operating and Managing the Web Gateway
To access the Web Gateway’s systems management suite, point your browser at one of the following locations:
http://<ip_address>/csp/bin/Systems/Module.cxw
http://<ip_address>/csp/bin/CSPmsSys.dll
The CSP engine is automatically invoked for requested files that contain a .csp, .cls, or .zen extension. For example:
http://<ip_address>/csp/samples/menu.csp
If you see an unauthorized user error message, refer to the section “Web Gateway and Security.”
Alternative Option 2: Using a Native Module with the NSD (CSPcms.dll)
IIS 7 does not, by default, run ISAPI extensions, ISAPI filters, or CGI modules. This option requires the CGI modules service for running the Web Gateway Management module (nph-CSPcgiSys.exe).
Follow the instructions in the section for installing the CGI service, Installing the ISAPI and CGI Services (If Required.
Configure the web server so that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the Web Gateway for processing.
Registering the Runtime Native Module
DLL: CSPcms.dll
Before this module can be used it must be registered with IIS. This is done in the Internet Information Services (IIS) Manager control panel.
  1. Open the Internet Information Services (IIS) Manager window.
  2. In the left panel, highlight:
    [MACHINE_NAME] ([machine_name]\[user_name])
  3. In the middle panel, double-click the Modules icon.
  4. In the right panel, select Add Native Module.
  5. Select Register and enter the following details in the Register Native Module dialogue:
    Name: CSPcms
    Path: C:\Inetpub\CSPGateway\CSPcms.dll
    Select OK.
  6. In the left panel expand the top level to reveal the Web Sites section, then the Default Web Site section. Highlight the Default Web Site section:
    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
  7. In the right panel, select Add Native Module.
  8. In the Add Native Module dialogue select CSPcms then select OK.
Enabling the CGI module for Web Gateway Management
Executable: nph-CSPcgiSys.exe
Before this module can be used it must be registered with IIS as being an Allowed application. This is done in the Internet Information Services (IIS) Manager control panel.
  1. Open the Internet Information Services (IIS) Manager.
  2. In the left panel, highlight:
    [MACHINE_NAME] ([machine_name]\[user_name])
  3. In the middle panel, double-click the ISAPI and CGI Restrictions icon.
  4. In the right panel, select Add.
  5. In the Add ISAPI or CGI Restriction dialogue, enter:
    ISAPI or CGI Path: C:\Inetpub\CSPGateway\nph-CSPcgiSys.exe
    Description: WebGatewayManagement
    Allow extension path to execute: Select
    Select OK.
Mapping the CSP File Extensions
Note:
Do NOT use Add Wildcard Script Mapping utility for this file extension mapping process; it gives you an error! Instead, use the utility called Add Module Mapping for *.
Choose one of the following configuration methods:
  1. Serve all content (including static content) from InterSystems IRIS. Map * to the Web Gateway. If you are configuring the web application so that the InterSystems IRIS server serves all static files, then follow the file map procedure in the section “Registering Additional File Types with CSP” in this book.
  2. Serve static content from the web server.
    Map only files of type .csp, .cls, .zen, .cxw to the Web Gateway.
If you are serving static files from the web server, map the CSP file extensions to the Web Gateway Modules as follows:
Extension Native Module Binary
*.csp CSPms C:\Inetpub\CSPGateway\CSPms.dll
*.cls CSPms C:\Inetpub\CSPGateway\CSPms.dll
*.zen CSPms C:\Inetpub\CSPGateway\CSPms.dll
*.cxw   C:\Inetpub\CSPGateway\nph-CSPcgiSys.exe
  1. Open the Internet Information Services (IIS) Manager window.
  2. In the left panel, expand the top level to reveal the Web Sites section, then the Default Web Site section. Highlight the Default Web Site section:
    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
    Note:
    This activates CSP for the whole web site. To restrict the use of CSP to specific virtual sub-directories (such as /csp/) focus control on the appropriate subdirectory (under Default Web Site) before creating the mappings. Repeat the process for each virtual subdirectory from which CSP content is to be served.
  3. In the middle panel, double-click the Handler Mappings icon.
  4. In the right panel, select Add Module Mapping.
  5. In the Add Module Mappings dialogue, enter:
    Request Path: *.csp
    Module: Select CSPcms
    Name: WebGateway_csp
  6. Select Request Restrictions.
    Clear: Invoke handler only if request is mapped to
    Select OK to return to the Add Module Mappings dialogue.
    Select OK.
  7. Repeat the above process to add the following Module Mappings:
    Request Path: *.cls
    Module: Select CSPcms
    Name: WebGateway_cls
    and
    Request Path: *.zen
    Module: Select CSPcms
    Name: WebGateway_zen
  8. In the left panel, highlight the Default Web Site section:
    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
  9. In the middle panel, double-click the Handler Mappings icon.
  10. In the right panel, select Add Script Map.
  11. In the Add Script Map dialogue, enter:
    Request Path: *.cxw
    Executable: C:\Inetpub\CSPGateway\nph-CSPcgiSys.exe
    Name: WebGatewayManagement
  12. Select Request Restrictions.
    Clear: Invoke handler only if request is mapped to
    Select OK to return to the Add Script Map dialogue.
    Select OK.
  13. You may be prompted as follows: “Would you like to enable this ISAPI extension? If yes, we add your extension as an “Allowed” entry in the ISAPI and CGI Restrictions list. If the extension already exists we allow it.”
    Select Yes.
    You can later find the list of allowed applications as follows:
    In the left panel, highlight:
    [MACHINE_NAME] ([machine_name]\[user_name])
    In the center panel, double-click the ISAPI and CGI Restrictions icon.
    If the Web Gateway Management CGI module is not included in the list of allowed applications, add it.
    You can add text of your own choice in the Description field. For example:
    WebGatewayManagement for nph-CSPcgiSys.exe
Operating and Managing the Web Gateway
This connectivity option depends on the Web Gateway’s network service daemon (NSD).
Start the CSP NSD as described in the section, Starting the NSD.
To access the Web Gateway’s Systems Management suite, point your browser at one of the following locations:
http://<ip_address>/csp/bin/Systems/Module.cxw
http://<ip_address>/csp-bin/nph-CSPcgiSys
The CSP engine is automatically invoked for requested files that contain a .csp, .cls, or .zen extension. For example:
http://<ip_address>/csp/samples/menu.csp
If you see an unauthorized user error message, refer to the section Web Gateway and Security.
Alternative Option 3: Using an ISAPI Module with the NSD (CSPcms.dll)
Use this option if your Web Gateway DLLs are unable to support the Native Module interface (Alternative Option 2).
IIS 7 does not, by default, run ISAPI extensions, ISAPI filters or CGI modules. This option requires both the ISAPI extensions and the CGI modules service.
Follow the instructions in the section for installing the CGI service, Installing the ISAPI and CGI Services.
The web server should be configured such that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the Web Gateway for processing.
Enabling the Runtime ISAPI Extension
DLLs: CSPcms.dll
Before this extension can be used it must be registered with IIS as being “Allowed” applications. This is done in the Internet Information Services (IIS) Manager control panel.
  1. Open the Internet Information Services (IIS) Manager window.
  2. In the left panel, highlight: [MACHINE_NAME] ([machine_name]\[user_name])
  3. In the middle panel, double-click the ISAPI and CGI Restrictions icon.
  4. In the right panel, select Add.
  5. In the Add ISAPI or CGI Restriction dialogue, enter:
    ISAPI or CGI Path: C:\Inetpub\CSPGateway\CSPcms.dll
    Description: WebGatewayRunTime
    Allow extension path to execute: Select
    Select OK
Enabling the CGI module for Web Gateway Management
Executable: nph-CSPcgiSys.exe
Before this module can be used it must be registered with IIS as being an “Allowed” application. This is done in the Internet Information Services (IIS) Manager control panel.
  1. Open the Internet Information Services (IIS) Manager window.
  2. In the left panel, highlight: [MACHINE_NAME] ([machine_name]\[user_name])
  3. In the middle panel, double-click the ISAPI and CGI Restrictions icon.
  4. In the right panel, select Add.
  5. In the Add ISAPI or CGI Restriction dialogue, enter:
    ISAPI or CGI Path: C:\Inetpub\CSPGateway\nph-CSPcgiSys.exe
    Description: WebGatewayManagement
    Allow extension path to execute: Select
    Select OK.
Mapping the CSP File Extensions
Choose one of the following configuration methods:
  1. Serve all content (including static content) from InterSystems IRIS. Map * to the Web Gateway. If you are configuring the web application in InterSystems IRIS so that the InterSystems IRIS server serves all static files, then follow the file map procedure in the section “Registering Additional File Types with CSP” in this book.
  2. Serve static content from the web server.
    Map only files of type .csp, .cls, .zen, .cxw to the Web Gateway.
If you are serving static files from the web server, map the CSP file extensions to the Web Gateway Modules as follows:
Extension Binary
*.csp C:\Inetpub\CSPGateway\CSPcms.dll
*.cls C:\Inetpub\CSPGateway\CSPcms.dll
*.zen C:\Inetpub\CSPGateway\CSPcms.dll
*.cxw C:\Inetpub\CSPGateway\nph-CSPcgiSys.exe
  1. Open the Internet Information Services (IIS) Manager window.
  2. In the left panel, expand the top level and expand Web Sites. Highlight Default Web Site.
    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
    Note:
    This activates CSP for the whole web site. To restrict the use of CSP to specific virtual sub-directories (such as /csp/) focus control on the appropriate subdirectory (under Default Web Site) before creating the mappings. Repeat the process for each virtual subdirectory from which CSP content is to be served.
  3. In the middle panel, double-click Handler Mappings.
  4. In the right panel, select Add Script Map.
  5. In the Add Script Map dialogue, enter:
    Request Path: *.csp
    Executable: C:\Inetpub\CSPGateway\CSPcms.dll
    Name: WebGateway_csp
  6. Select Request Restrictions.
    Clear: Invoke handler only if request is mapped to
    Select OK to return to the ‘Add Script Map’ dialogue.
    Select OK.
  7. At this point you may be prompted as follows:
    “Would you like to enable this ISAPI extension? If yes, we add your extension as an “Allowed” entry in the ISAPI and CGI Restrictions list. If the extension already exists we allow it.”
    Select Yes.
    You can later find the list of allowed applications as follows:
    In the left panel, highlight:
    [MACHINE_NAME] ([machine_name]\[user_name])
    In the middle panel, double-click the ISAPI and CGI Restrictions icon.
    If the Web Gateway ISAPI module is not included in the list of allowed applications, add it.
    You can add text of your own choice in the Description field. For example:
    WebGatewayRunTime for CSPcms.dll
    WebGatewayManagement for nph-CSPcgiSys.exe
  8. Repeat the above process: Use the Add Script Map dialogue to enter the following two mappings:
    Request Path: *.cls
    Executable: C:\Inetpub\CSPGateway\CSPcms.dll
    Name: WebGateway_cls
    Request Path: *.zen
    Executable: C:\Inetpub\CSPGateway\CSPcms.dll
    Name: WebGateway_zen
    Request Path: *.cxw
    Executable: C:\Inetpub\CSPGateway\nph-CSPcgiSys.exe
    Name: WebGatewayManagement
Operating and Managing the Web Gateway
This connectivity option depends on the Web Gateway’s network service daemon (NSD).
  1. Start the CSP NSD as described in the section dedicated to this service.
To access the Web Gateway’s Systems Management suite, point your browser at one of the following locations:
http://<ip_address>/csp/bin/Systems/Module.cxw
http://<ip_address>/csp-bin/nph-CSPcgiSys
The CSP engine is automatically invoked for requested files that contain a .csp, .cls, or .zen extension. For example:
http://<ip_address>/csp/samples/menu.csp
If you see an unauthorized user error message, refer to the section “Web Gateway and Security.”
Alternative Option 4: Using the CGI Modules with the NSD (nph-CSPcgi*.exe)
In most cases, the all-inclusive Native Module-based solution (the Recommended Option) is the option of choice, and is the implementation that gives the best performance. The CGI/NSD hybrid is useful for cases where it is necessary, for operational reasons, to manage the Web Gateway independently of the hosting web server. For example, if multiple instances of the web server are to share the same Web Gateway installation. In option 1 each instance of the core web server process binds to its own instance of the Web Gateway.
Another factor in choosing this approach might be that the in-house requirements of your web master (or ISP) dictate that all web server extensions are implemented using the CGI protocol.
IIS 7 does not, by default, run ISAPI extensions, ISAPI filters or CGI modules. This option requires the CGI modules service.
Follow the instructions in the section for installing the CGI service, Installing the ISAPI and CGI Services.
Configure the web server so that it recognizes CSP requests (files of type .csp, .cls, and .zen) and passes them to the Web Gateway for processing.
Enabling the CGI Modules
Executables: nph-CSPcgi.exe and nph-CSPmsSys.exe
Before these modules can be used they must be registered with IIS as being “Allowed” applications. This is done in the Internet Information Services (IIS) Manager control panel.
  1. Open the Internet Information Services (IIS) Manager window.
  2. In the left panel, highlight:
    [MACHINE_NAME] ([machine_name]\[user_name])
  3. In the middle panel, double-click the ISAPI and CGI Restrictions icon.
  4. In the right panel, select Add.
  5. In the Add ISAPI or CGI Restriction dialogue, enter:
    ISAPI or CGI Path: C:\Inetpub\CSPGateway\nph-CSPcgi.exe
    Description: WebGatewayRunTime
    Allow extension path to execute: Select
    Select OK.
  6. Repeat the above steps for nph-CSPcgiSys.exe, entering the following details in the Restrictions dialogue:
    ISAPI or CGI Path: C:\Inetpub\CSPGateway\nph-CSPcgiSys.exe
    Description: WebGatewayManagement
    Allow extension path to execute: Select
Mapping the CSP File Extensions
Choose one of the following configuration methods:
  1. Serve all content (including static content) from InterSystems IRIS. Map * to the Web Gateway. If you are configuring the web application in InterSystems IRIS so that the InterSystems IRIS server serves all static files, then follow the file map procedure in the section “Registering Additional File Types with CSP” in this book.
  2. Serve static content from the web server.
    Map only files of type .csp, .cls, .zen, .cxw to the Web Gateway.
If you are serving static files from the web server, map the CSP file extensions to the Web Gateway CGI Modules as follows:
Extension Binary
*.csp C:\Inetpub\CSPGateway\nph-CSPcgi.exe
*.cls C:\Inetpub\CSPGateway\nph-CSPcgi.exe
*.zen C:\Inetpub\CSPGateway\nph-CSPcgi.exe
*.cxw C:\Inetpub\CSPGateway\nph-CSPcgiSys.exe
  1. Open the Internet Information Services (IIS) Manager window.
  2. In the left panel expand the top level to reveal the Web Sites section, then the Default Web Site section. Highlight the Default Web Site section:
    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
    Note:
    This activates CSP for the whole web site. To restrict the use of CSP to specific virtual sub-directories (such as /csp/) focus control on the appropriate subdirectory (under Default Web Site) before creating the mappings. Repeat the process for each virtual subdirectory from which CSP content is to be served.
  3. In the middle panel, double-click the Handler Mappings icon.
  4. In the right panel, select Add Script Map.
  5. In the Add Script Map dialogue, enter:
    Request Path: *.csp
    Executable: C:\Inetpub\CSPGateway\nph-CSPcgi.exe
    Name:WebGateway_csp
  6. Select Request Restrictions.
    Clear: Invoke handler only if request is mapped to
    Select OK to return to the Add Script Map dialogue.
    Select OK.
  7. At this point you may be prompted as follows: “Would you like to enable this ISAPI extension? If yes, we add your extension as an “Allowed” entry in the ISAPI and CGI Restrictions list. If the extension already exists we allow it.”
    Select Yes.
  8. You can later find the list of allowed applications as follows:
    In the left panel, highlight:
    [MACHINE_NAME] ([machine_name]\[user_name])
    In the middle panel, double-click the ISAPI and CGI Restrictions icon.
    If the Web Gateway CGI components are not included in the list of allowed applications, add them.
    You can add text of your own choice in the Description field. For example:
    WebGatewayManagement for nph-CSPcgiSys.exe
    WebGatewayRunTime for nph-CSPcgi.exe
  9. Repeat the above process: Use the Add Script Map dialogue to enter the following two mappings:
    Request Path: *.cls
    Executable: C:\Inetpub\CSPGateway\nph-CSPcgi.exe
    Name: WebGateway_cls
    Request Path: *.zen
    Executable: C:\Inetpub\CSPGateway\nph-CSPcgi.exe
    Name: WebGateway_zen
    Request Path: *.cxw
    Executable: C:\Inetpub\CSPGateway\nph-CSPcgiSys.exe
    Name: WebGatewayManagement
Operating and Managing the Web Gateway
This connectivity option depends on the Web Gateway’s network service daemon (NSD).
  1. Start the CSP NSD as described in the section dedicated to this service.
To access the Web Gateway’s Systems Management suite, point your browser at one of the following locations:
http://<ip_address>/csp/bin/Systems/Module.cxw
http://<ip_address>/csp-bin/nph-CSPcgiSys
The CSP engine is automatically invoked for requested files that contain a .csp, .cls, or .zen extension. For example:
http://<ip_address>/csp/samples/menu.csp
If you see an unauthorized user error message, refer to the section “Web Gateway and Security”.
Alternative Options for Windows Apache
This section contains information for installations with Apache web servers on Microsoft Windows. Read the sections that apply to your installation.
Note:
If you are using Apache 2.2 or earlier: If you use the directions in this section, you add text to the end of the httpd.conf file. The text added specifying access control needs to be different for Apache 2.4 or Apache 2.2 (and earlier). If you are using Apache 2.4, use the text shown in this section. If you are using Apache 2.2, replace the following phrases in the httpd.conf sections. Replace Require all denied, with the line Deny from all. Replace Require all granted with the two lines Order allow,deny and Allow from all. If you require more information, see http://httpd.apache.org/docs/2.4/upgrading.html
Install Locations
The following modules are installed:
Note:
There are separate binaries for Apache Version 2.4.x are shown below:
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 file (CSP.ini) and Event Log (CSP.log) 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 CSP requests (files of type .csp, .cls, and .zen) 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 file types representing CSP content, .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.
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
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 /iris/csp/bin/CSPa24.dll
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 the CSP engine 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 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, 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
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
    <LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
                    SetHandler csp-handler
    </LocationMatch>
    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. Optional step, if required: The above configuration block expects that the Regular Expressions (regex) processor is available to the Apache environment. If this is not the case, which can happen particularly with Windows systems, CSP files are not served (File not found errors are returned). To remedy this situation, replace the following configuration block:
    <LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
                    SetHandler csp-handler
    </LocationMatch>
    with:
    CSPFileTypes csp cls zen
  3. Restart Apache after making changes to httpd.conf.
Registering additional file types with CSP
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, .css, and .js.
The following directive can be used to map requests for all files to CSP 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 to CSP 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, 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
Alternative Option 3: Apache and ISAPI Modules (CSPms.dll)
Note:
This connectivity option is superseded by the stand-alone API modules described in the Recommended Option and should not be used. It is documented here as a reference for legacy systems that have used it in the past.
The Apache Group provides a module that attempts to emulate Microsoft’s ISAPI interface. If Apache is configured to use this module then ISAPI extensions may be run. However, there are significant differences between the Apache Group ISAPI interface and Microsoft’s original. The most troublesome feature of the Apache ISAPI module is that it unloads its ISAPI extensions (DLLs) after servicing each and every request. This behavior is unacceptable for CSP because the Web Gateway relies on its ISAPI DLLs remaining in memory in order for it to manage a persistent pool of connections to InterSystems IRIS.
The modified ISAPI module supplied with CSP allows the Web Gateway’s ISAPI extensions to remain loaded between requests. The modifications only affect the Web Gateway’s ISAPI DLLs; all other ISAPI DLLs are subject to the original Apache Group’s functionality.
Rebuilding the Apache Executable
  1. Upgrade the Apache ISAPI module (mod_isapi.c)
    Overwrite the Apache Group’s ISAPI module with the version contained in the CSP distribution:
    C:\Program Files\Apache Group\Apache\src\os\win32\mod_isapi.c
  2. Rebuild the Apache executable
    In order to perform this step you need version 5.0 (or later) of the Microsoft C Compiler (Microsoft Visual C++).
    Change to the following directory:
    C:\Program Files\Apache Group\Apache\src\os\win32\mod_isapi.c
    Build Apache with:
    nmake /f Makefile.nt installr INSTDIR=d:\progra~1\apache~1\apache
    You can safely ignore the many warning messages that the build process displays.
  3. Runtime configuration
    Edit the Apache configuration file httpd.conf. For the standard Apache distribution this file is in:
    C:\Program Files\Apache Group\Apache\conf
    Assuming that you wish to invoke the CSP engine for requested files that contain a .csp, .cls, or .zen extension, add the following section to the end of httpd.conf:
    AddHandler isapi-isa dll
    AddHandler isapi-isa csp
    AddHandler isapi-isa cls
    AddHandler isapi-isa zen
    AddHandler isapi-isa 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>
    </Directory>
    Alias /csp/bin/Systems/Module.cxw 
    /csp/bin/CSPmsSys.dll
    
  4. Restart Apache after making changes to httpd.conf.
Operating and Managing the Web Gateway with Apache and ISAPI
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/CSPmsSys.dll
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
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
<Location "/csp/bin/Systems/">
    SetHandler csp-handler-sa
</Location>
<Location "/csp/bin/RunTime/">
    SetHandler csp-handler-sa
</Location>
CSPFileTypes csp cls zen cxw
Configuration for Atypical 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 Atypical Option 3: Apache API Module with NSD (mod_csp24.dll)
LoadModule csp_module \
    C:/Program Files/Apache Group/Apache/modules/mod_csp24.dll
<LocationMatch "/*\.([Cc][Ss][Pp]|[Cc][Ll][Ss]|[Zz][En][Nn])$">
    SetHandler csp-handler
</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"
Configuration for Atypical 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


Previous section           Next section
Send us comments on this page
View this book as PDF   |  Download all PDFs
Copyright © 1997-2019 InterSystems Corporation, Cambridge, MA
Content Date/Time: 2019-08-23 05:35:26