Microsoft Internet Information Services (IIS) for Windows

Enable IIS

To enable IIS:

1. Open the Windows Features manager by searching for Turn Windows features on or off, or by opening the Control Panel and selecting Programs > Programs and Features > Turn Windows Features on or off.

2. Select Internet Information Services.

3. To enable redirection of documentation links, HTTP Redirection must also be enabled within IIS. To enable it, ensure that Internet Information Services > World Wide Web Service > Common HTTP Features > HTTP Redirection is selected.

4. To enable debugging sessions in a supported IDE, the WebSocket Protocol must also be enabled within IIS. To enable it, ensure that Internet Information Services > World Wide Web Service > Application Development Features > WebSocket Protocol.

5. Select OK.

If you would like the installer to automatically configure a new or upgraded InterSystems IRIS instance to serve its web applications over IIS, IIS must be enabled prior to installation. However, the HTTP Redirection and WebSocket Protocol features of IIS can be enabled at any time.

Set Permissions for the Web Gateway Components

By default, IIS does not allow the user of a web application access to anything outside of the web document root directory (usually C:\Inetpub\wwwroot). To provide access to web application resources located in a directory outside of the web document root, the following user groups must possess Read, Write, and Execute permissions for the directory:

• [machine_name]\IIS_IUSRS, the user group under which IIS worker processes and applications controlled through IIS (such as the Web Gateway) operate.

• [machine_name]\Users

You must manually set these permissions for the Web Gateway directory (usually C:\Inetpub\CSPGateway) and for any directory containing static files which a web application serves. To do so:

1. In the Windows File Explorer, navigate to the directory’s parent directory. For example: if you are configuring the C:\Inetpub\CSPGateway directory, navigate to navigate to C:\Inetpub.

2. Right-click the directory name and select Properties.

3. Select the Security tab.

4. Select Edit.

5. Select Add.

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

   [machine_name]\IIS_IUSRS

7. Select Check Names and OK.

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

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

10. Select Apply and OK.

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

If the Web Gateway configuration file (CSP.ini) or the Web Gateway log file (CSP.log) is located elsewhere within your file system, you must also ensure that the IIS_IUSRS group has full read and write permissions for these files.

Register the Native Modules

Before you can use the Web Gateway Native Modules, you must register them within IIS. To do so:

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

2. Select your localhost connection from the Connections panel.

3. Within the Features View for the connection’s Home page, open (double-click) the Modules feature configuration item.

4. Select the Configure Native Modules... action from the Actions panel.

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

   Name: CSPms (or similar)

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

6. Select OK.

7. Within the Connections panel, expand the contents of your localhost connection to select Sites > Default Web Site.

8. Ensure that the Web Gateway module is enabled:

   1. Within the Features View for the Default Web Site Home page, open (double-click) the Modules feature configuration item.

   2. Select the Configure Native Modules... action from the Actions panel.

   3. Within the Configure Native Modules dialog, if CSPms appears in the list, select it and then select OK.

Configuring the Web Application Path

For each InterSystems IRIS web application you want to serve, configure its relative path (/csp or /irisinstance2) as an IIS Application.

Note that configuring an IIS Application creates the path mapping which is required to allow the web server to serve static files, provided that the web server has adequate permissions to access the physical path.

For each application path you want to configure, perform the following steps:

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

2. Within the Connections panel, expand the contents of your localhost connection to select Sites > Default Web Site.

3. Select View Applications from the Actions panel.

4. Select Add Application... from the Actions panel.

5. In the Add Application dialog, provide the following information:

   • Alias: the relative base URL path for the application. For example: /irisinstance2 for applications hosted by the instance IRISinstance2, or csp for the application /csp/sys and its sibling applications.

   • Physical path: the directory which contains the static files associated with the application. If you want IIS to serve static files from a different directory for applications with paths subordinate to the application path you are currently configuring, define an IIS Virtual Directory for the child directory.

6. Select OK.

7. If you are finished configuring IIS, restart it to allow configuration changes to take effect.

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. In most cases, this would be a mapping between the application path /csp/bin and the physical path C:\Inetpub\CSPGateway

Set Handler Mappings for Application Requests

For each IIS Application you have configured, direct IIS to invoke the Web Gateway as a handler for some (or all) requests sent to the application path by creating Handler Mappings.

To invoke the Web Gateway as a handler for all requests sent to an application path: follow the steps below to create a Handler Mapping for the Request Path * (wildcard).

To invoke the Web Gateway exclusively for certain file types: follow the steps below for each file type, specifying *.xxx as the Request Path, where xxx is the file extension. To serve InterSystems specific file types, create Handler Mappings for the following request paths: *.csp, *.cls, *.zen, and *.cxw. You must also create Handler Mappings for any static file types you want your application to serve. (Because REST API endpoints are often paths and not files, this file type-specific approach is not sufficient to invoke requests for REST applications.)

Perform the following steps to create a Handler Mapping for an IIS Application:

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

2. Within the Connections panel, expand the contents of your localhost connection and select the name of your Application from the list available within Sites > Default Web Site.

3. Within the Features View for the connection’s Home page, open (double-click) the Handler Mappings feature configuration item.

4. Within the actions panel, select Add Module Mapping....

   Note:

   Do not use the Add Wildcard Script Mapping... action to set the Web Gateway as the handler for all requests at an application path. Attempting to do so yields an error. Instead, add a module mapping for the wildcard (*) character.

5. In the Add Module Mappings dialog, specify the following:

   • Request Path — provide an expression that specifies the set of requests which the Web Gateway should handle. (See the beginning of this section for examples of valid expressions.)

   • Module — from the drop-down menu, select the name you provided for the Web Gateway module (CSPms).

   • Name — provide a descriptive name for this mapping, such as WebGateway_*.

6. Select Request Restrictions and ensure that the box next to Invoke handler only if request is mapped to is cleared (not selected). 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 then select OK again.

8. Repeat the above process to add all desired Handler Mappings for the IIS Application.

9. If you are finished configuring IIS, restart it to allow configuration changes to take effect.

Enable URLs with /bin

By default, IIS does not serve resources from request paths which contain the directory /bin. You must disable this filter to serve the Web Gateway management pages.

If the installer configured the Web Gateway automatically, this step was done automatically for you. If you are installing the Web Gateway manually, you must perform this configuration manually.

The following procedure enables IIS to serve the Web Gateway management pages specifically:

1. Open the applicationHost.config file in a text editor. The file is usually located in the C:\Windows\System32\Inetsrv\Config directory. To find the location of this file on your system:

   1. Select (double-click) the Configuration Editor from the Home page for your localhost connection or any site item within that connection in the Connections panel.

   2. Select Search Configuration... from the Actions panel.

   3. In the Hierarchy View, select ApplicationHost.config (or any of its child items). When you do so, the Configuration Search dialog displays the location of the ApplicationHost.config file.

2. At the end of the <configuration> block (but within it), append the following <Location> tag:

   <location path="localhost/csp/bin/Systems/Module.cxw">
       <system.webServer>
           <security>
              <requestFiltering>
                 <hiddenSegments>
                    <remove segment="bin" />                    
                  </hiddenSegments>
              </requestFiltering>
           </security>
        </system.webServer>
    </location>
   
   

   

3. Save the file.

4. If you are finished configuring IIS, restart it to allow configuration changes to take effect.

Configure the Launcher for Remote Web Server Connections

To enable the InterSystems IRIS launcher to construct valid URLs for an InterSystems IRIS instance’s built-in web, you must specify the connection details for the instance within the InterSystems IRIS Server Manager. These connection details should match your web server configuration. See Define a Remote Server Connection in System Administration Guide.

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. If you are finished configuring IIS, restart it to allow configuration changes to take effect.

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

https://docs.microsoft.com/en-us/iis/configuration/system.webServer/httpErrors/Opens in a new tab

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. However, it does not reinitialize a Web Gateway installation.

When you have made modifications to a Web Gateway installation, restart IIS in one of the following ways:

• Open the Windows Services manager and restart the World Wide Web Publishing service.

• From the command line, run the following command to stop IIS:

  sc stop W3SVC
  

  

  After the web server stops, run the following command to restart it:

  sc start W3SVC
  

  

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