ICS 4 Unix Installation

General Installation

The Integrated Control Suite™ (ICS) is a collection of modules designed to integrate directly into the IBM Cognos Analytics user interface, security system, content store and application server. This tight integration requires that the Integrated Control Suite™ be installed and configured on each server that comprises the IBM Cognos Analytics installation. If at any point problems are encountered or uncertainty arises, please contact support by emailing support@bspsoftware.com and the support team will provide assistance.

Installing version 4.0.x.xand higher

The ICS architecture now supports the ability to run a single database instance to support multiple ICS environments. This feature was first available in version 3.1.x.xand higher. The automatic installation process outlined below will guide the user through the process of configuring multiple ICS environments to use a single database instance.

Creating the ICS Database

Prior to running the ICS installation, create a new database instance in one of the supported database applications. Ensure proper credentials to create, alter, execute and drop objects exist. Upon startup, the ICS Service will install the database tables.

Installation Overview

The ICS Installation is comprised of three separate parts:

• ICS Server Installer

• ICS Plugin Installer

• ICS Extension Install

The ICS Server Installer will install the ICS web application comprised of an Apache Tomcat Server and a .NET core runtime environment. This installation should be performed on a server that is accessible to the IBM Cognos Analytics servers and may be installed on an IBM Cognos Analytics server if desired.

The IBM Cognos Analytics environment should be running during the ICS Server installation.

The ICS Plugin Installer will install integration components into the IBM Cognos Analytics installation. This install should be performed on each IBM Cognos Analytics Content Manager Server.

The IBM Cognos Analytics environment should be stopped during the ICS Plugin installation.

Notes: The plugin install is used to manage a filter file. The filter is still required in the IBM Cognos Analytics environment so that the instance knows that ICS has been integrated and is running. Future ICS Plugin upgrades are not required unless noted in the Hotfix guide and check all versions up to the current installed version for upgrades.

The ICS Extension package is uploaded into the IBM Cognos Analytics environment and serves as the gateway components for the ICS integration. (Manage > Customization > Extensions)

Unix Installation

In this section we will refer to the root Cognos directory as {Cognos}. The default root Cognos directory is “opt/ibm/cognos/c11” for Cognos 11.

Note: We referenced this Microsoft guide when developing the below process: https://docs.microsoft.com/en-us/aspnet/core/host-and-deploy/linux-apache?view=aspnetcore-6.0

Additional Requirements

In addition to the General Installation, you need to provide:

• Apache Webserver

• .NET 6

ICS Server – New Installation

To begin the ICS Server installation, download the ICS Unix Installer package and extract the UnixServer.zip file. Before running the ICS Server, installation be sure the IBM Cognos Analytics service is running.

1. Extract the “ICS4UnixInstall.zip” archive into a temporary location so that we can move files to your Unix environment.

2. From the extracted folder you will need to move the ics folder to var/www/ on your Unix environment.

Install .NET 6

To install .NET 6 run the following commands

1. sudo wget https://packages.microsoft.com/config/debian/10/packages-microsoft-prod.deb-O packages-microsoft-prod.deb

2. sudo dpkg -i packages-microsoft-prod.deb

3. sudo rm packages-microsoft-prod.deb

4. sudo apt-get update

5. sudo apt-get install -y apt-transport-https&&

6. sudo apt-get update &&

7. sudo apt-get install -y dotnet-sdk-6.0

8. sudo apt-get install -y dotnet-runtime-6.0

Install Apache

Note: We chose to create a bsp user during our installation. We will reference this user throughout this installation process.

1. Update CentOS packages to their latest stable versions.

   1. sudo yum update -y

2. Install the Apache web server on CentOS with a single yum command:

   1. sudo yum -y install httpd mod_ssl

Configure Apache

Configuration files for Apache are located within the /etc/httpd/conf.d/ directory. In Apache on Ubuntu, all the virtual host configuration files are stored in /etc/apache2/sites-available. Any file with the .conf extension is processed in alphabetical order in addition to the module configuration files in /etc/httpd/conf.modules.d/, which contains any configuration files necessary to load modules.

1. Create a configuration file, named icsservice.conf, for the app:

An example of our icsservice.conf file:

<VirtualHost*.*> RequestHeader set"X-Forwarded-Proto" expr=%{REQUEST_SCHEME} </VirtualHost>

<VirtualHost*.80> ProxyPreserveHost On ProxyPass / http://127.0.0.1:5000/ ProxyPassReverse / http://127.0.0.1:5000/ ServerName www.example.com ServerAlias *.example.com ErrorLog ${APACHE_LOG_DIR}icsservice-error.log CustomLog ${APACHE_LOG_DIR}icsservice-access.logcommon </VirtualHost>

2. Save the file and test the configuration. If everything passes, the response should be Syntax [OK].

a. sudo apachectl configtest

3. Restart Apache

a. sudo systemctl restart httpd b. sudo systemctl enable httpd

Monitor ICS

Apache is now set up to forward requests made to http://localhost:80 to the ASP.NET Core app running on Kestrel at http://127.0.0.1:5000. However, Apache isn't set up to manage the Kestrel process.  Use systemd and create a service file to start and monitor the underlying web app. systemd is an init system that provides many powerful features for starting, stopping, and managing processes.

1. Create a service file, named kestrel-ics4.service

a. sudo nano /etc/systemd/system/kestrel-ics4.service

An example of our kestrel-ics4.service file:

[Unit] Description=Example.NET Web API App running on CentOS 7

[Service] WorkingDirectory=/var/www/ics ExecStart=/usar/local/bin/dotnet/var/www/ics/ICS_Core.dll Restart=always #Restart service after 10 seconds if the dotnet service crashes: RestartSec=10 KillSignal=SIGINT SyslogIdentifier=ics4.net User=bsp Environment=ASPNETCORE_ENVIRONMENT=Production

[Install] WantedBy=multi-user.target

2. Save the file and enable the service

a. sudo systemctl enable kestrel-ics4.service

3. Start the service and verify that it’s running

a. sudo systemctl start kestrel-ics4.service b. sudo systemctl status kestrel-ics4.service

ICS Plugin – New Installation

To begin the ICS Plugin installation, download the ICS Unix Installer package and extract the Plugin.zip file.

Note: Before running this installation be sure the IBM Cognos Service is stopped.

1. Extract the Plugin.zip archive directly into the root of each IBM Cognos Content Manager Server.

Note: During testing theJava.exe located here was used: {Cognos installation}ibm-jre\jre\bin\Java.exe

Execute this command: “$java.exe -cp ICS.jar:lib/* com.bsp.ics.install.service.Main installplugin”

a. This command is also available in the UnixInstallCommands.txt file, located in the ics folder in the Cognos Root folder.

2. The Console will ask for a series of questions.

   1. The ICS Service location. Ex “localhost:7200”. This should match your environments private URL without the http://

   2. Instance Name, this must match exactly from the ICS Server – Instance Configuration. The Environment Name you entered in the ICS configuration for this environment

   3. Instance Id, this is the connection Id, you can copy from the ICS configuration
      

3. Once plugin finishes start cognos

Note: When you extract the files, they need to be in these locations. Here are some screens shots of how it looks in Windows, you should mirror this in Unix.

The ics folder should be in the root folder

The icsfilter.properties files need to be in the WEB-INF folder

ICS Extension – New Installation

Reference the installation and configuration guide for installation of the ICS extension.