Introduction

Purpose

This document will assist the reader in setting up IBM Cognos 10 with Internet Information Services (IIS) 7.x.

The document is structured in consecutive sections of which some are optional. The optional sections describe how to enable features which are not required but nice-to-have when running IBM Cognos 10 on IIS 7.x. All steps of any section not explicitly labelled optional must be implemented for the set-up to be successful.

Applicability

This document applies to IIS 7.x installed on a Windows 2008 Server (GA or R2) and IBM Cognos 10.1 or 10.1.1 Business Intelligence and/or Enterprise Planning. The only gateway implementations covered in this document are ISAPI and CGI as those are the only ones supported by IIS.

Exclusions and Exceptions

This document assumes IIS 7.x has previously been added to the Windows 2008 Server roles, and all necessary options have been selected to successfully run a website. For details, see Appendix A.

This document also assumes the IBM Cognos 10 Gateway install component has been successfully installed to the same machine as IIS.

This document will not cover configuring Single Sign-On for IBM Cognos 10 based on IIS authentication. For information about this topic, please refer to the IBM Cognos 10 Information Center, IBM Cognos Technotes and resources published on the developerWorks web site.

Back to top

Configuring An Application Pool

IBM Cognos 10 gateway modules will need to be executed in the context of an IIS 7.x application pool. While it's most convenient to simply use the Default Application Pool it's strongly recommended to define an additional separate application pool for IBM Cognos 10. This application pool can be shared by many IBM Cognos products such as IBM Cognos 10 BI, IBM Cognos Enterprise Planning, IBM Cognos TM1 Web or IBM Cognos Executive Viewer.

The initial steps are to setup an Application pool for the IBM Cognos gateway modules to reside in.

1. Open the Internet Information Services Manager by clicking Start > Administrative Tools, right-click Internet Information Services (IIS) Manager and select Run as administrator.
   
   Illustration 1: Screen from Windows Start menu showing how to invoke IIS Manager as Administrator
   
   
   NOTE : There may be an entry in the Start menu titled “Internet Information Services (IIS) 6.0 Manager”. Do not use this entry. Use the “Internet Information Services (IIS) Manager” only.
2. Expand on the <server name> which is located under the Start Page, then expand on Application Pools.
   
   Illustration 2: IIS Manager window default view
   
   
   
3. Click on Add Application Pool from the Actions pane on the far right.
4. Provide the required details in the New Application Pool dialog.
   • In the Name: field provide a name such as “IBM Cognos 10” for the new application pool. Do not use “cgi-bin” or “isapi” as a name.
   • Leave the .Net Framework version: and Managed pipeline mode: fields as the default.
   • Un-check the Start application pool immediately field.
     
     Illustration 3: The New Application Pool dialogue asking for Name, .Net Framework version and managed pipeline mode.
     
     
     
5. Click OK.
6. Once back in the IIS Manager's left explorer pane, select the newly created Application Pool and click Advanced Settings under Edit Application Pool within the Actions tool pane on the right.
   
   Illustration 4: Available actions from IIS Manager for an application pool.
   
   
   
7. If applicable, enable 32-bit applications. For Windows 2008 (R2) 64-bit, the application pools will use 64-bit operating mode by default. However, IBM Cognos 10 Gateway modules are 32-bit even in 64-bit installs of IBM Cognos 10. Therefore on 64-bit platforms the application pool must be configured for 32-bit operations mode to execute the IBM Cognos Gateway modules.
   For 64-bit installs of IIS, select the Enable 32-bit Applications setting and set the value to True.
   
   Illustration 5: Advanced Settings dialog showing the advanced properties of an application pool such as 32-bit application support and others.
   
   
   NOTE : For 32-bit installs of IIS, this option will not be available.
8. For either 32-bit or 64-bit installs, change the Start Automatically setting to True.
   
   llustration 6: Advanced settings dialogue of an application pool showing the Start Automatically option.
   
   
   
9. Click OK.
10. Again, in the IIS Manager's left explorer pane select the newly created application pool and click Start under Application Pool Tasks within the Actions tool pane on the right.
    
    Illustration 7: The available application pool tasks from IIS Manager
    
    
    

Back to top

Create The IBM Cognos 10 Virtual Directory

IIS, like any other web server, serves it's contents to clients by exposing a virtual directory tree. For IBM Cognos 10 one will have to create a new virtual directory. This virtual directory will determine the path (or alias) element to be used in the URL, right after the web server host name or address. The product documentation states “ibmcognos” as the default virtual directory name (for example, http://<server>/ibmcognos), however any other string can be used.

1. In the IIS Manager's left explorer pane, expand Sites and Default Web Site.
2. Right-click the Default Web Site and select Add Virtual Directory.
   
   Illustration 8: IIS Manager showing the Add Virtual Directory context menu option.
   
   
   
3. Provide the required details for the Add Virtual Directory dialog.
   • In the Alias: field, provide a name for the virtual directory (for example, “ibmcognos”).
   • In the Physical path: field, specify the location of the webcontent sub-directory within the IBM Cognos 10 Gateway install. If necessary, use the button with the ellipsis to browse for the directory.
     
     Illustration 9: The Add Virtual Directory dialogue asking for an alias and physical path.
     
     
     
4. Press OK to save the changes.

Back to top

Create An Application For cgi-bin

Creating an IIS Application for cgi-bin will map the IBM Cognos gateway modules to the application pool that was previously created.

1. In the IIS Manager's left explorer pane find the virtual directory created earlier. You possibly labelled it “ibmcognos”. Right-click on the virtual directory and select Add Application.
   
   Illustration 10: IIS Manager showing the right-click options such as Add Virtual Directory and Add Application.
   
   
   
2. Provide the required details in the Add Application dialog.
   • In the Alias: field, specify a value of cgi-bin. This is a mandatory value.
   • In the Physical path: field, specify the location of the cgi-bin sub-directory within the IBM Cognos 10 Gateway install. If necessary, use the button with the ellipsis to browse for the directory.
   • In the Application pool: field, select the application pool created earlier by clicking on the Select... button.
     
     Illustration 11: The Add Application dialog asking for the alias, physical path and application pool to use.
     
     
     
3. Press OK to save the changes.

Back to top

Configuring IIS 7 for IBM Cognos ISAPI

IBM Cognos 10 offers two implementations of gateway modules to be used with IIS, ISAPI and CGI. It is considered to be best practice to use ISAPI with IIS since this provides better performance and resource allocation over CGI. Therefore this section describes the setup of the ISAPI module and the next section describing CGI setup is optional. Use CGI on IIS only if required.

For the ISAPI module to work there are two steps. First, a module mapping must be configured which routes requests calling cognosisapi.dll to the executable. Second, the module must be added as an allowed extension so IIS is not blocking it's execution.

Setting up Module Mapping for ISAPI

1. Select the cgi-bin application from the Default Web Site > ibmcognos tree in the left pane of IIS Manager and select the Features View from the lower bar in the middle pane.
2. Double-click on Handler Mappings in the middle pane. This will bring up the list of handler mappings for this application in the middle pane.
   Note that by default ISAPI and CGI are not listed as Enabled. Also note that CGI is for .EXE file extensions only.
   
   Illustration 12: The Handler Mappings list of the cgi-bin application.
   
   
   
3. In the upper right Actions pane click "Add Module Mapping" to add the ISAPI mapping.
4. Provide the required details to the Add Module Mapping dialog.
   • In the Request path: field, specify the value cognosisapi.dll. This is a mandatory value.
   • In the Module: field, select IsapiModule from the drop down list.
   • In the Executable (optional): field, specify the path to the cognosisapi.dll within the IBM Cognos Gateway install. This file will be in <COG_ROOT>/cgi-bin, where <COG_ROOT> refers to the IBM Cognos BI installation directory.
   • In the Name: field, specify a name for this module (for example, IBMCOGNOS-ISAPI).
     
     Illustration 13: The Add Module Mapping dialog asking for the request path, module and name as well as an optional path to the executable.
     
     
     
5. Click OK.
6. A dialog will appear. Click Yes to allow the ISAPI extension for the module mapping.
   
   Illustration 14: Configuration prompt that appears when saving the new handler mapping asking if the ISAPI extension is an allowed restriction or not.
   
   
   
7. Back at the Handler Mappings screen, the newly added handler (in this example we labelled it IBMCOGNOS-ISAPI) will appear under the enabled section.
   
   Illustration 15: The list of handler mappings now showing the configured ISAPI mapping as enabled.
   
   
   

Setting the ISAPI Restrictions for the Web Server

1. In the IIS Manager, select the web server in the tree view on the left.
   
   Illustration 16: Selecting a web server in IIS Manager from the tree view in the right explorer pane.
   
   
   
2. In the content pane, select the Features View tab at the bottom.
3. Double-click on the ISAPI and CGI Restrictions feature. This will bring up the list of defined restrictions in the middle pane of IIS Manager.
4. Ensure that the entry for cognosisapi.dll is set to Allowed within the list. This entry should have been inserted automatically when the Handler Mapping was done earlier. It will have no description and one has to identify it based on the value shown in the Path column.
   
   llustration 17: List of defined ISAPI and CGI restrictions, showing the newly defined ISAPI module being allowed.
   
   
   If the restriction entry for the cognosisapi.dll is missing continue to Step 5 otherwise skip to the next section.
5. In the upper right Actions pane, click Add...
6. Provide the required details to the Add ISAPI or CGI Restriction dialog.
   • In the ISAPI or CGI path: field, specify the path to the cognosisapi.dll within the IBM Cognos Gateway install. This value will normally be <COG_ROOT>\cgi-bin\cognosisapi.dll.
   • In the Description: field, enter a description of the restriction, such as IBMCOGNOS-ISAPI.
   • Check the Allow extension path to execute checkbox.
     
     Illustration 18: Add ISAPI or CGI Restriction dialog with checked option to allow the extension path to execute.
     
     
     

Testing the ISAPI installation

There are several ways to call the IBM Cognos 10 ISAPI Gateway.

1. Call http://<webserver>/<alias>
2. Call http://<webserver>/<alias>/isapi
3. Call http://<webserver>/<alias>/cgi-bin/cognosisapi.dll

Out of those three, only the third will work by default though. For convenience reasons, administrators often desire to use the first URL which is the shortest to type. However, that URL is also the most general one to use and is not specific to any particular Gateway implementation. To make that URL work for ISAPI enable it by following the steps below and implement the settings from section 5.4. The second URL is prepared to call the ISAPI Gateway but is required to be enabled as well.

To enable the first or the second URL, some additional steps may be required to make IIS load a default document from the specified paths. For either URL to be enabled use the following steps:

• In IIS Manager, in the left explorer pane select the virtual directory for IBM Cognos 10 that was created earlier and switch to the Features View.
  
  Illustration 19: Feature view of the IBM Cognos 10 BI alias, showing the Default Document option
  
  
  
• Double-click Default Document.
  
  Illustration 20: IIS Manager showing the Default Document settings
  
  
  
• From the upper right Actions pane, select Add.
• Type default.htm and click OK to save.

This will make default.htm a default document to serve if the directory is accessed without specifying a particular document in it, as is the case here. The default.htm file contains JavaScript code to perform a redirect to the IBM Cognos 10 Gateway module after showing a splash screen. The default.htm in http://<webserver>/<alias>/isapi does redirect to the ISAPI module by default, the default.htm in http://<webserver>/<alias> will redirect to CGI by default.

After enabling the URLs, accessing either one should show you the IBM Cognos 10 log-in screen or, if anonymous authentication is enabled for IBM Cognos 10, IBM Cognos Connection. In the case where IBM Cognos 10 is not started, an error message stating that the IBM Cognos 10 Gateway could not contact the IBM Cognos 10 BI server will appear.

Making the ISAPI Gateway the default

To make the ISAPI Gateway module the default for the IBM Cognos 10 BI system, there are two more steps required. The first step is to change the Gateway URI configuration setting using IBM Cognos Configuration and the second step is to adjust the default.htm file for the /<alias> virtual directory.

Repeat for all installs of IBM Cognos 10 Application Tier or Content Manager.

• Open IBM Cognos Configuration, select the Environment element in the left Explorer pane and click on the Gateway URI field.
  
  Illustration 21: IBM Cognos Configuration showing the properties of the Environment element including Gateway URI
  
  
  
• Edit the Gateway URI field to reflect the actual URI used to call the ISAPI Gateway. As a best practice, use a fully qualified domain naming scheme for the server name, such as http://<server>.<domain>.<suffix>:<port>/<alias>/cgi-bin/cognosisapi.dll. An example URI might be http://myserver.domain.com:80/ibmcognos/cgi-bin/cognosisapi.dll.

If enabled earlier, the default.htm file in for the http://<webserver>/<alias> URL must be edited to change the redirect target from CGI to ISAPI. Be aware that editing default.htm has implications in that you can only redirect to one particular IBM Cognos 10 Gateway module at a time. If you plan to enable the CGI gateway as an alternative as well, you need to decide which module shall be the default, either CGI or ISAPI. It is likely that users will prefer the shorter URL for accessing the system, so although there is a particular URL for accessing the ISAPI module (http://<webserver>/<alias>/isapi), it's a good idea to edit the file to redirect to ISAPI if ISAPI shall be the default.

On the IBM Cognos 10 Gateway install

• Open <COG_ROOT>/webcontent/default.htm in a text editor.
• Find the line

  window.setTimeout("window.location.replace('cgi-bin/cognos.cgi? b_action=xts.run&m=portal/main.xts&startwel=yes')",5);

  
  and change cognos.cgi to cognosisapi.dll

  window.setTimeout("window.location.replace('cgi-bin/cognosisapi.dll? b_action=xts.run&m=portal/main.xts&startwel=yes')",5);

  
  

This will make http://<webserver>/<alias> work like http://<webserver>/<alias>/isapi, redirecting to the ISAPI Gateway after showing a splash screen.

Back to top

Configuring IIS 7 for IBM Cognos CGI (optional)

Although it is considered best practice to use the IBM Cognos 10 ISAPI Gateway module for Microsoft IIS, the IBM Cognos 10 CGI Gateway module can be enabled as well. Mind that CGI modules spawn a new worker process for each session which makes them unsuitable for high load production environments.

As with the ISAPI module, a module mapping needs to be defined first and then the module must be allowed to execute in IIS.

Setting up Module Mapping for CGI

1. Select the cgi-bin application from the Default Web Site > ibmcognos tree in the left pane of IIS Manager and select the Features View from the lower bar in the middle pane.
2. Double-click on Handler Mappings in the middle pane. This will bring up the list of handler mappings for this application in the middle pane.
3. In the upper right Actions pane, click Add Module Mapping to add the CGI mapping.
4. Provide the required details for the Add Module Mapping dialog.
   • In the Request path: field, specify a value of cognos.cgi. This is a mandatory value.
   • In the Module: field, select cgiModule from the dropdown list. Note that the use of fastCGIModule is not supported.
   • The Executable (optional): field should be left blank.
   • In the Name: field, enter a name for this module, such as IBMCOGNOS-CGI.
     
     Illustration 22: Add Module mapping dialog showing the required values for the request path, module and name.
     
     
     
5. Click OK to save.
6. Back at the Handler Mapping page, IBMCOGNOS-CGI will appear under the Enabled section.
   
   Illustration 23: List of handler mappings showing the newly added CGI mapping being enabled
   
   
   
7. With the newly created mapping (in this example labelled IBMCOGNOS-CGI) selected, click Edit Feature Permissions from the upper right Actions pane.
8. In the Edit Feature Permissions dialog, check the Execute checkbox to enable CGI execution.
   
   Illustration 24: Edit Feature Permissions dialog showing the Execute permission being enabled
   
   
   
9. Click OK.

Setting the CGI Restrictions for the Web Server

1. In the IIS Manager, select the web server in the tree view on the left and in the content pane select the Features View tab at the bottom.
   
   Illustration 25: Selecting a web server in IIS Manager from the tree view in the right explorer pane
   
   
   
2. Double-click on the ISAPI and CGI Restrictions feature. This will bring up the list of defined restrictions in the middle pane of IIS Manager.
3. In the upper right Actions pane, click Add...
4. Provide the required details in the Add ISAPI or CGI Restriction dialog.
   • In the ISAPI or CGI Path: field, specify the path to the cognos.cgi file within the IBM Cognos Gateway install. This file can be found in the <COG_ROOT>\cgi-bin directory. If browsing for the file, change the file type to All files (*.*), since .cgi is not a default suffix.
   • In the Description: field, specify a description of the restriction, such as IBMCOGNOS-CGI.
   • Ensure that the check-box for Allow extension path to execute is checked.
     
     Illustration 26: Add ISAPI or CGI Restriction dialog showing the values for the new CGI restriction
     
     
     

Testing the CGI installation

There are two ways to call the IBM Cognos 10 CGI Gateway module

1. By calling http://<webserver>/<alias>
2. By calling http://<webserver>/<alias>/cgi-bin/cognos.cgi

Note: If the steps in the section titled Making the ISAPI Gateway the default have been implemented (recall that this was editing the default.htm located in the /<alias> path), the first URL will re-direct to the ISAPI module and will not call the CGI module any more.

By default only the second URL will work. Howver, for convenience reasons, administrators often desire to use the first URL which is the shortest to type. However, that URL is the most general one to use and is not specific to any particular Gateway implementation. To make that URL work it needs to be enabled and the following steps will be required to make IIS load a default document from the specified paths.

• In IIS Manager, in the left explorer pane select the virtual directory for IBM Cognos 10 that was created earlier and switch to the Features View.
  
  Illustration 27: Feature view of the IBM Cognos 10 BI alias, showing the Default Document option
  
  
  
• Double-click Default Document.
  
  Illustration 28: IIS Manager showing the Default Document settings
  
  
  
• From the upper right Actions pane, select Add.
• Type default.htm and click OK to save.

This will make the file default.htm a default document to serve if the directory is accessed without specifying a particular document in it. The default.htm file contains JavaScript code to perform a redirect to the IBM Cognos 10 Gateway module after showing a splash screen. By default the redirect will be to the CGI module so no further changes are required unless the default.htm was edited previously.

Accessing either URL should show you the IBM Cognos 10 log-in screen or, if anonymous authentication is enabled for IBM Cognos 10, IBM Cognos Connection. In the case where IBM Cognos 10 is not started, an error message stating that the IBM Cognos 10 Gateway could not contact the IBM Cognos 10 BI server will appear.

Back to top

Modify the Application Host or Web Configuration Files

IBM Cognos 10 requires some additional parameter to be configured for the ISAPI and/or CGI IBM Cognos 10 Gateway module mapping handlers. This is required so that IBM Cognos Administration and IBM Cognos Mobile function correctly. Unfortunately this parameter cannot be specified via the IIS Manager UI. This section therefore describes two options for adding this configuration item.

In IIS 7.x, the website definitions are stored in XML files with an extension of .config. Depending on the IIS 7.x configuration, there are two possible locations for the module mapping handlers. They can occur in one of two configuration files.

• If IIS is configured for Feature Delegation on handler mappings, you should see a web.config file that was created by IIS automatically in the <COG_ROOT>\cgi-bin directory. An example of the contents of that web.config file, based on the setup from this document:

  <?xml version="1.0" encoding="UTF-8"?> <configuration> <system.webServer> <handlers accessPolicy="Read, Execute, Script"> <add name="IBMCOGNOS-CGI" path="cognos.cgi" verb="*" modules="CgiModule" resourceType="File" requireAccess="Execute"/> <add name="IBMCOGNOS-ISAPI" path="cognosisapi.dll" verb="*" modules="IsapiModule" scriptProcessor="D:\cognos\c10.1.1\cgi-bin\cognosisapi.dll" resourceType="File" requireAccess="Execute" preCondition="bitness32" /> </handlers> </system.webServer> </configuration>

  
  Notice the two handlers, one for ISAPI, one for CGI.
• If the Feature Delegation is disabled within your IIS, there may not be a web.config file at all in <COG_ROOT>\cgi-bin, or, if one exists, it may be blank and look as follows:

  <?xml version="1.0" encoding="UTF-8"?> <configuration> </configuration>

  
  If this is the case, you will need to modify the file applicationHost.config that was created by IIS at IIS installation time instead. This file can be found in the C:\Windows\System32\inetsrv\config directory.

Regardless of which configuration file contains the mapping handlers, the identified file must be edited now by one of the two alternate methods. Choose either one.

Adding allowPathInfo=”true” to the module mapping handlers

IBM Cognos 10 requires the allowPathInfo=true parameter to be added to the ISAPI and/or CGI module mapping handler.

This parameter controls how the handler will populate the standard CGI environment variable PATH_INFO for the mapped module. By default, IIS sets it to the full URL which is not compliant with the CGI specification, however some applications, in particular Active Server Pages, expect it that way. The IBM Cognos 10 Gateway modules however comply to the CGI specification and expect it to contain the last part of the URL only, for example “cognos.cgi” instead of “<alias>/cgi-bin/cognos.cgi”. This is why this additional parameter must be added.

The recommended approach to add this parameter to your configuration is to use Microsoft’s appcmd tool which is part of the IIS Management Tools. Alternatively, you may edit either the applicationHost.config or web.config file using a standard text editor. Both methods will be described below but it is recommended that the appcmd tool be used.

Modify configuration using the appcmd tool

If the configuration file containing the handlers is the applicationHost.config file, use the following steps. The syntax for the appcmd tool is slightly different if the configuration file is web.config and will be described separately.

1. Open a Command Prompt by going to Start > Run and typing cmd.
2. Issue the cd %SYSTEMROOT%\system32\inetsrv command to change the directory to the root IIS directory.
3. Execute the following appcmd for the ISAPI module:
   

   appcmd set config “Default Web Site/ibmcognos/cgi-bin” –section:system.webServer/handlers /[name=’IBMCOGNOS-ISAPI’].allowPathInfo:true /commit:apphost

   
   The “Default Web Site” will need to be modified to match the website name if different from default. Also, if different values were specified for the IBM Cognos 10 virtual directory (ibmcognos) or the module mapping name (IBMCOGNOS-ISAPI) they will need to be adjusted to your environment.
   
   Illustration 29: Windows command window showing the execution of the appcmd command
   
   
   
4. If the CGI module has been configure, issue the following command:

   appcmd set config “Default Web Site/ibmcognos/cgi-bin” –section:system.webServer/handlers /[name=’IBMCOGNOS-CGI’].allowPathInfo:true /commit:apphost

   
   As before, the “Default Web Site” will need to be modified to match the website name if different from default and if different values were specified for the IBM Cognos 10 virtual directory (ibmcognos) or the module mapping name (IBMCOGNOS-CGI) they will need to be adjusted to your environment.

If the configuration file containing the handlers is the web.config file or if you receive the error “Error ( message:Cannot find requested collection element. )”, then omit the “/commit:apphost” option on the appcmd commands given above as follows. Once again, make sure to adjust the command to your environment regarding the names of the web site and the handler names if necessary.

appcmd set config “Default Web Site/ibmcognos/cgi-bin”
 –section:system.webServer/handlers
 /[name=’IBMCOGNOS-ISAPI’].allowPathInfo:true

and

appcmd set config “Default Web Site/ibmcognos/cgi-bin”
 –section:system.webServer/handlers
 /[name=’IBMCOGNOS-CGI’].allowPathInfo:true 

Modify configuration by editing the configuration files

If for some reason the appcmd tool was not able to be used, you can also use a text editor to modify the web.config or applicationHost.config files directly.

1. Make a backup copy of the identified configuration file containing the mapping handlers.
2. Open the file C:\Windows\System32\inetsrv\config\ApplicationHost.config or <COG_ROOT>\cgi-bin\web.config in a text editor.
3. Search for the handler name that was previously created (for this document "IBMCOGNOS-ISAPI" and “IBMCOGNOS-CGI” were used). You should find one or two sub-entries of a <handlers> collection.
4. The default configuration for the ISAPI module should be:

   <add name="IBMCOGNOS-ISAPI" path="cognosisapi.dll" verb="*" modules="IsapiModule" scriptProcessor="D:\cognos\c10.1.1\cgi-bin\cognosisapi.dll" resourceType="File" requireAccess="Execute" preCondition="bitness32" />

   
   
5. Modify the ISAPI module to include allowPathInfo="true". The edited line should be:

   <add name="IBMCOGNOS-ISAPI" path="cognosisapi.dll" verb="*" modules="IsapiModule" scriptProcessor="D:\cognos\c10.1.1\cgi-bin\cognosisapi.dll" resourceType="File" requireAccess="Execute" preCondition="bitness32" allowPathInfo="true"/>

   
   
6. If configured, repeat for the CGI module. The default configuration for the CGI module should be:

   <add name="COGNOS-CGI" path="cognos.cgi" verb="*" modules="CgiModule" resourceType="File" requireAccess="Execute" />

   
   
7. Modify the CGI module to include allowPathInfo="true". The finished line should be:

   <add name="IBMCOGNOS-CGI" path="cognos.cgi" verb="*" modules="CgiModule" resourceType="File" requireAccess="Execute" allowPathInfo="true"/>

   
   
8. Save and close the file.
9. Restart IIS.

Testing allowPathInfo

Log in to IBM Cognos Connection as a member of the System Administrator role and bring up IBM Cognos Administration. If IBM Cognos Administration comes up without error, the configuration is fine.

If this is not set up properly, IBM Cognos Administration will not be accessible and will display the error “PF-SRV-6116 Unable to process the document, target is not valid or the target was not received” at the top of the page. Possible resolutions to this error are discussed towards the end of this document in the section titled Troubleshooting.

Note: For IBM Cognos Mobile, after the log-in screen, a pop-up containing the text “No Operation Specified” will occur.

Back to top

Performance Tips (Optional)

To help performance there are some small tweaks one can add to the IIS configuration. The first tip is to define the content expiration so that unchanged static web content will be taken from the local browser cache instead requesting it from the server. The second tip is to define connection time-out to some low value so that connections get dropped earlier when being idle for too long. The third (and probably most important) tip is to use the ISAPI Gateway module by default.

Content Expiration

1. In IIS Manager's left pane, select the IBM Cognos 10 virtual directory by clicking on it. During the course of this document we used ibmcognos as the name of the virtual directory.
2. Change to Features View at the bottom of the middle pane, then double-click HTTP Response Headers.
3. In the upper right Actions pane click Set Common Headers.
4. In the Set Common HTTP Response Headers dialog, check the Expire Web Content: checkbox, click the After: radiobutton and set the expiration period to 10 days. Lower values mean that content will expire earlier (more requests) , higher values will cause less requests.
   
   llustration 32: The Set Common HTTP Response Headers dialog showing web content expiry set to 10 days
   
   
   
5. Click OK.

Connection Time-out

1. In IIS Manager's left pane select the web site used to serve IBM Cognos Gateway content (likely named Default Web Site) by clicking on it.
2. In the upper right Actions pane in the Configure section click on Limits.
3. In the Edit Web Site Limits dialog, set the Connection time-out (in seconds): field to a value of 900.
   
   llustration 33: The Edit Web Site Limits dialog showing the connection time-out set to 900 seconds
   
   
   

Back to top

Configuring WebDAV (Optional)

Web-based Distributed Authoring and Versioning (WebDAV) is a protocol based on HTTP which allows clients to read, write and modify files served by a web server and save them back to the server.

IBM Cognos 10 uses this protocol to allow browsing for images in studios when a report author wants to add images to reports and analysis. Out of the box, IBM Cognos BI offers some sample image files, used by the product samples, to be used. They are located underneath the virtual directory configured for the IBM Cognos 10 Gateway.

By default WebDAV is disabled in IIS and has to be enabled explicitly. In addition, authorization must be defined to ensure only desired path of the virtual directory structure of the web server are exposed and only authorized users are allowed to access files.

For this to work, the WebDAV Publishing Role Service must be installed. Refer to Appendix A for details.

Enable WebDAV

1. In IIS Manager's left pane select the the web site hosting the image files by clicking on it.
2. Change to Features View at the bottom of the middle pane, then click WebDAV Authoring Rules.
3. In the upper right Action pane, click Enable WebDAV.

Define WebDAV access

Next step is to configure IIS authentication and authorization for the folders containing images. If the IBM Cognos 10 BI samples have been installed, there will be a folder of sample images at <COG_ROOT>/webcontent/samples/images which is accessible through IIS as <alias>/samples/images. We will use this folder to demonstrate the approach. Repeat it for any other folder containing images, even when in different virtual directories than the IBM Cognos 10 BI one.

Note that in this very simple demonstrative example, we're enabling WebDAV access for anonymous users and on all files as read-only. Discuss with your Windows Administrator about which users or groups should have which access. The same applies for the authentication method. To have file access secured by Windows security, Windows authentication must be configured. However, this is out of scope for this document.

1. In IIS Manager's left explorer pane, find the <alias>/samples/images folder and select it by clicking on it.
2. In the lower middle pane of IIS Manager, switch to Feature View and double-click on Authentication. This will display the configured authentication methods for this virtual folder in the middle pane.
3. In the middle pane, select Anonymous Authentication by clicking on it.
4. If the Status column states Disabled, in the upper right Actions pane click Enable to enable anonymous authentication for this folder.
   
   Illustration 34: Table of configured authentication methods for the folder showing anonymous authentication being enabled
   
   
   

This will allow anyone access to the folder without authentication. Be aware that IIS uses the special local IIS user account for file access in this configuration. The files in the <COG_ROOT>/webcontent/samples/images folder therefore must be accessible for this account for this to work.

1. In IIS Manager's left explorer pane, find the <alias>/samples/images and select it again by clicking on it.
2. Click on WebDAV Authoring Rules in the middle pane, showing the Features View for this folder.
3. In the upper right Actions pane, click on Add Authoring Rule...
4. In the Add Authoring Rule dialog, do the following:
   • In the Allow access to: section, click the All content radiobutton.
   • In the Allow access to this content to: section, click the All users radiobutton.
   • In the Permissions: section, click to check the Read checkbox.
     
     Illustration 35: Add Authoring Rules dialog showing the options to define WebDAV access
     
     
     
5. Click OK to save the changes.

You should now be able to see the image files when browsing them in one of the IBM Cognos 10 studios such as Report Studio.

Back to top

Enable Secure Socket Layer (SSL) communication

For sake of completeness only this document will provide the pointers and steps required to configure the IBM Cognos 10 Gateway for SSL. This task has several steps which are

1. Request a web server certificate for SSL.
2. Install the web server certificate to the web server.
3. Amend IBM Cognos Configuration settings on all affected installs of IBM Cognos 10.
4. Import a certificate required for establishing trust into IBM Cognos 10 trust store(s).

The first two steps are outside of the IBM Cognos domain and must be implemented by the web server administrator or someone with Public Key Infrastructure (PKI) knowledge. There are some best practices to follow though.

• The web server certificate should not be self-signed, that is, the certificate's subject and issuer shouldn't be identical. These certificates are considered insecure and are untrusted by IBM Cognos. They should be used for test or troubleshooting only as they are unsuitable by modern security standards for production systems. Self-signed certificates must bear the CA:True X.509 extension to work with IBM Cognos since they are server certificate and CA certificate in one.
  The best practice is to set up your own Certifying Authority (CA) and have it sign the web server certificate with it's CA certificate. Microsoft Server 2008 contains the Active Directory Certificate Services which can be used for this purpose. A free and widely adopted standard tool is OpenSSL which exists for many platforms and various guides can be found online.
• The web server certificate subject Distinguished Name (DN), that is the identity used by the web server, must be the server name and should be specified using Fully Qualified Domain Naming (FQDN) scheme like CN=<serverhost>.<domain>.<suffix>, ...<other optional DN attributes>. This is because browsers will compare the certificate subject to the URL used to call the server and issue a warning or reject the certificate if they don't match up.
  The best practice is to use FQDN for either certificates and any URI used to call the IBM Cognos 10 Gateway. The Gateway URI specified in IBM Cognos Configuration should always use FQDN, “localhost” is not feasible.
• SSL implements, amongst other things, encrypted communication. The protocol and method used for the encryption is called the cipher and is based on a key which, depending on it's length in bits, is considered to be either weak or strong. Recent web servers should use strong ciphers, which is keys with a length of 128bits and higher.
  The web server should be configured to disallow weak ciphers for security reasons. IIS 7.x only supports strong ciphers and therefore adheres to this best practice out of the box. IBM Cognos 10 does support strong ciphers out of the box and they are enabled for the supported ciphersuites option in IBM Cognos Configuration by default.

For details on how to configure IIS 7.x for SSL consult the following link on the Microsoft IIS 7 web site:
http://learn.iis.net/page.aspx/144/how-to-set-up-ssl-on-iis-7-and-above/

The steps 3 and 4 are covered in the IBM Cognos 10 Installation and Configuration Guide, available online as part of the IBM Cognos 10 Information Center at:
http://publib.boulder.ibm.com/infocenter/cbi/v10r1m0/topic/com.ibm.swg.im.cognos.inst_cr_winux.10.1.0.doc/inst_cr_winux_id21953ConfiguringtheSSLProtocol.html#ConfiguringtheSSLProtocol

While the general steps provided in the Information Center apply to the setups described in this document as well, there are some special things to consider:

• The import of the CA certificate (or the self-signed certificate with CA:True extension) must be implemented on any IBM Cognos 10 install which references the IBM Cognos 10 Gateway. This includes Application Tier installs and Content Manager installs, not only for IBM Cognos 10 BI but also for IBM Cognos Planning, IBM Cognos PowerPlay and other tools of the IBM Cognos 10 suite.
• In addition to changing the value of the Gateway URI in IBM Cognos Configuration, one must ensure the strong ciphers are enabled for SSL as well. To do this, in IBM Cognos Configuration check the Supported ciphersuites property at Security > Cryptography > Cognos.
  
  Illustration 36: The Supported ciphersuites property in IBM Cognos Configuration
  
  
  Click on the Edit symbol to display the list of enabled cipher suites. The dialog will display two lists, on the left will be one labeled Available values and on the right one labeled Current values. Current values should contain all entries from Available values. If not, add ciphers from the Available values list by checking them and click the Add button in the middle between the two lists. Press OK to save the changes.
  
  Illustration 37: The Supported ciphersuites dialog in IBM Cognos Cofiguration showing the available and current ciphers configured
  
  
  
• If using other IBM Cognos client tools to connect to this IBM Cognos 10 Gateway (for example IBM Cognos TM1 (Architect, Web), IBM Cognos Executive Viewer or even IBM Cognos Planning) these tools must establish trust to the web server certificate as well by importing the CA certificate into their respective trust stores. It's a good idea to inform the administrator of these IBM Cognos products that additional configuration steps are required. Not all of these tools use their own trust stores but leverage the machine trust store of the Windows box they run on. They should implement the step described next.
• For Internet Explorer clients, the CA certificate which signed the web server certificate should be imported as a trusted root certification authority. Consult your Windows administrator for details. The following link yields some basic guidance http://technet.microsoft.com/en-us/library/dd361898.aspx. By employing your favorite search engine, the internet will provide more verbose guides for this task.

Back to top

Troubleshooting

HTTP Error 404.0 – File Not Found

Issue: 404.0 - file not found for the path <some file system path>

Possible Solutions:

• The application "cgi-bin" has not been setup or is not at the correct level as a child to the main IBM Cognos 10 alias (virtual directory).
• Type in the URI or the virtual directory name.
• IIS is not started.

HTTP Error 404.2 – Not Found

Hitting the IBM Cognos 10 Gateway URI leads to “HTTP 402.2 - The page you are requesting cannot be served because of the ISAPI and CGI Restriction list settings on the Web server.”

Possible Solutions:

• Re-check the ISAPI restrictions.
• Verify the URI as it's possible you're getting redirected or calling the wrong IBM Cognos 10 Gateway module.

HTTP Error 503 – Service Unavailable

Issue: The service is unavailable when accessing an IBM Cognos 10 Gateway URI

Possible Solution:

• Ensure the Application Pool hosting the IBM Cognos 10 Gateway modules is started.

File Download dialog appears when accessing the ISAPI module

Issue: A file download dialog box, asking whether to open, save or cancel pops up when accessing the IBM Cognos 10 ISAPI Gateway module.

Possible Solution:

• Check the Edit Feature Permission for the ISAPI handler mapping, it must be set to Execute.

PF-SRV-6116 when starting Cognos Administration

Issue: When invoking IBM Cognos Administration, the error PF-SRV-6116 is displayed in a yellow box at the top of the page and the remainder of the browser window remains plain white.

Possible Solution:

• The additional allowPathInfo parameter in the mapping handler for the accessed IBM Cognos 10 Gateway module is missing or incorrectly configured. Refer to the section titled “Modify the Application Host of Web Configuration Files” for details on how to rectify.
• Accessed the wrong IBM Cognos 10 Gateway module (for example CGI instead of ISAPI) for which the mapping handler was not properly configured.

Error when browsing for images in Report Studio

Issue: When browsing for images in Report Studio the following error comes up in a dialog box:

“Web Server error: The web request failed. 404 – Not Found , <url>”

Possible Solution:

• Ensure WebDAV is configured for IIS.
• If the URL points to <alias>/samples/images, make sure the IBM Cognos 10 BI samples have been installed. The sample images are not part of the base IBM Cognos 10 BI install.

Back to top

Appendix A – IIS Installation Requirements

Before being able to set up IBM Cognos 10 with IIS 7.x, the following installation prerequisites regarding IIS7.x must be fulfilled:

• The Web Server role must have been added to the Microsoft Server 2008 (R2 )
• In addition, the following Role Services for the Web Server role must be installed:
  • Common HTTP Features with the following sub-components
    • Static Content
    • Default Document
    • Directory Browsing
    • HTTP Errors
  • Management Tools with the following sub-components
    • IIS Management Console
    • IIS Management Scripts and Tools
    • Management Service
• For cognos.cgi usage, the “CGI” Role Service must be installed
• For cognosisapi.dll usage, the “ISAPI Extensions” Role Service must be installed
• For WebDAV use, the “WebDAV Publishing” Role Service must be installed

To verify the installed Role Services, as a local administrator click Start > Administrative Tools > Server Manager. You should be able to see the Roles screen now.

In the section of the Roles screen for Web Server (IIS), you have a Role Services sub-category which lists all installed role services. If any of the Role Services listed above is missing, click Add Role Services and install the missing services. This may require a restart of the IIS server.

Back to top

Appendix B – Disabling Windows 2008 security features for troubleshooting

Microsoft Windows 2008 (R2) introduced several new security features which allow to harden a machine. Amongst those are User Account Control (UAC), Internet Explorer Enhanced Security Configuration (IE ESC) and Data Execution Prevention (DEP).

Each of those features affects IBM Cognos 10 components executing on the server. If problems occur these security features could be temporarily disabled by an Administrator. Some behaviors which would render it reasonable to temporarily disable a security feature for the purpose of ruling it out as the root cause are:

• DEP : Issues with Application Pools like CGI or ISAPI calls don't complete or crash.
• IE ESC: IE blocking access to the Gateway URI, Error messages when accessing the Gateway URI, redirect not working.
• UAC: Need to run some executable as admin but admin credentials cannot be shared. Ask the administrator to disable UAC temporarily during setup/configuration.

Disabling either of these features should be done temporarily for troubleshooting purposes only. It is strongly advised to leave them all in place to adhere to security practices and standards. IBM Cognos 10 is completely compatible with all of these features. Be aware that disabling any of those features may impose a security risk to the server and may violate corporate security policies. For details on each of the features, please refer to the Microsoft Windows 2008 Technet pages at http://technet.microsoft.com/en-us/library/cc754279%28WS.10%29.aspx.

Disable UAC

As a local Administrator,

• From the Start Menu, select Control Panel and select User Accounts.
• In User Accounts page, click on Change User Account Control Settings.
• In the User Account Control Settings screen, move the slider control to Never notify, the lowest possible setting.
  
  Illustration 43: The User Account Control Settings dialog with the slider control to specify the notification level set to “Never modify”
  
  
  
• Click OK to save the changes.

Turn off IE Enhanced Security Configuration (IE ESC)

To disable IE ESC, as an Administrator

• From the Start Menu, select Administrative Tools and then select Server Manager.
• In the Server Manager left explorer pane, select the root element labelled Server Manager <hostname> by clicking on it.
• In the Server Manager right pane, context dependent options will be presented. Click on Configure IE ESC.
  
  Illustration 44: Server Manager options pane listing the supported configuration options including Configure IE ESC
  
  
  
• This will have brought up the Internet Explorer Enhanced Security Configuration dialog. Change the status of the IE ESC for Administrators and Users to Off by clicking the associated radio buttons and press OK to save the changes.
  
  Illustration 45: Internet Explorer Enhanced Security Configuration dialog showing IE ESC for administrators and normal users as off
  
  
  

Turn off DEP on server

To disable DEP, as an Administrator

• From the Start Menu, select Computer and then select Properties.
• In the upcoming System Properties window, click Advanced System Settings on the left options pane.
• In the Advanced System Properties dialog, select the Advanced tab.
• On the Advanced tab, click Settings in the Performance section.
• From the Performance Options dialog, select the Data Execution Prevention tab.
• Select the first option Turn on DEP for essential Windows programs and services only.
• Press OK to save the changes.
  
  Illustration 46: The Performance Options dialog showing DEP turned on for only essential Windows programs and services
  
  
  

Back to top

Appendix C - References

More information about IBM Cognos BI version 10 can be found at the following URLs.

• Supported Environments:
  http://www.ibm.com/support/docview.wss?uid=swg27019126
• Information Center:
  http://publib.boulder.ibm.com/infocenter/cbi/v10r1m0/index.jsp?lang=en
• A Redbook about IBM Cognos 10
  http://www.redbooks.ibm.com/abstracts/sg247912.html?Open
• Customizing the IBM Cognos 10 Login Page:
  http://www.ibm.com/developerworks/data/library/cognos/security/cognos_bi_platform/page546.html

Some background on PKI and certificates in Microsoft Windows can be found at http://technet.microsoft.com/en-us/library/dd361898.aspx.

The official IIS7 site is at http://www.iis.net.

About the authors

Rate this article

Comments

Back to top

Table of contents

• Introduction
• Configuring An Application Pool
• Create The IBM Cognos 10 Virtual Directory
• Create An Application For cgi-bin
• Configuring IIS 7 for IBM Cognos ISAPI
• Configuring IIS 7 for IBM Cognos CGI (optional)
• Modify the Application Host or Web Configuration Files
• Performance Tips (Optional)
• Configuring WebDAV (Optional)
• Enable Secure Socket Layer (SSL) communication
• Troubleshooting
• Appendix A – IIS Installation Requirements
• Appendix B – Disabling Windows 2008 security features for troubleshooting
• Appendix C - References
• About the authors
• Comments

Next steps from IBM

• Try: Cognos Business Intelligence
• Demo: Video: Cognos 8 BI
• Community: Cognos BI
• Buy: Cognos Business Intelligence

Dig deeper into Information Management on developerWorks

Try IBM PureSystems. No charge.

Experience today!

---

Get started with the cloud-based trial and pattern development kit.

Special offers