c8.3 Installing Cognos8

Proven Practice
Application Servers – Installing

and Configuring the Cognos
Application
Product(s): Cognos 8, Application Servers
Area of Interest: Infrastructure
Application Servers – Installing and Configuring the Cognos 2
Application
Copyright
Copyright © 2008 Cognos ULC (formerly Cognos Incorporated). Cognos ULC
is an IBM Company. While every attempt has been made to ensure that the
information in this document is accurate and complete, some typographical
errors or technical inaccuracies may exist. Cognos does not accept
responsibility for any kind of loss resulting from the use of information
contained in this document. This document shows the publication date. The
information contained in this document is subject to change without notice.
Any improvements or changes to the information contained in this document
will be documented in subsequent editions. This document contains
proprietary information of Cognos. All rights are reserved. No part of this
document may be copied, photocopied, reproduced, stored in a retrieval
system, transmitted in any form or by any means, or translated into another
language without the prior written consent of Cognos. Cognos and the
Cognos logo are trademarks of Cognos ULC (formerly Cognos Incorporated)
in the United States and/or other countries. IBM and the IBM logo are
trademarks of International Business Machines Corporation in the United
States, or other countries, or both. All other names are trademarks or
registered trademarks of their respective companies. Information about
Cognos products can be found at www.cognos.com
This document is maintained by the Best Practices, Product and Technology
team. You can send comments, suggestions, and additions to
cscogpp@ca.ibm.com.
Cognos Proprietary Information

Application
Contents
1 INTRODUCTION ............................................................................................ 4
1.1 PURPOSE ............................................................................................................4
1.2 SCOPE ...............................................................................................................4
1.3 DEFINITIONS, ACRONYMS, AND ABBREVIATIONS .............................................................4
1.4 REFERENCES ........................................................................................................4
1.5 ASSUMPTIONS ......................................................................................................4
2 COGNOS 8 INSTALLATION WIZARD ............................................................. 5
2.1 COGNOS 8 INSTALLATION WIZARD .............................................................................5
2.1.1 Launch the Cognos 8 Installation Wizard ..............................................................5
2.1.2 Installation Location...........................................................................................5
2.1.3 Component Selection .........................................................................................7
2.1.4 Finish ...............................................................................................................8
3 COGNOS 8 UPDATES ..................................................................................... 8
4 GENERAL ENVIRONMENT SETUP .................................................................. 9
4.1 INSTALL DATABASE CLIENT(S) ..................................................................................9
4.2 INSTALL SECURITY PROVIDER FILES ............................................................................9
5 COGNOS CONFIGURATION ......................................................................... 12
5.1 SETUP THE ENVIRONMENT ..................................................................................... 12
5.2 AIX SPECIFIC ENVIRONMENT VARIABLES .................................................................... 12
5.3 LAUNCH COGNOS CONFIGURATION ........................................................................... 14
5.4 COGNOS CONFIGURATION SETTINGS ......................................................................... 16
5.4.1 Change URI Values .......................................................................................... 16
5.4.2 Delete the Tomcat Service Configuration ............................................................ 20
5.4.3 Remaining Cognos Configuration Changes .......................................................... 21
5.4.4 Save Cognos 8 Configuration Changes ............................................................... 21
5.5 BUILD APPLICATION FILES WIZARD .......................................................................... 22
5.5.1 Start the Build Application Files Wizard............................................................... 22
5.5.2 Select the Application Archives to be Built .......................................................... 22
5.5.3 Application File Type, Location and Context Root ................................................ 23
5.5.4 Build Application Files in Progress ...................................................................... 27
6 COGNOS 8 BUSINESS INTELLIGENCE MODELING...................................... 28
7 TROUBLESHOOTING / TIPS........................................................................ 29

Application
1 Introduction
1.1 Purpose
The purpose of this document is to detail the steps necessary to complete the transfer and configuration
phases of a Cognos 8 install to allow for a single server or a distributed implementation in an
application server environment.
The steps in this document represent common tasks that must be completed irrespective of the
application server being used.
1.2 Scope
Cognos 8 installation and general configuration will be covered in this document.
1.3 Definitions, Acronyms, and Abbreviations

Term Definition
Application Server A J2EE compliant Java application container environment. See
the
Cognos Support web site for a list of supported products.
JRE Java Runtime Environment
JVM Java Virtual Machine
Tomcat Servlet container that ships with Cognos 8
1.4 References
Ref. ID Author/Paper Location
Cognos 8 Installation and
Configuration Guide
<Cognos 8>/webcontent/documentation
1.5 Assumptions
• Single server install: The application server has been installed and configured with a single
server instance into which Cognos 8 will be deployed. The servlet gateway will not be used.
• Distributed install: The application server has been installed and configured with multiple
server instances into which Cognos 8 will be deployed.
• The hostname and port for each application server / JVM instance is known to the installer.
• The installation location has sufficient storage space to handle the install, the associated
application archive files, and temporary working space.
• If a web server is being used in the environment, that it is already installed and working.
• All required database clients are installed and tested.

Application
2 Cognos 8 Installation Wizard

Throughout this document, there will be notes that apply to a single server install and a distributed
install.
A single server install represents installing all the Cognos 8 components into a single location and
running ithin a single Java instance. This is ideal for demonstrations and low impact cases. The Cognos
8 Servlet Gteway cannot be used in a single server install as it must run in an isolated JVM instance. In
order to acess the Cognos 8 portal in a single server environment, a separate web server must be used,
or the Cognos 8 dispatcher can be accessed directly if the application is built with the static webcontent
option enabled.
A distributed install can comprise a variety of configurations. The examples in this document will
outline separating the Cognos 8 components in three distinct installs. The three components are
comprised of the Content Manager, Application Tier Components and the Gateway.
Many of these steps are similar for all Cognos 8 installs, even those that will run under Tomcat.
2.1 Cognos 8 Installation Wizard
2.1.1 Launch the Cognos 8 Installation Wizard

• Navigate to the mount point or Cognos 8 CD and run the Cognos 8 Installation Wizard
o Windows: issetup.exe
o Unix: issetup
• Select the language that you wish to use to perform the install
• Read and accept or decline the license agreement. If you decline, the installation will not
continue.
2.1.2 Installation Location

Enter the path into which you wish to install Cognos 8.
NOTE: Do not copy or rename a Cognos 8 installation directory when you

are using an application server. The installation path is stored in a file that
is used as part of the deployment so that the Java components of Cognos 8
can locate the remainder of the Cognos 8 product. If necessary, perform a
fresh install into the proper location.
Example: Windows Default Installation Location
NOTE: When installing into an application server environment, it is recommended that

you install into a path that does not contain spaces (Windows) as this causes issues for
some of the application server scripts. If absolutely necessary to install into a path with
spaces, use

Application
the DOS 8.3 naming convention where necessary to reference the install
path. (ie c:\program files\cognos\c8 would become
c:\progra~1\cognos\c8)
Example: Single Server – All Components Installation Location
In a distributed install where each component will run in a distinct JVM, each
component must be installed into a unique install location. There will be a direct one-
to-one correlation between the application server instance and the Cognos 8
installation. The Cognos 8 Installation Wizard must be run multiple times to
transfer the files to multiple locations.
Example: Distributed - Content Manager Installation Location
Example: Distributed - Application Tier Components Installation Location
Example: Distributed - Gateway Installation Location
The installation location does not have to exist prior to executing the Cognos 8
installation. If the path does not exist, you will be prompted to create it during the
install.

Application
2.1.3 Component Selection

Select the component(s) to install. By default, all components will be installed.
Example: Single Server – All Component Selection
Example: Distributed – Content Manager Component Selection
Example: Distributed – Application Tier Component Selection
Example: Distributed – Gateway Component Selection
Other distributed install combinations are possible and may be implemented in your
environment.

Application
• Shortcut Folder (Windows only) - For Windows, you may enter/change the
shortcut folder name to be used for Cognos 8 or accept the default value.
• Installation Summary - After all the selections have been made, you will be
presented with a summary page. Be sure to check the space requirements
carefully and allow for extra space for the application files and temporary
working space.
• Installation Progress - Installation will now proceed. Depending on the source

media and system speed, this step could take a few minutes to complete. On
Windows, anti-virus checking often slows this process as well due to the
number of files being transferred.
2.1.4 Finish
Once the installation is complete, you will be presented with a final page that will
indicate success or failure. You may select to view the logs and readme files at this
time.
Any errors during the transfer must be rectified prior to proceeding.
When installing into an application server environment, it is recommended that you

do not start Cognos Configuration at this time as there are additional steps that must
be completed prior to proceeding.
Example: Installation is complete
3 Cognos 8 Updates

Application
If you have any updates to Cognos 8 such as hotsite fixes or other patch files, now is
the time to apply them. They must be applied to each instance of Cognos 8 that
you have installed. It is critical that these be installed prior to building the web
application files.
Please refer to the documentation supplied with the update to obtain the correct
installation procedure.
4 General Environment Setup
4.1 Install Database Client(s)

Ensure that all necessary client software is installed and available to the user account
that will run the application server for access to the database that you will use for
Content Manager as well as your report database(s). The database that will be used
as the Content Manager data store must be created and a user id / password must
be given appropriate rights to the database.
It is recommended that you verify access to the database using an appropriate tool
(such as sqlplus) to ensure the client software is installed and configured correctly.
Keep in mind that this environment must be available to the user running the
application server and Cognos 8 and should therefore be setup in such a way that it
is set automatically and will be available if the server is restarted.
Important: Ensure that any java database client files are in place prior to
proceeding so that they will be properly included in the application archive
file that will be built later in this document. (example: classes12.jar for
Oracle Database) See the Cognos 8 documentation for more information
on setting up database clients.
4.2 Install Security Provider Files

Cognos Configuration requires that a number of security/encryption provider files be
copied into a location that the JRE that will be used by the application server can
access. This directory is location under <java>\<jre>\lib\ext. Cognos 8 ships the
required security provider files under <C8 install path>bin\jre\1.3.1\lib\ext on all
platforms.
Warning: To ensure that the application server environment is not

disrupted, only copy the files that are not already present, or do not
overwrite any existing files. You may wish to copy the original
<java>/<jre>/lib/ext directory to a backup location prior to copying the
Cognos 8 files.
Example: Cognos 8 Java Directory on Windows

Application
For a distributed environment, this step only needs to be performed once per
application server/JRE installation.
Note that each application server product will/may have a different location of the
JRE and the screen shot are provided only as examples. Some application servers do
not ship with a JRE and it must be installed separately.
Example: Oracle Application Server (Windows) JRE location after the security files
have been copied.

Application

Application
5 Cognos Configuration
5.1 Setup the Environment
Prior to launching Cognos Configuration or generating new encryption keys, you

must set the environment variable JAVA_HOME to point to the JDK that will be used
by the application server.
For most simple installations, it is recommended that the value be set as global
system environment variable (windows) or in a script (Unix). Many application
servers set this value in an environment script and this script can be run to setup
your environment. A reminder for Unix users, be sure to set the variables correctly
which may necessitate the “export” command as well. Different platforms and
different shell environments use slightly different syntax to accomplish this task.
Example: Windows Global System Environment Variable
On Unix, the JAVA_HOME variable can be set for the terminal session, in the user
profile or whatever means is appropriate for your environment.
Example: Unix Terminal Window
5.2 AIX Specific Environment Variables

On AIX, there are additional environment variables that should be set for memory
management and performance. Be sure to set the following variables to the indicated
values (as a starting point)
LDR_CNTRL MAXDATA=0x40000000

Application
MALLOCMULTIHEAP true
SPINLOOPTIME 50000
IBM_JAVA_MMAP_JAVA_HEAP true
This must be done for each shell or environment in which Cognos 8 will run. So, set
these in the profile or common environment setup script that runs in each instance.

Application
5.3 Launch Cognos Configuration
The following steps represent a single server installation.
If you are performing a distributed installation:

• Follow the steps as indicated starting with the Content Manager distributed
install. Complete all related tasks and start Cognos 8 Content Manager and
leave it active and running.
• Once the Cognos 8 Content Manager is running, repeat the steps making the
appropriate changes and start the Cognos 8 Application Tier Components.
• Finally, repeat the steps making the appropriate changes and configure the
Cognos 8 Gateway component.
To start Cognos Configuration after setting the JAVA_HOME environment variable,

navigate to the <C8 installation>\bin directory and run the batch file cogconfig.bat
(Windows) or the script cogconfig.sh (Unix).
Example: Windows cogconfig.bat file
Example: Unix cogconfig.sh script
If the security provider files were not copied to the correct location, you may
encounter an error.
Example: Security provider files could not be found (Windows)

Application
The batch file (Windows) or script file (Unix) will also indicate which JRE was found
based on the JAVA_HOME environment variable. This should be checked to ensure
the correct one is being used.
Example: Batch file output on Windows – check J_HOME value
Example: Script output on Unix
If Cognos Configuration was run previously and there are existing encryption keys,
then you may encounter a warning dialogue. This dialogue indicates that an
alternative JRE vendor or version was used previously and the keys are not
compatible with the current JRE vendor or version.
Example: Existing Encryption Keys
If the correct JRE is indeed referenced, then you may select the option to
automatically regenerate new encryption keys. This is typical when switching
between a Tomcat environment and an application server environment.

Application
Example: Regenerate Encryption Keys
Ensure that all steps complete successfully during the regeneration process prior to
proceeding. If the automatic regeneration of the encryption keys fails for any reason,
it may be necessary to follow the manual key recreation steps outlined in the Cognos
8 Installation and Configuration Guide, Chapter 8.
5.4 Cognos Configuration Settings
The default values in Cognos Configuration represent the out-of-box Tomcat solution
and therefore there are a number of settings that must be changed to suit your
application server environment. Obviously there are many other options that you
may have to alter that will not be covered in this document.
5.4.1 Change URI Values

A Cognos 8 URI contains the following elements:
• For a Content Manager or Dispatcher URI’s
protocol://host_name_or_IP:port/context_root/alias_path
• For a Gateway or Web content URI
protocol://host_name_or_IP:port/virtual_directory/gateway_application
or
protocol://host_name_or_IP:port/context_root/alias_path
Protocol
This element specifies whether standard (http) or secure (https) communication is
used when transmitting or receiving information.
Host Name or IP

Application
The host name is the name of the server as it is identified on the network. You may
use an IP address if name resolution is not possible. You must change the localhost
element of a URI to a server name, fully qualified domain name, or IP address in a
distributed installation. In a mixed environment of UNIX and Windows servers,
ensure that host names can be resolved to IP addresses by all servers in the
environment. Also ensure that the application server is configured to listen on the
value entered.

Application
Port
This element specifies the port on which the host system has a socket open to listen
for requests. The value entered must match the value in your Web server, Tomcat,
or application server configuration.
Context Root
The context root element is used by the Web server, Tomcat, or the application
server to route requests to the appropriate Java application. The context root can
only be changed if you are using an application server. In a distributed Cognos 8
environment, the context root for all application deployments must be the same,
with the exception that the Servlet Gateway application can have a unique value.
The context root must be a single entity, i.e. it may not contain slashes (“/”).
Alias Path
This portion of the URI must not be modified or Cognos 8 components will not
function correctly. The value is defined and used internally by Cognos 8.
Virtual Directory
This element must indicate the virtual directory alias exactly as it is defined in your
Web server configuration. For example, in the default Gateway URI of
http://localhost:80/cognos8/cgi-bin/cognos.cgi, the virtual directory is cognos8/cgi-
bin.
Gateway Application
The Gateway URI must include a reference to the gateway application. For example,
if you are accessing Cognos 8 components using a Common Gateway Interface
(CGI), then the default gateway application would be cognos.cgi.
In the Cognos Configuration Explorer window, under environment, set the appropriate values for all
URI entries used in your environment.
Example: Single Server - Cognos Configuration Default Values (Tomcat)

Application
Example: Distributed Content Manager - Cognos Configuration Default Values (Tomcat)
Example: Distributed Content Application Tier - Cognos Configuration Default Values (Tomcat)
Example: Distributed Gateway - Cognos Configuration Default Values (Tomcat)

Application
Example: Single Server – shows hostname as “localhost”, “127.0.0.1” &

“servername”. Port has been changed to 9081
5.4.2 Delete the Tomcat Service Configuration

By default, a Cognos 8 service entry will be defined in Cognos Configuration. As this
setting is used only for configuring to run under Tomcat, it should be removed.
To delete the entry, right-click on it and select “delete” as the action.
Example: Delete the Cognos 8 Service
As a safety measure, you will be prompted to confirm the removal of the Cognos 8
service. Should you wish to return to run under Tomcat, this service can be added
back into Cognos Configuration at a later time.

Application
5.4.3 Remaining Cognos Configuration Changes
• Navigate to the Content Manager Content Store field and enter the appropriate values for your
environment. Please see the Cognos 8 customer documentation for creating other Content
Store types.
• At this time you should make any other changes within Cognos Configuration
that are necessary for proper operation in your environment. Depending on
your setup, no other changes may be required.
5.4.4 Save Cognos 8 Configuration Changes

Once all the configuration changes have been made, you can save the configuration.
During the Save operation, encryption keys will be created using the JRE referenced
by the JAVA_HOME variable. Other actions such as backing up the configuration files
will also take place.
Reminder: For an Application Tier distributed install, the Content Manager must be
up and running in order for the Save operation to complete successfully.
Reminder: For a Gateway distributed install, the Content Manager and the
Application Tier must be up and running in order for the Save operation to complete
successfully.

Application
5.5 Build Application Files Wizard
Note: Should it be necessary to make any configuration changes in the future, it is

not necessary to recreate the application archive file. Make and save the appropriate
changes, then stop and restart the application server instance for the changes to be
recognised.
5.5.1 Start the Build Application Files Wizard

The Cognos Configuration Build Application Files Wizard can be run to create and
package all the files that are necessary to deploy to the application server.
Important: The Application file does not contain any of the configuration
information as entered into the Cognos Configuration UI and therefore the
application files does not have to be rebuild or redeployed should you wish to make
configuration changes. It does however contain a reference link to the actual
Cognos 8 installation directory and therefore you should not manually rename or
move the Cognos 8 install. Since the Cognos 8 install path is embedded in the
application file, the application file should not be used to deploy into multiple
application server installs or the one-to-one relationship will not be maintained. The
exception to this statement is deployment into a WebSphere cluster and the
configuration for that is covered in a separate document.
The Wizard can be initiated by selecting the Build Application Files option located in
the Actions menu.
Example: Initiating the Build Application Wizard
5.5.2 Select the Application Archives to be Built

The first step of the wizard allows you select the type of application that you are
building. The options may vary depending on the Cognos 8 components that you
have actually installed.
The main application, “Cognos 8” represents either or both the Content Manager and
Application Tier Components.

Application
• If you are going to use the application server as a Web Server and service
the Cognos 8 static content (images, javascripts, etc) from the application
server then select the option to include the static files into the application file.
If you are using a separate Web Server or the Servlet Gateway, then it is not
necessary to include this content and the resulting application file will be
much smaller and faster to deploy.
The Servlet Gateway can be selected, built and deployed to your application server
to replace the Web Server and gateway combination.
You may select to build the main Cognos 8 application, the Cognos 8 Servlet
Gateway application, or both applications.
Example: Build Application Wizard Application Selection
5.5.3 Application File Type, Location and Context Root

If you have elected to build the main Cognos 8 application file, you will be presented
with a number of options.
You may select a file type. An application server may require a specific file type for
proper deployment and management in its own environment. The Cognos 8
customer documentation and the application server vendor documentation should be
consulted. In most cases, an Enterprise Application Archive (EAR) file may be
selected. Older application servers may not support EAR files and therefore a Web
Archive (WAR) file is an alternative. Some application servers such as BEA WebLogic
also permit an application to be placed directly into a folder that it will manage. In
this case, the third file type, expand files into a folder, should be selected.
The Location entry represents the path and filename of the application file that will
be created by the wizard.

Application
Only if necessary, you may also change the context root value. Keep in mind that the
context root value for the Cognos 8 application must be consistent across your entire
install if you are performing a distributed install. In addition the value entered here
must match the value entered in the URI entries on the main Cognos Configuration
page as well as be identical to the context root value that you enter when deploying
the application file into the application server. Application servers that use the
Expand files into a folder option will use the folder name as a context root value.
WAR files will not store the context root value and it must be manually entered when
deploying the application into the application server.

Application
Example: Cognos 8 application file selections
Similar to the Cognos 8 application, the Cognos 8 Servlet Gateway will also allow you
to specify the file type, location and name of the application file as well as the
context root. Note that the context root in this case is not the same as the context
root of the Cognos 8 application above.

Application

Application
5.5.4 Build Application Files in Progress
After making the appropriate selections, the Build Application File Wizard will indicate
its progress as it builds the application files.
Example: Building the Cognos 8 application and the servlet gateway application
A number of files must be copied, manipulated and packaged into the application file
by the wizard so this step may take a few moments to complete based on your
selections.
Example: Build of Application Files Completed
This concludes the basic portion of the transfer and setup of Cognos 8 for a single
server installation.
In a distributed installation, repeat the various tasks as necessary to transfer and

setup Cognos 8 in preparation for deployment into an application server

Application
6 Cognos 8 Business Intelligence Modeling

In order to be able to create and publish modeling information, Cognos 8 Business
Intelligence Modeling must be installed and configured for your environment. Follow
the Cognos 8 Business Intelligence Modeling installation instructions.
Launch Cognos 8 Business Intelligence Modeling Configuration and make the

changes appropriate to your environment.

Application
7 Troubleshooting / Tips
If you encounter any encryption key issues, you can verify which JRE was actually used by Cognos
Configuration by looking at <cognos8>/configuration/cogconfig.prefs in both Windows and Unix. The
JRE path, vendor and version will be listed in the text file. This file must not be manually edited unless
directed by Cognos support.
Example: cogconfig.prefs text file

c8.3 Installing Cognos8

Diunggah oleh

Informasi Dokumen

Deskripsi Asli:

Judul Asli

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

c8.3 Installing Cognos8

Diunggah oleh

Hak Cipta:

Format Tersedia

Proven Practice

Application Servers – Installing

Cognos Proprietary Information

Cognos Proprietary Information

1.3 Definitions, Acronyms, and Abbreviations

Cognos Proprietary Information

2 Cognos 8 Installation Wizard

2.1 Cognos 8 Installation Wizard

2.1.1 Launch the Cognos 8 Installation Wizard

2.1.2 Installation Location

NOTE: Do not copy or rename a Cognos 8 installation directory when you

Example: Windows Default Installation Location

NOTE: When installing into an application server environment, it is recommended that

Cognos Proprietary Information

Example: Single Server – All Components Installation Location

Example: Distributed - Content Manager Installation Location

Example: Distributed - Application Tier Components Installation Location

Example: Distributed - Gateway Installation Location

Cognos Proprietary Information

2.1.3 Component Selection

Example: Single Server – All Component Selection

Example: Distributed – Content Manager Component Selection

Example: Distributed – Application Tier Component Selection

Example: Distributed – Gateway Component Selection

Cognos Proprietary Information

• Installation Progress - Installation will now proceed. Depending on the source

Any errors during the transfer must be rectified prior to proceeding.

When installing into an application server environment, it is recommended that you

Example: Installation is complete

Cognos Proprietary Information

4 General Environment Setup

4.1 Install Database Client(s)

4.2 Install Security Provider Files

Warning: To ensure that the application server environment is not

Example: Cognos 8 Java Directory on Windows

Cognos Proprietary Information

Cognos Proprietary Information

Cognos Proprietary Information

5.1 Setup the Environment

Prior to launching Cognos Configuration or generating new encryption keys, you

Example: Windows Global System Environment Variable

Example: Unix Terminal Window

5.2 AIX Specific Environment Variables

Cognos Proprietary Information

Cognos Proprietary Information

5.3 Launch Cognos Configuration

The following steps represent a single server installation.

If you are performing a distributed installation:

To start Cognos Configuration after setting the JAVA_HOME environment variable,

Example: Windows cogconfig.bat file

Example: Unix cogconfig.sh script

Example: Security provider files could not be found (Windows)

Cognos Proprietary Information

Example: Batch file output on Windows – check J_HOME value

Example: Script output on Unix

Example: Existing Encryption Keys

Cognos Proprietary Information

Example: Regenerate Encryption Keys

5.4 Cognos Configuration Settings

5.4.1 Change URI Values

• For a Content Manager or Dispatcher URI’s

• For a Gateway or Web content URI