Skip to main content

Configuring IIS to Work With the Web Gateway (Windows)

This article describes how to configure an existing Microsoft IIS web server for use with the InterSystems Web Gateway. (On Windows, the other options are Apache and Nginx; options are different on other operating systems.)

When you install the Web Gateway using the Web Gateway standalone installer, you can select the option to automatically configure an existing Microsoft IIS web server. If you do not choose this option, you can configure your web server manually as described in this article.

Common Steps (All Versions)

If you are using IIS as your web server, follow these steps to configure your web server.

  1. Set permissions for the Web Gateway components.

  2. Configure the web application path.

  3. Enable URLs with /bin.

Then if you are using IIS 7 or later, see Microsoft IIS 7. If you have an atypical configuration, see Alternative Options for IIS 7 or Later.

Setting Permissions for the Web Gateway Components

Regardless of which Web Gateway configuration option you choose, you need to assign appropriate permissions to web resources held outside the standard IIS documents root (for example, C:\inetpub\wwwroot).

IIS 7 does not, by default, allow the user of a web application to access anything outside the scope of the pre-configured documents root unless you assign Read & Execute and Write permissions for those external resources to the following user or groups:

[machine_name]\IIS_IUSRS

And:

[machine_name]\Users

Note that IIS_IUSRS represents the user (group) under which IIS worker processes operate. It replaces the IUSR_[machine_name] user group found in IIS versions earlier than version 7. Applications controlled through IIS (such as the Web Gateway) operate with the level of privilege assigned to IIS_IUSRS.

For CSP, resources external the web server's root usually include the following:

Web Gateway binary components:

C:\Inetpub\CSPGateway

Static file components:

install-dir\CSP\

Permissions can be manually assigned to these folders via Windows Explorer as follows:

  1. Right select the folder name and select Properties.

  2. Select the Security tab.

  3. Select Edit.

  4. Select Add.

  5. In the Enter the object names to select text box enter:

    [machine_name]\IIS_IUSRS

  6. Select Check Names and OK.

  7. Select [machine_name]\IIS_IUSRS in the Group or Usernames window, then:

  8. Assign Read & Execute and Write permissions in the Permissions window.

  9. Select Apply and OK.

  10. Repeat the above process for the [machine_name]\Users user group.

The IIS user group requires full read and write permissions for the Web Gateway configuration and log files. For example, at the Windows command prompt, enter:

cacls CSP.ini /E /G IIS_IUSRS:F

cacls CSP.log /E /G IIS_IUSRS:F

Of course, this can also be done via Windows Explorer.

Configuring the Web Application Path

This section describes the procedure for configuring the web application path (such as csp) for IIS. These procedures are common to all Web Gateway configuration options for IIS.

IIS is configured in the Internet Information Services (IIS) Manager control panel. Subdirectories configured under the documents root can be classed as either Virtual or Applications. Virtual subdirectories (or aliases) are mapped to physical equivalents (Windows directories). The same applies to subdirectories classed as Applications except that, in addition to defining the physical equivalent, you can associate the application with a particular application pool. The default is DefaultAppPool.

Since web applications are served through the Web Gateway, the hosting subdirectories (such as /csp) should be configured as Applications.

In a default CSP configuration, the /csp application path is mapped to the physical location install-dir\CSP. All the static files are located under this root (\csp\broker…).

  1. Open the Internet Information Services (IIS) Manager.

  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
  3. In the right panel, select View Applications.

  4. Again in the right panel, select Add Application.

  5. In the Add Application dialog, enter:

    Alias: csp

    Physical path: install-dir\CSP\

  6. Select OK.

If you are using a Web Gateway solution based on an alternative option, set up an application called /bin under the /csp application. Map this to the physical directory holding the Web Gateway binaries. For example:

Map application /csp/bin to C:\Inetpub\CSPGateway

Enabling URLs with /bin

If you installed the Web Gateway using the InterSystems IRIS installer, this step was done automatically for you. If you are installing the Web Gateway manually, you need to do this step. (See this external web site for more details and alternative ways to accomplish this https://weblogs.asp.net/owscott/iis7-blocks-viewing-access-to-files-in-bin-and-other-asp-net-folders.) To enable URLs that contain /bin, add the following location tag to your applicationHost.config file:

<location path="sitename.com/subfolder/bin/debug">
    <system.webServer>
        <security>
           <requestFiltering>
              <hiddenSegments>
                 <remove segment="bin" />                    
               </hiddenSegments>
           </requestFiltering>
        </security>
     </system.webServer>
 </location>

Restarting IIS

This section describes what happens when IIS is restarted via the various control panels.

Most configuration changes can be made in real-time to an active IIS installation. However, the Internet Information Services (IIS) Manager control panel provides stop, start, and restart options. These are useful for the refreshing the web server configuration but does not result in an active Web Gateway installation being reinitialized (the Web Gateway DLLs are not reloaded).

To force IIS to restart, so that the Web Gateway modules are reloaded, then restart the World Wide Web Publishing service via the main Windows Services control panel.

Troubleshooting

This section describes problems that commonly occur in configuring third-party modules (both Native and ISAPI) to work with IIS.

The most common problem likely to be encountered is that, after reconfiguring, requests to IIS fail with the following error:

Service Unavailable

HTTP Error 503. The service is unavailable.

This usually indicates that the default Application Pool has terminated.

  1. Open the Internet Information Services (IIS) Manager window.

  2. In the left panel expand the top level to reveal the Application Pools section.

    [MACHINE_NAME] ([machine_name]\[user_name])

    Application Pools

  3. Check that the Default Application Pool (DefaultAppPool), or whatever application pool your server is configured to use, is marked with a Status of Started.

  4. Restart the application pool if necessary (using the options in the right panel).

  5. If problems persist, look for clues in the main Windows Event Log (in the Applications section). In particular, check for the following error message:

    Failed to find the RegisterModule entrypoint in the module DLL C:\Inetpub\CSPGateway\CSPms.dll. The data is the error.

    This, for example, indicates that the version of Web Gateway DLLs that you are using do not implement the Native Modules interface. Either obtain later DLLs from InterSystems or configure the Web Gateway to work through the conventional ISAPI interface.

As with all software, restarting often clears transient problems: To completely restart IIS, restart the World Wide Web Publishing service via the main Windows Services control panel.

Do not use the Add Wildcard Script Map utility to map file extensions. If you do, you may see this error: The specified module required by the handler is not in the modules list. If you are adding a script map handler mapping, the IsapiModule or the CgiModule must in the modules list. Instead use Add Module Mapping for * to map file extensions using a wildcard.

If URLs with /bin in them do not work, see Manual Step for Enabling URLs with /bin

Additional Steps: Microsoft IIS 7 or Later

The Microsoft ISAPI extensions (CSPms.dll, CSPmsSys.dll and CSPcms.dll) have been adapted such that they can work directly to the Native Modules interface in IIS 7 and later.

The Web Gateway modules supplied with InterSystems IRIS can work with the Native Modules in IIS 7. They can also be used with ISAPI extensions. There are additional configuration options for customers who are using the NSD. This section describes how to configure your IIS 7 web server to work with the Native Modules. For other configurations, see Alternative Options for IIS 7 or Later.

Install Locations for IIS 7

Install the Web Gateway components and the CSP static files as follows:

  1. The default location for the Native Modules

    • CSPms.dll (Runtime module)

    • CSPmsSys.dll (Systems Management module)

    The default location for these modules is:

    C:\Inetpub\CSPGateway

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

  2. HyperEvents Components

    • CSPBroker.js

    • CSPxmlhttp.js

    The default location for these files is:

    install-dir\csp\broker

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

    install-dir\csp\sys

Recommended Option: Using Native Modules (CSPms*.dll)

This is the recommended and most-used configuration option. It uses the Native Modules interface introduced with IIS 7. This option provides the best performance.

For other configuration options, see Alternative Options for IIS 7 or Later (Windows) and Using the NSD (Windows).

Register the Native Modules and configure the web server so that it recognizes InterSystems file types and passes them to the Web Gateway for processing. Include any additional files that might be required for your installation (such as, for example, special CSP resources needed for analytics).

Registering the Native Modules

DLLs: CSPms.dll and CSPmsSys.dll

Before these modules can be used they 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 (or Configure Native Modules). The precise wording depends on the build of IIS in use.

  5. Select Register and enter the following in the Register Native Module dialog:

    Name: CSPms

    Path: C:\Inetpub\CSPGateway\CSPms.dll

    Select OK.

  6. In the left panel, expand the top level and expand Web Sites, and Default Web Site. Highlight Default Web Site:

    [MACHINE_NAME] ([machine_name]\[user_name])
                Web Sites
                        Default Web Site
  7. In the right panel, select Add Native Module.

  8. Select CSPms and select OK.

Mapping InterSystems IRIS File Extensions

Note:

Do not use Add Wildcard Script Mapping utility for this file extension mapping process; it gives an error. Instead, use the utility called Add Module Mapping for *.

Map the InterSystems file types to the Web Gateway native 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 CSPms C:\Inetpub\CSPGateway\CSPms.dll
  1. Open the Internet Information Services (IIS) Manager window.

  2. In the left panel, expand the top level and expand Web Sites, then the Default Web Site section. 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 the Handler Mappings icon.

  4. In the right panel, select Add Module Mapping.

  5. In the Add Module Mappings dialog, enter the following details:

    Request Path: *.csp

    Module: (select CSPms from the dropdown)

    Name: WebGateway_csp

  6. Select Request Restrictions and ensure that the box is not checked next to Invoke handler only if request is mapped to. This action sets the value of Path Type to Unspecified, as shown in the Handler Mappings table.

  7. Select OK to return to the Add Module Mappings dialog and select OK again.

  8. Repeat the above process to add the following Module Mappings:

    Request Path: *.cls

    Module: (select CSPms from the list)

    Name: WebGateway_cls

    Request Path: *.zen

    Module: (select CSPms from the list)

    Name: WebGateway_zen

    Request Path: *.cxw

    Module: (select CSPms from the list)

    Name: WebGatewayManagement

Mapping Additional File Types

To configure the web server to send additional file types to the Web Gateway, add configuration entries similar to the default ones for the additional file extensions. For example:

Extension Native Module Binary
*.xxx CSPms C:\Inetpub\CSPGateway\CSPms.dll

iIf you need to serve other static files through the Web Gateway, add mappings for the needed file types so that those files can be loaded. In particular, if you need to access the Management Portal through this web server, add mappings for file types .jpg, .gif, .png, .css, and .js. If you do not do so, the Management Portal will be missing its images, its Javascript, and its stylesheets.

To configure the web server to send all requests for a given path, set up the following wildcard entry for that path:

Extension Native Module Binary
* CSPms C:\Inetpub\CSPGateway\CSPms.dll

Operating and Managing the Web Gateway

To access the Web Gateway’s systems management suite, point your browser at the following location:

http://<ip_address>/csp/bin/Systems/Module.cxw

If you see an unauthorized user error message, see the security notes in Web Gateway and Security.

Configuring IIS to Return SOAP Fault Details

An InterSystems IRIS web service that encounters an error may return an HTTP 500 error without the associated SOAP fault details. By default, IIS returns extended error information only to local clients. However, you can modify this behavior in the <httpErrors> element within the configuration file web.config. To do so, add the following section to instruct IIS to dispatch detailed error information to all clients.

<configuration>
    <system.webServer>
       <httpErrors errorMode="Detailed" />
    </system.webServer>
</configuration>

Use caution with this approach as sensitive information about the hosting environment may be revealed to clients. An alternative approach that avoids the security concerns of using errorMode="Detailed” is to instead use the existingResponse="PassThrough" directive.

<configuration>
    <system.webServer>
       <httpErrors existingResponse="PassThrough" />
    </system.webServer>
</configuration>

Restart IIS after making changes to the configuration.

You can make these changes manually to the IIS web.config file. Or, for a better, less error prone, approach, use the Configuration Editor built into the IIS Manager.

  1. In the IIS Manager, from the Connections panel on the left, select the path which corresponds to the web service. For example: Default Web Site, then csp.

  2. In the middle panel, below the Management heading at the bottom, double-click on Configuration Editor.

  3. In the Configuration Editor dropdown at the top labeled Section, expand system.webServer and click httpErrors.

  4. Click on the value next to existingResponse and use the dropdown to view the options. Select PassThrough.

  5. In the Actions pane on the right, click Apply.

  6. Restart IIS after making changes to the configuration.

Further information about error handling in IIS can be found at:

https://docs.microsoft.com/en-us/iis/configuration/system.webServer/httpErrors/

Feedback