Chapter 6. Performance tuning and problem determination
6.4 Problem determination
6.4.5 Documenting a PMR
6.4.1 Installation issues
In this section, we discuss installation issues.
Anti-virus software can interfere with AccessAgent or IMS Server
Certain anti-virus software has been observed to interfere with AccessAgent or IMS Server, causing the following symptoms:
AccessAgent (on user’s PC, Terminal Server, or Citrix server) can become very slow.
AccessAgent (on user’s PC, Terminal Server, or Citrix server) can fail to start.
Logging on to AccessAgent (on Terminal Server or Citrix server) can fail intermittently.
The IMS Server can become very slow.
Note: At present, logs sent to external entities through the Syslog protocol are not tamper-evident. When administrators abort the IMS Server database logging in favor of MOM-managed audit logging and reporting, reporting log tampering is effectively lost.
These problems have been observed at deployments that use McAfee anti-virus.
To resolve the problem, store the following frequently changing Tivoli Access Manager for Enterprise Single Sign-On folders in the anti-virus software’s exclusion list:
For AccessAgent
C:\Program Files\Encentuate\logs for AccessAgent
For IMS Server
C:\Encentuate for IMS Server
For the particular McAfee example refer to “Configuration for McAfee antivirus”
on page 180.
Configuration for McAfee antivirus
To include Tivoli Access Manager for Enterprise Single Sign-On folders in the McAfee anti-virus software’s exclusion list, performing the following steps:
1. Open the scanner’s property pages.
2. On the Detection tab, under What not to scan, use the exclusions feature.
3. Click Exclusions to open the Set Exclusions dialog box.
4. Add files, folders, or drives, or edit an item in the list.
5. To add an item, click Add. The Add Exclusion Item dialog box opens.
6. Under What to exclude, select the folder using By name/location.
7. Under When to exclude, specify all options.
8. Click OK to save these settings and return to the Set Exclusions dialog box.
9. Click OK to save these settings and return to the Detection tab.
10.Click Apply to save these settings.
MSDE installation problem
If a previous version of MSDE1 (before Service Pack 3) is installed on Windows XP (Service Pack 2), there may be no errors during installation. However, because of a security vulnerability in older versions of MSDE, Windows disallows the SQL server to use port 1433. Windows disallows the SQL server to use port 1433, which can result in disconnections to the database during IMS Server installation.
Use the Event Viewer in the Applications category to find the logs generated by SQL server. Older versions of MSDE should indicate that port 1433 cannot be used because of a vulnerability in the current version of MSDE.
1 Microsoft SQL Server Desktop Engine (MSDE)
To resolve this issue, apply MSDE 2000 Service Pack 3 (or a newer version), or simply download the latest release of MSDE installer from the Microsoft Support Web site.
IMS Server installation problem as a result of database configuration
The IMS Server installation can fail if the database server has been configured to return No Count. Because the IMS Server uses these counts to determine the success or failure of database operations, this database feature must be disabled
To disable the database feature, perform the following steps:
1. From Enterprise Manager, right-click the database server and select Properties.
2. Go to Connection→ No Count, and disable it.
The IMS Server installation can also fail if the database has incorrect user privileges. The database user should have public, db_owner rights for the IMS database. The user should not be a DB administrator account.
To check whether the database user has the correct privileges, perform the following steps:
1. Select DB Server→ Security→ Logins.
2. Right-click DB login and select Properties.
3. Click on the Server Roles tab.
4. Privileges are incorrect if the System Administrators and Database Creators roles are marked. If incorrect, manually prepare the IMS database and refer to the instructions for preparing the IMS database in IBM Tivoli Access Manager for Enterprise Single Sign-On Administrator Guide Version 8.0, SC23-9951.
Failure to connect to named instance of SQL Server 2000 database
If an earlier version of IMS Server is upgraded to version 3.3.1.4 or later, the upgrade might fail if the IMS database is a named instance of an SQL Server 2000 database. The following error message occurs:
“There was a problem uploading all_storage_templates.xml” is displayed, since the IMS Server cannot connect to the database.
This problem is the result of a problem in a Microsoft’s SQL Server 2000 JDBC driver that was used prior to IMS Server version 3.3.1.4, which ignores the database port number field if a named instance is used. In the new SQL Server
2005 JDBC driver used in IMS Server version 3.3.1.4 and later, the port number field is not ignored, and the database connection can fail if the port number is incorrect.
To fix this problem during an IMS Server upgrade, modify the IMS Server configuration file to the correct the port number:
1. Provide the correct port number in the following keys in the ims.xml file (found in <IMS Installation Folder>\ims\config):
ds.ims.rdb.uri ds.ims_log.rdb.uri
For example, if the correct port number is 1074, select the following line:
jdbc:microsoft:sqlserver://serverName\instanceName:1433 Replace the line with:
jdbc:microsoft:sqlserver://serverName\instanceName:1074 2. To find the port number that is running the instance:
a. Select Start→ Programs→ Microsoft SQL Server→ Server Network Utility. Then choose TCP/IP.
b. Click Properties.
c. Right-click database server and select Properties.
3. For a fresh IMS Server installation, make sure that the port number in the installation wizard is correct.
RFID reader RDR-7172AKU problem
If you are using RFID reader RDR-7172AKU, card detection issues might be caused by putting a machine into standby or hibernation mode and then resuming from it. This recurring issue is the result of problems with the RFID reader drivers. To fix this problem unplug and re-plug the RFID reader.
AccessAgent displays incorrect icons after an installation upgrade
After an upgrade from a previous version of AccessAgent to AccessAgent 8.0, the program icons are not updated and continue to display the icons used in the previous version of AccessAgent.
This is a Microsoft Windows icon cache problem. For Windows 2000, the system caches the older icons and re-uses them during an AccessAgent upgrade. To correct the problem, rebuild the Windows icon cache.
Refer to the Microsoft knowledge base (KB) item 199152 at:
http://support.microsoft.com/kb/Q199152/
AccessAgent fails to install
If AccessAgent fails to install, check the following items:
Windows Scripting Host 5.6 and later should be installed.
Windows Management Instrumentation (WMI) has to be functional. To verify its functionality:
a. Go to Computer Management→ Services and Applications→ WMI Control.
b. Right-click Properties and verify whether the following message is displayed:
Successfully Connected to: <local computer>
If no message is displayed, AccessAgent does not install.
Issues concerning Microsoft Operations Manager
Various messages can display when you install MOM components:
The following message is displayed when you install Microsoft Operations Manager (MOM) 2005:
Microsoft SQL Server 2000 SP3a or above required Refer to Microsoft KB 902803:
http://support.microsoft.com/kb/902803
The following message is displayed when you install Microsoft Operations Manager Reporting:
Failed to create data source for data warehouse Refer to Microsoft KB 555533:
http://support.microsoft.com/kb/555533
The following message is displayed when you install the MOM Agent:
The MOM Server detected that DCOM was disabled on the remote computer
To resolve the problem:
a. Open dcomcnfg in Start→ Run.
b. Go to Console Root→ Component Services→ My Computer.
c. Right-click My Computer and select Properties.
d. In the My Computer Properties dialog, select the Default Properties tab.
e. Make sure the Enable Distributed COM on this computer option is marked.
6.4.2 IMS Server issues
In this section, we discuss IMS Server issues.
IMS Server logs
A useful approach for troubleshooting IMS Server problems is to view the log files in:
C:\Encentuate\IMSServerx.x.x.x\ims\logs
In general, the stdout.log and stderr.log files are most useful.
You should understand that the stdout.log and stderr.log are overwritten when the IMS Server starts up. Therefore, if you have a problem and you want to provide the IMS Server log files, collect them before you restart the IMS Server. Otherwise, the log files get lost during the next restart of the IMS Server.
IMS Configuration Utility cannot be accessed
If the IP address of the IMS Server has changed, the IMS Configuration Utility is inaccessible from the following URL unless the new IP address is included in the RemoteAddrValve configuration key of the <IMS Installation
Folder>\conf\server.xml file:
http://imsservername:8080/
Restart the IMS Server after the configuration key is modified.
Alternatively, to retain the original configuration key, you can still access the IMS Configuration Utility from:
http://localhost:8080/
IMS Server cannot issue certificate for an application
A known bug is that subject fields of IMS certificates must not contain the underscore character ( _ ). This character can cause problems at deployments that use certificate-based authentication for applications.
The result is that the IMS Server cannot issue SCR or CAPI certificates for an authentication service with an ID that contains the underscore character. The workaround is to remove all underscore characters from the IDs of authentication services that use certificate-based authentication.
IMS Server diagnostic information
To obtain IMS Server diagnostic information:
1. Log on to AccessAdmin.
2. Navigate to the following address:
https://imsserver/ims/ui/diagnostics
The site contains the list of SOAP services, IMS configuration information, test facilities for IMS Connectors, and descriptions of event and result codes.
IMS Server console startup
By default, the IMS Server runs automatically as a service IMSService when the machine starts up. When in this mode, troubleshooting any problem with the IMS Server might be difficult. Alternatively, the IMS Server can be run in console mode, so that any error messages are displayed in real-time.
To run the IMS Server in console mode, perform the following steps:
1. Stop the IMSService using the net stop IMSService command.
2. Run the batch file: <IMS Installation Folder>\ims\bin\runserver.bat.
IMS Server database housekeeping problems
For normal database backup operations, the IMS database user must have backup permissions on the IMS database. However, if the Housekeeping RDB System Backup Flag is set to true, the IMS database user also has
administrative privileges, otherwise the following exception appears in the IMS Server standard error logs:
java.sql.SQLException: [Microsoft][SQLServer 2000 Driver for
JDBC][SQLServer]BACKUP DATABASE permission denied in database 'master'.
If cleanupRdbLogs is enabled (that is, log table pruning), a log directory should exist in the <IMS Installation Folder>\bin directory, otherwise the following exception appears in the IMS Server standard error logs:
java.io.FileNotFoundException: logs\rdbLogCleanup.log (The system cannot find the path specified)
6.4.3 AccessAgent issues
In this first section, we focus on issues concerning the AccessAgent.
AccessAgent logs
To help you with troubleshooting AccessAgent problems, view the log files in the C:\Program Files\Encentuate\logs folder. The XML files indicate
communications with the IMS Server and are useful for troubleshooting failure because of AccessAgent-IMS Server interaction. The AccessAgent.log records internal AccessAgent processes and is useful for troubleshooting internal failure within AccessAgent. The aa_observer.log records observations of applications for automatic sign-on.
For installation problems, the AccessAgent installer logs can be found in the C:\AAInstaller.log file.
When reporting a problem, including a .zip file that contains the entire C:\Program Files\Encentuate\logs folder is helpful. You should also provide the approximate local time when the events occurred.
AccessAgent log level
Also useful when you troubleshoot AccessAgent problems is to increase the log level so that more debugging information can be produced.The log level is specified by the machine policy pid_log_level, which can be set through the registry entry:
[HKEY_LOCAL_MACHINE\SOFTWARE\Encentuate\DeploymentOptions]"LogLevel"
Log level 3 is usually enough for most debugging purposes. If more detailed logs are required, the log level can be set to 4.
AccessAgent cryptoboxes
AccessAgent stores user and machine Wallets as hidden files in the C:\Program Files\Encentuate\Cryptoboxes folder. The machine Wallet at C:\Program Files\Cryptoboxes\Wallets\machine.wlt contains system policies and AccessProfiles downloaded from the current IMS Server. To view the Wallet files, make sure that Windows Explorer has been configured to show hidden files and folders. To refresh the user Wallets during testing or troubleshooting, delete the corresponding Wallet files in the folder C:\Program
Files\Encentuate\Cryptoboxes\Wallets.
In the following steps that refresh the machine Wallet, the SOCIAccess service automatically replaces any deleted machine Wallet file, so deleting a folder (as with user Wallets) does not achieve the same result.