IBM Support

How to create a Gateway server (to allow 'Classic' client to use t=controller parameter) when using Cognos BI (for example Controller 10.1 with Cognos BI 10.x)

How To


Summary

Customer would like to configure their architecture so that end user's Controller 'classic' clients (in other words, the program CCR.EXE) do not connect directly to the main Controller application server. Instead they connect to a separate 'gateway' server.
- In other words, they want to achieve something similar to what is described inside separate IBM Technote #386373

How can they achieve this, when using Cognos BI (not the more modern 'Cognos Analytics')?

Objective

The Controller classic client (CCR.EXE) is the software client that look like this:
image 5484
  
When customers install the classic client, they type in a value of WSS Url, for example:
image 5487
  • WSS Url defines which website the Controller client connects to.
In the above example, it shows the default setting which means that the Controller client connects to this website: http://servername/ibmcognos/controllerserver/ccrws.asmx
  •  In other words, by default, the classic client connects directly to the IIS webserver of the 'main' Controller application server (in the above example it is called 'servername').
However, this Technote specifically relates to the scenario where the customer would like to instead have their 'classic' client connect to a different 'gateway' server (not the 'main' server):
image 5475
  • This is so that all classic client client<=>server communication travels via the Cognos BI 'gateway' server (which acts as a 'relay'/'proxy').

Environment

This Technote is based on the following software versions:
  • Controller 10.1.1
  • Cognos BI 10.2.x
For instructions using more modern versions of Controller (which use Cognos Analytics, not Cognos BI) see separate IBM Technote #386373.

Steps

Assumptions:
The following instructions assume that:
  • All webservers are using HTTP over TCP port 80 (for example not HTTPS over 443).
    • If you want to use SSL then (afterwards) use the instructions inside separate IBM Technote #372873.
  • It only refers to the settings that are 'different from normal' (settings that need to be changed to ensure that the DMZ configuration works)
  • It assumes that the reader is familiar/comfortable with the other settings (for example 'Internal Dispatcher URI'), and has configured them with the appropriate 'normal' values (for example 'http://<appserver>:9300/p2pd/servlet/dispatch')
  • It assumes that the system is configured to use CGI (not ISAPI).

    Steps:
    To make it easier to follow, this has been split into sections.
    • Each section contains parts to perform on the "Gateway" server (inside the DMZ), and parts to be done on the Controller application server (inside the LAN)
    • These are clearly labelled with " <gateway>" and "<appserver> " headings

    ====================================================
    First of all, perform all of the basic preparation (prerequisites) on each server, such as install Microsoft IIS.
    • TIP: If the reader is unfamiliar with how to perform these, then see Best Practice installation documentation, which is available inside Technote #213339.

    <gateway>
    Install the following:
    • Microsoft IIS (web server) including "Application Development - CGI"
    • Enable CGI ("Allow unspecified CGI modules")
    • Increase IIS timeout to 60 minutes
    • Microsoft SOAP 3.0 SDK (CNTRL_SOAP_10.1.1_Win32_TK001.msi)
     
    <appserver>
    Install *all* of the prerequisites (such as IIS, SOAP, etc.) as listed inside the best practice installation documentation (for example "Installing & Configuring IBM Cognos Controller 10.1.1 server - Proven Practice").
     
    ====================================================
    Next, install the relevant component files on each server:
     
    <gateway>
    • Navigate to the Controller installation media, and launch the installation wizard ("issetup.exe")
    image 5491
    • At the screen 'Component Selection' choose/select only the 'Gateway Components', and then complete the wizard
     
    <appserver>
    • Navigate to the Controller installation media, and launch the installation wizard server, and launch the installation wizard
    • At the screen 'Component Selection' for most customers your should choose/select all components:
    image 5492
    For the record:
    • If all users are going to be 'remote users' (connecting via the gateway in the DMZ) then there is no need to create/install a gateway on the main (LAN) application server, so therefore you do not need to tick 'Gateway Components' (however it does no harm to install it anyway!):
    • Naturally you only need to install the FAP components if you intend to use FAP functionality.

    ====================================================
    If required, patch both servers with the relevant latest Controller FixPack (or interim fix).
    • TIP: Care needs to be taken (during the patching process) to ensure that all Controller-related services/systems/components are stopped. See IBM Technotes for full details.
    ====================================================

    Then, ask your network administrator to modify the firewall (between the LAN and the DMZ) to:
    (1) Allow internet users access to <gateway> via TCP port 80 
    • In other words, open the firewall to allow TCP traffic on port 80 between the external client devices (on the Internet) and the gateway server's external IP address (in the DMZ)
    (2) Allow communication between <gateway> and <appserver> on TCP ports 80 and 9300 
    • In other words, open the firewall to allow TCP traffic on port 80 between the gateway server's IP address (which may be an 'internal' LAN IP address or an 'external' DMZ IP address - it all depends on your DMZ/firewall configuration) and the application server's (internal/LAN) IP address.

    ====================================================
    Create the correct/relevant IIS virtual directories on each server, as summarised below:

    (1) Gateway:
    • ibmcognos
    • ibmcognos\cgi-bin
    • ibmcognos\controller
    • ibmcognos\controllerhelp

    Afterwards, perform the relevant IIS configurations (see best practice installation documentation for full details). For example, with Windows 2008 you must:
    • configure "Handler Mappings" for the virtual directory "cgi-bin"
    • configure: allowPathInfo="true"

    (2) Appserver:
    • ibmcognos
    • ibmcognos\cgi-bin
    • ibmcognos\controllerserver

    TIP: You do not need to create the 'ibmcognos\cgi-bin' virtual directory if you are not going to install/use a gateway on the LAN application server.
    • In other words, if all users are going to be 'remote users' (connecting via the gateway in the DMZ) then there is no need to create/install a gateway on the main (LAN) application server, so therefore you do not need to create the 'cgi-bin' virtual directory. However, this scenario is unlikely (most customers would instead have some users accessing a 'LAN' gateway, and other users accessing a 'DMZ' gateway).

    Afterwards, perform the relevant IIS configurations (see best practice installation documentation for full details). For example, with Windows 2008 you must:
    • configure "Handler Mappings" for the virtual directory "cgi-bin"
    • configure: allowPathInfo="true"

    ====================================================
    Next, use the configuration programs on each server:

    (1) <gateway> server
    Because we are using the 't=' parameter, we must also explicitly configure Cognos BI's ControllerURI setting, to use the CCRWS.ASMX location, as follows:
    1. Launch Cognos Configuration
    2. Inside the 'environment' section modify the following:
    3. Dispatcher URI's for gateway: http://<appserver>:9300/p2pd/servlet/dispatch/ext
    4. Controller URI for gateway: http://<appserver>:80/ibmcognos/controllerserver/ccrws.asmx
     
    You must also increase the value of 'Maximum allowed content length' for the CGI-BIN virtual directory (on the gateway.)
    • The following instructions are based on Windows 2012. The steps may vary slightly depending on your operating system:
    1. Logon to the gateway server
    2. Launch IIS Mananger/administration tool
    3. Browse to find the following website: <default web site>\ibmcognos\cgi-bin
    4. Open section 'Request Filtering'
    5. Click on 'Edit Feature Settings'
    6. Click on 'Rules'
    7. Change this to:      3145728000
     
    (2) <appserver> server
    OPTIONAL: If you want all users (even those on the LAN) to utilise the DMZ gateway server, then you must now inform the 'main' (LAN) Application server where the Controller gateway server is by doing the following:
    1. Launch Cognos Configuration
    2. Inside the 'environment' section modify the following (under 'Gateway Settings'):
    3. Gateway URI: http://<gateway>:80/ibmcognos/cgi-bin/cognos.cgi
     
     
    (3) Client device
    Configure each end user's classic clients to use the 'relay/proxy' functionality of the gateway (not connect directly to the main Controller application server) by using the 't=controller' parameter.
     
    New classic client installs:
    During the installation wizard, choose the WSSUrl to be similar to:
    • http://gateway/ibmcognos/cgi-bin/cognos.cgi?t=controller
     
    Existing classic client installs:
    On the client device:
    • Browse to the installation folder (TIP: By default: C:\Program Files\IBM\IBM Cognos Controller Local Client)
    • Open the following file in NOTEPAD:   CCR.exe.config
    • Locate the setting similar to:
                <add key="WSSUrl" value="http://mainserver/ibmcognos/controllerserver"/> 
    • Modify it to something similar to:
                <add key="WSSUrl" value="http://gateway/ibmcognos/cgi-bin/cognos.cgi?t=controller"/> 
    • Save changes and test.
    ====================================================
    Appendix: Classic client 'Web download' method
    It is extremely rare for customers to deploy Controller classic client using the legacy 'web download' method.
    • TIP: For an explanation of what this method is, see separate IBM Technote #123099.
    In this rare scenario, you need to modify the Client Distribution Server settings::
    1. Launch Controller Configuration
    2. Open the section 'Controller Client Distribution Server'
    3. Modify the CASUrl: http://<gateway>/ibmcognos/controllerbin
    4. Modify the WSSUrl: http://<gateway>/ibmcognos/cgi-bin/cognos.cgi?t=controller
    5. Modify the HelpUrl: http://<gateway>/ibmcognos/controllerhelp
    ====================================================

    Document Location

    Worldwide

    [{"Business Unit":{"code":"BU059","label":"IBM Software w\/o TPS"},"Product":{"code":"SS9S6B","label":"IBM Cognos Controller"},"ARM Category":[{"code":"a8m0z0000000AxnAAE","label":"Documentation"}],"ARM Case Number":"","Platform":[{"code":"PF025","label":"Platform Independent"}],"Version":"10.1.0;10.1.1;10.2.0;10.2.1;8.5.1","Line of Business":{"code":"LOB10","label":"Data and AI"}}]

    Document Information

    Modified date:
    10 August 2020

    UID

    ibm16257771

    Page Feedback