Version 7.1: Troubleshooting Guide - e IBM Tivoli Composite

Security Policy ManagerVersion 7.1

Troubleshooting Guide

GC27-2711-00

��

Security Policy ManagerVersion 7.1

Troubleshooting Guide

GC27-2711-00

��

NoteBefore using this information and the product it supports, read the information in “Notices” on page 61.

This edition applies to version 7, release 1, modification 0 of IBM Tivoli Security Policy Manager (product number5724-S24) and to all subsequent releases and modifications until otherwise indicated in new editions.

© Copyright IBM Corporation 2010.US Government Users Restricted Rights – Use, duplication or disclosure restricted by GSA ADP Schedule Contractwith IBM Corp.

Contents

About this publication . . . . . . . . vIntended audience . . . . . . . . . . . . vPublications . . . . . . . . . . . . . . v

IBM Tivoli Security Policy Manager library . . . vPrerequisite publications . . . . . . . . . viAccessing terminology online . . . . . . . viAccessing publications online . . . . . . . viOrdering publications . . . . . . . . . . vi

Accessibility . . . . . . . . . . . . . . viiTivoli technical training . . . . . . . . . . viiSupport information . . . . . . . . . . . viiConventions used in this book . . . . . . . . vii

Typeface conventions . . . . . . . . . . viiOperating system differences . . . . . . . viii

Chapter 1. Introduction totroubleshooting . . . . . . . . . . . 1

Chapter 2. Learning about problemsymptoms . . . . . . . . . . . . . . 3About troubleshooting . . . . . . . . . . . 3About connectivity problems . . . . . . . . . 5About Tivoli Security Policy Manager . . . . . . 5

Installation from a mounted ISO image displaysan error message . . . . . . . . . . . . 6Cannot reinstall after a failed installation . . . . 7Migration is disabled after migration is completed 9LDAP provisioning fails . . . . . . . . . 10Configuration tool fails during security task . . 10Configuration tool fails during Services securitytask . . . . . . . . . . . . . . . . 11Console does not work . . . . . . . . . 12Various timeout errors occur. . . . . . . . 12Tivoli Security Policy Manager server certificatemust be replaced . . . . . . . . . . . 13Components are unable to communicate. . . . 16Parent permission not selected when all childpermissions are selected . . . . . . . . . 16Anonymous workspaces are created in thewstemp directory . . . . . . . . . . . 17Detailed information for file handler exception ismissing . . . . . . . . . . . . . . . 17Console session timeout occurs . . . . . . . 17No policies distributed status . . . . . . . 18User registry search using the wildcard symboldoes not produce expected results . . . . . . 19User registry search causes console to hang. . . 19One or more reports from the Tivoli CommonReporting component fail. . . . . . . . . 19Cannot configure a policy . . . . . . . . 20Problems importing a service from a file. . . . 20Text and tables do not wrap in console window 21

About runtime security services components . . . 22Using a stand-alone user registry with runtimesecurity services components . . . . . . . 23

WS-Security configuration issues . . . . . . 24Registration utility fails . . . . . . . . . 25Registration fails and error CWWSS5508E occurs 25Registration fails with an "Untrusted SecurityPolicy Manager Certificate Fingerprint" . . . . 26Certificate-related error messages are displayedduring registration . . . . . . . . . . . 27Exception error occurs during startup of theruntime security services client . . . . . . . 27Expired certificates . . . . . . . . . . . 28

About fixes and updates . . . . . . . . . . 29About messages . . . . . . . . . . . . . 30About performance problems and hangs . . . . 31About traps, crashes, and abends . . . . . . . 32

Chapter 3. Troubleshooting checklist 33

Chapter 4. Searching knowledge bases 35

Chapter 5. Obtaining a fix . . . . . . 37

Chapter 6. Collecting data . . . . . . 39Installation logs . . . . . . . . . . . . . 40Configuration tool logs . . . . . . . . . . 40Message and trace logs . . . . . . . . . . 41

Message logs . . . . . . . . . . . . . 41Trace logs . . . . . . . . . . . . . . 43

Configuring log settings . . . . . . . . . . 44Configuring message logging . . . . . . . 44

Configuring the JVM log . . . . . . . . 45Configuring the IBM Service log . . . . . 45

Enabling trace logging for WebSphereApplication Server . . . . . . . . . . . 46

Enabling trace at server startup. . . . . . 46Enabling trace on a running server . . . . 47

Enabling trace logging for Tivoli IntegratedPortal . . . . . . . . . . . . . . . 48Enabling trace logging for the registrationutilities . . . . . . . . . . . . . . . 48

Viewing logs . . . . . . . . . . . . . . 49

Chapter 7. Analyzing data . . . . . . 51

Chapter 8. Contacting IBM Support . . 53Using IBM Support Assistant . . . . . . . . 53

Using the IBM Support Assistant in graphicalmode . . . . . . . . . . . . . . . 54Using the IBM Support Assistant in consolemode . . . . . . . . . . . . . . . 55

IBM software maintenance contracts . . . . . . 56Determining the business impact . . . . . . . 57Describing a problem . . . . . . . . . . . 57Submitting data . . . . . . . . . . . . . 57

© Copyright IBM Corp. 2010 iii

Notices . . . . . . . . . . . . . . 61Trademarks . . . . . . . . . . . . . . 62

Index . . . . . . . . . . . . . . . 65

iv Version 7.1: Troubleshooting Guide

About this publication

IBM Tivoli Security Policy Manager enables you to manage access to resources bydefining and enforcing security policies. You can manage many types of resources,including Web services and applications..

This guide describes how to troubleshoot problems in Tivoli® Security PolicyManager.

Intended audienceThis publication is designed for the system administrators and networkadministrators in an organization that uses IBM® Tivoli Security Policy Manager tomanage its security policies.

Readers of this book should have working knowledge of the following topics:v The implementation of IBM Tivoli Security Policy Manager in their environmentv Web services security concepts and practicesv The types of resources being protected by policiesv IBM WebSphere® Application Server

PublicationsRead the descriptions of the IBM Tivoli Security Policy Manager library, theprerequisite publications, and the related publications to determine whichpublications that you might find helpful. The section also describes how to accessTivoli publications online and how to order Tivoli publications.

IBM Tivoli Security Policy Manager libraryThe following documents are available in the library:v IBM Tivoli Security Policy Manager Quick Start Guide

Provides instructions for getting started with IBM Tivoli Security PolicyManager.

v IBM Tivoli Security Policy Manager Installation Guide

Provides instructions for installing IBM Tivoli Security Policy Manager.v IBM Tivoli Security Policy Manager Configuration Guide

Provides instructions for configuring IBM Tivoli Security Policy Manager and itsrelated components.

v IBM Tivoli Security Policy Manager Administration Guide

Provides instructions for administering IBM Tivoli Security Policy Manager.v IBM Tivoli Security Policy Manager Error Message Reference

Provides explanations of the IBM Tivoli Security Policy Manager error messages.v IBM Tivoli Security Policy Manager Troubleshooting Guide

Provides troubleshooting information and instructions for problem solving.

You can obtain the publications from the IBM Tivoli Security Policy ManagerInformation Center:

© Copyright IBM Corp. 2010 v

http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?toc=/com.ibm.tspm.doc_7.1/toc.xml.

Prerequisite publicationsTo use the information in this book effectively, you should have some knowledgeof related software products, which you can obtain from the followingpublications:v IBM WebSphere Application Server Version 7.0 Information Center:

http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-nd-dist

v IBM WebSphere Application Server Version 6.1 Information Center:http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist

Accessing terminology onlineThe IBM Terminology Web site consolidates the terminology from IBM productlibraries in one convenient location. You can access the Terminology Web site athttp://www.ibm.com/software/globalization/terminology .

Accessing publications onlineThe documentation CD contains the publications that are in the product library.The format of the publications is PDF, HTML, or both. Refer to the readme file onthe CD for instructions on how to access the documentation.

IBM posts publications for this and all other Tivoli products, as they becomeavailable and whenever they are updated, to the Tivoli Documentation CentralWeb site at http://www.ibm.com/tivoli/documentation

Note: If you print PDF documents on other than letter-sized paper, set the optionin the File → Print window that allows Adobe Reader to print letter-sized pages onyour local paper.

Ordering publicationsYou can order many Tivoli publications online at http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss.

You can also order by telephone by calling one of these numbers:v In the United States: 800-879-2755v In Canada: 800-426-4968

In other countries, contact your software account representative to order Tivolipublications. To locate the telephone number of your local representative, performthe following steps:1. Go to http://www.elink.ibmlink.ibm.com/publications/servlet/pbi.wss.2. Select your country from the list and click Go.3. Click About this site in the main panel to see an information page that

includes the telephone number of your local representative.

vi Version 7.1: Troubleshooting Guide

http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?toc=/com.ibm.tspm.doc_7.1/toc.xml




http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist


http://www.ibm.com/software/globalization/terminology

http://www.ibm.com/tivoli/documentation

http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

http://www.ibm.com/e-business/linkweb/publications/servlet/pbi.wss

AccessibilityAccessibility features help a user who has a physical disability, such as restrictedmobility or limited vision, to use software products successfully. With this product,you can use assistive technologies to hear and navigate the interface. You also canuse the keyboard instead of the mouse to operate all features of the graphical userinterface.

For additional information, see the "Accessibility" topic in the Release Informationsection of the information center at http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?toc=/com.ibm.tspm.doc_7.1/toc.xml.

Tivoli technical trainingFor Tivoli software training information, refer to the IBM Tivoli Education Website: http://www.ibm.com/software/tivoli/education

Support informationIf you have a problem with your IBM software, you want to resolve it quickly.

IBM provides the following ways for you to obtain the support you need:

OnlineGo to the IBM Software Support site at http://www.ibm.com/software/support/probsub.html and follow the instructions.

IBM Support AssistantThe IBM Support Assistant (ISA) is a free local software serviceability toolthat helps you resolve questions and problems with IBM softwareproducts. The ISA provides quick access to support-related informationand serviceability tools for problem determination. For information aboutIBM Support Assistant, go to http://www.ibm.com/software/support/isa.

Troubleshooting GuideFor more information about resolving problems, see the IBM Tivoli SecurityPolicy Manager Troubleshooting Guide.

Conventions used in this bookThis reference uses several conventions for special terms and actions and foroperating system-dependent commands and paths.

Typeface conventionsThe following typeface conventions are used in this guide.

Bold

v Lowercase commands or mixed case commands that are difficult todistinguish from surrounding text, keywords, parameters, options,names of Java™ classes, and objects are in bold

v Interface controls (check boxes, push buttons, radio buttons, spinbuttons, fields, folders, icons, list boxes, items inside list boxes,multicolumn lists, containers, menu choices, menu names, tabs, propertysheets), labels (such as Tip:, and Operating system considerations:)

Italic

v Citations (examples: titles of publications, diskettes, and CDs)

About this publication vii



http://www.ibm.com/software/tivoli/education/

http://www.ibm.com/software/support/probsub.html


http://www.ibm.com/software/support/isa

v Words defined in text (example: a nonswitched line is called apoint-to-point line)

v Emphasis of words and letters (words as words example: "Use the wordthat to introduce a restrictive clause."; letters as letters example: "TheLUN address must start with the letter L.")

v New terms in text (except in a definition list): a view is a frame in aworkspace that contains data.

v Variables and values you must provide: ... where myname represents....

Monospace

v Examples and code examplesv File names, programming keywords, and other elements that are difficult

to distinguish from surrounding textv Message text and prompts addressed to the userv Text that the user must typev Values for arguments or command options

Operating system differencesThis publication uses the UNIX convention for specifying environment variablesand for directory notation.

When using the Windows command line, replace $variable with % variable% forenvironment variables and replace each forward slash (/) with a backslash (\) indirectory paths. The names of environment variables are not always the same inthe Windows and UNIX environments. For example, %TEMP% in Windowsenvironments is equivalent to $TMPDIR in UNIX environments.

Note: If you are using the bash shell on a Windows system, you can use the UNIXconventions.

viii Version 7.1: Troubleshooting Guide

Chapter 1. Introduction to troubleshooting

Troubleshooting, or problem determination, is a process of determining why aproduct is not functioning in the expected manner. This guide providesinformation to help you identify and resolve problems that you might encounterwhile using Tivoli Security Policy Manager and its prerequisite products.

You can often prevent certain problems by planning before the software isdeployed. Before installing Tivoli Security Policy Manager, review the Productinformation topics in the Tivoli Security Policy Manager information center. Thesetopics contain the following information:v Supported operating system levelsv Prerequisite software requirementsv Required software patchesv Minimum and recommended memory requirementsv Disk space requirementsv Upgrade considerations

The troubleshooting process, in general, requires that you isolate and identify aproblem, then seek a resolution. For help troubleshooting Tivoli Security PolicyManager, you can use the troubleshooting checklist in Chapter 3, “Troubleshootingchecklist,” on page 33. If the checklist does not lead you to a resolution, collectadditional diagnostic data that you can analyze yourself or that you can submit toIBM Software Support for analysis.

Troubleshooting topics for Tivoli Security Policy Manager are organized accordingto the sequence of these steps:1. Learn more about a symptom or the feature that does not seem to be

functioning as expected.Before you can successfully troubleshoot a symptom or a problem with aspecific product feature, you must have a basic understanding of that symptomor feature.

2. Follow the troubleshooting checklist for the appropriate feature or symptom.The troubleshooting checklist offers a series of questions to guide you throughthe process of isolating and identifying a problem. If the problem is known toIBM, the checklist guides you to a published fix, solution, or workaround.If the troubleshooting checklist has not led you to a resolution, continue to thenext step.

3. Collect diagnostic data.This information explains how to gather the necessary information that you, orIBM Software Support, must have in order to determine the source of aproblem.

4. Analyze diagnostic data.This information explains how to analyze the diagnostic data that youcollected.

© Copyright IBM Corp. 2010 1

2 Version 7.1: Troubleshooting Guide

Chapter 2. Learning about problem symptoms

The first step in the troubleshooting process is to learn more about the problemsymptoms or about the affected product feature.

The following topics can help you to acquire the information that you need toeffectively troubleshoot problems with IBM Tivoli Security Policy Manager and itscomponents:v “About troubleshooting”v “About connectivity problems” on page 5v “About Tivoli Security Policy Manager” on page 5v “About runtime security services components” on page 22v “About fixes and updates” on page 29v “About messages” on page 30v “About performance problems and hangs” on page 31v “About traps, crashes, and abends” on page 32

About troubleshootingTroubleshooting is a systematic approach to solving a problem. The goal is todetermine why something does not work as expected and how to resolve theproblem.

The first step in the troubleshooting process is to describe the problem completely.Without a problem description, neither you nor IBM know where to start to findthe cause of the problem. This step includes asking yourself basic questions, suchas:v What are the symptoms of the problem?v Where does the problem occur?v When does the problem occur?v Under which conditions does the problem occur?v Can the problem be reproduced?

The answers to these questions typically lead to a good description of the problem,and that is the best way to start down the path of problem resolution.

What are the symptoms of the problem?

When starting to describe a problem, the most obvious question is "What is theproblem?" This might seem like a straightforward question; however, you canbreak it down into several more-focused questions that create a more descriptivepicture of the problem. These questions can include:v Who, or what, is reporting the problem?v What are the error codes and messages?v How does the system fail? For example, is it a loop, hang, crash, performance

degradation, or incorrect result?v What is the business impact of the problem?


Where does the problem occur?

Determining where the problem originates is not always easy, but it is one of themost important steps in resolving a problem. Many layers of technology can existbetween the reporting and failing components. Networks, disks, and drivers areonly a few components to be considered when you are investigating problems. Thefollowing questions can help you to focus on where the problem occurs in order toisolate the problem layer.v Is the problem specific to one platform or operating system, or is it common

across multiple platforms or operating systems?v Is the current environment and configuration supported?

Remember that, even though one layer might report the problem, this does notmean that the problem originates in that layer. Part of identifying where a problemoriginates is understanding the environment in which it exists. Take some time tocompletely describe the problem environment, including the operating system, itsversion, all corresponding software and versions, and hardware information.Confirm that you are running within an environment that is a supportedconfiguration; many problems can be traced back to incompatible levels ofsoftware that are not intended to run together or have not been fully testedtogether.

When does the problem occur?

Develop a detailed timeline of events leading up to a failure, especially for thosecases that are one-time occurrences. You can most easily do this by workingbackward: Start at the time an error was reported (as precisely as possible, evendown to the millisecond), and work backward through the available logs andinformation. Typically, you need to look only as far as the first suspicious eventthat you find in a diagnostic log; however, this is not always easy to do and takespractice. Knowing when to stop looking is especially difficult when multiple layersof technology are involved, and when each has its own diagnostic information.

To develop a detailed timeline of events, try to answer these questions:v Does the problem happen only at a certain time of day or night?v How often does the problem happen?v What sequence of events leads up to the time that the problem is reported?v Does the problem happen after an environment change, such as upgrading or

installing software or hardware?

Responding to questions like this can help to provide you with a frame ofreference in which to investigate the problem.

Under which conditions does the problem occur?

Knowing what other systems and applications are running at the time that aproblem occurs is an important part of troubleshooting. These and other questionsabout your environment can help you to identify the root cause of the problem:v Does the problem always occur when the same task is being performed?v Does a certain sequence of events need to occur for the problem to surface?v Do any other applications fail at the same time?


Can the problem be reproduced?

From a troubleshooting standpoint, the ideal problem is one that can bereproduced. Typically with problems that can be reproduced, you have a larger setof tools or procedures at your disposal to help you investigate. Consequently,problems that you can reproduce are often easier to debug and solve. However,problems that you can reproduce can have a disadvantage: If the problem is ofsignificant business impact, you do not want it to recur! If possible, re-create theproblem in a test or development environment, which typically offers you moreflexibility and control during your investigation.v Can the problem be re-created on a test machine?v Are multiple users or applications encountering the same type of problem?v Can the problem be re-created by running a single command, a set of

commands, or a particular application, or a stand-alone application?

About connectivity problemsConnectivity problems typically involve multiple systems, including software,hardware, and communications. The best way to troubleshoot connectivityproblems is through a process of elimination.

First, collect relevant data and determine what you know, what data you have notyet collected, and what paths you can eliminate. At a minimum, answer thefollowing questions.v Are the communication paths operational?v Has the initial connection been successful?v Is the problem intermittent or persistent?v Have changes been made to the communication network that would invalidate

the previous directory entries?v Where is the communication breakdown encountered? For example, was the

breakdown between the client and a server?v Is the problem encountered only within a specific application?v What can you determine by the content of the message and the tokens that are

returned in the message?v Are other systems able to perform similar tasks successfully? If this is a remote

task, is it successful when performed locally?

Next, try to isolate the problem by answering the questions in the Chapter 3,“Troubleshooting checklist,” on page 33.

About Tivoli Security Policy ManagerBefore you begin troubleshooting a problem with Tivoli Security Policy Manager,review its overview and a list of symptoms that might indicate a typical problem.

IBM Tivoli Security Policy Manager provides standards-based application securitymanagement to secure access to applications and Web services in heterogeneous ITand service-oriented architecture (SOA) environments.

Typical problems with Tivoli Security Policy Manager can reveal themselves in thefollowing common symptoms:

During installation

Chapter 2. Learning about problem symptoms 5

v “Installation from a mounted ISO image displays an error message”v “Cannot reinstall after a failed installation” on page 7

During migration“Migration is disabled after migration is completed” on page 9.

During configuration

v “LDAP provisioning fails” on page 10v “Configuration tool fails during security task” on page 10v “Configuration tool fails during Services security task” on page 11

During operation

v “Console does not work” on page 12v “Various timeout errors occur” on page 12v “Tivoli Security Policy Manager server certificate must be replaced” on

page 13v “Components are unable to communicate” on page 16v “Parent permission not selected when all child permissions are selected”

on page 16v “Anonymous workspaces are created in the wstemp directory” on page

17v “Detailed information for file handler exception is missing” on page 17v “Console session timeout occurs” on page 17v “No policies distributed status” on page 18v “User registry search using the wildcard symbol does not produce

expected results” on page 19v “User registry search causes console to hang” on page 19v “One or more reports from the Tivoli Common Reporting component

fail” on page 19v “Cannot configure a policy” on page 20v “Problems importing a service from a file” on page 20v “Text and tables do not wrap in console window” on page 21

Installation from a mounted ISO image displays an errormessage

When you install the Installation Manager using a mounted ISO image, an errormessage is displayed.

Symptoms

The following error message is displayed if you install the Installation Managerusing a mounted ISO image:Concurrent access to HashMap attempted by Thread...

This error message is displayed at the end of the installation. You exit from theInstallation Manager and Installation Manager restarts itself.

Resolving the problem

Ignore this message. Click OK and proceed to exit Installation Manager.


Cannot reinstall after a failed installationA failed installation leaves files on the hard disk. If running the uninstall programdoes not remove the files, you must remove them manually before you can try toreinstall.

Symptoms

An attempt to reinstall fails after a failed installation and after uninstalling.

Causes

When the installation fails, it leaves many files on the hard disk. These filesprevent the installation program from running again.


If the installation fails, try running the uninstall program using the InstallationManager.

See the uninstallation tasks in the Tivoli Security Policy Manager Installation Guide.

If you cannot re-install after you have uninstalled, manually remove the files thatremain on the disk.1. Remove Tivoli Security Policy Manager server files:

On AIX®, Linux, or Solaris:

a. On the server where Tivoli Security Policy Manager is installed, remove theinstallation directories. By default, these directories are named TSPM andTSPMShared. For example, open a command prompt and run the followingcommands:rm -rf /opt/IBM/TSPMrm -rf /opt/IBM/TSPMShared

b. Uninstall the TSPM application from the WebSphere Application Server.Use the console or the command line.Using the console: See the topic for uninstalling enterprise applications inthe WebSphere Application Server information center:v WebSphere Application Server version 6.1 http://

www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist

v WebSphere Application Server version 7.0 http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-nd-dist

Using the command line:

1) Stop the WebSphere Application Server.2) Change to the config directory. For example, type

cd /opt/IBM/WebSphere/AppServer/profiles/AppSrv01/config

3) Remove "tspm." For example, typerm -rf tspm

4) Start WebSphere Application Server.c. Continue with the steps to remove files on the Tivoli Security Policy

Manager console server. See2 on page 8.On Windows:








a. On the server where Tivoli Security Policy Manager is installed, delete theinstallation directories. By default, these directories are named TSPM andTSPMShared. By default, these are located at C:\Program Files\IBM. Forexample, you can locate and delete the directories using Windows Explorer,or you can use the rmdir command on a command line.

b. Uninstall the TSPM application from the WebSphere Application Server.Use the console or the command line.Using the console: See the topic for uninstalling enterprise applications inthe WebSphere Application Server information center:v WebSphere Application Server version 6.1 http://

www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist

v WebSphere Application Server version 7.0 http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-nd-dist

Using the command line:

1) Stop the WebSphere Application Server.2) Change to the config directory. For example, type

cd C:\Program Files\IBM\WebSphere\AppServer\profiles\AppSrv0\config

3) Remove tspm using the delete command.4) Start WebSphere Application Server.

c. Continue with the steps to remove files on the Tivoli Security PolicyManager console server. See 2.

2. Remove files from the Tivoli Security Policy Manager console server:

Note: This is the server where you installed the Tivoli Integrated Portalcomponent.On AIX, Linux, or Solaris:

a. On the server where the Tivoli Security Policy Manager console is installed,remove the installation directories. By default, these directories are namedTSPM and TSPMShared. For example, open a command prompt and runthe following commands:rm -rf /opt/IBM/TSPMrm -rf /opt/IBM/TSPMShared

b. Remove the console installation directory and its associated directories andfiles. By default the console installation directory is /opt/tivoli. Forexample, Delete the following directories:v .tspm-tip

v acsiTemp_Administrator

v acsitempLogs_Administrator

Note: Your installation might have all or only one or two of thesedirectories.Open a command prompt and run the following commands:rm -rf /opt/tivolicd /var/ibm/common/acsi. ./setenv.shcd /usr/ibm/common/acsi/bin./si_inst.sh -r -frm -rf /usr/ibm/common/acsirm -rf /usr/ibm/tivoli/common








cd /tmprm -rf .tspm-tiprm -rf acsitempLogs_rootrm -rf acsiTemp_root

c. Restart WebSphere Application Server and then try the installation again.On Windows

a. On the server where Tivoli Security Policy Manager is installed, delete theinstallation directories. By default, these directories are named TSPM andTSPMShared. By default, these are located at C:\Program Files\IBM. Forexample, you can locate and delete the directories using Windows Explorer,or you can use the rmdir command on a command line.

b. Remove the console installation directory and its associated directories andfiles.1) Use Explorer to delete the installation directory. By default it is

C:\Program Files\tivoli

2) Open a command prompt and run the following commands:cd C:\Program Files\IBM\ascisetenv.cmdcd C:\Program Files\IBM\Common\acsi\binsi_inst.bat -r -f

c. Use explorer to delete C:\Program Files\IBM\Common\acsi

d. Use explorer to delete C:\Program Files\IBM\tivoli\common

e. Open a command prompt and run the set command to locate the 'temp' or'tmp' directory. Change directory to that temp directory and delete thefollowing directories, if they exist:v .tspm-tip

v acsiTemp_Administrator

v acsitempLogs_Administrator

f. Restart WebSphere Application Server and then try the installation again.

Migration is disabled after migration is completedIf you migrated Tivoli Security Policy Manager version 7.0 data to the TivoliSecurity Policy Manager version 7.1 database, the migration capability is disabled.

Symptoms

After you have migrated data, you cannot run migration again.

Causes

When a successful migration completes, the com.ibm.tspm.migration.enableparameter in the configuration file is set to false.


You can change the value from false to true if you must re-enable the migrationcapability. The configuration file is located in the following location:

AIX:/usr/IBM/WebSphere/AppServer/profiles/profile_name/config/

tspm/etc/com.ibm.tspm.conf.xmi

Linux or Solaris:


/opt/IBM/WebSphere/AppServer/profiles/profile_name/config/tspm/etc/com.ibm.tspm.conf.xmi

Windows:C:\Program Files\IBM\WebSphere\AppServer\profiles\profile_name\config\

tspm\etc\com.ibm.tspm.conf.xmi

Complete the following steps to enable migration:1. Open the com.ibm.tspm.conf.xmi file using a text editor.2. Locate the com.ibm.tspm.migration.enable parameter.3. Change the value to true.4. Save and close the file.5. Restart WebSphere Application Server.

LDAP provisioning failsThe configuration tool accesses the user registry to provision the groups that arerequired by Tivoli Security Policy Manager.

Symptoms

When you choose this option, the configuration tool must have direct write accessyour user registry.

Causes

The configuration tool cannot access the user registry to create the users, or theselected user (bind dn) does not have write permissions.


If your user registry is not accessible or you want to prevent the tool from writingto your user registry, choose the Create a Lightweight Directory InterchangeFormat (LDIF) file option. This method creates an LDIF file that you can use tosynchronize the group information to your user registry server. After you use thismethod, examine the content of the file to ensure that it is correct for your userregistry requirements. You must also use the instructions for your user registry tosynchronize the content of the file with your user registry.

See the tasks for configuring policy administration components in the TivoliSecurity Policy Manager Configuration Guide.

Configuration tool fails during security taskThe configuration tool might fail while running the security task.

Symptoms

The following message is displayed:CTGVU0027I - Could not find the group with cn=<groupname>.Verify that the group exists in your LDAP repository and thatthis LDAP repository is properly configured in both the TivoliSecurity Policy Manager server and the Tivoli Security PolicyManager console.


Causes

This problem can occur when the console has not been configured to use the TivoliSecurity Policy Manager user registry as a federated repository. The configurationtool tries to use the proper identities that have access to Tivoli Security PolicyManager resources. The same identities must be available to both the TivoliSecurity Policy Manager server and the Tivoli Security Policy Manager console.


To resolve this problem:1. Configure the console to use the same user registry as the Tivoli Security Policy

Manager server. See the topics about configuring user registries in the TivoliSecurity Policy Manager Configuration Guide.

2. Run the configuration tool again using the advanced mode, which preselectsthe tasks that have not completed. See the topics about running theconfiguration tool in the Tivoli Security Policy Manager Configuration Guide.

Configuration tool fails during Services security taskIf you are using WebSphere Application Server 6.1 and the configuration tool fails,the most likely cause is that the Web Services Feature Pack was not augmented.

Symptoms

The configuration tool fails when the Services security task is running. Either ofthe following messages are recorded in the log files:SEVERE: ADMF0005E Command or Command Group listPolicySets not found.java.lang.Exception: ADMF0005E Command or Command Group listPolicySets not found.

SEVERE: CTGVU0007E An error occurred when attempting to execute theWebSphere administrativetask importPolicySet.java.lang.Exception: CTGVU0007E An error occurred when attempting toexecute the WebSphere administrative task importPolicySet.

Causes

This problem occurs on WebSphere Application Server version 6.1 when theWebSphere Application Server profile has not been augmented with the WebServices Feature Pack. Unlike a fix pack, the feature packs are not applied to theprofiles.


To resolve this problem:1. Uninstall Tivoli Security Policy Manager. See the uninstalling topics in the Tivoli

Security Policy Manager Installation Guide.2. Delete the WebSphere Application Server profile.3. Create a new profile that is enabled with the feature pack. See the profile topics

in the WebSphere Application Server 6.1 information centerhttp://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist.

4. Install Tivoli Security Policy Manager. See the Tivoli Security Policy ManagerInstallation Guide.




5. Run the Tivoli Security Policy Manager configuration tool. See the TivoliSecurity Policy Manager Configuration Guide.

Console does not workYou might experience problems with the console after you have run theconfiguration tool.

Symptoms

You ran the configuration tool, and it completed successfully. However, you cannotuse the console to manage Tivoli Security Policy Manager.

Causes

This problem typically occurs if the Tivoli Security Policy Manager server and theTivoli Security Policy Manager console have not been restarted after configuration.You must restart the WebSphere Application Server where each of thesecomponents is installed. The restart forces the configuration to be loaded.


To resolve this problem, restart the WebSphere Application Servers where each ofthese components is installed. Then, try to use the console.

Various timeout errors occurSome Tivoli Security Policy Manager transactions might take longer to completethan the time that is specified by the configured server timeout values.

Symptoms

The following exception errors might be displayed if the transaction takes longer tocomplete than the time allocated:

Error Server that displays the error

org.omg.CORBA.NO_RESPONSE WebSphere Application Serverwhere the Tivoli Integrated Portalis installed.

com.ibm.wsspi.uow.UOWException:javax.transaction.RollbackException:Global transaction timed outafter 0 seconds

WebSphere Application Serverwhere the Tivoli Security PolicyManager is installed.

Causes

The timeout values on the WebSphere Application Server where the TivoliIntegrated Portal, or Tivoli Security Policy Manager, or both are installed are notlong enough for the transactions to complete.


A script file is included with Tivoli Security Policy Manager that you can use toincrease the affected timeout values.


The file is located in the installation directory of Tivoli Security Policy Manager.For example:

AIX/usr/IBM/TSPM/bin/increaseTimeout.py

Linux or Solaris/opt/IBM/TSPM/bin/increaseTimeout.py

WindowsC:\Program Files\IBM\TSPM\bin\increaseTimeout.py

Use the script with wsadmin scripting client. For information about the wsadminscripting client, see the WebSphere Application Server documentation:v WebSphere Application Server version 6.1 http://www14.software.ibm.com/

webapp/wsbroker/redirect?version=pix&product=was-nd-distv WebSphere Application Server version 7.0 http://www14.software.ibm.com/

webapp/wsbroker/redirect?version=compass&product=was-nd-dist

The script file requires the following parameters:

--cell The cell name.

--node The node name.

--secondsThe time in seconds in which the transaction must complete before atimeout occurs. For example, 90 seconds might be a reasonable value formost transactions.

Example

The following example shows the syntax for running the script on a Linux system.In this example, TIPCell and TIPNode are the names of the cell and node of theserver where the Tivoli Integrated Portal is installed../wsadmin.sh -f /opt/IBM/TSPM/bin/increaseTimeout.py

--cell TIPCell --node TIPNode --seconds 90

Tivoli Security Policy Manager server certificate must bereplaced

If the default server certificate for the Tivoli Security Policy Manager server hasexpired or you experience certificate-related errors, replace the certificate.

Symptoms

You might receive errors about the certificate or you might know that thecertificate has expired.

Causes

The server certificate has expired.


You can replace the certificate using the WebSphere Application Server console onthe server where Tivoli Security Policy Manager is installed.






1. Delete the existing certificate:

a. Log in to the WebSphere Application Server where Tivoli Security PolicyManager is installed.

b. Click Security > SSL certificate and key management > Key stores andcertificates.

c. Click DefaultTSPMKeystore.d. Under Additional Properties, click Personal certificates.e. Select the tspm_default certificate and click Delete.

2. Create a new self-signed certificate:

Note: The following steps use the Create a self-signed certificate function inthe console to create the certificate. You can use a certificate tool, such asiKeyman or keytool instead. If you use a certificate tool, use the same certificateproperties listed below and save the certificate to a file. Use the Import buttonin the console to import the personal certificate and specify tspm_default as theImported certificate alias value.a. Log in to the WebSphere Application Server where Tivoli Security Policy

Manager is installed.b. Click Security > SSL certificate and key management > Key stores and

certificates.c. Click DefaultTSPMKeystore.d. Under Additional Properties, click Personal certificates.e. Click Create a self-signed certificate.f. Use the following values for the certificate properties:

Alias tspm_default

Common nametspm_default

Organizationibm

Organizational unittivoli

Country or regionUS

Set other properties such as validity period, to values appropriate to yourenvironment.

g. Click Apply.h. Click OK. A self-signed personal certificate and a signer certificate are

created.i. Restart WebSphere Application Server.

3. Extract the new signer certificate:

Note: Extract the new signer certificate to share with other keystores that usedthe old signer certificate. For example, if you are using runtime securityservices components in your environment, replace the certificate in theirkeystores with the new tspm_default certificate.a. Log in to the WebSphere Application Server where Tivoli Security Policy

Manager is installed.


b. Click Security > SSL certificate and key management > Key stores andcertificates.

c. Click DefaultTSPMKeystore.d. Under Additional Properties, click Personal certificates.e. Select the tspm_default certificate and click Extract.f. Specify a file name to extract the certificate into. Note the Data type value;

you use the same data type when you import the certificate.g. Click OK.

4. Import the new signer certificate into other keystores:

Note: Replace the tspm_default signer certificate in any keystore or truststoreto which it has been distributed. Your environment might use keystores inaddition to the ones in the following steps.a. Replace the certificate in the Tivoli Security Policy Manager truststore:

1) Log in to the WebSphere Application Server where Tivoli Security PolicyManager is installed.

2) Click Security > SSL certificate and key management > Key stores andcertificates > DefaultTSPMKeystore > Signer certificates.

3) Select the existing tspm_default certificate.4) Click Delete.

5) Click Add.6) Type tspm_default as the alias name.7) Complete the File name and Data type fields. Use the same data type

value that you used when you extracted the certificate.8) Click OK.

b. Replace the certificate in the runtime security services keystore, if you useruntime security services components:

1) Transfer the file that holds the extracted certificate to the system that isrunning your runtime security services component. If the runtimesecurity services component is installed in a cluster, transfer the file tothe deployment manager.

2) Log in to the WebSphere Application Server where the runtime securityservices server or client is installed.

3) Click Security > SSL certificate and key management > Key storesand certificates > DefaultTSPMKeystore > Signer certificates.

4) Select the existing tspm_default certificate and click Delete.5) Click Add.6) Type tspm_default as the alias name.7) Complete the File name and Data type fields. Use the same data type

value that you used when you extracted the certificate.8) Click OK.9) Click Save.

10) Log out of the console and restart WebSphere Application Server. If theruntime security services component is installed in a cluster, restart theapplication servers, the cluster, the nodes, and the deploymentmanager, as applicable.


Components are unable to communicateTivoli Security Policy Manager components and systems that communicate withthose components must have static IP addresses and accurate name server entries.

Symptoms

Components in the environment cannot communicate.

Causes

Possible causes include:v Use of dynamic IP addresses.v Failure to register systems with a domain name service.


Tivoli Security Policy Manager is a distributed solution. All components must beable to communicate reliably with each other. These components include the TivoliSecurity Policy Manager server, administration console, and runtime securityservices. They must also be able to communicate with other entities such as serviceand user registries, policy distribution targets, and so on. Systems that use static IPaddresses and accurate name server entries can be located more reliably thansystems that use dynamic host configuration protocol (DHCP) to obtain IPaddresses.

Additionally, systems on which Tivoli Security Policy Manager is installed must beregistered with a domain name service (DNS) server. During installation, the fullyqualified host name of the Tivoli Security Policy Manager server is written to theTivoli Security Policy Manager properties file. If the system is not DNS registered,the current IP address is written to the properties file. If the system acquires a newIP address, Tivoli Security Policy Manager experiences communication errorsbecause Tivoli Security Policy Manager does not update the IP address in theproperties file after installation.

Parent permission not selected when all child permissions areselected

When a new administrator role is created, clearing and selecting child permissionsagain might not result in the expected permission set.

Symptoms

Permissions for administrator roles are listed in the console in a hierarchical checklist. By default, all permission check boxes are selected when a new role is created.If you clear a child permission check box, each permission that is parent to thatchild is also cleared and those parent permissions are not assigned. When youre-select a child permission check box, the parents are not automaticallyre-selected, even when all child permissions are selected. Subsequent creation ofthis role results in each child permission being assigned to the role but not theparent permission that was left cleared.


The activities in the Symptoms section describe the correct function of rolepermissions. Use caution when you clear child permissions from a parent.


Anonymous workspaces are created in the wstemp directoryDuring the course of normal Tivoli Security Policy Manager operations, theWebSphere Application Server workspace management component creates andstores temporary session data in the <profile_name> /wstemp directory of the TivoliSecurity Policy Manager application server profile. As the directory accumulatesmore and more temporary session data, the files and directories can take up a lotof space in the file system.

Symptoms

Temporary session data remains on the file system and takes up space.

Causes

Temporary session data is required as long as a user is logged in. WebSphere cancreate a large number of directories even when no user is logged in. By default,session directories are deleted after a user correctly logs out of the administrativeconsole. However, if a user ends a session by closing the Web browser instead oflogging out, the directories remain in the file system.


You can safely delete the temporary session data to free space on the file system.Shut down the server before deleting the content. The shutdown ensures that nouser is logged in and that no open or active sessions become corrupted.

For more information, see the WebSphere Process Server technote athttp://www-01.ibm.com/support/docview.wss?uid=swg21315735.

Detailed information for file handler exception is missingWhen certain failures occur during audit logging, such as the file system being full,audit events for either the Tivoli Security Policy Manager or runtime securityservices components can trigger an exception that is logged in the SystemOut.logfile.

Symptoms

The following exception message is logged, but it is missing detailed informationabout the cause of the exception.CTGVM0014E The file handler used for writing audit recordsto log files threw an exception.


If the SystemOut.log file contains error CTGVM0014E, examine the SystemErr.logfile for detailed information about the cause of the exception.

Console session timeout occursUser activity that is read-only in the Tivoli Security Policy Manager console doesnot register as user activity with the WebSphere server.


http://www-01.ibm.com/support/docview.wss?uid=swg21315735

Symptoms

If an administrator only performs view operations in the Tivoli Security PolicyManager console, a session timeout error occurs when the administrator clicksanother part of the console. For example, the following message might result:Session timeout due to inactivity.

Causes

Activities in the console such as adding, modifying, and attaching policies orservices generate server activity. Viewing service and policy information, however,generates only client-side activity that does not register on the server. If the userexceeds the WebSphere console inactivity timeout value without generatingserver-side activity, a session timeout error can occur.


To avoid this error, the user can either perform an action that generates serveractivity, such as adding, modifying, or attaching policies or services or can move toanother area of the console.

No policies distributed statusThe status, No policies distributed, can be misleading.

Symptoms

You distribute or remove policies and No policies distributed is displayed as thestatus.

Causes

Depending on the type of policy distribution target, policy distribution and policyremoval can be asynchronous processes. In asynchronous policy removal ordistribution, Tivoli Security Policy Manager communicates with a WS-Notificationbroker, which, in turn, communicates with the policy distribution target. In thiscase, Tivoli Security Policy Manager is notified only whether the broker receivedthe communication, not whether the broker actually succeeded in completing itscommunication flow.

Under typical circumstances, policy removal and distribution work correctly, andthe status message is accurate. However, if the WS-Notification broker cannot reachthe policy distribution target due to network difficulties or because the policydistribution target is down, the Tivoli Security Policy Manager policy distributionstatus can be inaccurate. For example, the Tivoli Security Policy Manager policydistribution status might indicate there are no policies distributed although thepolicy still exists on the target. In this case, the WS-Notification broker continues toperform the request until it is successful.


If you see a No policies distributed status after the policy is removed but youknow that the policy still exists on the policy distribution target, you can performthe following actions to ensure policy removal or distribution:


1. Verify that the policy distribution target configuration parameters are correct inTivoli Security Policy Manager. Log in to the console and view the policydistribution target configuration.

2. Verify that there is network connectivity between Tivoli Security PolicyManager and the policy distribution target.

3. Allow time to pass and then check the status again; the discrepancy might be atransient condition because the broker could not initially reach the policydistribution target. (The WS-Notification broker continues to try reaching thepolicy distribution target until it is successful.)

4. Modify the policy distribution target (for example, change the description) andthen make another attempt to remove or distribute the policy. Modifying thepolicy distribution target destroys and re-creates data structures used by theWS-Notification broker to communicate with the policy distribution target.

5. Stop and restart the WebSphere Application Server on which Tivoli SecurityPolicy Manager is deployed. (The stop and /restart recycles theWS-Notification broker and supporting applications.)

6. Attempt to remove or distribute the policy.

User registry search using the wildcard symbol does notproduce expected results

The only supported LDAP wildcard search string is attribute=*. Other combinationsusing the wildcard symbol (*) are not supported.

User registry search causes console to hangThe user registry search function sometimes causes the console to hang.

Symptoms

After attempting a user registry search, you might find that the console cannot beused.

Causes

The user registry search function does not include methods to configure a timeoutvalue or a limit on the number of entries the search returns. If a search filtermatches many entries in LDAP, then the console can appear to hang while theseentries are located and returned from LDAP. If the number of entries is large, it ispossible for the search to use all the available memory for the WebSphere serverand cause it to fail.


To avoid this problem, provide as much data as possible and limit the use ofwildcard searches.

One or more reports from the Tivoli Common Reportingcomponent fail

One or more reports might fail.

Symptoms

Error messages related to the failure of a report are logged or displayed in theTivoli Common Reporting log files.


Causes

The Tivoli Common Reporting and the Tivoli Security Policy Manager reports relyon direct access to a DB2® database to compile the data in a report. The SQLqueries are tightly coupled with the database schema and table structure. If one ormore tables required for a particular report do not exist in the database, the SQLqueries issued for the report fails.


Ensure that all Tivoli Security Policy Manager data tables have been created usingthe provided DB2 database setup script. The script is in the Tivoli Security PolicyManager installation directory.

Review the SQL errors in the Tivoli Common Reporting log files.

The logs are located on the server where the Tivoli Integrated Portal component isinstalled and are in the following directory:

AIX, Linux, or Solaris/opt/IBM/tivoli/tip/profiles/profile_name/logs/

WindowsC:\Program Files\tivoli\tip\profiles\profile_name\logs\

where profile_name is TIPProfile by default.

The logs are in the format: ReportEngine_YYYY_MM_DD_HH_mm_ss.log

Cannot configure a policyYou might experience problems when you configure a policy, such as errormessages or a policy that does not display "configured" status.

Causes

Policy configuration is conducted on a per-service basis. To configure the policiesof a service, the service must have at least one policy attached. The policy can beattached through a classification or to at least one element of the service (root orchild).


If you cannot configure the policies for a service, verify that a policy is attached tothe service.

Problems importing a service from a fileYou might experience problems when you import a service from a Web ServiceDefinition Language (WSDL) standard format file.

Symptoms

A Web service is derived from one or more files in Web Service DefinitionLanguage (WSDL) standard format. These files define the service and its ports,operations, messages, and so on. Defining a Web service across multiple filesenables the reuse or replacement of portions of the service definition.


In Tivoli Security Policy Manager, if you import a Web service using a multipartWSDL file, you must follow specific requirements. If you do not, the operationfails.

The following error is recorded in the WebSphere SystemOut.log file:FileNotFoundException


To import a Web service from a multipart WSDL file, ensure that the file meets thefollowing requirements:v The implementation WSDL file must be located on the system where the

browser that is running the console is invoked.The implementation WSDL file is the file that contains the <wsdl:service>element. The file must be accessible by the system from which the browser thatis running the Tivoli Security Policy Manager console is invoked.

v Any document that the implementation WSDL directly or indirectly referencesmust be accessible by the system that is running the console.The implementation WSDL file contains one or more import or include elementsthat reference other documents. The referenced documents can, in turn, importor include other documents. All of the referenced documents must be accessibleto the system where the Tivoli Security Policy Manager console is deployed. Thissystem might be a different system from the one where the browser is invoked.If the documents are referenced through file paths, then the files must exist onthe Tivoli Security Policy Manager console system. If the documents arereferenced through network protocols, then the network resources must beaccessible by the Tivoli Security Policy Manager console server.

v Import or include elements in the implementation WSDL must specify absolutepaths to referenced documents.In a multipart WSDL, the implementation WSDL file contains one or moreelements that reference other documents. These elements must specify the exactlocation of the referenced document by using an absolute file system path nameor an absolute URL. The value of the location attribute of any <wsdl:import> or<wsdl:include> elements must be absolute. The value of the schemaLocationattribute of any <xs:import> or <xs:include> elements must also be absolute. Ifa relative path is used in an import or include element in the top-level serviceimplementation WSDL, change it to an absolute path and make sure that path isaccessible from the Tivoli Security Policy Manager console system. Otherwise,the WSDL processing code cannot locate the referenced document and the TivoliSecurity Policy Manager console logs a FileNotFoundException inSystemOut.log.

v Import or include elements in referenced documents do not require absolutepaths to referenced documents. Referenced documents are those documentsother than the top-level service implementation WSDL file.XML documents that are imported or included by the top-level implementationWSDL may, in turn, have their own referenced documents. The elements thatimport or include the documents need not specify the exact location; a relativepath can be used. The only requirement is that the relative path is accuraterelative to the importing document.

Text and tables do not wrap in console windowIn some versions of the Mozilla Firefox Web browser, text and table content in theconsole does not wrap when it exceeds the right margin.


Symptoms

On the Tivoli Security Policy Manager Administrator Roles page, text and tablecontent exceeds the right boundary of the browser window. The text that does notwrap is not viewable in the Web browser window.


Use a different browser.

About runtime security services componentsBefore you begin troubleshooting a problem with runtime security servicescomponents, review the overview and a list of symptoms that might indicate atypical problem.

Overview of runtime security services components

The runtime security services components act as policy decision points in thepolicy management environment. They can:v Evaluate an access request against a policy.v Decide whether access is to be permitted or denied.

You can use the component in either of the following configurations:

Runtime security services server and one or more runtime security servicesclients in remote mode

The runtime security services server is installed in its own installation ofWebSphere Application Server. The server provides an authorizationdecision. A runtime security services client is installed on each server thathosts the resources you plan to protect with policies. The client receives theauthorization decision remotely from the server. The client in thisconfiguration is referred to as a client in remote mode. You can havemultiple clients protecting multiple resources and each client receivesauthorization decisions from the same server.

Runtime security services client in local modeThe runtime security services client is installed on the server that hosts theresources you plan to protect with policies. The client makes its ownauthorization decision locally. The client in this configuration is referred toas a client in local mode.

Problems with runtime security services components

Typical problems with runtime security services components have the followingcommon symptoms:

During configuration

v “Using a stand-alone user registry with runtime security servicescomponents” on page 23

v “WS-Security configuration issues” on page 24v “Registration utility fails” on page 25v “Registration fails and error CWWSS5508E occurs” on page 25v “Registration fails with an "Untrusted Security Policy Manager

Certificate Fingerprint"” on page 26


During operation

v “Certificate-related error messages are displayed during registration” onpage 27“Exception error occurs during startup of the runtime securityservices client” on page 27

v “Expired certificates” on page 28

Using a stand-alone user registry with runtime securityservices components

If the WebSphere Application Server for the runtime security services componentsis not configured as a federated repository, the users that are usually createdduring the runtime security services registration might not be createdautomatically. Additional setup is required.

Symptoms

The users that are typically created by the runtime security services registrationutility are not created. The utility creates users in:v The user registry for the Tivoli Security Policy Manager server.v The user registry for the runtime security services server and clients.

If the users are not created, registration cannot complete and the componentscannot communicate. In some cases, the users are created and registrationcompletes, however, the administrative commands for the runtime security servicescomponents do not work.

Cause

The user registry that is configured for use by your runtime security servicescomponents is not configured as a federated repository.


Complete the following configuration of your LDAP registry and then create theusers manually.1. Configure the LDAP registry:

a. Log in to the WebSphere Application Server where the runtime securityservices component is installed and where your LDAP registry isconfigured.

b. Click Security > Secure administration, applications, and infrastructure >Standalone LDAP registry.

c. Complete the required fields and select Server identity that is stored in therepository. Specify the user ID and password that is prompted by this field.

d. In the Additional Properties section, click Advanced Lightweight DirectoryAccess Protocol (LDAP) user registry settings.

e. Ensure that the required properties for your specific user registry arespecified and then complete the following fields:

Certificate map modeSelect CERTIFICATE_FILTER to use the specified certificate filterfor the mapping.

Certificate filterSpecify the filter certificate mapping property for the LDAP filter.For example, (cn=${SubjectCN})


f. Click Apply.2. Create the users manually:

The steps for creating users in a user registry are specific to that registry. If youneed assistance when creating the users, see the documentation for your userregistry.v Tivoli Directory Server. See the Tivoli Directory Server information center for

creating users: http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?toc=/com.ibm.IBMDS.doc/toc.xml

v Microsoft Active Directory. See the user creation documentation for yourActive Directory server.

a. On the user registry that is used by your Tivoli Security Policy Managerserver, create a user that represents the runtime security services policydistribution target.v Use the CN attribute that you create for this user as the policy

distribution target name when you register the target.v Create the user in the tspm_pdt group. This group was created when you

configured Tivoli Security Policy Manager.

Note: The password and DN attribute are not used by Tivoli SecurityPolicy Manager.

b. On the user registry for your runtime security services server or client,create a user that represents the Tivoli Security Policy Manager server. Usetspm_default as the CN attribute.

Complete the registration tasks for the runtime security services server or clientthat you must register. See the tasks in the Tivoli Security Policy ManagerConfiguration Guide.

WS-Security configuration issuesWS-Security secures messages that are exchanged between the runtime securityservices components and the Tivoli Security Policy Manager server. TroubleshootWS-Security issues by verifying that the RTSSWSSecurity.py script was successful.

Symptoms

Error messages are displayed or written to the log files that indicate issues withthe WS-Security configuration.

Causes

The RTSSWSSecurity.py script was not successful, or the configuration wasincomplete.


Verify the configuration with the following task:1. Log in to the WebSphere Application Server where the runtime security

services server or client is installed.2. Click Services > Policy Sets > Application Policy Sets.3. Verify that the following entry is in the table:

RTSSAdminCommandServicePolicySet.


http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?toc=/com.ibm.IBMDS.doc/toc.xml

http://publib.boulder.ibm.com/infocenter/tivihelp/v2r1/index.jsp?toc=/com.ibm.IBMDS.doc/toc.xml

4. Verify that the correct policy set and binding have been associated with theservice. Click Services > Service providers.The following services are listed:v servicesAdminCommandv servicesNotificationConsumer

5.

v For a client, click: IBM Tivoli Runtime Security Services Agent > Serviceprovider policy sets and bindings to see the policy set and bindings for theservices.

v For a server, click IBM Tivoli Runtime Security Services > Service providerpolicy sets and bindings to see the policy set and bindings for the services.

For the servicesAdminCommand service, look for:

Policy setRTSSAdminCommandServicePolicySet

BindingRTSSAdminCommandServiceBinding

If you do not find these settings, try to run the RTSSWSSecurity.py script again.

Registration utility failsYou might experience a failure with the registration utility.

Symptoms

The registration fails with error messages, or the policy distribution target is notdisplayed in the console.


Examine the tspmRegisterRTSS.properties file to verify that the entries you madethere are correct. For example, verify that the WebSphere Application Server valuesand the profile and path information are correct. If you make a correction, retry theTSPMRegisterRTSS command. See the tasks for configuring policy decisioncomponents in the Tivoli Security Policy Manager Configuration Guide.

Set trace logging levels and examine the log files for the runtime security servicescomponents. For more information see the following topics:v “Enabling trace logging for the registration utilities” on page 48v “Enabling trace at server startup” on page 46v “Message and trace logs” on page 41

Registration fails and error CWWSS5508E occursBefore you can use the runtime security services components, you must registerthem. Sometimes registration fails, and a WebSphere Application Server error isreturned.

Symptoms

Registration of the runtime security services components fails with errorCWWSS5508E:


SEVERE: CTGVT0052E The registration web service request failed.javax.xml.ws.soap.SOAPFaultException:security.wssecurity.WSSContextImpl.s02:com.ibm.websphere.security.WSSecurityException:Exception org.apache.axis2.AxisFault:

CWWSS5508E: All the attempts based on each TokenConsumer failed.The last exception is {0}:com.ibm.wsspi.wssecurity.core.SoapSecurityException:

CWWSS6521E: The Login failed because of an exception:javax.security.auth.login.LoginException: java.security.cert.CertPathBuilderException:unable to find valid certification pathto requested target ocurred while running action:com.ibm.ws.wssecurity.handler.WSSecurityConsumerHandler$1@53c853c8


You have two options:v Locate and download the interim fix (iFix) that is appropriate to the version of

WebSphere Application Server where the following components are installed:– Tivoli Security Policy Manager– Runtime security services components

WebSphere Application Server 6.1Interim fix PM 13008 (for version 6.1.0.27 through 6.1.0.31)

WebSphere Application Server 7.0Interim fix PM 12973 (for version 7.0.0.7 through 7.0.0.11)

The interim fix packages are available at: http://www-933.ibm.com/support/fixcentral/swg/identifyFixes?query.parent=ibm/WebSphere&query.product=ibm/WebSphere/WebSphere%20Application%20Server&query.release=All&query.platform=All&source=SPEApply the interim fix to all WebSphere Application Servers in your environment.Use the instructions provided with the interim fix.

v If you do not want to apply the interim fix, complete the following steps:1. Restart the WebSphere Application Server where the Tivoli Security Policy

Manager server is installed.2. Restart the WebSphere Application Server where the runtime security

services component is installed. If the runtime security services component isinstalled in a cluster, restart the application servers, the cluster, the nodes,and the deployment manager, as applicable.

3. Run the registration script and use the -o register parameter.

Registration fails with an "Untrusted Security Policy ManagerCertificate Fingerprint"

If application security is not enabled, registration will fail.

Symptoms

Registration fails.


http://www-933.ibm.com/support/fixcentral/swg/identifyFixes?query.parent=ibm/WebSphere&query.product=ibm/WebSphere/WebSphere%20Application%20Server&query.release=All&query.platform=All&source=SPE




Causes

The Tivoli Security Policy Manager registration service must authenticate therequest, and WebSphere is not providing the user ID because application securityis not enabled.


Verify that application security is enabled on the Tivoli Security Policy Managerserver.1. In the WebSphere administration console, expand Security and click Secure

administration, applications, and infrastructure.2. On the Secure administration, applications, and infrastructure page, select

Enable application security, and click Apply.3. Restart the WebSphere Application Server.

Certificate-related error messages are displayed duringregistration

Some certificate-related error messages are displayed during registration.

Symptoms

The messages displayed are:WARNING: ssl.keystore.type.invalid.CWPKI0018WWARNING: trusted certificate entries are not password-protected


Ignore these messages and complete the registration process.

Exception error occurs during startup of the runtime securityservices client

If the runtime security services client is not installed correctly, an exception erroroccurs when the runtime security services agent application is started.

Symptoms

The following exception occurs:SRVE0100E:Did not realize init() exception thrown by servlet AgentStartupServlet:java.lang.NoClassDefFoundError: com.ibm.tscc.pep.common.RTSSEmbedded

Cause

The runtime security services client is not installed correctly.


Complete the installation using the following steps:1. Stop the WebSphere Application Server where the runtime security services

client is installed.


2. Expand the plugins-deploy.jar file contents into the WAS_home/pluginsdirectory. (The runtime security services client installation places theplugins-deploy.jar in RTSS_install_dir/runtime, for example/opt/IBM/RTSSClient/runtime.)a. Navigate to the WAS_home/plugins directory. For example:

AIX/usr/IBM/WebSphere/AppServer/plugins

Linux or Solaris/opt/IBM/WebSphere/AppServer/plugins

WindowsC:\Program Files\IBM\WebSphere\AppServer\plugins

b. Expand the .jar file using the following command:jar -xvf RTSS_install_dir/runtime/plugins-deploy.jar

If the jar executable location is not in your PATH, specify the full path inthe command. For example:WAS_home/java/bin/jar RTSS_install_dir/runtime/plugins-deploy.jar

3. Change directory to the bin directory for the WebSphere profile where theruntime security services client is deployed. The configuration script is locatedin this directory.v AIX, Linux, or Solaris

# cd /opt/IBM/WebSphere/AppServer/profiles/profile_name/bin

where profile_name is the name of your WebSphere Application Server profile,such as AppSrv01.

v Windowscd C:\Program Files\IBM\WebSphere\AppServer\profiles\profile_name\bin

where profile_name is the name of your WebSphere Application Server profile,such as AppSrv01.

4. Run the OSGi configuration script. On some operating systems, no data isreturned from this script.v AIX, Linux, or Solaris

osgiCfgInit.sh

v WindowsosgiCfgInit.bat

5. Before you try to use the runtime security services client, complete all of itsconfiguration tasks. See the Tivoli Security Policy Manager Configuration Guide.

Expired certificatesBy default, the certificate created during the registration of runtime securityservices components expires 3650 days (10 years) after its creation. You can refreshthe certificate by resetting its expiration using the tspmRegisterRTSS utility. If thecertificate expires before you can refresh it, you must take additional steps.

Causes

The certificates used by runtime security services components have expired.


Resolving the problem1. On the server where Tivoli Security Policy Manager is installed, use the

WebSphere Application Server console to remove the policy distribution targetuser from the user registry. The policy distribution target user has the namespecified by the pdt-name property used during registration.a. Log in to the console.b. Click Users and Groups > Manage Users.c. Locate the policy distribution target user.d. Select the user.e. Click Delete.

2. On the server where Tivoli Security Policy Manager is installed, use theWebSphere Application Server console to remove the policy distribution targetsigner certificate from the DefaultTSPMTruststore:a. Log in to the console.b. Click Security > SSL certificate and key management > Key stores and

certificates > DefaultTSPMTruststore > Signer certificates.c. Select the signer certificate for the policy distribution target.d. Click Delete.

3. Use the Tivoli Security Policy Manager console to remove the policydistribution target object from the Tivoli Security Policy Manager datarepository:a. Log in to the console.b. Click Identity and Access > Registries and Repositories > Policy

Distribution Targets.c. Select the policy distribution target.d. Click Delete.

4. On the server where the runtime security services component is installed, usethe WebSphere Application Server console to remove the following certificatesfrom the RTSS keystore:v Policy distribution target signer certificatev Policy distribution target personal certificatea. Log in to the console.b. Click Security > SSL certificate and key management > Key stores and

certificates > RTSS > Signer certificates.c. Select the signer certificate for the policy distribution target certificate.d. Click Delete.e. Click RTSS and then click Personal certificates.f. Select the personal certificate for the policy distribution target.g. Click Delete.

5. Restart all servers.6. Re-register the runtime security services component. See the registration tasks

in the Tivoli Security Policy Manager Configuration Guide.

About fixes and updatesIf you encounter a problem with Tivoli Security Policy Manager software, firstcheck the list of recommended updates to confirm that your software is at thelatest maintenance level. Next, check the list of problems fixed to see if IBM hasalready published an individual fix to resolve your problem.


These lists are located at the Tivoli Support Web site:http://www.ibm.com/software/sysmgmt/products/support/

Individual fixes are published as often as necessary to resolve defects in IBM TivoliSecurity Policy Manager. In addition, two kinds of cumulative collections of fixes,called fix packs and refresh packs, are published periodically for IBM TivoliSecurity Policy Manager, in order to bring users up to the latest maintenance level.You should install these update packages as early as possible in order to preventproblems.

To receive weekly notification of fixes and updates, subscribe to My Support e-mailupdates. For more information, see Chapter 5, “Obtaining a fix,” on page 37.

The following table describes the characteristics of each maintenance deliveryvehicle.

Table 1. Maintenance types

Name Characteristics

Fix v A single fix that is published between updates to resolve a specificproblem.

v After you install a fix, test any functions that the fixed component has animpact on.

Fix pack v A cumulative fix package that contains all fixes that have been publishedsince the previous fix pack or refresh pack; a fix pack might also containnew fixes.

v Fix packs increment the modification level of the product and are namedaccordingly, for example, 7.0.1

v A fix pack can update specific components, or it can update the entireproduct image.

v During fix pack installation, all previously applied fixes are automaticallyuninstalled.

v After you install a fix pack, you should regression-test all critical functions.

v The most recent two fix packs are available for download (for example,7.0.2 and 7.0.1). Earlier fix packs are not available.

Refreshpack

v A cumulative fix package that contains all fixes that have been publishedsince the previous fix pack or refresh pack, as well as new fixes.

v A refresh pack typically contains new function, in addition to fixes, and itupdates the entire product image.

v Refresh packs increment the modification level of the product and arenamed accordingly, for example, 7.0.1.

v During refresh pack installation, all previously applied fixes areautomatically uninstalled.

v After you install a refresh pack, you should regression-test all criticalfunctions.

About messagesWhen you receive a message from Tivoli Security Policy Manager, you can oftenresolve the problem by reading the entire message text and the recovery actionsthat are associated with the message.


http://www.ibm.com/software/sysmgmt/products/support/

http://www.ibm.com/software/sysmgmt/products/support/

You can find the full text of messages, their explanations, and the recommendedrecovery actions by searching for the message identifier in the Tivoli Security PolicyManager Error Message Reference.

About performance problems and hangsPerformance problems occur in many different situations. A hang is a performanceproblem in which users wait for a response for an indefinite period of time.Troubleshooting techniques for hangs are similar to the techniques you use forother performance problems.

The following list includes some examples of situations in which performanceproblems become evident:v Query performance is slower than expected.v The workload or a batch job is not completing as soon as expectedv The transaction rate or throughput becomes slower.v The overall system slows down.v A bottleneck is suspected in one of the system resources such as CPU, I/O, or

memory.v Query or other workload processing is consuming more resource than is

expected or available.v One system performs better than another.v A query, application, or system hangs.

Hangs can be particularly difficult to troubleshoot because the symptoms oftenseem to match the symptoms of other problems. For example, if the response to aquery takes a long time, the user might think that the system is hung. However,there might be other reasons:v The query is extremely complex.v The system is experiencing heavy traffic and is responding slowly.v During a severe system shutdown, a significant buildup of activity can result in

most or all commands appearing to hang.

In addition to characterizing the problem correctly in terms of what the symptomsare (slowness, too much resource used, and so on) and where the symptoms areobserved (in a query, application, system resource, and so on), you need severalother pieces of information to put the problem in context.

Answer the following questions to quickly determine the best place to start lookingfor the cause of the performance problem.1. When did the problem first occur?

If the problem has been occurring for some time, consider using historical datato find differences. You can focus on changes in system behavior and thenfocus on why these changes were introduced. Consider whether any recentchanges occurred, such as hardware or software upgrades, a new applicationrollout, additional users, and so on.

2. Is the performance issue constant or intermittent?If the poor performance is continual, check if the system has started to handle alarger workload or if a shared database resource has become a bottleneck.Other potential causes of performance degradation include increased useractivity, multiple large applications, or removal of hardware devices. Ifperformance is poor only for brief periods, begin by looking for common


applications or utilities that run at these times. If users report that a group ofapplications experiences performance issues, begin by focusing on theseapplications.

3. Does the problem appear to be system-wide or isolated to Tivoli Security PolicyManager or its components?System-wide performance problems suggest an issue outside of Tivoli SecurityPolicy Manager. You might need to address something at the operating systemlevel.

4. If the problem is isolated to one component, does one particular activity appearto cause the problem?If one component seems to cause the problem, you can evaluate whether userswho are reporting that specific activity are experiencing a slowdown. Youmight be able to isolate the issue to one component and a specific activity.

5. Do you notice any common characteristics of the poor performance, or do theproblems appear to be random?Determine if any common functions are involved. If so, this suggests that thesefunctions are a point of contention.

About traps, crashes, and abendsThe terms trap, crash, and abnormal end (abend) are often used synonymously.

If Tivoli Security Policy Manager cannot continue processing as the result of a trap,segmentation violation, or exception, it generates an error.

Most traps, crashes, and abends for Tivoli Security Policy Manager result in anexception. Exceptions appear in the message log and typically do not require atrace to be reported. However, the trace log can record these errors when enabled.If you open a problem report, IBM Support might instruct you to enable tracelogging and provide the trace log for analysis.

Although Tivoli Security Policy Manager can generate trace logs on demand,generate trace files only when IBM Software Support asks you to do so. See “Tracelogs” on page 43.


Chapter 3. Troubleshooting checklist

The following questions help you to identify the source of a problem inTivoliSecurity Policy Manager.1. Are your fixes and fix packs up to date?

See Chapter 5, “Obtaining a fix,” on page 37.2. Is the problem documented in “About Tivoli Security Policy Manager” on page

5 or “About runtime security services components” on page 22?3. Is the problem documented in the Tivoli Security Policy Manager Technotes?

See the technotes at http://www.ibm.com/support/search.wss?tc=SSNGTE&rs=3554&rank=8&atrn=SWVersion&atrv=7.1&dc=DB520+DB560.

4. Does the IBM Knowledge Base contain additional information about theproblem?See Chapter 4, “Searching knowledge bases,” on page 35.

5. Do you receive any error messages?See the the Tivoli Security Policy Manager Error Message Reference.

6. Do the logs contain any messages about the problem?See “Message logs” on page 41 and “Trace logs” on page 43 for moreinformation.

7. Does the problem occur while installing or uninstalling one of the followingfeatures?v Tivoli Security Policy Manager or its components, such as the runtime

security services components.See the Tivoli Security Policy Manager Installation Guide.

v WebSphere Application ServerSee the installation troubleshooting topics in the IBM WebSphere ApplicationServer information center at– IBM WebSphere Application Server Version 7.0 Information Center:


– IBM WebSphere Application Server Version 6.1 Information Center:http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist

.v Tivoli Common Reportingv Tivoli Federated Identity Manager

8. If you could not resolve the problem in the preceding steps, determineadditional information about the location of the problem or conditions duringwhich the problem occurs:v Did the problem occur during runtime processing?

– Did it fail to connect?– Did it crash?– Did it have a performance problem such as slow response, or a "hang"?– Did it abend, trap, or throw a Java exception?

v Does the problem occur when you configure a specific function?


http://www.ibm.com/support/search.wss?tc=SSNGTE&rs=3554&rank=8&atrn=SWVersion&atrv=7.1&dc=DB520+DB560

http://www.ibm.com/support/search.wss?tc=SSNGTE&rs=3554&rank=8&atrn=SWVersion&atrv=7.1&dc=DB520+DB560





v Does the problem occur when you perform a specific task?The answers to these questions might help you determine the location of theproblem and assist you in locating additional information about the problem.For example, if the problem occurs during configuration of a specific functionor performance of a specific task, you might find a solution in thedocumentation of that function or task.

If the checklist does not guide you to a resolution, you can collect additionaldiagnostic data to continue troubleshooting. The additional data helps IBMSupport personnel troubleshoot the problem. See Chapter 6, “Collecting data,” onpage 39.


Chapter 4. Searching knowledge bases

You can often find solutions to problems by searching IBM knowledge bases. Learnhow to optimize your results by using available resources, support tools, andsearch methods and how to receive automatic updates.

Available technical resources

In addition to this information center, the following technical resources areavailable to help you answer questions and resolve problems:v Tivoli Security Policy Manager version 7.1 technotesv Tivoli Security Policy Manager Support Web sitev Tivoli Redbooks® Domainv Tivoli support communities (forums and newsgroups)

Searching with support tools

The following tools are available to help you search IBM knowledge bases:v IBM Support Assistant (ISA) is a free software serviceability workbench that

helps you resolve questions and problems with IBM software products.Instructions for downloading and installing the ISA can be found on the ISAWeb site: www.ibm.com/software/support/isa/

v IBM Software Support Toolbar is a browser plug-in that provides you with amechanism to easily search IBM support sites. You can download the toolbar at:www.ibm.com/software/support/toolbar/.

Search tips

The following resources describe how to optimize your search results:v Searching the IBM Support Web sitev Using the Google search engine

Receiving automatic updates

You can receive automatic updates in the following ways:v My support. To receive weekly e-mail notifications regarding fixes and other

support news, go to the product support site Tivoli Security Policy ManagerSupport Web site and click Request e-mail updates.

v RSS feeds. For information about RSS, including steps for getting started and alist of RSS-enabled IBM Web pages, see www.ibm.com/software/support/rss/


http://www-01.ibm.com/support/search.wss?tc=SSNGTE&rs=3554&rank=8&atrn=SWVersion&atrv=7.1&dc=DB520+DB560&dtm

http://www.ibm.com/software/tivoli/support/security-policy-mgr/

http://publib-b.boulder.ibm.com/Redbooks.nsf/portals/TivoliRedbooks

http://www.ibm.com/software/sysmgmt/products/support/Tivoli_Communities.html

http://www.ibm.com/software/support/isa/

http://www.ibm.com/software/support/toolbar/

http://www.ibm.com/support/us/srchtips.html

http://www.google.com/support



http://www.ibm.com/software/support/rss/


Chapter 5. Obtaining a fix

A product fix might be available to resolve your problem.

About this task

You can determine what fixes are available for Tivoli Security Policy Manager bychecking the product support Web site.

Procedure1. Go to the IBM Software Support Web site for Tivoli Security Policy Manager:

http://www.ibm.com/software/tivoli/support/security-policy-mgr/. A list ofmost recent fixes is listed in the Downloads section of the page.

2. Click the name of a fix to read the description and optionally download the fixand any tools that are required to get the fix.




Chapter 6. Collecting data

Sometimes you cannot solve a problem by troubleshooting the symptoms. In suchcases, you must collect more diagnostic data.

Before you collect data for a problem report, consider installing and running theIBM Support Assistant. This troubleshooting tool includes a console for submittingan online problem management record (PMR). The process gathers informationthat is specific to your system, environment, and product into a file for IBMSoftware Support. See “Using IBM Support Assistant” on page 53.

Collecting data early, even before opening a problem management record (PMR),can help you to answer the following questions:1. Do the symptoms match any known problems?2. If so, has a fix or workaround been published?3. Is this a non-defect-oriented problem that can be identified and resolved

without a code fix?4. Where does the problem originate?

The diagnostic data that you must collect and the sources from which you collectthat data depends on the type of problem that you are investigating. For example,if you are investigating a potential disk error in an AIX environment, one criticalsource of diagnostic data is the output from an errpt command.

For help identifying the component from which the problem originates, follow thequestions in the troubleshooting checklist for Tivoli Security Policy Manager.

Collecting general data

When you submit a problem to IBM Software Support, there is a base set ofinformation that you typically provide. This information includes:v Version of Tivoli Security Policy Manager and patch levels on affected systemsv Operating system name and versionv General details about the structure of your environment, such as:

– Number of servers and software installed, including WebSphere ApplicationServer version numbers, fix packs, and feature packs

– Domains and federations configured

Collecting problem-specific data

For specific symptoms or for problems in a specific part of the product, you mightneed to collect additional data, such as message and trace information. See thefollowing topics for more information:v “Installation logs” on page 40v “Configuration tool logs” on page 40

After you collect the appropriate diagnostic data, you can attempt to analyze thedata yourself, or you can provide it to IBM Software Support.


Installation logsInstallation Manager and Tivoli Integrated Portal handle the logging for TivoliSecurity Policy Manager installation.

Installation Manager logs

Use the following methods to locate and view the Installation Manager log fileswhen you encounter problems during installation:v If your installation or uninstallation fails, use the View Log File link on the

Installation Manager summary failure panel to see the log results.v To view a log file using the main Installation Manager panel, click File > View

Log or File > Install History > View Log.

Inside the Installation Manager log viewer, the default sorting and view shows thenewest information at the top and the oldest at the end of the log. Begin lookingat the messages at the end of the file to find the first exception and, most likely,the cause of the failure.

You can find helpful information in the Custom Operation items before theexception itself. Highlight the custom operation column and select the link to thelog file that displays in the bottom pane on the panel.

Tivoli Integrated Portal logs

You can view the log files that Tivoli Integrated Portal installation creates calledIA-TIPInstall-xx.log, located in your home directory. This log file shows theinstallation as it progresses and gives tracing information. Each step that is run inthe installation creates a log in the TSPM_install_dir/logs directory.

You can also view the uninstallation in the logs called IA-TIPUninstall-xx.log.

Configuration tool logsThe configuration tool creates logs for message and trace information.

The TSPM_install_dir/configtool/logs directory contains the configuration toollogs.

By default, the configuration tool logs information, warning, and severe messages.To enable tracing, you must change the logging level property:1. Edit the logging.properties file located in the TSPM_install_dir/configtool/

configuration directory.2. Change the following property in the file to the level you need for tracing, such

as ALL or FINEST.


Property default value Description

config.util.logging.level=INFO Log informational messages only. The otheroptions for levels are:

v SEVERE - A problem has occurred whichresults in a significant or complete loss ofsome function.

v WARNING - A problem has occurred butdoes not affect normal operations.

v INFO - Normal operation.

v CONFIG - Configuration messages.

v FINE - Significant events that explain theflow or state of the system.

v FINER - Detailed trace.

v FINEST - Developer or debug tracing.

WebSphere Application Server also collects the configuration tool messageinformation. See “Enabling trace logging for WebSphere Application Server” onpage 46.

Message and trace logsWebSphere Application Server and Tivoli Integrated Portal manage and store TivoliSecurity Policy Manager message and trace logs.

See the troubleshooting topics in the WebSphere Application Server informationcenter for detailed information about logs and logging at:v Version 6.1: http://www14.software.ibm.com/webapp/wsbroker/

redirect?version=pix&product=was-nd-distv Version 7.0: http://www14.software.ibm.com/webapp/wsbroker/

redirect?version=compass&product=was-nd-dist

See the troubleshooting topics in the Tivoli Integrated Portal information center fordetailed information about logs and logging at http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/topic/com.ibm.tip.doc/welcome_tip_ic.htm

Message logsMessage logs record the operations of the system in text files.

The following types of messages are recorded by default:

Informational messagesIndicate conditions that are worthy of noting, but that do not require youto take any precautions or perform an action.

Warning messagesIndicate that a condition has been detected about which you should beaware, but does not necessarily require that you take any action.

Error messagesIndicate that a condition has occurred that requires you to take action.

Chapter 6. Collecting data 41





http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/topic/com.ibm.tip.doc/welcome_tip_ic.htm


Message log files

All Tivoli Security Policy Manager messages are logged in the following defaultWebSphere Application Server and Tivoli Integrated Portal message logs.

Table 2. Message logs

Log Default file name Content

JVM Logs SystemOut.log Messages in text format forthe application serverinstance.

IBM Service Log activity.log Messages in binary CommonBase Event format for theapplication serverinstallation.Note: WebSphereApplication Server providestools for viewing this format.See the WebSphereApplication Serverinformation center.

Using the WebSphere Application Server administrative console or the TivoliIntegrated Portal console, you can configure some settings of the logs, such as:v Location, name, and maximum size of the log filesv Levels of severity that you want to log (such as Warning and Severe)

For more information, see “Configuring log settings” on page 44.

Message log locations

By default, the message logs are located in the directories listed in Table 3 andTable 4 on page 43.

Table 3. WebSphere Application Server default message log locations

Log Path

JVM Logs AIX, Linux, Linux on System z®, or Solaris:

/opt/IBM/WebSphere/AppServer/profiles/profile_name/logs/server_name/SystemOut.log

Windows:

C:\Program Files\IBM\WebSphere\AppServer\profiles\profile_name\logs\server_name\SystemOut.log

IBM Service Log AIX, Linux, Linux on System z, or Solaris:

/opt/IBM/WebSphere/AppServer/profiles/profile_name/logs/activity.log

Windows:

C:\Program Files\IBM\WebSphere\AppServer\profiles\profile_name\logs\server_name\activity.log


Table 4. Tivoli Integrated Portal default message log locations

Log Path

JVM Logs AIX, Linux, Linux on System z, or Solaris:

/opt/IBM/tivoli/tip/profiles/profile_name/logs/server_name/SystemOut.log

Windows:

C:\Program Files\tivoli\tip\profiles\profile_name\logs\server_name\SystemOut.log

IBM Service Log AIX, Linux, Linux on System z, or Solaris:

/opt/IBM/tivoli/tip/profiles/profile_name/logs/server_name/activity.log

Windows:

C:\Program Files\tivoli\tip\profiles\profile_name\logs\server_name\activity.log

Console message logs are saved in the message log directories of the WebSphereApplication Server node where the administration console is installed.

Trace logsTrace logging, or tracing, provides IBM Software Support personnel withadditional information about the condition of the system at the time a problemoccurred.

In contrast to message logs, in which records are made of noteworthy events, tracelogs capture transient information about the current operating environment when acomponent or application fails to operate as intended. Trace logs are available inEnglish only.

Trace logging is not enabled by default because in some circumstances it can causelarge amounts of data to be collected in a short amount of time and might result insignificant performance degradation. Enable trace logging only at the direction ofIBM Software Support personnel. See “Configuring log settings” on page 44 formore information.

Trace log entries can provide the following level of detail:

Fine Significant events that explain the flow or state of the system.

Finer Detailed trace.

Finest Developer or debug tracing.

Trace log file

If tracing is enabled, Tivoli Security Policy Manager trace information is logged forWebSphere Application Server or Tivoli Integrated Portal. The default log file nameis trace.log and it provides trace information in text format.

Using the WebSphere Application Server administrative console or the TivoliIntegrated Portal console, you can configure some settings of the logs, such as:v Location, name, maximum size of the log files


v Level of detail that you want to log, such as Fine, Finer, or Finest

For more information, see “Configuring log settings.”

Trace log locations

By default, the trace log is located in the directories listed in Table 5 and Table 6.

Table 5. WebSphere Application Server default trace log locations

Log Path

Diagnostic Trace AIX, Linux, Linux on System z, or Solaris:

/opt/IBM/WebSphere/AppServer/profiles/profile_name/logs/server_name/trace.log

Windows:

C:\Program Files\IBM\WebSphere\AppServer\profiles\profile_name\logs\server_name\trace.log

Table 6. Tivoli Integrated Portal default trace log locations

Log Path

Diagnostic Trace AIX, Linux, Linux on System z, or Solaris:

/opt/IBM/tivoli/tip/profiles/profile_name/logs/server_name/trace.log

Windows:

C:\Program Files\tivoli\tip\profiles\profile_name\logs\server_name\trace.log

Console trace logs are saved in the trace log directories of the WebSphereApplication Server node where the administration console is installed.

Configuring log settingsSettings for message and trace logs can be configured using the WebSphereApplication Server administration console or the Tivoli Integrated Portal console.Message logging is enabled by default. Enable trace logging only at the direction ofIBM Support personnel.

Configuring message loggingMessage logging to the Java Virtual Machine (JVM) log and the IBM Service log isenabled by default. Both logs are configured to log messages for all Tivoli SecurityPolicy Manager components of all severity levels for WebSphere Application Serverand Tivoli Integrated Portal.

You can modify the names, location, file size, and severity level to be logged to theJVM or IBM service log:v “Configuring the JVM log” on page 45v “Configuring the IBM Service log” on page 45


Configuring the JVM logYou can modify the file name, location, file format, file size, logging start and stoptimes, number of logs to keep, and severity level to be logged in the JVM log. TheWebSphere administrative console and the Tivoli Integrated Portal console bothproduce the JVM log.

About this task

The JVM log, or SystemOut.log, is a standard WebSphere Application Server logused for messages. For detailed information, see the JVM log topics in theWebSphere Application Server information center:v WebSphere Application Server version 6.1 http://www14.software.ibm.com/



Use the following procedure to configure the JVM log for WebSphere ApplicationServer or Tivoli Integrated Portal.

Procedure1. Start the WebSphere Application Server administrative console or the Tivoli

Integrated Portal console and log in, if necessary.2. Click Troubleshooting > Logs and Trace to open the Logging and Tracing

page.3. Click the name of the server that you want to configure.4. Click JVM Logs to view the configuration options.5. Select the Configuration tab.6. Scroll through the panel to display the attributes to configure.7. Change the configuration attributes and click Apply.8. Save your configuration changes.

Configuring the IBM Service logThe IBM Service log is enabled by default. You can change this setting or modifythe names, location, file size, and severity level to be logged in the log using theWebSphere administrative console or the Tivoli Integrated Portal console.

About this task

The service log, or activity.log, is a standard WebSphere Application Server logused for messages. For detailed information about the log, see the service logtopics in the WebSphere Application Server information center:v WebSphere Application Server version 6.1 http://www14.software.ibm.com/



Use the following procedure to configure the IBM Service log for WebSphereApplication Server or Tivoli Integrated Portal.

Procedure1. Start the WebSphere Application Server administrative console or the Tivoli

Integrated Portal console and log in, if necessary.










2. Click Troubleshooting > Logs and Trace to open the Logging and Tracingpage.

3. Click the name of the server that you want to configure.4. Click IBM Service Logs to view the configuration options.5. Select or clear the Enable service log box to enable or disable logging. The

service log is enabled by default.6. Set the name for the service log in the File Name field. The default name is

activity.log. If the name is changed, the run time requires write access to thenew file, and the file must use the .log extension.

7. Specify the number of megabytes to which the file can grow in the MaximumFile Size field. When the file reaches this size, it wraps, replacing the oldestdata with the newest data.

8. Click Apply to save the configuration changes.9. Restart the server for the configuration changes to take effect.

Enabling trace logging for WebSphere Application ServerYou can enable trace logging at server startup or on a running server forWebSphere Application Server.

Note: To maintain system performance, enable trace logging only at the directionof IBM Support personnel.

Enabling trace at server startupTrace logging can be enabled at server startup.

About this task

The trace log is a standard WebSphere Application Server log used for traceinformation. For detailed information about the log, see the WebSphere ApplicationServer information center.v WebSphere Application Server version 6.1 http://www14.software.ibm.com/



Procedure1. Start the WebSphere Application Server administrative console and log in, if

necessary.2. Click Troubleshooting > Logs and Trace to open the Logging and Tracing

page. For version 6.1, click Troubleshooting > Logging and Tracing.3. Click the Configuration tab.4. Follow the instruction, depending on your version:

v WebSphere Application Server 6.1:Select the Enable Log check box to enable trace or clear the check box todisable trace. Selecting the option turns off only the final step of loggingthese records to the WebSphere trace file. All other handlers, includinghandlers registered locally by customers or even applications, still have anopportunity to process these traces.

v WebSphere Application Server 7.0:






Do not select the None check box. If this option is selected, the trace data isnot logged or recorded anywhere. All other handlers, including handlersregistered by applications, still have an opportunity to process these traces.

5. Select whether to direct trace output to either a file or an in-memory circularbuffer.

Note: Different components can produce different amounts of trace outputper entry. Naming and security tracing, for example, produces a much highertrace output than web container tracing. Consider the type of data beingcollected when you configure your memory allocation and output settings.

6. If you selected the in-memory circular buffer for the trace output, set the sizeof the buffer specified in thousands of entries. This size is the maximumnumber of entries that are retained in the buffer at any given time.

7. If you selected a file for trace output, set the maximum size in megabytes towhich the file is allowed to grow. When the file reaches this size, the existingfile is closed, renamed, and a new file with the original name reopened. Thenew name of the file is based upon the original name with a timestampqualifier added to the name. In addition, specify the number of history files tokeep.

8. Select the format for the generated trace.9. Save the changed configuration.

10. Enter a trace string to set the trace specification to the state you want:a. Click Troubleshooting > Logs and trace in the console navigation tree. For

version 6.1, click Troubleshooting > Logging and Tracing.b. Select a server name.c. Click Change Log Detail Levels.d. If All Components has been enabled, you might want to turn it off, and

then enable specific components.e. Click a component or group name. For more information, see the

information about log level settings in the WebSphere Application ServerInformation Center. If the selected server is not running, you cannot seeindividual component in graphic mode.

f. Enter a trace string in the trace string box. For example, specifycom.ibm.tspm.* to enable logging for all Tivoli Security Policy Managercode.

g. Select Apply, then OK.11. Allow enough time for the nodes to synchronize, and then start the server.

Enabling trace on a running serverTrace logging can be enabled on a running server.

About this task

The trace log is a standard WebSphere Application Server log used for traceinformation. For detailed information about the log, see the WebSphere ApplicationServer information center.v WebSphere Application Server version 6.1 http://www14.software.ibm.com/








Procedure1. Start the WebSphere Application Server administrative console and log in, if

necessary.2. Go to the diagnostic trace page.

v For WebSphere Application Server 6.1:Click Servers > Application Servers > server_name > Troubleshooting >Diagnostic Trace Service.

v For WebSphere Application Server 7.0:Click Troubleshooting > Logs and Trace in the console navigation tree, theclick server > Diagnostic Trace.

3. Click the Runtime tab.4. Select the Save runtime changes to configuration as well box if you want to

write your changes back to the server configuration.5. Change the existing trace state by specifying the trace specification you want.

For example, specify com.ibm.tspm.* to enable logging for all Tivoli SecurityPolicy Manager code.

6. Configure the trace output if you want to change the existing one.7. Click Apply.

Enabling trace logging for Tivoli Integrated PortalTrace logging can be enabled for Tivoli Integrated Portal.

About this task

The trace log is a standard log used for trace information.

See information about Tivoli Integrated Portal logs at: http://publib.boulder.ibm.com/infocenter/tivihelp/v15r1/topic/com.ibm.tip.doc/welcome_tip_ic.htm

Note: To maintain system performance, enable trace logging only at the directionof IBM Support personnel.

Procedure1. Start the Tivoli Integrated Portal console and log in, if necessary.2. Click Troubleshooting > Logs and Trace to open the Logging and Tracing

page.3. Click the name of the Tivoli Integrated Portal server that you want to

configure.4. Click Diagnostic Trace.5. In the Configuration tab, click Change Log Detail Levels.6. In the Groups list, expand com.ibm.tspm.console.*.7. Select a log level (such as All Messages and Traces) and click OK or Apply.8. When prompted to save the configuration, click Save.9. Stop, and then restart the Tivoli Integrated Portal Server.

Enabling trace logging for the registration utilitiesYou can capture trace output generated by the registration utilities.





About this task

Use these steps to update the logging values for the tspmRegisterRTSS ortspmRegisterPDT utilities.

Procedure1. Create a TraceSettings.properties file in the TSPM_install_dir/registration

directory. Set the following properties in the file:

Property Description and example value

traceFileName=output_file_for_trace_info Name to use for the trace file.

traceFileName=/opt/IBM/RTSS/registration/MyTraceFile.log

maxFilesSize=size_in_MB_of_trace_file Maximum file size of the trace file inmegabytes.

maxFilesSize=20

maxFiles=max_number_of_trace_files_to_collect Maximum number of trace files to collect.

maxFiles=5

trace_specification_for_tspmRegisterRTSS Trace specification for the tspmRegisterRTSSutility.

com.ibm.tspm.*=allcom.ibm.tscc.*=all

trace_specification_for_tspmRegisterPDT Trace specification for the tspmRegisterPDTutility.

com.ibm.tspm.*=all

2. Access one of the following registration utility files:v AIX, Linux, or Solaris: tspmRegisterRTSS.sh or tspmRegisterPDT.sh located

in tspm_install_dir/registration

v Windows: tspmRegisterRTSS.bat or tspmRegisterPDT.bat located intspm_install_dir\registration

3. Modify the file:a. Add the directory that contains the TraceSettings.properties file to the

LOCAL_CLASSPATH.b. Add the property to enable trace,

-DtraceSettingsFile=TraceSettings.properties, to the Java command. Thefile name must not be fully qualified.

c. Add these properties to the Java command:v -Djava.util.logging.manager=com.ibm.ws.bootstrap.WsLogManager

v -Djava.util.logging.configureByServer=true

Viewing logsYou can view the JVM, IBM Service, and Trace logs from the WebSphereApplication server, but you have other options.

You can find more information about viewing each log in the following table bysearching the WebSphere Application Service Information Center. Use the followinglinks to access the appropriate version of the information center:


v Version 6.1: http://www14.software.ibm.com/webapp/wsbroker/redirect?version=pix&product=was-nd-dist

v Version 7.0: http://www14.software.ibm.com/webapp/wsbroker/redirect?version=compass&product=was-nd-dist

Log Viewing optionsSearch for informationabout:

JVM You can use:

v WebSphere ApplicationServer administrativeconsole, which supportsviewing from a remoteworkstation.

v A text editor on theworkstation where the logfiles are stored.

Viewing JVM logs

IBM Service The service logs are writtenin binary format. You canuse tools in WebSphereApplication Server.

Viewing the service log

Trace Trace data is generated asplain text in basic, advanced,or log analyzer format. Onan application server, youcan direct trace data to a fileor an in-memory circularbuffer.

If you use the circular buffer,dump the data into a file toview it.

On an application client orstand-alone process, you candirect trace data to a file orto the process consolewindow.

Trace output






Chapter 7. Analyzing data

After you collect data from multiple sources, you need to determine how that datacan help you to resolve your particular problem.

To analyze the data, take the following actions:v Determine which data sources are most likely to contain information about the

problem, and start your analysis there. For example, if the problem is related toinstallation, start your analysis with the installation log files (if any), rather thanstarting with the general product or operating system log files.

v Have a clear understanding of how the various pieces of data relate to eachother. For example, if the data spans more than one system, keep your data wellorganized so that you know which pieces of data come from which sources.

v Confirm that each piece of diagnostic data is relevant to the timing of theproblem by checking timestamps. Note that data from different sources can havedifferent timestamp formats; be sure to understand the sequence of the differentelements in each timestamp format so that you can tell when the different eventsoccurred.

The specific method of analysis is unique to each data source, but one tip that isapplicable to most traces and log files is to start by identifying the point in thedata where the problem occurs. After you identify that point, you can workbackward in time through the data in order to unravel the root cause of theproblem.

If you are investigating a problem for which you have comparative data for aworking and non-working environment, start by comparing the operating systemand product configuration details for each environment.



Chapter 8. Contacting IBM Support

IBM Support provides assistance with product defects.

Before you begin

Before contacting IBM Support, your company must have an active IBM softwaremaintenance contract, and you must be authorized to submit problems to IBM. Forinformation about the types of maintenance contracts available, see “EnhancedSupport” in the Software Support Handbook at: techsupport.services.ibm.com/guides/services.html

About this task

Complete the following steps to contact IBM Support with a problem:

Procedure1. Define the problem, gather background information, and determine the severity

of the problem. For help, see the “Contacting IBM” in the Software SupportHandbook: techsupport.services.ibm.com/guides/beforecontacting.html

2. Gather diagnostic information. See Chapter 6, “Collecting data,” on page 39.3. Submit your problem to IBM Support in one of the following ways:

v Using IBM Support Assistant (ISA). See “Using IBM Support Assistant.”v Online: Click the Report problems tab on the IBM Software Support site:

www.ibm.com/software/support/probsub.htmlv By phone: For the phone number to call in your country, go to the Contacts

page of the Software Support Handbook: techsupport.services.ibm.com/guides/contacts.html

What to do next

If the problem you submit is for a software defect or for missing or inaccuratedocumentation, IBM Support creates an Authorized Program Analysis Report(APAR). The APAR describes the problem in detail. Whenever possible, IBMSoftware IBM Support provides a workaround that you can implement until theAPAR is resolved and a fix is delivered. IBM publishes resolved APARs on theIBM Support web site daily, so that other users who experience the same problemcan benefit from the same resolution.

Using IBM Support AssistantThe IBM® Support Assistant Lite for Tivoli Security Policy Manager tool aidstroubleshooting of Tivoli Security Policy Manager. Use the tool to automaticallycollect problem data.

You must install the plug-in for IBM Support Assistant as part of the productinstallation. If you did not specify the IBM Support Assistant component wheninstalling the product, install it now.

To use the tool, see:v “Using the IBM Support Assistant in graphical mode” on page 54


http://techsupport.services.ibm.com/guides/services.html

http://techsupport.services.ibm.com/guides/services.html

http://techsupport.services.ibm.com/guides/beforecontacting.html




v “Using the IBM Support Assistant in console mode” on page 55

Using the IBM Support Assistant in graphical modeYou can use a graphical user interface to collect data with IBM Support Assistant.

About this task

To access the graphical user interface, run a script from the command line.

Procedure1. Ensure that your Java environment is configured correctly:

a. Verify that your Java runtime environment is at level 1.4.2 or higher.b. Determine if the location of the Java runtime environment is included in

your PATH environment setting. If the location is not included in your path,set the variable JAVA_HOME to point to the Java runtime environment.

Table 7. Specifying JAVA_HOME for your environment

Operating system Sample command

Windows For example, if you have a Java Development Kit installedat C:\jre1.4.2, use the command:

SET JAVA_HOME=C:\jre1.4.2

UNIX or Linux For example, if you are using the bash shell and you have aJava Development Kit installed at /opt/jre142, use thecommand:

export JAVA_HOME=/opt/jre142

2. Start the IBM Support Assistant tool:Open a command window, and change directory to the ISAlite installationdirectory. The ISAlite installation directory is the location where youuncompressed the TFIMISALite.zip file. Enter the command for yourenvironment:

Table 8. Running IBM Support Assistant

Operating system type Command

Windows runISALite.bat

UNIX or Linux runISALite.shNote: Ensure that the script is executable. Ifnecessary, use the following command tochange the file permissions:

chmod 755 runISALite.sh

The IBM Support Assistant now starts a graphical user interface.3. In the Problem Type window, select a problem type.

Expand the folders to display all problem types. Find your problem type andselect it.

4. Supply a filename for the data collection ZIP file.You can use any filename. The tool automatically appends the ZIP fileextension. For example, if you enter the filename Install_problem, the file isnamed Install_problem.zip.

5. Click Collect Data.


The collection script runs and prompts you for additional information. Theinformation can include configuration information or, the sequence of eventsleading to the problem. The script might also prompt you for preferences fordata collection.When the scripts finishes collecting the setup information, it collects thenecessary data. The tool creates a ZIP file that you can send to IBM Support.

6. When prompted, enter a filename in the Output Filename/Path box.The tool appends the server hostname and current timestamp to the filenamethat you entered.

7. Send the ZIP file to IBM SupportYou can choose FTP or HTTPS for file transfer. Note that FTP is unencryptedand HTTPS is encrypted.

Using the IBM Support Assistant in console modeYou can collect data with IBM Support Assistant in console mode.

About this task

Console mode provides command-line control of the IBM Support Assistant Litecollection scripts. The tool lets you record your responses from a console-modesession in a response file. You can then use the response file to drive subsequentexecutions of the same collection script.

Procedure1. Ensure that your Java environment is configured correctly:

a. Verify that your Java runtime environment is at level 1.4.2 or higher.b. Determine if the location of the Java runtime environment is included in

your PATH environment setting. If the location is not included in your path,set the variable JAVA_HOME to point to the Java runtime environment.

Table 9. Specifying JAVA_HOME for your environment

Operating system Sample command

Windows For example, if you have a Java Development Kit installedat C:\jre1.4.2, use the command:

SET JAVA_HOME=C:\jre1.4.2

UNIX or Linux For example, if you are using the bash shell and you have aJava Development Kit installed at /opt/jre142, use thecommand:

export JAVA_HOME=/opt/jre142

2. Start the IBM Support Assistant tool:Open a command window, and change directory to the ISAlite installationdirectory. The ISAlite installation directory is the location where youuncompressed the TFIMISALite.zip file. Enter the command for yourenvironment:

Table 10. Running IBM Support Assistant


Windows runISALiteConsole.bat

Chapter 8. Contacting IBM Support 55

Table 10. Running IBM Support Assistant (continued)


UNIX or Linux runISALiteConsole.shNote: Ensure that the script is executable. Ifnecessary, use the following command tochange the file permissions:

chmod 755 runISALite.sh

The IBM Support Assistant now starts in console mode.3. Create a response file.

Table 11. Syntax for recording data input for IBM Support Assistant


Windows runISALiteConsole.bat -record response.txt

UNIX or Linux runISALiteConsole.sh -record response.txt

You can specify your own filename for response.txt.When running in this mode, you supply data input during an interactivesession. The tool records your responses into the file that you specify.

4. Run the tool using the response file.

Table 12. Syntax for using IBM Support Assistant with a response file


Windows runISALiteConsole.bat response.txt

UNIX or Linux runISALiteConsole.sh response.txt

Note:v The response file is a plain text file. You can edit it to modify values as

needed. For example, you can use the file on another computer afteradjusting the response file values to reflect settings for the local computer.

v Remember that sensitive information, such as user names and passwords,might be stored in the response file. Manage the file carefully, to preventunauthorized access to important information.

v Some data collection sessions require interaction with the user, and thus arenot suitable for the silent collection option. For example, IBM Support mightask you to reproduce a problem during data collection, in order to collect logand trace files. In this case, silent collection cannot record and reproduce allsteps.

IBM software maintenance contractsBefore you submit a problem to IBM Software Support, ensure that your companyhas an active maintenance contract, and that you are authorized to submitproblems to IBM.

If you are not sure what type of software maintenance contract you need, call1-800-IBMSERV (1-800-426-7378) in the United States. From other countries, go tothe Contacts page of the IBM Software Support Handbook at http://techsupport.services.ibm.com/guides/contacts.html, and click the name of yourgeographic region for phone numbers of people who provide support for yourlocation.


http://techsupport.services.ibm.com/guides/contacts.html

http://techsupport.services.ibm.com/guides/contacts.html

Determining the business impactWhen you submit a problem to IBM, you are asked to supply a severity level.Therefore, you need to understand and assess the business impact of the problemthat you are reporting.

Use the following criteria:

Table 13. Severity levels

Severity 1 The problem has a critical business impact: You are unable to use theprogram, resulting in a critical impact on operations. This conditionrequires an immediate solution.

Severity 2 This problem has a significant business impact: The program is usable,but it is severely limited.

Severity 3 The problem has some business impact: The program is usable, butless significant features (not critical to operations) are unavailable.

Severity 4 The problem has minimal business impact: The problem causes littleimpact on operations or a reasonable circumvention to the problemwas implemented.

Describing a problemWhen describing a problem to IBM, be as specific as possible. Include all relevantbackground information so that IBM Software Support specialists can help yousolve the problem efficiently.

To save time, know the answers to these questions:v What software versions were you running when the problem occurred?v Do you have logs, traces, and messages that are related to the problem

symptoms?v Can you re-create the problem? If so, what steps do you perform to re-create the

problem?v Did you make any changes to the system? For example, did you make changes

to the hardware, operating system, networking software, or other systemcomponents?

v Are you currently using a workaround for the problem? If so, be prepared todescribe the workaround when you report the problem.

Submitting dataYou can send diagnostic data, such as log files and configuration files, to IBMSoftware Support.

Use one of the following methods:v IBM Support Assistantv FTP (EcuRep)v ESR tool

IBM Support Assistant

IBM Support Assistant includes a service feature which has an automated systemcollector and a symptom-based collector. The system collector gathers general


information from your operating system, registry, and other sources. Thesymptom-based collector gathers specific product information relating to aparticular problem that you are having. The service feature also enables you toautomatically set tracing to help IBM support in the data gathering process. Referto “Using IBM Support Assistant” on page 53 for more information on IBMSupport Assistant.

FTP (EcuRep)

To submit files using the FTP service called EcuRep, package the data files that youcollected into ZIP or TAR format, and name the package according to yourProblem Management Record (PMR) identifier. Your file must use the followingnaming convention in order to be correctly associated with the PMR:

xxxxx.bbb.ccc.yyy.yyy

where:

xxxxx PMR number

bbb Branch, from the PMR identifier

ccc Country code, from the PMR identifier

yyy.yyy File type (ZIP or TAR format)

To transfer your files using FTP, complete these steps:1. Using an FTP utility, connect to the emea.ibm.com server (for example,

ftp.emea.ibm.com).2. Log in as anonymous, and enter your e-mail address as your password.3. Change directories to toibm (for example, cd toibm).4. Change to one of the platform-specific subdirectories: aix, cae, hw, linux, lotus,

mvs, os2, os400, swm, tivoli, unix, vm, vse, and windows.5. Change to binary (bin) mode (for example, bin).6. Put your file on the server. You can send but not update files on the FTP

server; therefore, any subsequent time that you need to change the file, youneed to create a new file with a unique name.

For more information about the EcuRep service, see IBM EMEA CentralizedCustomer Data Store Service at http://www.ibm.com/de/support/ecurep/index.html.

If your product runs in a z/OS® environment and you want to compress your datasets, you can use the TRSMAIN utility, which you can download from thefollowing Web page: ftp://ftp.software.ibm.com/s390/mvs/tools/packlib.

ESR tool

Registered users who are on an authorized caller list can submit diagnostic datausing the Electronic Service Request (ESR) tool. The ESR tool enables you tosubmit and manage Problem Management Records (PMRs) on demand, 24 hours aday, seven days a week, 365 days a year.

To submit data using ESR, complete these steps:1. Sign onto ESR.


http://www.ibm.com/de/support/ecurep/index.html

http://www.ibm.com/de/support/ecurep/index.html

ftp://ftp.software.ibm.com/s390/mvs/tools/packlib

2. On the Welcome page, enter your PMR number in the Enter a report numberfield, and click Go.

3. Scroll down to the Attach Relevant File field.4. Click Browse to locate the log, trace, or other diagnostic file that you want to

submit to IBM Software Support.5. Click Submit. Your file is transferred to IBM Software Support through FTP,

and it is associated with your PMR.



Notices

This information was developed for products and services offered in the U.S.A.

IBM may not offer the products, services, or features discussed in this document inother countries. Consult your local IBM representative for information on theproducts and services currently available in your area. Any reference to an IBMproduct, program, or service is not intended to state or imply that only that IBMproduct, program, or service may be used. Any functionally equivalent product,program, or service that does not infringe any IBM intellectual property right maybe used instead. However, it is the user's responsibility to evaluate and verify theoperation of any non-IBM product, program, or service.

IBM may have patents or pending patent applications covering subject matterdescribed in this document. The furnishing of this document does not grant youany license to these patents. You can send license inquiries, in writing, to:

IBM Director of LicensingIBM CorporationNorth Castle DriveArmonk, NY 10504-1785U.S.A.

For license inquiries regarding double-byte (DBCS) information, contact the IBMIntellectual Property Department in your country or send inquiries, in writing, to:

Intellectual Property LicensingLegal and Intellectual Property LawIBM Japan Ltd.1623-14, Shimotsuruma, Yamato-shiKanagawa 242-8502 Japan

The following paragraph does not apply to the United Kingdom or any othercountry where such provisions are inconsistent with local law:INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THISPUBLICATION “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHEREXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIEDWARRANTIES OF NON-INFRINGEMENT, MERCHANTABILITY OR FITNESSFOR A PARTICULAR PURPOSE. Some states do not allow disclaimer of express orimplied warranties in certain transactions, therefore, this statement may not applyto you.

This information could include technical inaccuracies or typographical errors.Changes are periodically made to the information herein; these changes will beincorporated in new editions of the publication. IBM may make improvementsand/or changes in the product(s) and/or the program(s) described in thispublication at any time without notice.

Any references in this information to non-IBM Web sites are provided forconvenience only and do not in any manner serve as an endorsement of those Websites. The materials at those Web sites are not part of the materials for this IBMproduct and use of those Web sites is at your own risk.


IBM may use or distribute any of the information you supply in any way itbelieves appropriate without incurring any obligation to you.

Licensees of this program who wish to have information about it for the purposeof enabling: (i) the exchange of information between independently createdprograms and other programs (including this one) and (ii) the mutual use of theinformation which has been exchanged, should contact:

IBM Corporation2Z4A/10111400 Burnet RoadAustin, TX 78758USA

Such information may be available, subject to appropriate terms and conditions,including in some cases, payment of a fee.

The licensed program described in this information and all licensed materialavailable for it are provided by IBM under terms of the IBM Customer Agreement,IBM International Program License Agreement, or any equivalent agreementbetween us.

Any performance data contained herein was determined in a controlledenvironment. Therefore, the results obtained in other operating environments mayvary significantly. Some measurements may have been made on development-levelsystems and there is no guarantee that these measurements will be the same ongenerally available systems. Furthermore, some measurements may have beenestimated through extrapolation. Actual results may vary. Users of this documentshould verify the applicable data for their specific environment.

Information concerning non-IBM products was obtained from the suppliers ofthose products, their published announcements or other publicly available sources.IBM has not tested those products and cannot confirm the accuracy ofperformance, compatibility or any other claims related to non-IBM products.Questions on the capabilities of non-IBM products should be addressed to thesuppliers of those products.

All statements regarding IBM's future direction or intent are subject to change orwithdrawal without notice, and represent goals and objectives only.

This information contains examples of data and reports used in daily businessoperations. To illustrate them as completely as possible, the examples include thenames of individuals, companies, brands, and products. All of these names arefictitious and any similarity to the names and addresses used by an actual businessenterprise is entirely coincidental.

TrademarksIBM, the IBM logo, and ibm.com are trademarks or registered trademarks ofInternational Business Machines Corporation in the United States, other countries,or both. If these and other IBM trademarked terms are marked on their firstoccurrence in this information with the appropriate symbol (® or ™), these symbolsindicate U.S. registered or common law trademarks owned by IBM at the time thisinformation was published. Such trademarks may also be registered or common


law trademarks in other countries. A current list of IBM trademarks is available onthe Web at "Copyright and trademark information" at http://www.ibm.com/legal/copytrade.shtml

Adobe, Acrobat, Portable Document Format (PDF), and PostScript are eitherregistered trademarks or trademarks of Adobe Systems Incorporated in the UnitedStates, other countries, or both.

Intel, Intel Inside (logos), Itanium, MMX, and Pentium are trademarks of IntelCorporation in the United States, other countries, or both.

Linux is a trademark of Linus Torvalds in the United States, other countries, orboth.

Microsoft, Windows, Windows NT, and the Windows logo are trademarks ofMicrosoft Corporation in the United States, other countries, or both.

UNIX is a registered trademark of The Open Group in the United States and othercountries.

Java and all Java-based trademarks and logos are trademarks orregistered trademarks of Oracle and/or its affiliates.

Other company, product, or service names may be trademarks or service marks ofothers.

Notices 63

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

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


Index

Aabends 32accessibility viiactivity.log 42, 45administrator role permissions 16analyzing log data 51application security 26audit records file handler 17

Bbooks

See publications

Ccertificate replacement 13checklist for troubleshooting 1, 33collecting data for a problem 39component communication fails 16configuration

console does not work 12failure during security task 10failure during services task 11LDAP provisioning fails 10

configuration toollogs 40

connectivity problems 5console

does not work 12hangs 19session timeout 18

contracts, software maintenance 56crashes 32

Ddata, collecting for a problem 39directory names, notation viii

EEcuRep service 58education

See Tivoli technical trainingElectronic Service Request 58environment variables, notation viiierror messages 31errpt command 39ESR tool 58

Ffile handler 17file names of message logs 42file names of trace logs 44file, message log 42fix pack 30

fixesabout 30obtaining 37

FTP EcuRep service 58

IIBM Service log

path 42, 43steps to configure 45

IBM Support Assistant 39, 57installation

cannot reinstall 7logs 40mounted ISO error 6

Installation Managerlogs 40

Internet, searching to find softwareproblem resolution 37

JJVM log

filepath 42, 43steps to configure 45

LLDAP provisioning fails 10log files 25

installation 40uninstallation 40

loggingtrace

registration utility 49logs

analyzing data 51configuration tool 40enabling trace at server startup 46enabling trace for Tivoli Integrated

Portal 48enabling trace on a running

server 47file names 41, 43Installation Manager 40locations 42, 44message 42message types 41Tivoli Integrated Portal 40trace 43, 44viewing 49

Mmaintenance contracts 56manuals

See publicationsmessage logs 41messages 31

methods for submitting data to IBM 57migration disabled 9mounted ISO image error 6

Nnotation

environment variables viiipath names viiitypeface viii

Oonline publications

accessing viordering publications vi

Ppath names, notation viiiperformance problems 31policy

configuration errors 20distribution 18removal 18

problem-specific data 39problems

collecting data 39connectivity 5performance 31report 57symptoms 3

product fixes 30publications v

accessing online viordering vi

Rrefresh pack 30registration utility 25, 26

certificate errors 27error CWWSS5508E 25expired certificates 28trace logging 49

reports fail 19runtime security services

certificate errors 27CWWSS5508E error 25expired certificates 28registry not federated repository 23WS-Security issues 24

Sservice import error 20severity levels of problems 57software maintenance contracts 56submitting data to IBM, methods 57


support handbook 56symptoms, troubleshooting 3SystemOut.log 42

Ttext does not wrap 22timeout errors 12Tivoli Information Center viTivoli Integrated Portal

logs 40Tivoli Integrated Portal console

IBM Service log 45JVM log 45

Tivoli Security Policy Manageradministrator role permissions 16cannot reinstall 7certificate replacement 13component communication fails 16configuration tool fails 10, 11console does not work 12console hangs 19installation error 6LDAP provisioning fails 10migration disabled 9mounted ISO error 6policy configuration errors 20reports fail 19service import error 20session timeout 18text does not wrap 22timeout errors 12

Tivoli technical training viitrace 25trace logging

registration utility 49trace logging, enabling 46trace logs 43training, Tivoli technical viitraps 32troubleshooting

checklist 1, 33exceptions 17performance 17policy distribution 18policy removal 18process 1registration 25, 26symptoms 3user search 19

TRSMAIN utility 58types of messages 41

Uuninstallation

logs 40updates to product 30user registry

not a federated repository 23

Vvariables, notation for viiiviewing logs 49

WWeb site for fixes 30WebSphere administrative console

IBM Service log 45JVM log 45

WebSphere security 26workspaces in wstemp directory 17WS-Security issues 24wstemp directory 17


��

Printed in USA

GC27-2711-00

Documents

Version 7.1: Troubleshooting Guide - e IBM Tivoli Composite