Use the information provided in the following sections to help diagnose and fix problems you might encounter as you work with Waveset:
For additional troubleshooting information, including the Waveset FAQ, go to the following URL:
https://sharespace.sun.com/gm/document-1.26.2296/IdM_FAQ.html?
You must sign up for a Share Space ID to access information provided on this site.
You can use several different debugging tools to help identify and fix problems in your Waveset deployment. These tools include:
You can use Waveset Debug pages to help identity and fix problems in your deployment. For example, you can enable or disable tracing for various activities and objects, collect statistical information, verify that processes are running, or investigate bottlenecks and memory problems.
The following table describes the most commonly used Debug pages and their actual .jsp file names.
For a comprehensive list of all Waveset Debug pages, open a command window and list the contents of the idm/debugdirectory.
See Working With Waveset Debug Pages for more information about these Debug pages.
You must have the Debug capability to access and execute operations from the Waveset Debug pages. If you do not have the Debug capability, an error message results. Administrators and the Configurator are assigned the Debug capability by default.
Open a browser and log into the Administrator interface.
Type the following URL to open the System Settings page:
http://host:port/idm/debug
where:
host is the local server on which you are running Waveset.
port is the number of the TCP port on which the server is listening.
From this page, you can enable or disable tracing for various Waveset activities and objects and use the information displayed on these pages to troubleshoot problems in your deployment.
Some Debug pages are not linked to the System Settings page, and you must type the page’s .jsp file name to open the page. For example:
http:// host:port/idm/debug/pageName.jsp
Where pageName.jsp is the particular Debug page you want to open.
The Oracle Waveset Integrated Development Environment (Waveset IDE) is Java application that enables you to view, customize, and debug Oracle Waveset (Waveset) objects in your deployment.
Specifically, the Waveset IDE provides a graphical Debugger that you can use to debug &Waveset forms, rules, and workflows. You can use this Debugger to set breakpoints and watches, step through code, examine and modify variables, examine classes and the callstack, follow threads, and run multiple sessions.
Instructions for installing and configuring the Oracle Waveset Integrated Development Environment (Waveset IDE) are now available from the following URL:https://identitymanageride.dev.java.net.
You can configure Waveset system monitoring to track system events. System monitoring collects and aggregates statistics at various levels to present a real-time view of system events, based on your specifications.
Viewing this information in dashboard graphs enables you to quickly assess system resources, view abnormalities, understand historical performance trends, and interactively isolate problems before looking at audit logs. Although dashboards do not provide as much detail as audit logs, dashboards can indicate where to look for problems in the logs.
For more information about dashboards and system monitoring, see Chapter 8, Reporting, in Oracle Waveset 8.1.1 Business Administrator’s Guide.
Adapter logs capture information about the adapter that is currently processing. You can use this information to monitor the adapter’s progress and to diagnose and debug adapter problems.
You must enable tracing and identify the methods for which tracing is requested before any logging can occur. Also, your customized adapter must include calls that create log entries for new methods.
Nearly every adapter has its own log file, path, and log level. You can specify the level of detail captured by the adapter log, along with these other values in the Logging section of the Synchronization Policy for the appropriate Waveset or Service Provider user type.
For more information about using adapter log files as a debugging tool, see Troubleshooting Adapters.
DTrace is a comprehensive, dynamic tracing framework for the Solaris operating environment. DTrace provides more than 30,000 probes into your production system and integrates user- and kernel-level tracing. You can use DTrace to monitor JVM activity. This facility also allows you to use the D language (similar to C or awk) to trace arbitrary data and expressions.
The Java Monitoring and Management Console (JConsole) is a Java Management Extension (JMX) technology-compliant graphical management tool bundled with JDK 5 (and later). JConsole connects to a running JVM and gathers information from the JVM MBeans in the connected JMX agent.
For example, you can use JConsole to
Detect low memory
Enable or disable garbage collection
Enable or disable verbose tracing
Detect deadlocks
Control Waveset log levels
Access information about operating systems resources (Oracle’s platform extension)
Monitor and manage MBeans
View information about the JVM and monitored values, threads running on the application, and class loading
For more information about JConsole, see the article titled, Using JConsole to Monitor Applications. You can view this article from the following URL:
http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html
If a red error message displays in the Waveset interface after you have performed an action, you might be able to view more complete information and further analyze the error by viewing and saving the page source.
To view the page source
If you are using Internet Explorer, select View -> Source from the menu bar.
If you are using Netscape, select View -> Page Source from the menu bar.
If you still need help resolving the problem,
View the page source, and then select File -> Save to save the file to your system.
Locate the error in your saved file.
Send the error information, the URL from the page where the problem occurred, and a description of the problem in an email to Oracle Support for resolution assistance.
To troubleshoot an adapter, review the adapter’s log file. Almost all adapters write their resource settings to a log file, and you can use this information to confirm that the adapter started and that all setting changes have been saved.
You must enable tracing and identify the methods for which tracing is requested before any logging can occur. Also, your custom adapter must include calls that create log entries for new methods.
If necessary, review Tracing the Waveset Server for instructions about how to enable tracing.
Most adapter log files are located in the $WSHOME/config directory and they are named WSTrace1.log.
Active Sync-enabled adapters that make log calls to the ActiveSyncUtil instance create a log file or set of log files in a directory specified by the Log File Path resource attribute. Be sure to check these log files for additional Active Sync-related log entries.
The information in this section is organized as follows:
Follow these general steps to debug your custom adapter.
Create a test program for your adapter, and be sure this Java file performs the following basic functions:
Create a new resource
Create a user
Get a user
Update a user
Delete a user
Perform create, get, update and delete operations on multiple users
A sample test file (SkeletonResourceTests.java) is provided in the /REF directory on your installation CD.
Set an appropriate logging level for debugging.
For example, for the first debugging pass, increase the logging level to 4 (maximum debugging output), set the log file path, and specify a maximum file size.
When you start the adapter, all of the resource settings are written to the log file. You can use this information to validate that the adapter started and that all setting changes were saved.
Compile and test your adapter.
To compile the test program, open a command window and enter the javac -d . test/filename.java command. This command creates the class file in the appropriate com/waveset/adapter/test directory.
To test your new adapter using this class file, be sure that your compiled adapter is in the com/waveset/adapter directory and use the following command to run the adapter:
java– D waveset.home=path com.waveset.adapter.test. MyResourceAdapter |
Create an HTML help file for your resource.
Example help files are supplied in the idm.jar file located in the com/waveset/msgcat/help/resources directory.
See Oracle Waveset 8.1.1 Deployment Reference for information about how to include online help with the application.
(For Active Sync-enabled adapters only) To reset synchronization on the last resource, delete the XmlData SYNC_resourceName object.
Read the error log and modify the adapter.
Reset the logging level.
For example, specifying Level 2 debugging yields information about the adapter settings and any errors, but limits the amount of log detail to a manageable level.
Before starting Waveset, you must identify the new adapter in the $WSHOME/config/Waveset.properties file by placing the adapter name under the resource.adapters entry or Waveset cannot recognize the adapter.
Install your adapter and its associated help file into Waveset.
Before Waveset can recognize an instance of a new adapter in the display, you must create a new resource of that type from the List Resource page.
From this page, select New -> new adapter and use the Resource Wizard to create the new adapter.
Use Waveset to create a resource and a user on that resource.
When troubleshooting an Active Sync-enabled adapter, if you edit the XmlData SYNC_resourceName object to remove the MapEntry for the Active Sync synchronization process from the Debug page, the adapter starts over from the first detected change.
If you used the IAPI event, you must set the Property() method to store synchronization state for the resource, such as a last change processed value. Setting this method is very useful for troubleshooting adapters. You can set the adapter to run and ignore past changes. Subsequently, you can modify the adapter and see your change results in the adapter log file.
If your resource is an Active Sync resource, you might see additional information if you enable logging on the resource edit page. Set the logging level (0-4) and the file path where the log file will be written (as resource_name.log).
(For Active Sync-enabled adapters only) Restart synchronization for the last resource.
To debug LoginConfig-related changes to your adapter, you must
Enable trace for the selected files and trace the following classes at Method/Class Level 1 trace:
com.waveset.security.authn.WSResourceLoginModule
com.waveset.session.LocalSession
com.waveset.session.SessionFactory
com.waveset.ui.LoginHelper
com.waveset.ui.web.common.ContinueLoginForm
com.waveset.ui.web.common.LoginForm
Test Single Sign-On (SSO) pass-through authentication login through Telnet as follows:
After correctly configuring the SSO login module, telnet directly to the HTTP port and send an HTTP request to login.jsp.
Paste the following request, which contains an SSO login module that looks for the sm_user HTTP header, into your telnet session:
HEAD /idm/login.jsp HTTP/1.0 Accept: text/plain,text/html,*/* Accept-Language: en-us Accept-Encoding: gzip, deflate User-Agent: Mozilla/4.0 Host: LOCALHOST sm_user: Configurator |
A trace displays to indicate that your user has logged in correctly. For example:
2003.07.08 14:14:16.837 Thread-7 WSResourceLoginModule#checkForAuthenticatedResourceInfo() Found authenticated resource accountId, ’Configurator@Netegrity SiteMinder’on Identity Manager user ’Configurator’. null null 2003.07.08 14:14:16.837 Thread-7 WSResourceLoginModule#checkForAuthenticatedResourceInfo() Exit null null 2003.07.08 14:14:16.837 Thread-7 WSResourceLoginModule#login() Exit, return code = true null null 2003.07.08 14:14:16.847 Thread-7 LocalSession#login() Login succeeded via Netegrity SiteMinder null null 2003.07.08 14:14:16.847 Thread-7 LocalSession#login() Overall authentication succeeded null null 2003.07.08 14:14:16.897 Thread-7 LocalSession#checkIfUserDisabled() Entry null null 2003.07.08 14:14:16.897 Thread-7 LocalSession#checkIfUserDisabled() Exit null null 2003.07.08 14:14:16.927 Thread-7 LocalSession#login() Exit null null |
This section describes methods for debugging some common adapter connection problems.
The topics in this section are organized as follows:
Generally, you can identify adapter connection issues by tracing the adapter class com.waveset.adapter.adapter_classname. For example:
com.waveset.adapter.ADSIResourceAdapter
If necessary, review instructions for enabling trace in Tracing the Waveset Server.
Some common authentication problems include
Missing authentication properties
You must include a property name for the specified DataSource type in the set of names output in the trace.
An Waveset user is missing a matching resource account
If authentication succeeds for the resource adapter, but an exception occurs indicating that no Waveset user could be found with a matching resource account ID, be sure that the resource accountId associated with the user is the same as the accountId returned by your resource adapter’s authenticate method.
To verify the Waveset user’s resource accountId, review Waveset’s Edit Trace Configuration page (debug/Show_Trace.jsp). If a mismatch exists, change the content of the name being returned by your authenticate method or change your resource’s ID template. The template must generate a resource accountId that matches the accountId being returned by the authenticate method.
The most common problems with custom Active Sync adapters are form-related. These errors generally occur because you have not provided necessary information, such as password or email information, in a required field.
Waveset prints form validation errors to the adapter log after the final XML of the view. For example:
20030414 17:23:57.469: result from submit (blank means no errors): 20030414 17:23:57.509: Validation error: missing required field password |
Waveset also prints all messages to the adapter log. These messages include account creation and update times, adapter errors, and a summary of the schema map data.
Active Sync resource adapters store information about the last change processed in the SYNC.resourceName XMLData object.
Following are some common Domino gateway and adapter configuration errors and instructions for fixing these problems:
If an error message states the ’New Domino Gateway’ resource is not accessible and the connection is refused, try stopping and restarting the Oracle Waveset Gateway.
If an error message states no ID file name is specified and the path to the userID file is set incorrectly, specify a target location for the userID file and edit the resource adapter to set this attribute to a correct path. Typically, the target location for the userID file is the directory into which you installed the Gateway.
If an error message states you are not authorized to use the server, you have not set the correct access permissions for the ID file. Specify the correct permissions for this file and retry.
When RACF, ACF2, or TopSecret host adapters fail to reuse or cache connections, users are forced to log in frequently, which negatively impacts performance. Generally, the cache timeout setting causes this problem.
To check the cache timeout setting, trace Waveset’s adapter connection pool as follows:
From Waveset’s Edit Configuration Object page, trace the com.waveset.adapter.HostConnPool#reapConnections method at level 4.
If necessary, review instructions for enabling trace in Tracing the Waveset Server.
Capture trace for a sufficiently long period of time (at least 30-60 minutes), while the adapter performs operations.
Review the trace output in the application server stdout or trace file and look for Info reaping connection entries.
If this entry occurs more than once every 30 minutes, you have a good indication that connections are being timed out unnecessarily.
To resolve this problem, increase the Idle Timeout resource attribute value to prevent connections from being reaped too frequently. The Idle Timeout attribute controls how long a connection remains idle before the connection is logged out. The default value is 90 seconds, which causes new logins to occur frequently.
Ideally, specify a value that is greater than the average idle time for your deployment environment. For example, adjust the Idle Timeout attribute to 30 minutes (1800000 milliseconds) or more.
This section describes methods for troubleshooting the following PeopleSoft adapter problems:
Executing a “Test Connection” from the PeopleSoft resource adapter causes a failure with a generic exception.
Open the Waveset.properties file and set exception.trace=true.
Retry the test connection, and if you see the following results:
FormState: expansion complete java.lang.NullPointerException: PSProperties not loaded from file WavesetException: WavesetException: ==> com.waveset.util.WavesetException: FormState: derivation Log in to the PeopleSoft web interface to verify that you are using the correct UID and password. |
The PeopleSoft application server logs are not showing login attempts.
This problem generally occurs because you did not use the psjoa.jar file supplied with the PeopleSoft installation to which you are connecting. (See the Oracle Waveset 8.1.1 Resources Reference for more information about the PeopleSoft resource adapter).
If an error results when you try to test the connection from an SAP or SAP HR Active Sync adapter to the SAP system, open a command window and run this command from your installation directory WEB-INF/lib:
java -jar sapjco.jar
The sapjco.jar command shows which version of the SAP Java Connector (JCO) is installed and whether the adapter is installed correctly. The command also returns the Java Native Interface (JNI) platform-dependent and the RFC libraries that communicate with the SAP system.
If these platform-dependent libraries are not found, consult the SAP documentation to find out how to correctly install the SAP Java Connector.
This section contains information about debugging some common problems with UNIX adapters.
If you see timeout errors when provisioning to a UNIX resource adapter, you can determine where the provisioning process is failing by tracing the com.waveset.adapter.ScriptedConnection method at Method/Class level 4, which gives you the maximum logging output.
When becoming root to perform administrative commands, if the resource adapter executes a su root command instead of a su - root command, the environment does not inherit any of the custom environment variables defined for root; including any custom prompts (environment variable of PS1).
When configuring a UNIX adapter, you can determine which prompt to enter into the Root Shell Prompt field as follows:
Telnet or ssh to the system as the user you specified in the Login User field.
After typing the password and logging in, type su root without a dash and press return.
Type the root password.
The next prompt displayed is the prompt you must enter into the Root Shell Prompt field.
You can trace the following methods to troubleshoot issues with Identity Auditor:
com.sun.idm.auditor.policy to trace issues with Audit Scans.
com.sun.idm.auditor.accessreview to trace issues with Access Reviews.
com.sun.idm.auditor.report to trace issues with Audit Reports.
com.sun.idm.auditor.view to trace issues with Auditor Views.
In addition, you can set the following hidden flags by modifying Forms or TaskDefinitions:
Audit Policy Scan Task - maxThreads (int). Number of concurrent threads used. (Defaults to 5).
Audit Policy Scan Task - userLock (int). Time (in milliseconds) to wait to acquire a lock on the User object. (Defaults to 5000)
Audit Policy Scan Task - scanDelay (int). Time (in milliseconds) to delay between launching a new scan thread. (Defaults to 0, no delay)
Audit Policy Scan Task - clearuserLocks (boolean). If true, the scanner attempts to clear the user lock before scanning.
In addition, the Show Timings page (/debug/callTimer.jsp) provides the following information:
How long it takes to fetch the initial User view, with no resources, during the scan
How long it takes to refresh the User view, including resources, during the scan
How long it takes to evaluate the policy on the User view
How long each user scan takes, including User view fetch, policy evaluation, and so forth
How long it takes to fetch a list of users for access review
How long it takes to evaluate the attestation rule in access review
In the event of a ClassNotFound exception error, verify that the missing class is included in the server's classpath. If the classpath is configured properly, try configuring your application server such that the application class loader loads before the parent class loader. Sometimes loading the application classpath before the server classpath can resolve this issue. Consult your application server documentation for instructions.
This section describes some common form problems and how to fix these problems.
You added a <script> tag to your user form, but see the following exception when trying to access the user form:
java.lang.NoClassDefFoundError: org/mozilla/javascript/NativeScript
You must put the WEB-INF/lib/javascript.jar file into the application server’s classpath. For example:
If you installed Tomcat as a service (Windows only), edit the following registry key:
HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Services\Tomcat\Parameters\JVM Option Number 0
Append the path to your jar file to the end of the JVM Option Number 0 key string value, wherever it is located. For example:
;C:\tomcat\lib\javascript.jar
If you just started Tomcat from the command line, move the jar file into the tomcat/lib directory.
You customized a Tabbed User Form, but when you try accessing the form through User Creation, you see the following exception:
com.waveset.util.WavesetException: Maximum form stack depth exceeded
You are limited to pushing 1000 hard-coded elements on the stack and you exceeded this limit.
If you added a check to detect Field containers that include a FieldRef or Field that matches the name of the Field container, you might have inadvertently created a circular reference on the form. To fix this problem, change the FieldRef or Field name.
You used a MultiSelect field in a form for LDAP users, assigned groups to a user in this field, edited the user again, and then see the same group on both sides of the MultiSelect. For example:
Left side value. cn=Group1,dc=test,dc=Com
Right side value. cn=Group1,dc=test,dc=com
In this example, the LDAP baseContext resource field is set to dc=test,dc=com and the LDAP groups are listed as dc=test,dc=Com, which causes a problem because LDAP is not case sensitive, but the MultiSelect widget is case-sensitive.
To alleviate this problem, change the baseContext on the LDAP resource to match the case in your LDAP resource dc=test,dc=Com or use the <upcase> XPRESS function to uppercase both the left and right side displays.
When troubleshooting the Oracle Waveset Gateway, it is often useful to run the Gateway from the command line. Using command line options allows you to input a wider range of start-up options, which includes starting the Gateway as a normal application instead of a service and running the Gateway on a different port.
You must kill the Waveset Gateway as a service before running it from the command line. For example, type
gateway.exe -k
The following table describes the Gateway command line arguments.
Argument |
Description |
---|---|
-i |
Install this program as an NT service, with specified startup |
-r |
Remove this program from the Service Manager |
-s |
Start the service |
-k |
Kill the service |
-t |
Set start-up for an existing service |
-d |
Debug, and run as a regular application |
-p |
Specify a TCP/IP port number (Default is 9278) |
-f |
Specify the path to the trace file |
-l |
Specify the level of tracing (Default is 0, no information) |
-m |
Specify the maximum trace file size in kilobytes |
-v |
Display the version |
Usage: gateway -i n -r -s -k -t n -d -p n -f name -l n -m n -v.
The -d and -s options are mutually exclusive.
See To Enable Tracing from the Command Line for more information about the Gateway tracing levels.
You can also use the Waveset Gateway Debug page (debug/Gateway.jsp ) to troubleshoot the Gateway. See How to Configure Gateway Tracing for more information.
If you have the basic Java programming skills required to work with Waveset, you should be able to diagnose and resolve most Java code problems.
However, a fairly common problem occurs where someone opens a connection to the database but does not close the connection properly. If you do not close the connection properly, performance issues result.
This section describes several methods you can use to investigate low memory conditions, including:
If you start experiencing slow response times when accessing users or when logging into accounts, you might have exceeded the admin cache size, which results in the admin cache being disabled.
The admin cache is a cache maintained on each server that contains all WSUser objects that are considered to be administrators. Waveset loads this cache when the server starts up, and automatically maintains this cache by watching for WSUser object changes.
Users are generally considered administrators when they have at least one capability and control an object group. If the number of administrator users exceeds the number specified for the cache, Waveset disables the cache, which causes poor system performance.
The default size of the admin cache is 10K. If you have more than 10K administrators, Waveset does not initialize the admin cache. You can adjust this limit by changing the admincache.rowlimit property in Waveset.properties. The cost of increasing admin cache size is the additional use of heap memory. The WSUser objects in the cache consume memory for the entire lifecycle of the server.
Waveset reads the admincache.rowlimit property at server startup, so any change to this property requires the server to be restarted.
You must set this property on each server because Waveset.properties is not shared across servers.
Waveset no longer requires approvers to be administrators, as in earlier versions of the product, which potentially reduces the number of administrators in the cache and improves system performance.
Out-of-memory conditions can be difficult to troubleshoot, but you can start by ensuring that sufficient memory was initialized at start up and by checking that Waveset is tracing memory usage levels and alerts.
If you are debugging problems with the admin cache, tracing com.waveset.server.InitAdminCacheThread at level 4 can show the following information:
What were the start-up timings
How long did it take to load the admin and auth caches
What data was loaded
What happened when you added or edited a user from the Waveset Administrator interface
You can use com.waveset.server.InitAdminCacheThread to trace start-up timings. For example,
20091124 12:02:56.203 InitAdminCacheThread(0x010dae16) InitAdminCacheThread#initAdminCache() Info Getting 9 admins from admin cache took 0m0.266s 20091124 12:02:56.437 InitAdminCacheThread(0x010dae16) InitAdminCacheThread#initAdminCache() Info Loading auth cache for 9 admins took 0m0.234s
Changing admincache.rowlimit in Waveset.properties only takes affect after you restart the server. Increasing the cache size to accommodate all of the administrators in the repository may increase server performance if there is enough memory to hold the cache without resulting in excessive JVM garbage collection.
Be aware that this solution does not scale.
Available JVM heap memory is a limitation to consider when using the admincache.rowlimit property to configure cache size, particularly when implementing and tuning an x64 system.
To test your configuration,
Set admincache.rowlimit=xxxxx on VM (where xxxxx denotes the cache size setting).
Trace com.waveset.server.InitAdminCacheThread at level 4.
Review the trace file output.
Verify that the cache was loaded.
Confirm that you can disable the admincache.rowlimit setting.
Compare the machine's memory usage before and after you disable the admincache.rowlimit setting.
Ensure that the operating system has sufficient memory available to run effectively. For example, check for excess paging, CPU activity, and so forth.
Check the JVM memory usage.
Verify how long it takes the cache to load and compare this time with that of a smaller cache, such as 1000.
You must have the Debug capability to access and execute operations from the Waveset Debug pages. Administrators and the Configurator are assigned this capability by default.
If you do not have the Debug capability, an error message results.
You can open the following Waveset Debug pages from the Administrator interface to monitor how much memory is being used by your system:
Host Connection Pool page (debug/Show_ConnectionPools.jsp). View a summary of connection pool statistics (if you are not using a data source), including the pool version, how many connections were created, how many are active, how many connections are in the pool, how many requests were serviced from the pool, and how many connections were destroyed.
You can also use the Host Connection Pool page to view a summary of the connection pools used to manage connections to the Gateway. You can use this information to investigate low-memory conditions.
List Cache Cleared (debug/Clear_XMLParser_Cache.jsp ). Clear the cache of recently used XML parsers.
Private collection pool (debug/Show_JDBC.jsp). View a summary of the cache of Java DataBase Connectivity (JDBC) connections being used by the repository and some resource adapters.
System Memory Summary page (debug/Show_Memory.jsp). View the used and total memory in the system. You must click the Garbage Collect button to get the most current used memory value.
System Memory Summary page (debug/Show_Memory2.jsp). View an updated Show_Memory.jsp page that allow you to clear all unused memory in the JVM so you can investigate heap usage.
User Session Pool Cleared (Clear_User_Cache.jsp). Clear the cached sessions for recently logged in users.
XML Resource Adapter Caches Flushed and Cleared (Clear_XMLResourceAdapter_Cache.jsp). Clear the cache of the test XML resource adapter.
Use the Java Monitoring and Management Console (JConsole) to detect low memory and deadlocks. JConsole is a Java Management Extension (JMX) technology-compliant graphical management tool that is co-packaged with JDK 5 (and later).
JConsole accesses the memory system, memory pools, and MBeans garbage collector to provide information about memory use such as memory consumption, memory pools, and garbage collection statistics. In addition, You can use JConsole to monitor MBeans for information about current heap memory use and non-heap memory use.
For information about using JConsole to monitor applications that run on the Java platform, see Using JConsole to Monitor Applications. This document is available from the following URL:
http://java.sun.com/developer/technicalArticles/J2SE/jconsole.html
When you are trying to troubleshoot problems with PasswordSync, review the following logs for information:
PasswordSync Error Logs. PasswordSync writes all failures to the Windows Event Viewer. (For more information about Event Viewer, see Windows’ Help.) The source name for error log entries is PasswordSync.
PasswordSync Trace Logs. PasswordSync writes all trace logs to the file location specified when you configured tracing. See Using the PasswordSync Configuration Tool.
Some common PasswordSync problems and solutions include
PasswordSync is not propagating password changes from the Windows server to Waveset.
PasswordSync relies on the registry settings when creating a connection from Active Directory to the Waveset Server. PasswordSync reads the registry and processes the settings, but PasswordSync does not perform any checks to see if it can create a connection.
The following example shows a registry entry for a PasswordSync server. This example includes the default registry setting values, but does not show all of the settings used by PasswordSync.
[HKEY_LOCAL_MACHINE\SOFTWARE\Sun Microsystems\Sun Identity Manager\PasswordSync] "reinitIntervalMilli"=dword:1B77400 "securityIgnoreCertRevoke"=dword:00000000 "securityAllowInvalidCert"=dword:00000000 "directMode"=dword:00000001 "lhuser"="config" "lhcred"="rsVtQZpa5Ys=" "endpointURL"="http://10.10.10.10:8080/idm/servlet/PasswordSync" "installdir"="C:\\Program Files\\Sun Microsystems\\Sun Identity Manager PasswordSync" "tracelevel"=dword:00000000 "tracemaxKB"=dword:00002710 "tracefile"="C:\\Program Files\\Sun Microsystems\\Sun Identity Manager PasswordSync\\trace.log" |
If you have not enabled tracing at an appropriate level, PasswordSync does not log connection failures in much detail. To see more detailed trace information, edit the PasswordSync registry settings as described on Editing the Registry Keys. Specify tracelevel 4 to output the maximum trace information, and change the tracefile value to point to a writable file. For example:
"tracelevel"=dword:00000004 "tracefile"="C:\\Program Files\\Sun\\IdentityManager\\PasswordSync\\pwicsvc.log"
The registry settings will be reread based on the <i>reinitIntervalMilli</i> setting in the registry. After rereading the registry settings, PasswordSync automatically starts or stops tracing, depending on the trace parameters set in the registry. For each intercepted password change, PasswordSync logs the actions taken to push the password to Waveset.
If a connection fails during creation, you might encounter the following situations:
Each of these situations has its own error code and set of log entries. Waveset removes the date, time stamp, and process number from these entries to keep them short.
An incorrect or unreachable URL error that occurs when the server cannot be reached, is not running, or does not reply with a correct response.
Check that PasswordSync can access the server and page.
Be sure the server is running and that you have configured your firewalls and routers correctly.
Check the application server to be sure it is running, and that PasswordSync can connect to the endpointURL without the application path. If PasswordSync can does not return a page or an error, the application server is not running.
Check the servlet response by opening the endpointURL in a standard browser. If you do not see an error that starts with: com.waveset.util.WavesetException see if the servlet is compiling and available..
JMS usage for PasswordSync relies on the jms.jar being available in the classpath. The following exception message displays if you access the endpointURL without the correct file in place:
com.waveset.util.WavesetException: A JMS request arrived, but JMS PasswordSync is unavailable. Is JMS jar file available? |
An incorrect user name error generally occurs when the userID stored in the lhuser entry is incorrect. Use the Configure.exe utility to replace the user or replace the lhuser registry key value with a valid userID.
An incorrect password error generally occurs when the password stored in the lhcred entry is not correct when used in combination with the userID stored in lhuser. Use the Configure.exe utility to replace the password, but do not manually edit the lhcred registry key.
A garbage in the password entry error generally occurs when the registry key is corrupted and or when the registry key is manually edited, which causes garbage in the password entry.
This situation causes the process to hang in RAEncryptor::Decrypt3DES and PasswordSync cannot decrypt the entry. Use the Configure.exe utility to replace the password.
When you are trying to troubleshoot problems with a reconciliation task, review the Reconciliation Status Debug page (debug/Show_Reconciler.jsp) to see what the resource threads are working on.
Some common reconciliation problems include
Reconciliation does not start.
Open the System Threads Debug page (debug/Show_Threads.jsp) to see if the Reconcilerserver_name task is running.
If the task is not running, open the System Settings page and click Trace Scheduler.
Running the Scheduler restarts the Reconciler server_name task.
Check the System Threads page again, and if the Reconciler server_name task has not restarted, the Scheduler might be hung.
Restart your application server.
Reconciliation fails for a certain user object.
If the object exists in Waveset, try editing the object directly. If the Waveset account does not exist, load the one account from the resource.
Verify the reconciliation user has the proper access rights.
Try extracting the object to a file using the same code path as reconciliation.
Open the System Memory Summary Debug page (debug/Show_Memory.jsp or debug/Show_Memory2.jsp) and verify you have enough free memory.
Waveset’s lh commands are very useful when you are troubleshooting connection problems. These commands use Waveset’s web application installation, but remove the application server from the equation.
This section describes the following
This section describes how to use the lh commands; starting with using the more basic commands and progressing to using commands that exercise most of Waveset.
After becoming familiar with these debugging tools, you can develop your own variations for using these lh commands.
Use the lh setRepo -c -n command to perform the most basic connection test, which allows you to examine the current repository location without connecting. You can use this command to verify that parameters, such as URL and JDBC driver, are correct.
If the connection is successful, you can read the ServerRepository.xml bootstrap file.
If the connection fails, try to solve this failure first. A decryption error is the most common cause of this failure. For example, you might have a J2EE mismatch or classpath conflict.
Use the lh setRepo -c -v command to connect to and examine the current repository location. (The -v provides verbose output.) You can use this command to exercise almost all of the Repository code without requiring the Waveset server.
If the connection is successful, then you are successfully connected to the current repository location.
If the connection fails, try to solve this problem first. Solving your connection problem can be very helpful in resolving DNS, firewall, or remote connection privilege problems.
For more information, see Testing DataSource Connections.
Use the setRepo command throughout the debugging process, to specify a new repository location or to set the repository to the same location.
You can use this command to confirm that all of the necessary components, such as the JAR files, are in place. The setRepo command also lets you vary connection information, such as userid and password, to debug table ownership or privilege problems.
Use this command to actually start an Waveset Server using the JAR files in the WEB-INF/lib and the classes in WEB-INF/classes under WSHOME. The lh console command uses your Waveset installation environment and actually starts the Waveset application, but removes the application server from the equation.
If the connection is successful, the problem is specific to the application server environment or configuration.
If the connection fails, review the failure messages.
If the connection failure is the same as the application server failure, you have reproduced this failure with significantly fewer variables.
If the failure appears to be different from the application server failure, try fixing the Waveset connection problem first because there are fewer variables and more of these variables are under Waveset control.
If you are testing a DataSource connection, the lh setRepo -c command might fail.
This failure is especially likely if you configured Waveset to use the application server’s database connectivity service or the application server’s directory service. These services often work only in the environment that a running application server provides to a web application.
Initially, approach the DataSource configuration you want in a step-by-step manner. Once you are comfortable with these steps, you can adapt your approach to suit your needs.
Try using a direct JDBC DriverManager connection, such as a non-DataSource connection, that bypasses the application server’s database connectivity service.
Use a DataSource, but store the DataSource object in a directory service other than application server’s directory service.
If you have no other directory service available, you can download a free directory service, including the reference implementation of JNDI that uses only the local file system.
If these steps work, you have localized the problem to the application server.
Then, if useful, you can add the application server’s database connectivity service or the application server’s directory service, whichever service works outside of the environment that the application server provides to web applications.
This section describes how to diagnose and fix some common server-related problems.
You can analyze your application server logs for fatal errors and other server-related problems.
To troubleshoot server problems, use the application server’s Administrative Console to increase the logging level for each module. For more information, see the product documentation supplied with your server.
Most application servers have a standard location for standard out files (stdout) and standard error files (stderr) for the JVM running the application server. To analyze your application server logs, locate the logs directory or the log files specified for your Waveset application server.
Open the stdoutfile to view minor messages and other tracings.
Open the stderr file to view fatal and critical exceptions.
You will see Waveset start up and shut down the messages in this trace output.
Beginning with Sun Identity Manager Version 7.1, a sealing violation exception occurs in the application server log when you use Waveset with Oracle 10g on Sun Java System Application Server Enterprise Edition 8.2.
This exception generally occurs if you are using more than one Java Archive file (JAR file) containing Oracle JDBC drivers.
To prevent this problem, be sure the CLASSPATH contains only one JDBC driver JAR file, and that you use the ojdbc14_g.jar provided with Oracle 10g. In addition, you must use the ojdbc14_g.jar provided by the Oracle 10g installation to ensure correct operation.
Waveset depends on, and includes, some jar files that may also be provided by the application server, which can cause a conflict.
For example, an error can result when you deploy:
Sun Identity Manager 8.1 on jBoss
Sun Identity Manager 7.0 on Apache Tomcat 4.1
Tomcat ships with a commons-logging jar file in $TOMCAT_HOME/server/lib/commons-logging-1.1.jar and Identity Manager 7.0 ships with a commons-logging file in $TOMCAT_HOME/webapps/idm/WEB-INF/lib/commons-logging.jar.
The version of the jar file provided by the application server must be newer than the one provided by Waveset. To determine which jar file is newer, inspect the Specification-Version and Implementation-Version meta tags in the META-INF/MANIFEST.MF file.
If you deploy Waveset on certain application servers and errors result, you can remove the Waveset commons-*.jar files from the Waveset WEB-INF/lib directory to fix the problem.
If you are using the Oracle Waveset Service Provider End User Login page in WebSphere, and a javax.servlet.UnavailableException occurs with a 404 error displayed in your browser, you must reset some properties in the IBM 1.5 JDK.
Use the following steps:
In the was-install/java/jre/lib directory, rename the jaxb.properties.sample to jax.properties and uncomment these two lines:
javax.xml.parsers.SAXParserFactory= org.apache.xerces.jaxp.SAXParserFactoryImpl javax.xml.parsers.DocumentBuilderFactory= org.apache.xerces.jaxp.DocumentBuilderFactoryImpl |
Save the file and restart the application server.
To test an SPML configuration:
Open the Connect page and click Test.
A dialog indicating that the connection was successful pops up.
Open the Schema page and click Submit.
The system displays a hierarchical view of the schemas supported by the Waveset server.
If you cannot establish a successful connection
Double-check the URL you entered.
If the error you receive contains phrases such as no response or connection refused, then the problem is most likely the host or port used in the connection URL.
If the error suggests that a connection was made, but the web application or servlet could not be located, the problem is most likely in the WEB-INF/web.xml file.
If you encounter problems during the upgrade, check the upgrade log files located in the $WSHOME/patches/logs directory. The file names for the logs are based on a timestamp and the stage of the upgrade.
If, following an upgrade, Waveset fails to start with the following exception, your JDK/JRE may be the problem:
java.lang.IllegalStateException: Error attempting to decrypt: Given final block not properly padded |
Verify that you are using a JDK/JRE supplied by the same vendor that you were using previously. For example, you cannot upgrade to a Sun JDK if previously you were using a JDK from IBM. To fix this problem, uninstall the JDK/JRE and install the JDK or JRE from your previous vendor.