IBM Cognos 10 Microsoft Internet Information Services 7.x...

© Copyright IBM Corporation 2011 TrademarksIBM Cognos Proven Practices: Configure MicrosoftInternet Information Services 7.x for IBM Cognos 10

of 45

IBM Cognos Proven Practices: ConfigureMicrosoft Internet Information Services 7.x forIBM Cognos 10Nature of Document: Guideline; Product(s): IBM Cognos10 BI, IBM Cognos Enterprise Planning; Area of Interest:Infrastructure; Version: 1.0

Bastian KiesslingProblem Resolution Analyst, IBM CognosIBM

Ryan LaginskiAccelerated Value Specialist, Cognos BIIBM

Roger ÖstlundCognos Technical SpecialistIBM

Skill Level: Introductory

Date: 02 Dec 2011

How to configure Microsoft IIS 7 and 7.5 on Win2008 or Win2008R2 to host anIBM Cognos 10 gateway. This document provides comprehensive details on thesteps and various best practices and is a must-read for anyone configuring IIS7for Cognos 10.

View more content in this series

IntroductionPurposeThis document will assist the reader in setting up IBM Cognos 10 with InternetInformation Services (IIS) 7.x.

The document is structured in consecutive sections of which some are optional. Theoptional 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 explicitlylabelled optional must be implemented for the set-up to be successful.

http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/developerworks/ibm/trademarks/

http://www.ibm.com/developerworks/data/library/cognos/cognosprovenpractices.html

developerWorks® ibm.com/developerWorks/

IBM Cognos Proven Practices: Configure MicrosoftInternet Information Services 7.x for IBM Cognos 10

of 45

Applicability

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

Exclusions and Exceptions

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

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

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

Configuring An Application Pool

IBM Cognos 10 gateway modules will need to be executed in the context of an IIS 7.xapplication pool. While it's most convenient to simply use the Default ApplicationPool it's strongly recommended to define an additional separate application pool forIBM Cognos 10. This application pool can be shared by many IBM Cognos productssuch as IBM Cognos 10 BI, IBM Cognos Enterprise Planning, IBM Cognos TM1 Webor IBM Cognos Executive Viewer.

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

1. Open the Internet Information Services Manager by clicking Start >Administrative Tools, right-click Internet Information Services (IIS) Managerand select Run as administrator.

ibm.com/developerWorks/ developerWorks®


of 45

Illustration 1: Screen from Windows Start menu showing how to invoke IISManager as Administrator

NOTE : There may be anentry 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, thenexpand on Application Pools.



of 45

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 newapplication pool. Do not use “cgi-bin” or “isapi” as a name.

• Leave the .Net Framework version: and Managed pipeline mode: fieldsas the default.

• Un-check the Start application pool immediately field.

Illustration 3: The New Application Pool dialogue asking forName, .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 Poolwithin the Actions tool pane on the right.



of 45

Illustration 4: Available actions from IIS Manager for an application pool

7. If applicable, enable 32-bit applications. For Windows 2008 (R2) 64-bit, theapplication pools will use 64-bit operating mode by default. However, IBMCognos 10 Gateway modules are 32-bit even in 64-bit installs of IBM Cognos10. 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 setthe value to True.

Illustration 5: Advanced Settings dialog showing the advanced propertiesof an application pool such as 32-bit application support and others

NOTE : For 32-bitinstalls of IIS, this option will not be available.

8. For either 32-bit or 64-bit installs, change the Start Automatically setting toTrue.



of 45

llustration 6: Advanced settings dialogue of an application pool showingthe 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 theActions tool pane on the right.

Illustration 7: The available application pool tasks from IIS Manager

Create The IBM Cognos 10 Virtual Directory

IIS, like any other web server, serves it's contents to clients by exposing a virtualdirectory 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 theURL, right after the web server host name or address. The product documentationstates “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.



of 45

Illustration 8: IIS Manager showing the Add Virtual Directory context menuoption

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 thebutton with the ellipsis to browse for the directory.



of 45

Illustration 9: The Add Virtual Directory dialogue asking for an aliasand physical path

4. Press OK to save the changes.

Create An Application For cgi-binCreating an IIS Application for cgi-bin will map the IBM Cognos gateway modules tothe 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 andselect Add Application.Illustration 10: IIS Manager showing the right-click options such as AddVirtual 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 buttonwith the ellipsis to browse for the directory.

• In the Application pool: field, select the application pool created earlier byclicking on the Select... button.



of 45

Illustration 11: The Add Application dialog asking for the alias,physical path and application pool to use

3. Press OK to save the changes.

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 thisprovides better performance and resource allocation over CGI. Therefore this sectiondescribes the setup of the ISAPI module and the next section describing CGI setup isoptional. Use CGI on IIS only if required.

For the ISAPI module to work there are two steps. First, a module mapping mustbe 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'sexecution.

Setting up Module Mapping for ISAPI

1. Select the cgi-bin application from the Default Web Site > ibmcognos tree inthe left pane of IIS Manager and select the Features View from the lower bar inthe middle pane.

2. Double-click on Handler Mappings in the middle pane. This will bring up the listof handler mappings for this application in the middle pane.Note that by default ISAPI and CGI are not listed as Enabled. Also note thatCGI is for .EXE file extensions only.



of 45

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 ISAPImapping.

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 CognosBI installation directory.

• In the Name: field, specify a name for this module (for example,IBMCOGNOS-ISAPI).



of 45

Illustration 13: The Add Module Mapping dialog asking for therequest path, module and name as well as an optional path to theexecutable

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 newhandler mapping asking if the ISAPI extension is an allowed restriction ornot

7. Back at the Handler Mappings screen, the newly added handler (in this examplewe labelled it IBMCOGNOS-ISAPI) will appear under the enabled section.



of 45

Illustration 15: The list of handler mappings now showing the configuredISAPI 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.



of 45

Illustration 16: Selecting a web server in IIS Manager from the tree view inthe 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 wasdone earlier. It will have no description and one has to identify it based on thevalue shown in the Path column.



of 45

llustration 17: List of defined ISAPI and CGI restrictions, showing thenewly defined ISAPI module being allowed

If the restriction entry for the cognosisapi.dll is missing continue to Step 5otherwise 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.dllwithin 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 asIBMCOGNOS-ISAPI.

• Check the Allow extension path to execute checkbox.

Illustration 18: Add ISAPI or CGI Restriction dialog with checkedoption 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>/isapi3. Call http://<webserver>/<alias>/cgi-bin/cognosisapi.dll

Out of those three, only the third will work by default though. For conveniencereasons, 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 anyparticular Gateway implementation. To make that URL work for ISAPI enable it byfollowing the steps below and implement the settings from section 5.4. The secondURL is prepared to call the ISAPI Gateway but is required to be enabled as well.



of 45

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

• In IIS Manager, in the left explorer pane select the virtual directory for IBMCognos 10 that was created earlier and switch to the Features View.

Illustration 19: Feature view of the IBM Cognos 10 BI alias, showing theDefault Document option

• Double-click Default Document.Illustration 20: IIS Manager showing the Default Document settings

• From the upper right Actions pane, select Add.



of 45

• Type default.htm and click OK to save.

This will make default.htm a default document to serve if the directory is accessedwithout specifying a particular document in it, as is the case here. The default.htmfile contains JavaScript code to perform a redirect to the IBM Cognos 10 Gatewaymodule 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 Cognos10 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 errormessage stating that the IBM Cognos 10 Gateway could not contact the IBM Cognos10 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 URIconfiguration setting using IBM Cognos Configuration and the second step is toadjust 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 leftExplorer pane and click on the Gateway URI field.



of 45

Illustration 21: IBM Cognos Configuration showing the properties of theEnvironment element including Gateway URI

• Edit the Gateway URI field to reflect the actual URI used to call the ISAPIGateway. As a best practice, use a fully qualified domain naming scheme forthe 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 mustbe edited to change the redirect target from CGI to ISAPI. Be aware that editingdefault.htm has implications in that you can only redirect to one particular IBMCognos 10 Gateway module at a time. If you plan to enable the CGI gateway asan alternative as well, you need to decide which module shall be the default, eitherCGI or ISAPI. It is likely that users will prefer the shorter URL for accessing thesystem, 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 ISAPIshall 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);



of 45

and change cognos.cgi to cognosisapi.dllwindow.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.

Configuring IIS 7 for IBM Cognos CGI (optional)

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

As with the ISAPI module, a module mapping needs to be defined first and then themodule 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 inthe left pane of IIS Manager and select the Features View from the lower bar inthe middle pane.

2. Double-click on Handler Mappings in the middle pane. This will bring up the listof handler mappings for this application in the middle pane.

3. In the upper right Actions pane, click Add Module Mapping to add the CGImapping.

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.



of 45

Illustration 22: Add Module mapping dialog showing the requiredvalues 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.



of 45

Illustration 23: List of handler mappings showing the newly added CGImapping 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 toenable CGI execution.

Illustration 24: Edit Feature Permissions dialog showing the Executepermission being enabled

9. Click OK.



of 45

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 thecontent pane select the Features View tab at the bottom.

Illustration 25: Selecting a web server in IIS Manager from the tree view inthe right explorer pane

2. Double-click on the ISAPI and CGI Restrictions feature. This will bring up thelist 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 filewithin the IBM Cognos Gateway install. This file can be found in the<COG_ROOT>\cgi-bin directory. If browsing for the file, change the filetype to All files (*.*), since .cgi is not a default suffix.

• In the Description: field, specify a description of the restriction, such asIBMCOGNOS-CGI.

• Ensure that the check-box for Allow extension path to execute ischecked.



of 45

Illustration 26: Add ISAPI or CGI Restriction dialog showing thevalues 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 havebeen 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 moduleany 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 particularGateway implementation. To make that URL work it needs to be enabled andthe following steps will be required to make IIS load a default document from thespecified paths.

• In IIS Manager, in the left explorer pane select the virtual directory for IBMCognos 10 that was created earlier and switch to the Features View.



of 45

Illustration 27: Feature view of the IBM Cognos 10 BI alias, showing theDefault 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 isaccessed without specifying a particular document in it. The default.htm file containsJavaScript code to perform a redirect to the IBM Cognos 10 Gateway module after



of 45

showing a splash screen. By default the redirect will be to the CGI module so nofurther changes are required unless the default.htm was edited previously.

Accessing either URL should show you the IBM Cognos 10 log-in screen or, ifanonymous 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 theIBM Cognos 10 Gateway could not contact the IBM Cognos 10 BI server will appear.

Modify the Application Host or Web Configuration Files

IBM Cognos 10 requires some additional parameter to be configured for the ISAPIand/or CGI IBM Cognos 10 Gateway module mapping handlers. This is requiredso that IBM Cognos Administration and IBM Cognos Mobile function correctly.Unfortunately this parameter cannot be specified via the IIS Manager UI. This sectiontherefore 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 themodule mapping handlers. They can occur in one of two configuration files.

• If IIS is configured for Feature Delegation on handler mappings, youshould 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.configfile, 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 blankand 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 thatwas created by IIS at IIS installation time instead. This file can be found in theC:\Windows\System32\inetsrv\config directory.



of 45

Regardless of which configuration file contains the mapping handlers, the identifiedfile 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 ISAPIand/or CGI module mapping handler.

This parameter controls how the handler will populate the standard CGI environmentvariable PATH_INFO for the mapped module. By default, IIS sets it to the full URLwhich is not compliant with the CGI specification, however some applications, inparticular Active Server Pages, expect it that way. The IBM Cognos 10 Gatewaymodules however comply to the CGI specification and expect it to contain the lastpart 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 useMicrosoft’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 texteditor. Both methods will be described below but it is recommended that the appcmdtool 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 theconfiguration 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 ifdifferent from default. Also, if different values were specified for the IBM Cognos10 virtual directory (ibmcognos) or the module mapping name (IBMCOGNOS-ISAPI) they will need to be adjusted to your environment.



of 45

Illustration 29: Windows command window showing the execution of theappcmd 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 websitename if different from default and if different values were specified for theIBM 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 receivethe error “Error ( message:Cannot find requested collection element. )”, then omit the“/commit:apphost” option on the appcmd commands given above as follows. Onceagain, make sure to adjust the command to your environment regarding the names ofthe 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



of 45

Illustration 30: Windows command window showing an ERROR when issuingthe appcmd command

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 texteditor to modify the web.config or applicationHost.config files directly.

1. Make a backup copy of the identified configuration file containing the mappinghandlers.

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 findone 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 shouldbe:<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 CGImodule 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 shouldbe:<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.



of 45

Testing allowPathInfo

Log in to IBM Cognos Connection as a member of the System Administrator role andbring up IBM Cognos Administration. If IBM Cognos Administration comes up withouterror, the configuration is fine.

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

llustration 31: Error PF-SRV-6116 as displayed when calling IBM CognosAdministration if the allowPath configuration is missing

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

Performance Tips (Optional)

To help performance there are some small tweaks one can add to the IISconfiguration. The first tip is to define the content expiration so that unchanged staticweb content will be taken from the local browser cache instead requesting it fromthe server. The second tip is to define connection time-out to some low value so thatconnections get dropped earlier when being idle for too long. The third (and probablymost 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 clickingon it. During the course of this document we used ibmcognos as the name ofthe virtual directory.

2. Change to Features View at the bottom of the middle pane, then double-clickHTTP 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 periodto 10 days. Lower values mean that content will expire earlier (more requests) ,higher values will cause less requests.



of 45

llustration 32: The Set Common HTTP Response Headers dialog showingweb 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 CognosGateway 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 connectiontime-out set to 900 seconds



of 45

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

IBM Cognos 10 uses this protocol to allow browsing for images in studios whena report author wants to add images to reports and analysis. Out of the box, IBMCognos 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 10Gateway.

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 directorystructure of the web server are exposed and only authorized users are allowed toaccess files.

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

Enable WebDAV1. 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 accessNext step is to configure IIS authentication and authorization for the folderscontaining images. If the IBM Cognos 10 BI samples have been installed, therewill be a folder of sample images at <COG_ROOT>/webcontent/samples/imageswhich is accessible through IIS as <alias>/samples/images. We will use this folderto demonstrate the approach. Repeat it for any other folder containing images, evenwhen in different virtual directories than the IBM Cognos 10 BI one.

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

1. In IIS Manager's left explorer pane, find the <alias>/samples/images folderand 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 methodsfor this virtual folder in the middle pane.



of 45

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 foldershowing anonymous authentication being enabled

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

1. In IIS Manager's left explorer pane, find the <alias>/samples/images andselect it again by clicking on it.

2. Click on WebDAV Authoring Rules in the middle pane, showing the FeaturesView 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.



of 45

Illustration 35: Add Authoring Rules dialog showing the options todefine 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 IBMCognos 10 studios such as Report Studio.

Enable Secure Socket Layer (SSL) communication

For sake of completeness only this document will provide the pointers and stepsrequired to configure the IBM Cognos 10 Gateway for SSL. This task has severalsteps 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).



of 45

The first two steps are outside of the IBM Cognos domain and must be implementedby 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'ssubject and issuer shouldn't be identical. These certificates are consideredinsecure and are untrusted by IBM Cognos. They should be used for test ortroubleshooting only as they are unsuitable by modern security standards forproduction systems. Self-signed certificates must bear the CA:True X.509extension to work with IBM Cognos since they are server certificate and CAcertificate in one.The best practice is to set up your own Certifying Authority (CA) and have it signthe web server certificate with it's CA certificate. Microsoft Server 2008 containsthe Active Directory Certificate Services which can be used for this purpose.A free and widely adopted standard tool is OpenSSL which exists for manyplatforms and various guides can be found online.

• The web server certificate subject Distinguished Name (DN), that is theidentity used by the web server, must be the server name and shouldbe specified using Fully Qualified Domain Naming (FQDN) scheme likeCN=<serverhost>.<domain>.<suffix>, ...<other optional DN attributes>. This isbecause browsers will compare the certificate subject to the URL used to callthe 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 tocall the IBM Cognos 10 Gateway. The Gateway URI specified in IBM CognosConfiguration should always use FQDN, “localhost” is not feasible.

• SSL implements, amongst other things, encrypted communication. The protocoland method used for the encryption is called the cipher and is based on a keywhich, 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 of128bits and higher.The web server should be configured to disallow weak ciphers for securityreasons. IIS 7.x only supports strong ciphers and therefore adheres to this bestpractice out of the box. IBM Cognos 10 does support strong ciphers out of thebox and they are enabled for the supported ciphersuites option in IBM CognosConfiguration by default.

For details on how to configure IIS 7.x for SSL consult the following link on theMicrosoft 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 ConfigurationGuide, 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

http://learn.iis.net/page.aspx/144/how-to-set-up-ssl-on-iis-7-and-above/

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





of 45

While the general steps provided in the Information Center apply to the setupsdescribed 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:Trueextension) must be implemented on any IBM Cognos 10 install whichreferences the IBM Cognos 10 Gateway. This includes Application Tier installsand Content Manager installs, not only for IBM Cognos 10 BI but also for IBMCognos Planning, IBM Cognos PowerPlay and other tools of the IBM Cognos10 suite.

• In addition to changing the value of the Gateway URI in IBM CognosConfiguration, one must ensure the strong ciphers are enabled for SSL as well.To do this, in IBM Cognos Configuration check the Supported ciphersuitesproperty at Security > Cryptography > Cognos.

Illustration 36: The Supported ciphersuites property in IBM CognosConfiguration

Click on the Edit symbol to display the list of enabled cipher suites. The dialogwill display two lists, on the left will be one labeled Available values and on theright one labeled Current values. Current values should contain all entries fromAvailable values. If not, add ciphers from the Available values list by checkingthem and click the Add button in the middle between the two lists. Press OK tosave the changes.



of 45

Illustration 37: The Supported ciphersuites dialog in IBM CognosCofiguration showing the available and current ciphers configured

• If using other IBM Cognos client tools to connect to this IBM Cognos 10Gateway (for example IBM Cognos TM1 (Architect, Web), IBM CognosExecutive Viewer or even IBM Cognos Planning) these tools must establishtrust to the web server certificate as well by importing the CA certificate intotheir respective trust stores. It's a good idea to inform the administrator of theseIBM Cognos products that additional configuration steps are required. Not all ofthese tools use their own trust stores but leverage the machine trust store of theWindows box they run on. They should implement the step described next.

• For Internet Explorer clients, the CA certificate which signed the web servercertificate should be imported as a trusted root certification authority. Consultyour Windows administrator for details. The following link yields some basicguidance http://technet.microsoft.com/en-us/library/dd361898.aspx. Byemploying your favorite search engine, the internet will provide more verboseguides for this task.

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 achild to the main IBM Cognos 10 alias (virtual directory).

• Type in the URI or the virtual directory name.• IIS is not started.



of 45

HTTP Error 404.2 – Not Found

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

Illustration 38: Internet Explorer displaying the error HTTP 404.2 - Not Found

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 isstarted.

File Download dialog appears when accessing the ISAPI module

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



of 45

Illustration 39: File Download dialogue presented by IIS

Possible Solution:

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

PF-SRV-6116 when starting Cognos Administration

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

Illustration 40: The PF-SRV-6116 error upon launching IBM CognosAdministration

Possible Solution:

• The additional allowPathInfo parameter in the mapping handler for theaccessed IBM Cognos 10 Gateway module is missing or incorrectly configured.Refer to the section titled “Modify the Application Host of Web ConfigurationFiles” for details on how to rectify.

• Accessed the wrong IBM Cognos 10 Gateway module (for example CGI insteadof 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 adialog box:

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



of 45

Illustration 41: Web server error dialog when browsing for images in ReportStudio

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 IBMCognos 10 BI install.

Appendix A – IIS Installation RequirementsBefore being able to set up IBM Cognos 10 with IIS 7.x, the following installationprerequisites 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



of 45

• For cognosisapi.dll usage, the “ISAPI Extensions” Role Service must beinstalled

• 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 Rolesscreen now.

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

Illustration 42: Server Manager displaying the installed server roles and thecorresponding role services

Appendix B – Disabling Windows 2008 security features fortroubleshootingMicrosoft Windows 2008 (R2) introduced several new security features which allow toharden a machine. Amongst those are User Account Control (UAC), Internet ExplorerEnhanced 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 anAdministrator. Some behaviors which would render it reasonable to temporarilydisable a security feature for the purpose of ruling it out as the root cause are:



of 45

• DEP : Issues with Application Pools like CGI or ISAPI calls don't complete orcrash.

• IE ESC: IE blocking access to the Gateway URI, Error messages whenaccessing the Gateway URI, redirect not working.

• UAC: Need to run some executable as admin but admin credentials cannotbe shared. Ask the administrator to disable UAC temporarily during setup/configuration.

Disabling either of these features should be done temporarily for troubleshootingpurposes only. It is strongly advised to leave them all in place to adhere to securitypractices and standards. IBM Cognos 10 is completely compatible with all of thesefeatures. Be aware that disabling any of those features may impose a security riskto the server and may violate corporate security policies. For details on each ofthe 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.

http://technet.microsoft.com/en-us/library/cc754279%28WS.10%29.aspx

http://technet.microsoft.com/en-us/library/cc754279%28WS.10%29.aspx



of 45

Illustration 43: The User Account Control Settings dialog with the slidercontrol 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 ServerManager.

• In the Server Manager left explorer pane, select the root element labelledServer 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 supportedconfiguration options including Configure IE ESC



of 45

• This will have brought up the Internet Explorer Enhanced SecurityConfiguration dialog. Change the status of the IE ESC for Administrators andUsers to Off by clicking the associated radio buttons and press OK to save thechanges.

Illustration 45: Internet Explorer Enhanced Security Configuration dialogshowing 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.



of 45

Illustration 46: The Performance Options dialog showing DEP turned onfor only essential Windows programs and services

Appendix C - ReferencesMore information about IBM Cognos BI version 10 can be found at the followingURLs.

• 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 10http://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 athttp://technet.microsoft.com/en-us/library/dd361898.aspx.

http://www.ibm.com/support/docview.wss?uid=swg27019126

http://publib.boulder.ibm.com/infocenter/cbi/v10r1m0/index.jsp?lang=en

http://www.redbooks.ibm.com/abstracts/sg247912.html?Open

http://www.ibm.com/developerworks/data/library/cognos/security/cognos_bi_platform/page546.html

http://www.ibm.com/developerworks/data/library/cognos/security/cognos_bi_platform/page546.html

http://technet.microsoft.com/en-us/library/dd361898.aspx



of 45

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

http://www.iis.net



of 45

About the authors

Bastian Kiessling

Bastian Kiessling studied Network Computing at TU BergakademieFreiberg. He joined IBM Cognos in 2008 and since then has workedin the Installation, Configuration and Security team of the German IBMCognos Support. Currently he is working as a Problem ResolutionAnalyst supporting IBM ValueNet Partners and Support Analysts.

Ryan Laginski

Ryan Laginski has been a part of Cognos Business IntelligenceAccelerated Value Program for 6 years. His current role is AcceleratedValue Specialist for various BI customers. Areas of focus include theCognos Module on Smart Analytics, Applications Servers, Web Servers,AIX and zLinux.

Roger Östlund

Roger Östlund is a Cognos Technical Specialist, and has been workingwith IBM Cognos Controller implementations since 2002. Most recently,he has been acting as Technical Project Leader and expanding hisknowledge into the Cognos TM1 and SPSS tools.

© Copyright IBM Corporation 2011(www.ibm.com/legal/copytrade.shtml)Trademarks(www.ibm.com/developerworks/ibm/trademarks/)

http://www.ibm.com/legal/copytrade.shtml

http://www.ibm.com/developerworks/ibm/trademarks/

IBM Cognos 10 Microsoft Internet Information Services 7.x...

Documents

Transcript of IBM Cognos 10 Microsoft Internet Information Services 7.x...