Configure the Microsoft Internet Information Services 7.5 Web Server on a Windows Server 2008 System

To configure the IIS 7.5 Web server on a Windows Server 2008 system:

1. Open Server Manager on the Microsoft IIS Web server host and make sure that the ISAPI Filters and ISAPI Extensions role services are installed.

   Note: If you must install the ISAPI Filters and ISAPI Extensions, make sure that you restart after you install these services.

2. Create a virtual directory named jakarta that points to the IIS scripts directory, as follows:

   1. Select Start > Control Panel > Administrative Tools > Internet Information Services (IIS) Manager.

   2. Under your IIS Web server, create a new (or identify an existing) Web site to integrate with the PPM Server.

   3. In your file system, create a new (or select an existing) directory in which to store integration-related files. In this procedure, this directory is referred to as <ISAPI_REDIRECTOR_HOME>.

      Caution: The <ISAPI_REDIRECTOR_HOME> directory must have run permission.

   4. Copy the workers.properties file, uriworkermap.properties file and <PPM_Home>/integration/webserverplugins/iis/windows/x86-64/isapi_redirect.dll file to the <ISAPI_REDIRECTOR_HOME> directory you created (or selected) in step c of step 2.

   5. Right-click the Web site you created (or identified) in step b of step 2, and then select Add Virtual Directory from the shortcut menu.

   6. In the first Add Virtual Directory window, do the following:

   1. In the Alias box, type the alias name (for example, Jakarta).

   2. Use the Physical path multiselect to navigate to and select the <ISAPI_REDIRECTOR_HOME> directory path.

      Note: An example of this directory is c:\inetpub\scripts. The drive and directory depend on the IIS root directory configuration. This directory must have run permission.

3. If you are using NTLM for user authentication, then do the following:

   1. Start the Internet Information Services (IIS) Manager and access the Error Pages feature.

   2. Right-click error 500, and then select Edit Feature Settings from the shortcut menu.

   3. Set Error Responses to Detailed errors.

   4. Click OK to close the window.

4. Configure both a workers.properties file and a uriworkermap.properties file.

5. Configure IIS to load isapi_redirect.dll as a filter, as follows:

   1. To define registry values for IIS with Apache Jakarta Tomcat Connector (JK):

   1. Add the following registry key:

      HKEY_LOCAL_MACHINE\SOFTWARE\Apache Software Foundation\Jakarta Isapi Redirector\1.0

   2. Add a string named extension_uri and set its value to
      /jakarta/isapi_redirect.dll.

   3. Add a string named worker_file and set its value to the full directory path for the workers.properties file. That is, <ISAPI_REDIRECTOR_HOME>\workers.properties.

      Example:

      C:\inetpub\scripts\workers.properties

   4. Add a string with the name log_level and set its value to ERROR. (For more verbose logging, options include DEBUG and INFO.)

   5. Add a string with the name log_file and set its value to the directory in which you want to save your log file. Include the log file name in the directory path (for example, C:\PPM\isapi.log).

   6. Add a string named worker_mount_file and set its value to the full directory path for the uriworkermap.properties file. That is, <ISAPI_REDIRECTOR_HOME>\uriworkermap.properties.

      Example:

      C:\inetpub\scripts\uriworkermap.properties

   7. Create a file named rewrites.properties in the <ISAPI_REDIRECTOR_HOME> directory

   8. Add a string named rewrite_rule_file to the rewrites.properties file and set its value to the full directory path for the new rewrites.properties file. That is, <ISAPI_REDIRECTOR_HOME>\rewrites.properties.

      Example:

      C:\inetpub\scripts\rew rites.properties

   2. Open Internet Information Services (IIS) Manager, and then do the following:

   1. Select the name of the Web site you created (or identified) in step b of step 2, and then, in the center pane, double-click ISAPI Filters.

   2. In the Actions pane, click Add.

      The Add ISAPI Filter dialog box opens.

   3. In the Filter name box, type a name for the ISAPI filter.

   4. In the Executable box, click the ellipsis button (...), and then navigate to and select the folder that contains the isapi_redirect.dll file.

      The ISAPI Filters list displays the filter name.

6. Enable the Tomcat redirector DLL in Web service extensions, as follows:

   1. From the Connections pane of Internet Information Services (IIS) Manager, select the Web server name.

   2. In Features View, double-click ISAPI and CGI Restrictions.

      The ISAPI and CGI Restrictions window opens.

   3. In the Actions pane, click Add.

      The Add ISAPI or CGI Restriction dialog box opens.

   4. Do the following:

      1. In the ISAPI or CGI path text box, provide the full directory path for the isapi_redirect.dll file.

      2. In the Description text box, type a short description of the restriction.

      3. Select the Allow extension path to execute check box.

   5. In the ISAPI and CGI Restrictions list, select the restriction you added.

   6. In the Actions pane, click Allow.

7. Enable execution of ISAPI filter, as follows:

   1. From the Connections pane of Internet Information Services (IIS) Manager, select the Web site (see step b of step 2).

   2. In Features View, double-click Handler Mappings.

      The Handler Mappings window opens.

   3. Right-click the ISAPI DLL item, and then select Edit Feature Permissions from the shortcut menu.

      The Edit Feature Permissions window opens.

   4. Select the Read,Script, and Execute check boxes.

8. Check the Allow double escaping setting is correct by following these steps:

   1. Open Internet Information Services (IIS) Manager.
   2. Select the name of the Web site you created (or identified) in step b of step 2. And then, in the center pane, double-click Request filtering.

   3. Right-click in the center pane and select Edit Feature Settings from the menu displayed.

      The Edit Request Filtering Settings window is displayed.

   4. Under General, select the Allow double escaping checkbox, as shown in the following figure.

      

   5. Click OK.

9. To make sure the IIS does not remove the JSON response content when the PPM server returns a 400 error, edit the web.config file, system.web Server section to set httpErrors existingResponse attribute to "PassThrough".

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

10. Restart the IIS service. (Restarting the Web site is not enough. You must restart World Wide Web Publishing Service from the Services management console.)

    Note: After you restart the IIS service, the ISAPI filter does not load immediately. The IIS service may require a few minutes to establish a connection with PPM. Before the connection is established, your browser may display the error message "HTTP Error 404 - File or directory not found. Internet Information Services (IIS)".

11. Start the PPM Server(s).

    Caution: If your PPM instance includes multiple nodes in a cluster configuration, you must start these nodes one at a time. Make sure that you wait until each node is fully started before you start the next node.