Troubleshooting Guide - PDF Free Download

Tioli Access Manager for e-business Version 6.1.1 Troubleshooting Guide GC27-2717-00

Note Before using this information and the product it supports, read the information in Appendix E, Notices, on page 169. Edition notice This edition applies to ersion 6, release 1, modification 1 of IBM Tioli Access Manager (product number 5724-C87) and to all subsequent releases and modifications until otherwise indicated in new editions. All rights resered. Copyright IBM Corporation 2002, 2010. US Goernment Users Restricted Rights Use, duplication or disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

Contents About this publication........ ii Intended audience............ ii Publications.............. ii IBM Tioli Access Manager for e-business library ii Related products and publications...... ix Accessing terminology online........ x Accessing publications online........ x Ordering publications.......... x Accessibility.............. xi Tioli technical training.......... xi Tioli user groups............ xi Support information........... xi Conentions used in this publication...... xii Typeface conentions.......... xii Operating system-dependent ariables and paths xii Part 1. Introduction......... 1 Chapter 1. Introduction to problem determination............ 3 Aoiding potential problems......... 3 Problem resolution............ 4 Product short names............ 4 Sericeability enhancements......... 4 Chapter 2. Tioli Common Directory.. 5 Location of the Tioli Common Directory properties file.................. 5 Common directories used by Tioli Access Manager 5 Configuration setting used by Tioli Access Manager 6 Chapter 3. Messages......... 9 Message types.............. 9 Message format............. 10 Message identifiers............ 10 Chapter 4. Tioli XML Log Viewer... 11 Installing the Tioli XML Log Viewer...... 11 Running the Tioli XML Log Viewer...... 12 Part 2. Deployment........ 13 Chapter 5. Installation and initial configuration............ 15 Log files............... 15 Installation wizard log files........ 15 Natie installation log files........ 16 Natie configuration log files....... 17 Installation wizard problems........ 18 Tioli Directory Serer installation wizard problems.............. 18 Insufficient disk space for temporary files... 18 Cannot launch the installation wizard.... 18 Installation wizard failed......... 19 Remoing the ibmjcaproider.jar file..... 19 Operating system problems......... 20 Multiple network interfaces........ 20 Initial configuration problems........ 20 Inalid LDAP management domain location DN causes error............. 21 Timing out during configuration...... 21 Recoering an LDAP serer........ 21 Upgrade common problems......... 21 Cannot create users or groups after upgrade.. 22 Chapter 6. Verifying the deployment.. 23 System types in a deployment........ 23 Base systems............. 23 Web security systems.......... 24 Distributed session management systems... 26 Checking installed software......... 26 Verifying Global Security Kit........ 27 Verifying user registries.......... 27 Tioli Directory Serer.......... 27 Microsoft Actie Directory........ 28 Lotus Domino Serer.......... 29 Verifying base systems........... 29 Verifying the policy serer........ 30 Verifying the authorization serer...... 30 Verifying the runtime.......... 30 Verifying Web security systems........ 30 Verifying WebSEAL........... 30 Verifying Plug-in for Web Serers...... 31 Chapter 7. Validating and maintaining policy databases.......... 33 Displaying all database contents....... 33 Displaying summary reports........ 33 Repairing a damaged policy database..... 34 Replacing a damaged policy database..... 34 Part 3. Logging.......... 35 Chapter 8. Diagnostics ersus auditing 37 Diagnostic eents............ 37 Auditing eents............. 37 Chapter 9. Routing files....... 39 Location of routing files.......... 39 Routing file entries............ 40 Chapter 10. Jaa properties files... 43 Location of Jaa properties files....... 43 Application-specific logging of Jaa applications.. 43 Configuring message eents with the Jaa properties file.............. 44 Message loggers and file handlers...... 44 Copyright IBM Corp. 2002, 2010 iii

When PDJLog.properties is used...... 45 Console handler and console message logging.. 45 Tailoring message logging in Web Portal Manager.............. 46 Configuring trace eents with the Jaa properties file................. 46 Trace loggers and file handlers....... 46 Enabling trace in a Runtime for Jaa enironment............. 46 Enabling trace in Web Portal Manager.... 47 Chapter 11. Message eent logging.. 49 Seerity of message eents......... 49 FATAL messages............ 49 ERROR messages........... 49 WARNING messages.......... 49 NOTICE messages........... 50 NOTICE_VERBOSE messages....... 50 Location of message logs.......... 50 Location with Tioli Common Directory.... 50 Location without Tioli Common Directory... 51 Names of message logs.......... 51 Names of runtime logs......... 51 Names of serer logs.......... 53 Format of messages in logs......... 54 Messages in text format......... 54 Messages in XML log format....... 55 Enironment ariables........... 56 Displaying and not displaying enironment ariables in the log........... 56 Routing files for message eents....... 57 C runtime routing file.......... 57 Policy serer pdmgrd_routing file...... 57 Authorization serer pdacld_routing file.... 58 Policy proxy serer pdmgrproxyd_routing file.. 58 WebSEAL routing file.......... 59 Understanding message routing files...... 59 C runtime routing file on Windows..... 59 Policy serer routing file on UNIX...... 60 WebSEAL routing file on UNIX....... 61 Limiting the size of message logs....... 61 Estimating the size of message logs...... 62 Changing the location of log files....... 62 Logging all messages the same way...... 63 Using GOESTO statements......... 64 Changing the message format in log files.... 64 Sending messages to multiple places in different formats................ 65 Chapter 12. Trace eent logging.... 67 Mechanisms for controlling trace logging.... 67 Routing file examples........... 68 Trace logging in Tioli XML log format.... 68 Trace logging to multiple files....... 68 Tracing a particular component....... 69 Determining maximum size of a trace log.... 69 Enabling trace............. 69 Using the trace commands......... 70 Listing aailable trace components..... 70 Enabling trace............ 70 Showing enabled trace components..... 71 Changing the name and location of trace files.. 71 Format of trace entry in logs......... 72 Trace logging for session management..... 72 Aailable trace components......... 73 Part 4. Problems with base systems 77 Chapter 13. Common Tioli Access Manager problems.......... 79 Enironment information messages in the serer log file at startup.............. 79 Unable to configure the policy serer...... 80 Unable to communicate with user registry... 80 Configuration fails with LDAP serer.... 80 Configuration fails with Domino serer.... 81 Unable to create new user......... 81 Unable to authenticate user......... 81 Insufficient disk space........... 82 Windows disk space.......... 82 Linux and UNIX disk space........ 82 Unexpected access to resources........ 82 ACL commands............ 82 POP commands............ 83 Authorization rule commands....... 83 Processes terminate abruptly on Intel 64-bit processor............... 84 Chapter 14. Tioli Access Manager user registries.............. 85 LDAP common problems.......... 85 LDAP does not start after creating suffix... 85 Insufficient priileges to perform operations.. 86 Tioli Directory Serer common problems.... 86 Jaa error during installation....... 86 Passwords not encrypted......... 86 Location of error logs.......... 87 Tioli Directory Serer error log warnings... 87 Setting up SSL............ 87 Actie Directory common problems...... 88 Receiing HPDRG0100E for Actie Directory operations.............. 88 Receiing HPDRG0101E The user password iolates the Actie Directory user password policies............... 88 Global Security Kit common problems..... 89 Error when importing a PKCS12 formatted file 89 Part 5. Problems with Web security systems.............. 91 Chapter 15. Desktop single sign-on.. 93 Basic SPNEGO troubleshooting........ 93 Linux and UNIX workflow........ 93 Windows workflow........... 93 Kerberos initialization failing........ 94 Unable to initialize Kerberos libraries..... 94 Unable to obtain initial credentials...... 94 i Troubleshooting Guide

Web security serer not starting....... 96 Authentication method not configured.... 96 No match to principal in key table..... 96 Unable to authenticate........... 97 Ticket not yet alid........... 97 Cannot acquire credentials........ 98 Wrong principal in request........ 98 Encryption type not permitted....... 99 Key ersion is incorrect......... 99 Cannot authenticate using NTLM...... 99 Cannot complete authentication...... 100 Algorithm to resole host names....... 101 Useful Kerberos procedures........ 102 Validating keys in key tables....... 102 Listing caches, principals, and serice principals 103 Listing keys in key tables........ 103 Listing tickets in credential caches..... 103 Chapter 16. WebSEAL serers.... 105 WebSEAL trace components........ 105 pdweb.debug component........ 105 pdweb.snoop component........ 106 WebSEAL fails to start when configured to use Hardware Cryptographic deices....... 107 Unable to customize response when using basic authentication............. 108 WebSEAL not responding on ports 80 or 443... 108 Multiple log ins with e-community...... 108 e-community SSO Master Authentication Serer configured with EAI........... 108 Verifying junctioned, third-party Web serer... 108 WebSEAL performance is degraded when downloading files............ 109 WebSEAL does not start after being configured to use PKCS #11............. 109 DPWWA0305E inconsistent message seerity... 110 Error when creating an LTPA junction..... 110 Chapter 17. Web serer plug-ins... 111 Setting cache controls for Web serers..... 111 Plug-in for Edge Serer.......... 111 Tailoring message logging an Edge Serer enironment............. 111 Tailoring trace logging in an Edge Serer enironment............. 111 Part 6. Collecting troubleshooting data............... 113 Chapter 18. Gathering initial diagnostic information....... 115 Installation directories.......... 115 Tioli Access Manager......... 115 Shared Session Management....... 115 WebSEAL.............. 116 Plug-in for Web Serers......... 116 Plug-in for Edge Serer......... 116 Locating diagnostic utilities......... 116 Gathering ersion information........ 117 Tioli Access Manager......... 117 IBM Global Security Kit......... 117 User registries............ 117 Gathering system information........ 118 Chapter 19. Collecting troubleshooting data............... 119 General information to collect........ 119 Collecting trace information........ 119 Collecting trace information by serer..... 120 Collecting the policy serer trace file.... 120 Collecting the policy proxy serer trace file.. 120 Collecting the WebSEAL trace files..... 121 Collecting the authorization serer trace file.. 121 Collecting the C-language trace file..... 121 Collecting the Jaa-language trace files.... 121 Collecting the message files....... 121 Submitting your gathered data to IBM..... 122 Appendix A. Sericeability commands 125 Reading syntax statements......... 125 Sericeability and problem determination commands.............. 125 serer list............... 126 serer task trace............ 127 Sericeability and problem determination utilities 129 pdbackup.............. 130 pdjsericeleel............. 134 pdsericeleel............. 135 pdersion.............. 136 pdwebpi............... 138 pdwpi-ersion............. 139 Appendix B. User registry differences 141 General concerns............ 141 LDAP concerns............. 141 Sun Jaa System Directory Serer concerns.. 142 Microsoft Actie Directory Application Mode (ADAM) concerns........... 142 URAF concerns............. 143 Lotus Domino Serer concerns...... 143 Microsoft Actie Directory Serer concerns.. 143 Length of names............ 145 Appendix C. AutoTrace....... 149 AutoTrace features........... 149 AutoTrace files............. 150 Files installed during installation...... 150 Files not installed during installation.... 152 Initializing the Windows AutoTrace serice... 153 Initializing the AutoTrace control program.... 153 Verifying the initialization......... 153 Displaying channel information...... 153 Displaying configuration information.... 154 Displaying product information...... 154 Collecting trace data........... 154 Trace file format and example........ 155 Reading trace data.......... 156 Trace file example........... 156 Creating a trace ID file.......... 157 Contents

Technique 1............. 157 Technique 2............. 158 Known problems............ 158 Useful AutoTrace commands........ 158 atctl commands........... 158 atrpt commands........... 160 atdb commands........... 160 Appendix D. Support information... 163 Searching knowledge bases......... 163 Searching information centers....... 163 Searching the Internet......... 163 Obtaining fixes............. 163 Registering with IBM Software Support.... 164 Receiing weekly software updates...... 164 Contacting IBM Software Support...... 165 Determining the business impact...... 165 Describing problems and gathering information 166 Submitting problems.......... 166 Appendix E. Notices........ 169 Trademarks.............. 171 Glossary............. 173 Index............... 183 i Troubleshooting Guide

About this publication Intended audience Publications The IBM Tioli Access Manager for e-business: Troubleshooting Guide proides a comprehensie set of procedures and reference information for troubleshooting Tioli Access Manager. IBM Tioli Access Manager for e-business proides an access control management solution to centralize network and application security policy for e-business applications. This guide is for system administrators and field support personnel responsible for troubleshooting a Tioli Access Manager enironment. Readers should be familiar with the following: PC and UNIX operating systems Database architecture and concepts Security management Internet protocols, including HTTP, TCP/IP, File Transfer Protocol (FTP), and Telnet Lightweight Directory Access Protocol (LDAP) and directory serices A supported user registry Authentication and authorization Secure Sockets Layer (SSL) protocol, key exchange (public and priate), digital signatures, cryptographic algorithms, and certificate authorities. This section lists publications in the IBM Tioli Access Manager for e-business library and related documents. The section also describes how to access Tioli publications online and how to order Tioli publications. IBM Tioli Access Manager for e-business library The following documents are in the Tioli Access Manager for e-business library: IBM Tioli Access Manager for e-business: Quick Start Guide, GI11-9333 Proides steps that summarize major installation and configuration tasks. IBM Tioli Access Manager for e-business: Release Notes, GC23-6501 Proides information about installing and getting started, system requirements, and known installation and configuration problems. IBM Tioli Access Manager for e-business: Installation Guide, GC23-6502 Explains how to install and configure Tioli Access Manager for e-business. IBM Tioli Access Manager for e-business: Upgrade Guide, SC23-6503 Upgrade from ersion 5.0, 6.0, or 6.1 to ersion 6.1.1. IBM Tioli Access Manager for e-business: Administration Guide, SC23-6504 Describes the concepts and procedures for using Tioli Access Manager. Proides instructions for performing tasks from the Web Portal Manager interface and by using the pdadmin utility. Copyright IBM Corp. 2002, 2010 ii

IBM Tioli Access Manager for e-business: WebSEAL Administration Guide, SC23-6505 Proides background material, administratie procedures, and reference information for using WebSEAL to manage the resources of your secure Web domain. IBM Tioli Access Manager for e-business: Plug-in for Edge Serer Administration Guide, SC23-6506 Proides instructions for integrating Tioli Access Manager with the IBM WebSphere Edge Serer application. IBM Tioli Access Manager for e-business: Plug-in for Web Serers Administration Guide, SC23-6507 Proides procedures and reference information for securing your Web domain using a Web serer plug-in. IBM Tioli Access Manager for e-business: Shared Session Management Administration Guide, SC23-6509 Proides deployment considerations and operational instructions for the session management serer. IBM Global Security Kit: Secure Sockets Layer Introduction and ikeyman User's Guide, SC23-6510 Proides information for enabling SSL communication in the Tioli Access Manager enironment. IBM Tioli Access Manager for e-business: Auditing Guide, SC23-6511 Proides information about configuring and managing audit eents using the natie Tioli Access Manager approach and the Common Auditing and Reporting Serice. You can also find information about installing and configuring the Common Auditing and Reporting Serice. Use this serice for generating and iewing operational reports. IBM Tioli Access Manager for e-business: Command Reference, SC23-6512 Proides reference information about the commands, utilities, and scripts that are proided with Tioli Access Manager. IBM Tioli Access Manager for e-business: Administration C API Deeloper Reference, SC23-6513 Proides reference information about using the C language implementation of the administration API to enable an application to perform Tioli Access Manager administration tasks. IBM Tioli Access Manager for e-business: Administration Jaa Classes Deeloper Reference, SC23-6514 Proides reference information about using the Jaa language implementation of the administration API to enable an application to perform Tioli Access Manager administration tasks. IBM Tioli Access Manager for e-business: Authorization C API Deeloper Reference, SC23-6515 Proides reference information about using the C language implementation of the authorization API to enable an application to use Tioli Access Manager security. IBM Tioli Access Manager for e-business: Authorization Jaa Classes Deeloper Reference, SC23-6516 Proides reference information about using the Jaa language implementation of the authorization API to enable an application to use Tioli Access Manager security. iii Troubleshooting Guide

IBM Tioli Access Manager for e-business: Web Security Deeloper Reference, SC23-6517 Proides programming and reference information for deeloping authentication modules. IBM Tioli Access Manager for e-business: Troubleshooting Guide, GC27-2717 Proides problem determination information. IBM Tioli Access Manager for e-business: Error Message Reference, GI11-8157 Proides explanations and recommended actions for the messages and return code. IBM Tioli Access Manager for e-business: Performance Tuning Guide, SC23-6518 Proides performance tuning information for an enironment consisting of Tioli Access Manager with the IBM Tioli Directory Serer as the user registry. Related products and publications This section lists the IBM products that are related to and included with a Tioli Access Manager solution. IBM Global Security Kit Tioli Access Manager proides data encryption through the use of the Global Security Kit (GSKit), ersion 7.0. GSKit is included on the IBM Tioli Access Manager Base CD for your particular platform, as well as on the IBM Tioli Access Manager Web Security CDs, the IBM Tioli Access Manager Shared Session Management CDs, and the IBM Tioli Access Manager Directory Serer CDs. The GSKit package proides the ikeyman key management utility, gsk7ikm, which creates key databases, public-priate key pairs, and certificate requests. The IBM Global Security Kit: Secure Sockets Layer Introduction and ikeyman User's Guide is aailable on the Tioli Information Center Web site in the same section as the Tioli Access Manager product documentation. IBM Tioli Directory Serer IBM Tioli Directory Serer, ersion 6.1, is included on the IBM Tioli Access Manager Directory Serer set of CDs for the required operating system. You can find additional information about Tioli Directory Serer at: http://www.ibm.com/software/tioli/products/directory-serer/ IBM Tioli Directory Integrator IBM Tioli Directory Integrator, ersion 6.1.1, is included on the IBM Tioli Directory Integrator CD for the required operating system. You can find additional information about IBM Tioli Directory Integrator at: http://www-306.ibm.com/software/tioli/products/directory-integrator/ IBM DB2 Uniersal Database IBM DB2 Uniersal Database Enterprise Serer Edition, ersion 9.1, is proided on the IBM Tioli Access Manager Directory Serer set of CDs and is installed with the Tioli Directory Serer software. DB2 is required when using Tioli Directory Serer or z/os LDAP serers as the user registry for Tioli Access Manager. For z/os LDAP serers, you must separately purchase DB2. You can find additional information about DB2 at: About this publication ix

http://www.ibm.com/software/data/db2 IBM WebSphere Application Serer WebSphere Application Serer, ersion 6.1, is included on the IBM Tioli Access Manager WebSphere Application Serer set of CDs for the required operating system. WebSphere Application Serer enables the support of the following applications: Web Portal Manager interface, which administers Tioli Access Manager. Web Administration Tool, which administers Tioli Directory Serer. Common Auditing and Reporting Serice, which processes and reports on audit eents. Session management serer, which manages shared session in a Web security serer enironment. Attribute Retrieal Serice. You can find additional information about WebSphere Application Serer at: http://www.ibm.com/software/webserers/appser/infocenter.html Accessing terminology online The Tioli Software Glossary includes definitions for many of the technical terms related to Tioli software. The Tioli Software Glossary is aailable at the following Tioli software library Web site: http://publib.boulder.ibm.com/tiidd/glossary/tioliglossarymst.htm The IBM Terminology Web site consolidates the terminology from IBM product libraries in one conenient location. You can access the Terminology Web site at http://www.ibm.com/software/globalization/terminology. Accessing publications online The 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 on the CD for instructions on how to access the documentation. The product CD contains the publications that are in the product library. The format of the publications is PDF, HTML, or both. To access the publications using a Web browser, open the infocenter.html file. The file is in the appropriate publications directory on the product CD. IBM posts publications for this and all other Tioli products, as they become aailable and wheneer they are updated, to the Tioli Documentation Central Web site at http://www.ibm.com/tioli/documentation. Note: If you print PDF documents on other than letter-sized paper, set the option in the File Print window that allows Adobe Reader to print letter-sized pages on your local paper. Ordering publications You can order many Tioli publications online at http:// www.elink.ibmlink.ibm.com/publications/serlet/pbi.wss. You can also order by telephone by calling one of these numbers: In the United States: 800-879-2755 x Troubleshooting Guide

In Canada: 800-426-4968 In other countries, contact your software account representatie to order Tioli publications. To locate the telephone number of your local representatie, perform the following steps: 1. Go to http://www.ibm.com/e-business/linkweb/publications/serlet/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 representatie. Accessibility Tioli technical training Tioli user groups Support information Accessibility features help users with a physical disability, such as restricted mobility or limited ision, to use software products successfully. With this product, you can use assistie technologies to hear and naigate the interface. You can also use the keyboard instead of the mouse to operate all features of the graphical user interface. Visit the IBM Accessibility Center at http://www.ibm.com/alphaworks/topics/ accessibility/ for more information about IBM's commitment to accessibility. For additional information, see the Accessibility Appendix in IBM Tioli Access Manager for e-business Installation Guide. For Tioli technical training information, refer to the following IBM Tioli Education Web site at http://www.ibm.com/software/tioli/education. Tioli user groups are independent, user-run membership organizations that proide Tioli users with information to assist them in the implementation of Tioli Software solutions. Through these groups, members can share information and learn from the knowledge and experience of other Tioli users. Tioli user groups include the following members and groups: 23,000+ members 144+ groups Access the link for the Tioli Users Group at http://www.tioli-ug.org/. If you hae a problem with your IBM software, you want to resole it quickly. IBM proides the following ways for you to obtain the support you need: Online Access the Tioli Software Support site at http://www.ibm.com/software/ sysmgmt/products/support/index.html?ibmprd=timan. Access the IBM Software Support site at http://www.ibm.com/software/support/ probsub.html. IBM Support Assistant The IBM Support Assistant is a free local software sericeability workbench that helps you resole questions and problems with IBM software About this publication xi

products. The Support Assistant proides quick access to support-related information and sericeability tools for problem determination. To install the Support Assistant software, go to http://www.ibm.com/software/ support/isa. Troubleshooting Guide For more information about resoling problems, see the IBM Tioli Access Manager for e-business Installation Guide. Conentions used in this publication This publication uses seeral conentions for special terms and actions, operating system-dependent commands, and paths. Typeface conentions This publication uses the following typeface conentions: Bold Italic Lowercase commands and mixed case commands that are otherwise difficult to distinguish from surrounding text 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:) Keywords and parameters in text Citations (examples: titles of publications, diskettes, and CDs Words defined in text (example: a nonswitched line is called a point-to-point line) Emphasis of words and letters (words as words example: "Use the word that to introduce a restrictie clause."; letters as letters example: "The LUN address must start with the letter L.") New terms in text (except in a definition list): a iew is a frame in a workspace that contains data. Variables and alues you must proide:... where myname represents... Monospace Examples and code examples File names, programming keywords, and other elements that are difficult to distinguish from surrounding text Message text and prompts addressed to the user Text that the user must type Values for arguments or command options Operating system-dependent ariables and paths This publication uses the UNIX conention for specifying enironment ariables and for directory notation. When using the Windows command line, replace $ariable with % ariable% for enironment ariables and replace each forward slash (/) with a backslash (\) in directory paths. The names of enironment ariables are not always the same in the Windows and UNIX enironments. For example, %TEMP% in Windows enironments is equialent to $TMPDIR in UNIX enironments. xii Troubleshooting Guide

Note: If you are using the bash shell on a Windows system, you can use the UNIX conentions. About this publication xiii

xi Troubleshooting Guide

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

2 Troubleshooting Guide

Chapter 1. Introduction to problem determination Aoiding potential problems Problem determination, or troubleshooting, is a process of determining why a product is not functioning in the expected manner. This guide proides information to help you identify and resole problems that you might encounter while using Tioli Access Manager and its prerequisite products. Tioli Access Manager proides an authentication and authorization framework for permitting or restricting access to system resources that are located in a secure domain. You can often preent problems through planning before deploying software. Before installing Tioli Access Manager, reiew the IBM Tioli Access Manager for e-business: Release Notes. This document contains the following information: Supported operating system leels Prerequisite software requirements Required software patches Minimum and recommended memory requirements Disk space requirements Upgrade considerations Known problems, limitations, and recoery procedures Customer support contact information After installing Tioli Access Manager, ensure that you hae a comprehensie backup and system recoery strategy in place. When creating your backup and recoery strategy, include the following information to help aoid the possibility of running into problems: Perform regular periodic backups of Tioli Access Manager by using the pdbackup command. Periodically backup the user registry following the instructions proided by the user registry endor. Maintain information about your enironment, including system topology, IP addresses, host names, and which components are installed on each system. Maintain updated information that describes the key system resources that are being managed by Tioli Access Manager and the security policies that are being applied to them by Tioli Access Manager. Periodically check that all systems running Tioli Access Manager hae 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. Regularly check for the aailability of fix packs and install them as they become aailable. Information on fix packs and other useful information can be found on the IBM Software Support site at the following Web address: http://www.ibm.com/software/support Copyright IBM Corp. 2002, 2010 3

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

Chapter 2. Tioli Common Directory To proide a consistent mechanism for locating sericeability information, Tioli Access Manager proides the ability to use Tioli Common Directory logging. Tioli Access Manager does not take adantage of the Tioli Common Directory unless you explicitly request this behaior during the installation of the product. By default, sericeability information is stored in the /log subdirectory of the product installation directory. If Tioli Common Directory support is requested, the installation wizard uses the existing Tioli Common Directory as the default location for sericeability information. If no existing Tioli Common Directory is in use, the directory specified during the installation is identified as the Tioli Common Directory and sericeability information for Tioli Access Manager and other Tioli 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 Tioli Common Directory store the following types of sericeability-related files in this central location: Logs files First-failure data capture (FFDC) files Sericeability scripts Note: After defining the Tioli Common Directory location, you cannot change it. Location of the Tioli Common Directory properties file If any product on the system uses Tioli 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/tioli/common/cfg/log.properties Windows operating systems c:\program files\ibm\tioli\common\cfg\log.properties On a Linux or UNIX operating system, this file should hae the 664 permission and should be owned by group tioli. Common directories used by Tioli Access Manager During the configuration of the Tioli Access Manager C runtime or Jaa runtime, the default location is displayed. If Tioli Access Manager is the first Tioli product on this system to use Tioli 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, 2010 5

After enabling Tioli Common Directory, Tioli Access Manager uses the /logs subdirectory to store message and trace logs. Tioli 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 sericeability data. This directory is usually defined by the first Tioli product that uses Tioli Common Directory. The default alues, if Tioli Access Manager is the first Tioli product, is one of the following platform-specific directories: Linux and UNIX operating systems /ar/ibm/tioli/common Windows operating systems c:\program files\ibm\tioli\common\ Note: On a Linux or UNIX operating system, this directory should hae the 771 permissions and be owned by the tioli group. xxx logs Represents the 3-letter identifier to use for the product-specific message log files. Tioli Access Manager uses the following identifiers: HPD The identifier for Tioli Access Manager DPW The identifier for Tioli Access Manager WebSEAL AMZ The identifier for Tioli Access Manager Plug-in for Web Serers AWD The identifier for Tioli Access Manager Plug-in for Edge Serer AOS The identifier for Tioli Access Manager for Operating Systems DRQ The identifier for Tioli Access Manager for Business Integration The subdirectory that is used for Tioli Access Manager message and trace log files. Only one subdirectory, /logs, is defined for these log files. Configuration setting used by Tioli Access Manager When configured for Tioli Common Directory, the tioli_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] tioli_common_dir = ar/ibm/tioli/common/ Windows operating systems [pdrte] tioli_common_dir = c:\program Files\IBM\Tioli\common\ When configured for Tioli Common Directory, the log-file stanza entry of the serer-specific configuration file contains the fully qualified names of the log files. For example, when configured for Tioli Common Directory, the log_file stanza entry for the authorization serer log files would be similar to one of the following entries: 6 Troubleshooting Guide

Linux and UNIX operating systems [iacld] log-file = ar/ibm/tioli/common/hpd/logs/msg pdacld_utf8.log Windows operating systems [iacld] log-file = c:\program Files\IBM\Tioli\common\HPD\logs \msg pdacld_utf8.log Chapter 2. Tioli Common Directory 7

8 Troubleshooting Guide

Chapter 3. Messages Message types All messages issued by Tioli Access Manager adhere to the Tioli Message Standard. The Tioli Message Standard specifies a standard format for all messages issued by Tioli products. The standard, based on the IBM Message Standard, is intended to proide a consistent and meaningful way for identifying messages across the entire Tioli product set. Messages issued by Tioli Access Manager, along with detailed explanations and suggested actions, can be found in the IBM Tioli Access Manager for e-business: Error Message Reference. Tioli Access Manager is written in both the C and Jaa programming languages. Applications that use the Tioli Access Manager APIs are also written in these programming languages. Tioli Access Manager produces the following types of messages: Runtime messages Messages that are generated by applications, commands, and utilities that use the Tioli Access Manager Runtime component, as well as messages that are generated from the C language-based Tioli Access Manager components, such as WebSEAL. These messages are written to the runtime message logs based on their seerity leels. These messages follow the message standard. Additional information on these messages can be found in the IBM Tioli Access Manager for e-business: Error Message Reference. Tioli Access Manager Runtime for Jaa messages Messages that are generated by applications, commands, and utilities that use the Tioli Access Manager Runtime for Jaa component, as well as messages that are generated from the Jaa language-based Tioli Access Manager components. These messages are written to the Tioli Access Manager Runtime for Jaa message logs. These messages tend to proide exception and stack trace information from the JRE. Serer messages Messages that are generated by the Tioli Access Manager daemons and serers. Messages from the policy serer, authorization serer, WebSEAL serers, and policy proxy serer are written to the serer message logs. These messages follow the message standard. Additional information on these messages can be found in the IBM Tioli 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 hae 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 proides the capability of logging HTTP messages. This message logging capability is described in the IBM Tioli Access Manager for e-business: Auditing Guide. Copyright IBM Corp. 2002, 2010 9

Message format Message identifiers A message consists of a message identifier (ID) and message text and an error code. The error code is a unique 32-bit alue. 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 Tioli Access Manager for e-business: Error Message Reference. Each of these messages has a detailed explanation and suggested actions. A message ID consists of 10 alphanumeric characters that uniquely identify the message. The message ID consists of the following parts: A 3-character product identifier (see Table 2 for the list of identifiers that are used by Tioli Access Manager) A 2-character component or subsystem identifier A 4-digit serial or message number A 1-character type code indicating the one of the following message seerities: W Warning E Error I Information Table 2. Product identifiers that are used by Tioli Access Manager Product identifier Tioli Access Manager component HPD Tioli Access Manager serers DPW Tioli Access Manager WebSEAL AWD Tioli Access Manager Plug-in for Edge Serer AMZ Tioli Access Manager Plug-in for Web Serers CTG Tioli Access Manager Shared Session Management 10 Troubleshooting Guide

Chapter 4. Tioli XML Log Viewer The C-based components of Tioli Access Manager support the generation of message and trace information in a common XML format. This format is known as the Tioli XML log format and is used by a number of Tioli applications. A Jaa-based log iewer is proided that allows these messages and traces to be filtered in a number of ways, including by time window, seerity, thread ID, and component. Information that is produced by different products can be analyzed and conerted into ASCII or HTML that use the Tioli XML Log Viewer. This log iewer is not installed as part of any Tioli Access Manager installation. You must explicitly install the Tioli XML Log Viewer. Note: Jaa language-based Tioli Access Manager components and applications cannot produce messages or traces in the Tioli XML log format. To more easily iew XML output, use the Tioli XML Log Viewer tool that is proided with Tioli 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 Tioli XML Log Viewer are both Jaa applications, a JRE must be installed prior to installing and using the iewer. The same JRE that is used by Tioli Access Manager can be used for the Tioli XML Log Viewer. If a different JRE is used, that JRE must be at ersion 1.2.2 or later. Installing the Tioli XML Log Viewer The Tioli XML Log Viewer is installed using an InstallShield MultiPlatform installation program. Howeer, the installation program for the iewer is proided as a Jaa archie (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 Tioli Access Manager Base CD in the /operating_system/xmllogiewer directory. For example, the Tioli XML Log Viewer installation program for Windows operating systems is in the \windows\xmllogiewer directory of the IBM Tioli Access Manager Base for Windows CD, and the Tioli XML Log Viewer installation program for Solaris operating enironments is in the /solaris/xmllogiewer directory of the IBM Tioli Access Manager Base for Solaris CD. To install the iewer, perform the following steps: 1. From a command prompt, naigate to the /xmllogiewer directory. 2. Enter the following command: jaa -cp setup.jar run 3. Naigate through the InstallShield MultiPlatform panels and select a location for the Tioli XML Log Viewer, then proceed to install the iewer. 4. After the installation program completes, you can add the Tioli XML Log Viewer directory to the search path. Copyright IBM Corp. 2002, 2010 11

5. On Linux and UNIX operating systems, you might need to explicitly set execute permissions on the iewer.sh file: chmod +x iewer.sh Running the Tioli XML Log Viewer To run the Tioli XML Log Viewer, use the iewer script and specify the name of one or more XML files. Output is directed to STDOUT in either HTML or text format. The output can be redirected to a file for iewing with a Web browser or text editor. For example, to create an HTML file containing all of the messages from the policy and authorization serers sorted into chronological sequence, enter the following command: iewer msg pdmgrd.xml msg pdacld.xml > msg_19oct2003_report.html To display the messages from the policy serer in text format, do the following: iewer -s text msg pdmgrd.xml Additional information on the Tioli XML Log Viewer, including how to tailor the output and how to uninstall it, can be found in the readme.html file, located in the same directory as the iewer script. This readme file also is proided in the /xmllogiewer directory on the installation media. 12 Troubleshooting Guide

Part 2. Deployment Chapter 5. Installation and initial configuration 15 Log files............... 15 Installation wizard log files........ 15 Natie installation log files........ 16 Natie configuration log files....... 17 Installation wizard problems........ 18 Tioli Directory Serer installation wizard problems.............. 18 Insufficient disk space for temporary files... 18 Cannot launch the installation wizard.... 18 Installation wizard failed......... 19 Problems when a local firewall is enabled.. 19 Enabling the Jaa console in a separate window............. 19 Writing the Jaa console output to a log file 19 Remoing the ibmjcaproider.jar file..... 19 Operating system problems......... 20 Multiple network interfaces........ 20 Initial configuration problems........ 20 Inalid LDAP management domain location DN causes error............. 21 Timing out during configuration...... 21 Recoering an LDAP serer........ 21 Upgrade common problems......... 21 Cannot create users or groups after upgrade.. 22 Displaying summary reports........ 33 Repairing a damaged policy database..... 34 Replacing a damaged policy database..... 34 Chapter 6. Verifying the deployment..... 23 System types in a deployment........ 23 Base systems............. 23 Web security systems.......... 24 Distributed session management systems... 26 Checking installed software......... 26 Verifying Global Security Kit........ 27 Verifying user registries.......... 27 Tioli Directory Serer.......... 27 Verifying the serer.......... 27 Verifying the client.......... 28 Microsoft Actie Directory........ 28 Verifying the configuration....... 28 Verifying ersion numbers....... 28 Confirming connectiity........ 29 Lotus Domino Serer.......... 29 Verifying the configuration....... 29 Verifying ersion numbers....... 29 Confirming connectiity........ 29 Verifying base systems........... 29 Verifying the policy serer........ 30 Verifying the authorization serer...... 30 Verifying the runtime.......... 30 Verifying Web security systems........ 30 Verifying WebSEAL........... 30 Verifying Plug-in for Web Serers...... 31 Chapter 7. Validating and maintaining policy databases.............. 33 Displaying all database contents....... 33 Copyright IBM Corp. 2002, 2010 13

14 Troubleshooting Guide

Chapter 5. Installation and initial configuration Log files This chapter describes problems that you might encounter while installing or configuring Tioli Access Manager and proides information about how to determine the origin of the problem. After determining what caused the problem, you can use the information that is proided to resole this problem. Before listing some of the common Tioli Access Manager problems that you might encounter during installation or configuration, it is worthwhile to mention that the cause of most common installation and configuration problems is one of the following failures: Failure to install all of the prerequisite and corequisite software that is required. This required software can include: Operating system software Operating system patches Prerequisite software products Prerequisite software product patches Failure to install the correct leel of any of the software aboe Failure to install all of the required software components for any gien type of Tioli Access Manager system Failure to install or configure any of the aboe items properly Failure to adhere to all hardware prerequisites as well as disk space and memory requirements When you install and configure Tioli Access Manager components, log files are created. If you use the installation wizards to install the components, the log file contains both the installation and configuration information. If you natiely install and configure, there are separate log files for installation and configuration. Installation wizard log files Problems encountered after you hae filled in the installation panels, reiewed the configuration options summary page, and clicked Next to begin the installation can usually be diagnosed by reiewing the installation log files created by the installation wizards. These installation log files are written to the temporary directory on the system (typically the /tmp or /ar/tmp directory on Linux and UNIX operating systems, and to the directory defined by the TEMP enironment ariable on Windows operating systems). Table 3 proides the names of the arious installation log files created by the installation wizards. Table 3. Installation log file names for installation wizards Component Policy serer Policy proxy serer Authorization serer Installation wizard log file msg ammgr_install.log msg amproxy_install.log msg amacld_install.log Copyright IBM Corp. 2002, 2010 15