Troubleshooting
Problem
This document details steps for tracing authentication processes in IBM Cognos BI. Typically those traces are requested by Customer Support to analyze issues.
Cause
Authentication in Cognos BI is handled by a subcomponent of the Content Manager install component called Cognos Access Manager (CAM), not to be mixed up with Series7 Access Manager. CAM offers authentication Services through a component called AAA. When dealing with authentication issues it is mandatory to collect a trace of messages generated by CAM-AAA as they will enable efficient troubleshooting. This log file is often called a triple A trace, AAA trace or CAM trace.
If the setup contains a Custom Java Authentication Providers (CJAP) an additional log file can be generated containing the calls sent by CAM to the CJAP implementation code. Tracing/Logging of the CJAP itself is up to the CJAP and is not provided by the product.
Environment
The steps provided will work on every set-up, although some adjustments may be required. Refer to the steps below for details.
Resolving The Problem
In Cognos BI, many logging mechanisms are based on the Indication Processing Facility (IPF). This layer works similar to log4j - a de facto standard for logging in JAVA applications.
To enable CAM logging, a special file containing logging configuration information must be present in the /configuration subfolder of the Content Manager install. The file must be called ipfclientconfig.xml. The system keeps a watch on that file and if present, it will be read and processed instantly, no restart required. The same is true for disabling.
As of Cognos 10, the product install contains templates for ipfclientconfig.xml files for several components. Those will be disabled by default by adding .sample extensions to them.
For CAM, the file is called ipfaaaclientconfig.xml. For activation, it has to be renamed to ipfclientconfig.xml. The result will be an additional log file AAAclient.log written to the /logs folder, the AAA trace file.
As this tracing activity can impact performance, it is important that the file be renamed (so as to disable the tracing) once complete.
Please note that an actively configured auditing database may not receive any data from the system while the ipfclientconfig.xml is active. If this is crucial, please address the issue with Customer Support, as they can provide a version of ipfclientconfig.xml that will not disturb audit logging..
For tracing calls sent by CAM to a CJAP, a file named aaa.properties has to be dropped into the /configuration folder. As with the ipfclientconfig.xml file, it is read and processed if found but this one requires a restart. To disable the trace, simply rename the file to something else.
Steps to enable an AAA trace:
- In the install running the active Content Manager, navigate to the /configuration directory.
- Make sure there is no file named ipfclientconfig.xml within the directory. If present, it indicates that tracing is already being performed. If that is the case, please consult with your Administrator to verify whether the current trace can be stopped. To disable, simply rename the file to ipfclientconfig.xml.off, for example.
If Cognos 10 is running in Tomcat, skip to Step 7, otherwise proceed.
In non-Tomcat environments, the log file must be referred to by absolute path using forward slash ("/"), no backslash.
- Open ipfaaaclientconfig.xml.sample file in a text editor.
- Search for a line containing
<param name="File" value="../logs/AAAclient.log"/> - Edit the value to specify an ABSOLUTE path including the filename like
<param name="File" value="c:/Programs/cognos/logs/AAAclient.log"/>
or
<param name="File" value="/usr/cognos/logs/AAAclient.log"/> - save the file
- Copy the ipfaaaclientconfig.xml.sample file and rename it to ipfclientconfig.xml.
- Wait 30 seconds for the Cognos System to recognize the new configuration parameters which begins the tracing and records the information to a file named AAAclient.log in the /logs folder.
- Recreate the authentication related issue.
- Remove the ipfclientconfig.xml file by renaming it to ipfclientconfig.xml.sample
- Provide Cognos Customer Support with the resultant AAAclient.log along with all other files in the /logs folder. Zip/tar formats are appreciated.
Steps to enable the additional CAM->CJAP interface trace:
- In the install running the active Content Manager navigate to the /configuration directory.
- Make sure there is no file named aaa.properties within the directory. If present, it indicates that tracing is already being performed, please consult with your Administrator to verify whether the current trace can be stopped. To disable simply rename the file to aaa.properties.off for example.
- Either drop into place (/configuration folder) the attached aaa.properties file or rename an existing aaa.properties.sample to aaa.properties.
- Edit the aaa.properties file to specify an absolute path for the logfile using forward slash ("/") including filename. The result for example should look like this:
#############################
# Custom Provider Debugging #
#############################
trace.output=c:/Programs/cognos/logs/CJAP.log
trace.debug=true
trace.debug.exception=true
trace.debug.API=true
trace.debug.logic=true
- Save the file and restart Content Manager
- Recreate the authentication related issue.
- Remove the aaa.properties file by renaming it to aaa.properties.off
- Provide Cognos Customer Support with the resultant CJAP.log along with all other files in the /logs folder. Zip/tar formats are appreciated.
Related Information
- 1041712_2.zipWas this topic helpful?
Document Information
Modified date:
15 June 2018
UID
swg21343375