Tivoli Access Manager for e-business

Transcription

1 Tivoli Access Manager for e-business Version 6.1 Problem Determination Guide GI

2

3 Tivoli Access Manager for e-business Version 6.1 Problem Determination Guide GI

4 Note Before using this information and the product it supports, read the information in Appendix E, Notices, on page 167. Edition notice This edition applies to version 6, release 1 of IBM Tivoli Access Manager (product number 5724-C08) and to all subsequent releases and modifications until otherwise indicated in new editions. Copyright International Business Machines Corporation 2002, All rights reserved. US Government Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

5 Contents About this publication vii Intended audience vii What this publication contains vii Publications ix IBM Tivoli Access Manager for e-business library ix Related products and publications......xi Accessing terminology online xii Accessing publications online xii Ordering publications xiii Accessibility xiii Tivoli technical training xiii Support information xiii Conventions used in this publication..... xiv Typeface conventions xiv Operating system-dependent variables and paths xiv Part 1. Introduction Chapter 1. Introduction to problem determination Avoiding potential problems Problem resolution Product short names Serviceability enhancements Chapter 2. Tivoli Common Directory.. 5 Location of the Tivoli Common Directory properties file Common directories used by Tivoli Access Manager 5 Configuration setting used by Tivoli Access Manager 6 Chapter 3. Messages Message types Message format Message identifiers Chapter 4. Tivoli XML Log Viewer Installing the Tivoli XML Log Viewer Running the Tivoli XML Log Viewer Part 2. Deployment Chapter 5. Installation and initial configuration Log files Installation wizard log files Native installation log files Native configuration log files Installation wizard problems Insufficient disk space for temporary files...18 Cannot launch the installation wizard Installation wizard failed Removing the ibmjcaprovider.jar file Operating system problems Multiple network interfaces Initial configuration problems Timing out during configuration Recovering an LDAP server Upgrade common problems Cannot create users or groups after upgrade..21 Chapter 6. Verifying the deployment.. 23 System types in a deployment Base systems Web security systems Distributed session management systems...26 Checking installed software Verifying Global Security Kit Verifying user registries Tivoli Directory Server Microsoft Active Directory Lotus Domino Server Verifying base systems Verifying the policy server Verifying the authorization server Verifying the runtime Verifying Web security systems Verifying WebSEAL Verifying Plug-in for Web Servers Chapter 7. Validating and maintaining policy databases Displaying all database contents Displaying summary reports Repairing a damaged policy database Replacing a damaged policy database Part 3. Logging Chapter 8. Diagnostics versus auditing 37 Diagnostic events Auditing events Chapter 9. Routing files Location of routing files Routing file entries Chapter 10. Java properties files Location of Java properties files Application-specific logging of Java applications..43 Configuring message events with the Java properties file Message loggers and file handlers When PDJLog.properties is used Console handler and console message logging..45 Copyright IBM Corp. 2002, 2008 iii

6 Tailoring message logging in Web Portal Manager Configuring trace events with the Java properties file Trace loggers and file handlers Enabling trace in a Runtime for Java environment Enabling trace in Web Portal Manager Chapter 11. Message event logging.. 49 Severity of message events FATAL messages ERROR messages WARNING messages NOTICE messages NOTICE_VERBOSE messages Location of message logs Location with Tivoli Common Directory Location without Tivoli Common Directory...51 Names of message logs Names of runtime logs Names of server logs Format of messages in logs Messages in text format Messages in XML log format Environment variables Routing files for message events C runtime routing file Policy server pdmgrd_routing file Authorization server pdacld_routing file Policy proxy server pdmgrproxyd_routing file..58 WebSEAL routing file Understanding message routing files C runtime routing file on Windows Policy server routing file on UNIX WebSEAL routing file on UNIX Limiting the size of message logs Estimating the size of message logs Changing the location of log files Logging all messages the same way Using GOESTO statements Changing the message format in log files Sending messages to multiple places in different formats Chapter 12. Trace event logging Mechanisms for controlling trace logging Routing file examples Trace logging in Tivoli XML log format Trace logging to multiple files Tracing a particular component Determining maximum size of a trace log Enabling trace Using the trace commands Listing available trace components Enabling trace Showing enabled trace components Changing the name and location of trace files..71 Format of trace entry in logs Trace logging for session management Part 4. Problems with base systems 75 Chapter 13. Common Tivoli Access Manager problems Unable to configure the policy server Unable to communicate with user registry...77 Configuration fails with LDAP server Configuration fails with Domino server Unable to create new user Unable to authenticate user Insufficient disk space Windows disk space Linux and UNIX disk space Unexpected access to resources ACL commands POP commands Authorization rule commands Processes terminate abruptly on Intel 64-bit processor Chapter 14. Tivoli Access Manager user registries LDAP common problems LDAP does not start after creating suffix...83 Insufficient privileges to perform operations..84 Tivoli Directory Server common problems Java error during installation Passwords not encrypted Location of error logs Tivoli Directory Server error log warnings...85 Setting up SSL Active Directory common problems Receiving HPDRG0100E for Active Directory operations Receiving HPDRG0101E The user password violates the Active Directory user password policies Global Security Kit common problems Error when importing a PKCS12 formatted file 87 Part 5. Problems with Web security systems Chapter 15. Desktop single sign-on.. 91 Basic SPNEGO troubleshooting Linux and UNIX workflow Windows workflow Kerberos initialization failing Unable to initialize Kerberos libraries Unable to obtain initial credentials Web security server not starting Authentication method not configured No match to principal in key table Unable to authenticate Ticket not yet valid Cannot acquire credentials Wrong principal in request Encryption type not permitted Key version is incorrect iv Problem Determination Guide

7 Cannot authenticate using NTLM Cannot complete authentication Algorithm to resolve host names Useful Kerberos procedures Validating keys in key tables Listing caches, principals, and service principals 101 Listing keys in key tables Listing tickets in credential caches Chapter 16. WebSEAL servers WebSEAL trace components pdweb.debug component pdweb.snoop component WebSEAL fails to start when configured to use Hardware Cryptographic devices Unable to customize response when using basic authentication WebSEAL not responding on ports 80 or Multiple log ins with e-community e-community SSO Master Authentication Server configured with EAI Verifying junctioned, third-party Web server WebSEAL performance is degraded when downloading files WebSEAL does not start after being configured to use PKCS # DPWWA0305E inconsistent message severity Error when creating an LTPA junction Chapter 17. Web server plug-ins Setting cache controls for Web servers Plug-in for Edge Server Tailoring message logging an Edge Server environment Tailoring trace logging in an Edge Server environment Part 6. Collecting troubleshooting data Chapter 18. Gathering initial diagnostic information Installation directories Tivoli Access Manager Shared Session Management WebSEAL Plug-in for Web Servers Plug-in for Edge Server Locating diagnostic utilities Gathering version information Tivoli Access Manager IBM Global Security Kit User registries Gathering system information Chapter 19. Collecting troubleshooting data General information to collect Collecting trace information Collecting trace information by server Collecting the policy server trace file Collecting the policy proxy server trace file..118 Collecting the WebSEAL trace files Collecting the authorization server trace file..119 Collecting the C-language trace file Collecting the Java-language trace files Collecting the message files Submitting your gathered data to IBM Appendix A. Serviceability commands 123 Reading syntax statements Serviceability and problem determination commands server list server task trace Serviceability and problem determination utilities 127 pdbackup pdjservicelevel pdservicelevel pdversion pdwebpi pdwpi-version Appendix B. User registry differences 139 General concerns LDAP concerns Sun Java System Directory Server concerns Microsoft Active Directory Application Mode (ADAM) concerns URAF concerns Lotus Domino Server concerns Microsoft Active Directory Server concerns Length of names Appendix C. AutoTrace AutoTrace features AutoTrace files Files installed during installation Files not installed during installation Initializing the Windows AutoTrace service Initializing the AutoTrace control program Verifying the initialization Displaying channel information Displaying configuration information Displaying product information Collecting trace data Trace file format and example Reading trace data Trace file example Creating a trace ID file Technique Technique Known problems Useful AutoTrace commands atctl commands atrpt commands atdb commands Appendix D. Support information Contents v

8 Searching knowledge bases Searching information centers Searching the Internet Obtaining fixes Registering with IBM Software Support Receiving weekly software updates Contacting IBM Software Support Determining the business impact Describing problems and gathering information 164 Submitting problems Appendix E. Notices Trademarks Glossary Index vi Problem Determination Guide

9 About this publication The IBM Tivoli Access Manager for e-business: Problem Determination Guide provides a comprehensive set of procedures and reference information for troubleshooting Tivoli Access Manager. IBM Tivoli Access Manager is the base software that is required to run applications in the Tivoli Access Manager product suite. This base software enables the integration of Tivoli Access Manager applications to provide a wide range of authorization and management solutions. Sold as integrated products, these applications can provide an access control management solution to centralize network and application security policy for e-business applications. Intended audience This guide is for system administrators and field support personnel responsible for troubleshooting a Tivoli Access Manager environment. Readers should be familiar with the following: v PC and UNIX operating systems v Database architecture and concepts v Security management v Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and Telnet v Lightweight Directory Access Protocol (LDAP) and directory services v A supported user registry v Authentication and authorization v Secure Sockets Layer (SSL) protocol, key exchange (public and private), digital signatures, cryptographic algorithms, and certificate authorities. What this publication contains This book contains the following sections: v Part 1: Introduction Chapter 1, Introduction to problem determination, on page 3 Provides an overview of the troubleshooting process to help you determine why Tivoli Access Manager for e-business is not functioning in the expected manner. Chapter 2, Tivoli Common Directory, on page 5 Provides information about Tivoli Common Directory and how Tivoli Access Manager for e-business can be enabled to use this functionality. Chapter 3, Messages, on page 9 Provides information about the Tivoli Message Standard and information about the messages produced by Tivoli Access Manager for e-business. Chapter 4, Tivoli XML Log Viewer, on page 11 Provides information about and instructions for using the Tivoli XML Log Viewer. v Part 2: Deployment Copyright IBM Corp. 2002, 2008 vii

10 Chapter 5, Installation and initial configuration, on page 15 Provides detailed information about identifying and resolving installation problems. Chapter 6, Verifying the deployment, on page 23 Provides details about verifying the installation and functionality of the Tivoli Access Manager for e-business components. Chapter 7, Validating and maintaining policy databases, on page 33 Provides detailed information about using the pdacld_dump command. v Part 3: Logging Chapter 8, Diagnostics versus auditing, on page 37 Explains the difference between diagnostic events and auditing events. Chapter 9, Routing files, on page 39 Provides information about the routing files that you can use configure the capture of diagnostic events for C-based applications. Chapter 10, Java properties files, on page 43 Provides information about the Java properties files that you can use configure the capture of diagnostic events for Java-based applications. Chapter 11, Message event logging, on page 49 Describes the logging of message events for the Tivoli Access Manager for e-business components. Chapter 12, Trace event logging, on page 67 Describes the logging of trace events for the Tivoli Access Manager for e-business components. v Part 4: Problems with base systems Chapter 13, Common Tivoli Access Manager problems, on page 77 Provides details about resolving common problems with the Tivoli Access Manager base systems. Chapter 14, Tivoli Access Manager user registries, on page 83 Provides detailed information about resolving common problems with the user registries that are supported by Tivoli Access Manager. v Part 5: Problems with Web security systems Chapter 15, Desktop single sign-on, on page 91 Provides detailed information about resolving common problems with Desktop single sign-on. Chapter 16, WebSEAL servers, on page 103 Provides detailed information about resolving common problems with Tivoli Access Manager WebSEAL. Chapter 17, Web server plug-ins, on page 109 Provides detailed information about resolving common problems with Tivoli Access Manager plug-ins. v Part 6 Collecting troubleshooting data Chapter 18, Gathering initial diagnostic information, on page 113 Provides detailed information about the tools and utilities that you can use to diagnose software problems. Chapter 19, Collecting troubleshooting data, on page 117 Provides detailed information about contacting IBM Software Support for problems not resolved in this guide. viii Problem Determination Guide

11 This book contains the following appendixes: v Appendix A, Serviceability commands, on page 123 Provides reference information about the serviceability and problem determination commands and utilities. v Appendix B, User registry differences, on page 139 Describes the differences that are known to exist in the supported user registries. v Appendix C, AutoTrace, on page 147 Describes the AutoTrace tools to be used at the direction of IBM Software Support to aid in the identification and resolution of software problems. v Appendix D, Support information, on page 161 Provides information about how to use the IBM Support Web site and instruction for report problems to IBM Software Support. Publications This section lists publications in the IBM Tivoli Access Manager for e-business library and related documents. The section also describes how to access Tivoli publications online and how to order Tivoli publications. IBM Tivoli Access Manager for e-business library Review the descriptions of the Tivoli Access Manager library, the prerequisite publications, and the related publications to determine which publications you might find helpful. After you determine the publications you need, refer to the instructions for accessing publications online. Additional information about the Tivoli Access Manager for e-business product itself can be found at the following Web address: The Tivoli Access Manager library is organized into the following categories: v Release information v Installation and upgrade documentation v Administration documentation on page x v Reference documentation on page x v Problem determination documentation on page xi v Performance tuning documentation on page xi Release information v IBM Tivoli Access Manager for e-business: Release Notes, GC Provides information about installing and getting started, system requirements, known installation and configuration problems, and problem workarounds. Installation and upgrade documentation v IBM Tivoli Access Manager for e-business: Installation Guide, GC Explains how to install and configure Tivoli Access Manager for e-business. v IBM Tivoli Access Manager for e-business: Upgrade Guide, SC Explains how to upgrade to Tivoli Access Manager for e-business version 6.1. v IBM Tivoli Access Manager for e-business: Quick Start Guide, GI About this publication ix

12 Provides a high-level overview of a Tivoli Access Manager for e-business version 6.1 installation. Administration documentation v IBM Tivoli Access Manager for e-business: Administration Guide, SC Describes the concepts and procedures for using Tivoli Access Manager. Provides instructions for performing tasks from the Web Portal Manager interface and by using the pdadmin utility. v IBM Tivoli Access Manager for e-business: WebSEAL Administration Guide, SC Provides background material, administrative procedures, and technical reference information for using WebSEAL to manage the resources of your secure Web domain. v IBM Tivoli Access Manager for e-business: Plug-in for Edge Server Administration Guide, SC Provides administration instructions for integrating Tivoli Access Manager with the IBM WebSphere Edge Server application. v IBM Tivoli Access Manager for e-business: Plug-in for Web Servers Administration Guide, SC Provides administration procedures, and technical reference information for securing your Web domain using a Web server plug-in. v IBM Tivoli Access Manager for e-business: Shared Session Management Administration Guide, SC Provides deployment considerations and operational instructions for the session management server. v IBM Global Security Kit: Secure Sockets Layer Introduction and ikeyman User s Guide, SC Provides information for network or system security administrators who plan to enable SSL communication in their Tivoli Access Manager environment. v IBM Tivoli Access Manager for e-business: Auditing Guide, SC Provides information about configuring and managing audit events using the native Tivoli Access Manager approach and the Common Auditing and Reporting Service. Information about installing and configuring the Common Auditing and Reporting Service that can be used for generating and viewing operational reports is also provided. Reference documentation v IBM Tivoli Access Manager for e-business: Command Reference, SC Provides reference information about the commands, utilities, and scripts that are provided with Tivoli Access Manager. v IBM Tivoli Access Manager for e-business: Administration C API Developer Reference, SC Provides reference information about using the C language implementation of the administration API to enable an application to perform Tivoli Access Manager administration tasks. v IBM Tivoli Access Manager for e-business: Administration Java Classes Developer Reference, SC Provides reference information about using the Java language implementation of the administration API to enable an application to perform Tivoli Access Manager administration tasks. x Problem Determination Guide

13 v IBM Tivoli Access Manager for e-business: Authorization C API Developer Reference, SC Provides reference information about using the C language implementation of the authorization API to enable an application to use Tivoli Access Manager security. v IBM Tivoli Access Manager for e-business: Authorization Java Classes Developer Reference, SC Provides reference information about using the Java language implementation of the authorization API to enable an application to use Tivoli Access Manager security. v IBM Tivoli Access Manager for e-business: Web Security Developer Reference, SC Provides programming and reference information for developing authentication modules. Problem determination documentation v IBM Tivoli Access Manager for e-business: Problem Determination Guide, GI Provides problem determination information for Tivoli Access Manager. v IBM Tivoli Access Manager for e-business: Error Message Reference, GI Provides explanations and recommended actions for the messages and return code that are generated by Tivoli Access Manager. Performance tuning documentation v IBM Tivoli Access Manager for e-business: Performance Tuning Guide, SC Provides performance tuning information for an environment consisting of Tivoli Access Manager with the IBM Tivoli Directory Server as the user registry. Related products and publications This section lists the IBM products that are related to and included with a Tivoli Access Manager solution. IBM Global Security Kit Tivoli Access Manager provides data encryption through the use of the Global Security Kit (GSKit) version 7.0. GSKit is included on the IBM Tivoli Access Manager Base CD for your particular platform, as well as on the IBM Tivoli Access Manager Web Security CDs, the IBM Tivoli Access Manager Shared Session Management CDs, and the IBM Tivoli Access Manager Directory Server CDs. The GSKit package provides the ikeyman key management utility, gsk7ikm, which is used to create key databases, public-private key pairs, and certificate requests. The IBM Global Security Kit: Secure Sockets Layer Introduction and ikeyman User s Guide is available on the Tivoli Information Center Web site in the same section as the Tivoli Access Manager product documentation. IBM Tivoli Directory Server IBM Tivoli Directory Server version 6.1 is included on the IBM Tivoli Access Manager Directory Server set of CDs for the desired operating system. Additional information about Tivoli Directory Server can be found at the following Web address: About this publication xi

14 IBM Tivoli Directory Integrator IBM Tivoli Directory Integrator version is included on the IBM Tivoli Directory Integrator CD for the desired operating system. Additional information about IBM Tivoli Directory Integrator can be found at the following Web address: IBM DB2 Universal Database IBM DB2 Universal Database Enterprise Server Edition version 9.1 is provided on the IBM Tivoli Access Manager Directory Server set of CDs and is installed with the Tivoli Directory Server software. DB2 is required when using Tivoli Directory Server or z/os LDAP servers as the user registry for Tivoli Access Manager. For z/os LDAP servers, you must separately purchase DB2. Additional information about DB2 can be found at the following Web address: IBM WebSphere Application Server WebSphere Application Server version 6.1 is included on the IBM Tivoli Access Manager WebSphere Application Server set of CDs for the desired operating system. WebSphere Application Server enables the support of the Web Portal Manager interface, which is used to administer Tivoli Access Manager; the Web Administration Tool, which is used to administer Tivoli Directory Server; the Common Auditing and Reporting Service, which is used to process and report on audit events; the session management server, which is used to managed shared session in a Web security server environment and the Attribute Retrieval Service. Additional information about WebSphere Application Server can be found at the following Web address: Accessing terminology online The Tivoli Software Glossary includes definitions for many of the technical terms related to Tivoli software. The Tivoli Software Glossary is available at the following Tivoli software library Web site: The IBM Terminology Web site consolidates the terminology from IBM product libraries in one convenient location. You can access the Terminology Web site at the following Web address: Accessing publications online The Tivoli Software Library provides a variety of Tivoli publications such as white papers, data sheets, demonstrations, Redbooks, and announcement letters. The publications for this product and many other Tivoli products are available online in Portable Document Format (PDF) or Hypertext Markup Language (HTML) format, or both in the Tivoli software library at the following Web address: xii Problem Determination Guide

15 Accessibility Ordering Tivoli technical training To locate product publications in the library, click the first letter of the product name or scroll until you find the product name. Then click the name of the product. Product publications include release notes, installation guides, user s guides, administrator s guides, and developer s references. Note: To ensure proper printing of PDF publications, select the Fit to page check box in the Adobe Acrobat Print window (which is available when you click File Print). publications You can order many Tivoli publications online at You can also order by telephone by calling one of these numbers: v In the United States: v In Canada: In other countries, contact your software account representative to order Tivoli publications. To locate the telephone number of your local representative, perform the following steps: 1. Go to 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. Accessibility features help users with a physical disability, such as restricted mobility or limited vision, to use software products successfully. With this product, you can use assistive technologies to hear and navigate the interface. You can also use the keyboard instead of the mouse to operate all features of the graphical user interface. For Tivoli technical training information, refer to the following IBM Tivoli Education Web site at Support information If 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: Online Go to the IBM Software Support site at supportand follow the instructions. IBM Support Assistant The IBM Support Assistant (ISA) is a free local software serviceability workbench that helps you resolve questions and problems with IBM software products. The ISA provides quick access to support-related information and serviceability tools for problem determination. To install the ISA software, go to About this publication xiii

16 Problem Determination Guide For more information about resolving problems, see the IBM Tivoli Access Manager for e-business: Problem Determination Guide. Conventions used in this publication Typeface This publication uses several conventions for special terms and actions, operating system-dependent commands and paths, and margin graphics. conventions This publication uses the following typeface conventions: Bold Italic v Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text v Interface controls (check boxes, push buttons, radio buttons, spin buttons, fields, folders, icons, list boxes, items inside list boxes, multicolumn lists, containers, menu choices, menu names, tabs, property sheets), labels (such as Tip:, and Operating system considerations:) v Keywords and parameters in text v Citations (examples: titles of publications, diskettes, and CDs v Words defined in text (example: a nonswitched line is called a point-to-point line) v Emphasis of words and letters (words as words example: "Use the word that to introduce a restrictive clause."; letters as letters example: "The LUN address must start with the letter L.") v New terms in text (except in a definition list): a view is a frame in a workspace that contains data. v Variables and values you must provide:... where myname represents... Monospace v Examples and code examples v File names, programming keywords, and other elements that are difficult to distinguish from surrounding text v Message text and prompts addressed to the user v Text that the user must type v Values for arguments or command options Operating system-dependent variables and paths This publication uses the UNIX convention for specifying environment variables and for directory notation. When using the Windows command line, replace $variable with % variable% for environment variables and replace each forward slash (/) with a backslash (\) in directory paths. The names of environment variables are not always the same in the Windows and UNIX environments. For example, %TEMP% in Windows environments is equivalent to $TMPDIR in UNIX environments. Note: If you are using the bash shell on a Windows system, you can use the UNIX conventions. xiv Problem Determination Guide

17 Part 1. Introduction Chapter 1. Introduction to problem determination 3 Avoiding potential problems Problem resolution Product short names Serviceability enhancements Chapter 2. Tivoli Common Directory Location of the Tivoli Common Directory properties file Common directories used by Tivoli Access Manager 5 Configuration setting used by Tivoli Access Manager 6 Chapter 3. Messages Message types Message format Message identifiers Chapter 4. Tivoli XML Log Viewer Installing the Tivoli XML Log Viewer Running the Tivoli XML Log Viewer Copyright IBM Corp. 2002,

18 2 Problem Determination Guide

19 Chapter 1. Introduction to problem determination Avoiding potential problems Problem determination, or troubleshooting, is a process of determining why a product is not functioning in the expected manner. This guide provides information to help you identify and resolve problems that you might encounter while using Tivoli Access Manager and its prerequisite products. Tivoli Access Manager provides an authentication and authorization framework for permitting or restricting access to system resources that are located in a secure domain. You can often prevent problems through planning before deploying software. Before installing Tivoli Access Manager, review the IBM Tivoli Access Manager for e-business: Release Notes. This document contains the following information: v Supported operating system levels v Prerequisite software requirements v Required software patches v Minimum and recommended memory requirements v Disk space requirements v Upgrade considerations v Known problems, limitations, and recovery procedures v Customer support contact information After installing Tivoli Access Manager, ensure that you have a comprehensive backup and system recovery strategy in place. When creating your backup and recovery strategy, include the following information to help avoid the possibility of running into problems: v Perform regular periodic backups of Tivoli Access Manager by using the pdbackup command. v Periodically backup the user registry following the instructions provided by the user registry vendor. v Maintain information about your environment, including system topology, IP addresses, host names, and which components are installed on each system. v Maintain updated information that describes the key system resources that are being managed by Tivoli Access Manager and the security policies that are being applied to them by Tivoli Access Manager. v Periodically check that all systems running Tivoli Access Manager have sufficient disk space for runtime and problem determination data. As your security policy grows, and the number of users, groups, and protected objects increase, the space requirements for the policy databases, message logs, trace logs, and any auditing information can increase as well. v Regularly check for the availability of fix packs and install them as they become available. Information on fix packs and other useful information can be found on the IBM Software Support site at the following Web address: Copyright IBM Corp. 2002,

20 Problem resolution Product short names When problems do occur, use the information in this guide to identify and possibly resolve them. If you are unable to correct the problem, gather the relevant diagnostic information as described in this guide and then use the information in Chapter 19, Collecting troubleshooting data, on page 117 to get further assistance. To provide consistency with other IBM and Tivoli products, components of Tivoli Access Manager identify some product-specific information with a unique product identifier. This three-character identifier is used in the following places: v As the first three characters of message IDs. (See the IBM Tivoli Access Manager for e-business: Error Message Reference for a complete explanation of messages in Tivoli Access Manager) v To identify the subdirectory that contains the serviceability information when using the Tivoli Common Directory v AutoTrace (see Appendix C, AutoTrace, on page 147 for details) The product identifiers associated with Tivoli Access Manager for e-business are shown in Table 1. Table 1. Product short names in Tivoli Access Manager Product identifier Tivoli Access Manager component HPD Tivoli Access Manager DPW Tivoli Access Manager WebSEAL AWD Tivoli Access Manager Plug-in for Edge Server AMZ Tivoli Access Manager Plug-in for Web Servers CTG Tivoli Access Manager Shared Session Management Note: CTG is a product identifier for multiple Tivoli components, not just the Shared Session Management component. Serviceability enhancements Tivoli Access Manager supports the following serviceability initiatives: v Tivoli Common Directory as explained in Chapter 2, Tivoli Common Directory, on page 5. v Tivoli Message Standard as explained in Chapter 3, Messages, on page 9. v Tivoli XML log format as explained in Chapter 4, Tivoli XML Log Viewer, on page Problem Determination Guide

21 Chapter 2. Tivoli Common Directory To provide a consistent mechanism for locating serviceability information, Tivoli Access Manager provides the ability to use Tivoli Common Directory logging. Tivoli Access Manager does not take advantage of the Tivoli Common Directory unless you explicitly request this behavior during the installation of the product. By default, serviceability information is stored in the /log subdirectory of the product installation directory. If Tivoli Common Directory support is requested, the installation wizard uses the existing Tivoli Common Directory as the default location for serviceability information. If no existing Tivoli Common Directory is in use, the directory specified during the installation is identified as the Tivoli Common Directory and serviceability information for Tivoli Access Manager and other Tivoli products is stored there. When enabled, all message log file are in this central location. Other types of application log files continue to be located in their installation directories. Products that support Tivoli Common Directory store the following types of serviceability-related files in this central location: v Logs files v First-failure data capture (FFDC) files v Serviceability scripts Note: After defining the Tivoli Common Directory location, you cannot change it. Location of the Tivoli Common Directory properties file If any product on the system uses Tivoli Common Directory, the parent directory is defined in the log.properties file. Depending on your operating system, the log.properties file is in one of the following default locations: Linux and UNIX operating systems /etc/ibm/tivoli/common/cfg/log.properties Windows operating systems c:\program files\ibm\tivoli\common\cfg\log.properties On a Linux or UNIX operating system, this file should have the 664 permission and should be owned by group tivoli. Common directories used by Tivoli Access Manager During the configuration of the Tivoli Access Manager C runtime or Java runtime, the default location is displayed. If Tivoli Access Manager is the first Tivoli product on this system to use Tivoli Common Directory, you can change this location. If another product already defined this location, this location is displayed and you cannot change this location. Copyright IBM Corp. 2002,

22 After enabling Tivoli Common Directory, Tivoli Access Manager uses the /logs subdirectory to store message and trace logs. Tivoli Access Manager does not use the /ffdc or /scripts subdirectories. The logs files can be found at the following default location: common_directory/xxx/logs/ where: common_directory Represents the parent directory for serviceability data. This directory is usually defined by the first Tivoli product that uses Tivoli Common Directory. The default values, if Tivoli Access Manager is the first Tivoli product, is one of the following platform-specific directories: Linux and UNIX operating systems /var/ibm/tivoli/common Windows operating systems c:\program files\ibm\tivoli\common\ Note: On a Linux or UNIX operating system, this directory should have the 771 permissions and be owned by the tivoli group. xxx Represents the 3-letter identifier to use for the product-specific message log files. Tivoli Access Manager uses the following identifiers: HPD The identifier for Tivoli Access Manager DPW The identifier for Tivoli Access Manager WebSEAL AMZ The identifier for Tivoli Access Manager Plug-in for Web Servers AWD The identifier for Tivoli Access Manager Plug-in for Edge Server AOS The identifier for Tivoli Access Manager for Operating Systems DRQ The identifier for Tivoli Access Manager for Business Integration logs The subdirectory that is used for Tivoli Access Manager message and trace log files. Only one subdirectory, /logs, is defined for these log files. Configuration setting used by Tivoli Access Manager When configured for Tivoli Common Directory, the tivoli_common_dir stanza entry of the pd.conf configuration file would be similar to one of the following entries: Linux and UNIX operating systems [pdrte] tivoli_common_dir = var/ibm/tivoli/common/ Windows operating systems [pdrte] tivoli_common_dir = c:\program Files\IBM\Tivoli\common\ When configured for Tivoli Common Directory, the log-file stanza entry of the server-specific configuration file contains the fully qualified names of the log files. For example, when configured for Tivoli Common Directory, the log_file stanza entry for the authorization server log files would be similar to one of the following entries: 6 Problem Determination Guide

23 Linux and UNIX operating systems [ivacld] log-file = var/ibm/tivoli/common/hpd/logs/msg pdacld_utf8.log Windows operating systems [ivacld] log-file = c:\program Files\IBM\Tivoli\common\HPD\logs \msg pdacld_utf8.log Chapter 2. Tivoli Common Directory 7

24 8 Problem Determination Guide

25 Chapter 3. Messages All messages issued by Tivoli Access Manager adhere to the Tivoli Message Standard. The Tivoli Message Standard specifies a standard format for all messages issued by Tivoli products. The standard, based on the IBM Message Standard, is intended to provide a consistent and meaningful way for identifying messages across the entire Tivoli product set. Messages issued by Tivoli Access Manager, along with detailed explanations and suggested actions, can be found in the IBM Tivoli Access Manager for e-business: Error Message Reference. Message types Tivoli Access Manager is written in both the C and Java programming languages. Applications that use the Tivoli Access Manager APIs are also written in these programming languages. Tivoli Access Manager produces the following types of messages: Runtime messages Messages that are generated by applications, commands, and utilities that use the Tivoli Access Manager Runtime component, as well as messages that are generated from the C language-based Tivoli Access Manager components, such as WebSEAL. These messages are written to the runtime message logs based on their severity levels. These messages follow the message standard. Additional information on these messages can be found in the IBM Tivoli Access Manager for e-business: Error Message Reference. Tivoli Access Manager Runtime for Java messages Messages that are generated by applications, commands, and utilities that use the Tivoli Access Manager Runtime for Java component, as well as messages that are generated from the Java language-based Tivoli Access Manager components. These messages are written to the Tivoli Access Manager Runtime for Java message logs. These messages tend to provide exception and stack trace information from the JRE. Server messages Messages that are generated by the Tivoli Access Manager daemons and servers. Messages from the policy server, authorization server, WebSEAL servers, and policy proxy server are written to the server message logs. These messages follow the message standard. Additional information on these messages can be found in the IBM Tivoli Access Manager for e-business: Error Message Reference. Installation and configuration messages Messages that are generated by the InstallShield MultiPlatform installation wizards as well as by the configuration utilities. Some of these messages follow the message standard and have an associated ID. These messages are written to the log files described in Chapter 5, Installation and initial configuration, on page 15 during installation. WebSEAL HTTP messages WebSEAL provides the capability of logging HTTP messages. This message logging capability is described in the IBM Tivoli Access Manager for e-business: Auditing Guide. Copyright IBM Corp. 2002,

26 Message format A message consists of a message identifier (ID) and message text and an error code. The error code is a unique 32-bit value. The error code is either a decimal or hexadecimal number and indicates that an operation was not successful. All messages that follow the message standard are listed in the IBM Tivoli Access Manager for e-business: Error Message Reference. Each of these messages has a detailed explanation and suggested actions. Message identifiers A message ID consists of 10 alphanumeric characters that uniquely identify the message. The message ID consists of the following parts: v A 3-character product identifier (see Table 2 for the list of identifiers that are used by Tivoli Access Manager) v A 2-character component or subsystem identifier v A 4-digit serial or message number v A 1-character type code indicating the one of the following message severities: W Warning E Error I Information Table 2. Product identifiers that are used by Tivoli Access Manager Product identifier Tivoli Access Manager component HPD Tivoli Access Manager servers DPW Tivoli Access Manager WebSEAL AWD Tivoli Access Manager Plug-in for Edge Server AMZ Tivoli Access Manager Plug-in for Web Servers CTG Tivoli Access Manager Shared Session Management 10 Problem Determination Guide

27 Chapter 4. Tivoli XML Log Viewer The C-based components of Tivoli Access Manager support the generation of message and trace information in a common XML format. This format is known as the Tivoli XML log format and is used by a number of Tivoli applications. A Java-based log viewer is provided that allows these messages and traces to be filtered in a number of ways, including by time window, severity, thread ID, and component. Information that is produced by different products can be analyzed and converted into ASCII or HTML that use the Tivoli XML Log Viewer. This log viewer is not installed as part of any Tivoli Access Manager installation. You must explicitly install the Tivoli XML Log Viewer. Note: Java language-based Tivoli Access Manager components and applications cannot produce messages or traces in the Tivoli XML log format. To more easily view XML output, use the Tivoli XML Log Viewer tool that is provided with Tivoli Access Manager. The XMLFILE, XMLSTDERR, and XMLSTDOUT format in the routing file are used to produce XML message logs and XML trace logs. Because the InstallShield MultiPlatform installation program and the Tivoli XML Log Viewer are both Java applications, a JRE must be installed prior to installing and using the viewer. The same JRE that is used by Tivoli Access Manager can be used for the Tivoli XML Log Viewer. If a different JRE is used, that JRE must be at version or later. Installing the Tivoli XML Log Viewer The Tivoli XML Log Viewer is installed using an InstallShield MultiPlatform installation program. However, the installation program for the viewer is provided as a Java archive (JAR) file, and not as an executable file like the other product installation programs. The installation JAR file is located on the operating system-specific IBM Tivoli Access Manager Base CD in the /operating_system/xmllogviewer directory. For example, the Tivoli XML Log Viewer installation program for Windows operating systems is in the \windows\xmllogviewer directory of the IBM Tivoli Access Manager Base for Windows CD, and the Tivoli XML Log Viewer installation program for Solaris operating environments is in the /solaris/xmllogviewer directory of the IBM Tivoli Access Manager Base for Solaris CD. To install the viewer, perform the following steps: 1. From a command prompt, navigate to the /xmllogviewer directory. 2. Enter the following command: java -cp setup.jar run 3. Navigate through the InstallShield MultiPlatform panels and select a location for the Tivoli XML Log Viewer, then proceed to install the viewer. 4. After the installation program completes, you can add the Tivoli XML Log Viewer directory to the search path. Copyright IBM Corp. 2002,