Sun Java System Directory Editor 1 2005Q1 Installation and Configuration Guide |
Chapter 10
Error Logging and TroubleshootingThis chapter explains how to troubleshoot problems you may encounter as you work with Directory Editor. The information is organized into the following chapters:
Before You Call Technical SupportBefore you call technical support, please get as much information as possible about the problem you are experiencing.
- Using instructions provided in Obtaining Information About the Problem, to increase logging levels where appropriate and then try to re-create the problem.
- Save all logs and error information, and be ready to provide this information to the technical support staff.
If you perform an action in Directory Editor and an error page displays, you can email that error page to your Technical Support representative. Directory Editor embeds exceptions as comments in its error pages.
- Be prepared to answer questions about your Directory Editor installation.
For example,
- Which application server and version are you running?
- Which J2SDK version are you running?
- Which operating system is running the application server?
- Which browser version and operating system are you using to access Directory Editor?
- Which user was logged in when the problem occurred?
- How are the Startup Properties and Managed Directory configured?
- Which Directory Editor build are you running?
Obtaining Information About the ProblemThe first step to solving problems is to figure out what went wrong. Directory Editor provides the following information to help you diagnose and solve problems:
Information in the Page
If an error page displays in Directory Editor, the error page will contain information about the problem. (For example, Directory Editor embeds exceptions as comments in its error pages.) To locate this information, right-click on the page and when a pop-up menu displays, select View Page Source.
Inspect the page, and if it contains a Java stack trace or the exception information, select File > Save Page As from the browser’s menubar to save the page, and then forward it to your Administrator for assistance.
Information in the Logs
There are various log files that may contain relevant information about the problem. These log files are described in the following sections:
Directory Editor Log
The Directory Editor log contains log statements generated from Directory Editor.
Possible log levels include:
You can set these logging levels per Java class or package. For example, to get detailed messages about the operations being sent to the LDAP server, you can add the following line to the file:
log4j.logger.com.sun.dml.resource.LDAPConnector=TRACE
The log4j.properties file shipped with Directory Editor provides more documentation about setting logging levels and commonly used levels.
Changing Logging Properties on Application Server 7 or
Application Server 8 Platform EditionTo change Directory Editor’s log location or logging levels, you must edit the log4j.properties file as follows:
You can also change the loggers in a log file to use a different appender.
For example, the default log4j.properties file contains an appender defined for a rolling log file that rolls with a maximum file size. to use the rolling log file appender, you must edit the following log4j.rootLogger file to use the new appender name (log4j.rootLogger=WARN,rollingfile).
For more information about configuring appenders and logging levels in the log4j.properties file, see the Log4j documentation provided at the following location:
http://logging.apache.org/log4j/docs/
Changing Log Levels on Application Server 8 Enterprise Edition
To change Directory Editor’s logging levels on Application Server 8 Enterprise Edition, you must perform the following steps:
- Open the Sun ONE Server Admin Console.
- On the left side of the Console, select the application server where you want to change the logging level.
- Select the Logging tab, and then select Log Levels.
- Click the Add Property button (located at the bottom of the screen).
- Type in the fully-qualified name of the class for which you want to see output
(for example, com.example.dml.view.LDAPView).
- When you are finished, click Save.
- If you are running Sun Java System Application Server 8.1, stop and restart the server. Continue to Step 7.
- If you are running Sun Java System Application Server 8.0, you must stop the server and modify the domain.xml file found in the following location:
<INSTALL_DIR>/AppServer/domains/domain1/config
- Select the <log-service> node, and then select the <module-log-levels> node.
- Locate the <property> nodes you just entered from the Admin Console.
These nodes are currently in the wrong location. You must move these nodes from the <module-log-levels> node to the <log-service> node.
For example, (note that all values were removed from the log and module nodes for readability):
<log-service alarms="false" ...>
<module-log-levels admin="INFO" ...>
</module-log-levels>
<property name="com.sun.dml.logging.DMLLogging" value="FINEST"/>
</log-service>
- Restart your server.
- Use one of the following methods to view your log output:
Identity Manager Log
Some of Directory Editor’s core components are provided by Sun Java System Identity Manager, which also supports logging. You can configure this product’s logging using the Java system properties or the following file:
<application root>/config/Waveset.properties
Logging levels are configurable on a per package, per class, or per method basis. By default, the Identity Manager log goes to the WSTrace.log file located in the <application root>/config/ directory. You can change this file by defining the trace.destination and trace.Logging levels as follows:
- 0: Disable tracing
- 1: Entry and exit of public methods, plus major exceptions
- 2: Entry and exit of all methods
- 3: Significant informational displays (such as variable values that control flow) that occur only once per method invocation
- 4: Informational displays that occur n times per method invocation
Here as an example of tracing configuration in the Waveset.properties file:
Code Example 10-1 Sample Identity Manager Trace Configuration
You can also turn on tracing for forms and XPRESS by setting the form.trace and xpress.trace properties to true in the Waveset.properties file. You must restart the application server for any Identity Manager logging changes to take effect. For more information, see the Sun Java System Identity Manager Technical Deployment Guide.
Directory Server Log
Sun Java System Directory Server and Sun ONE Directory Server both can log directory access and detailed auditing messages.
The audit log contains detailed information about changes to the directory — such as creates, edits, deletes, and renames. The log entries provide information about:
These log files are available at <directory server root>/slapd-<host>/logs/ in the access and audit files respectively. (Directory Server keeps back-ups of these files in time-stamped files.)
The access file is enabled by default, and logs messages for directory binds, unbinds, searches, creates, edits, deletes, and renames.
The audit log file is not enabled by default. To enable audit logging, use the following steps:
Application Server Logs
Generally, relevant information is available from one of the previously mentioned sources; but occasionally, error information will be logged in the application server’s log files. The location and format of these messages varies, depending on which application server is being used to run Directory Editor.
Consult your application server’s product documentation for information about accessing and configuring logs.
Information in the Debug Pages
Directory Editor provides several Debug pages to help you identify and debug problems. If you are assigned the Debug capability, you can access these Debug pages from the following URL:
<protocol>//<host>[:<port>]/de/Debug.do
Note
For more information about the Debug capability, see Understanding Capabilities and
Creating Directory Editor Roles.
When you visit this URL, Directory Editor provides a Debug tab containing the following subtabs:
- HTTP Session (default tab): This tab contains an HTTP Session Parameters table that lists all of the attributes and attribute values being used in the current HTTP session. (For example, see Figure 10-2.)
Figure 10-2 Partial HTTP Session Parameters Page
- Directory Properties: Select this tab to view the directory properties and object IDs (OIDs) for Directory Editor’s configuration directory. (For example, see Figure 10-3.)
Figure 10-3 Partial Directory Properties Page
- Java System Properties: Select this tab to view the Java system properties and property values currently being used by your current working environment.
(For example, see Figure 10-4.)Figure 10-4 Partial Java System Properties Page
- Memory: Select this tab to view the maximum memory that can be allocated, the total memory currently allocated, and how much free memory is available in the Java Virtual Machine (JVM) being run by the application server and Directory Editor. (For example, see Figure 10-5.)
Figure 10-5 Application Server Memory Usage
This page also provides a Garbage Collect button, which is used to force garbage collection in the Java Virtual Machine (JVM).
Note
Garbage collection is a Java concept, in which the program finds unused memory (from unreferenced objects) and automatically forces it back into the available memory pool.
In Directory Editor’s case, you use garbage collection to make more memory available to the application server, Directory Editor, and any other applications running in the application server instance.
The JVM automatically performs garbage collection (in a separate thread) as needed. However, clicking the Garbage Collection button forces the JVM to perform the operation immediately.
When the garbage collection operation is finished, Directory Editor adds a new row to the table and reports how much memory resulted from the collection. (For example, see Figure 10-6.)
Figure 10-6 Garbage Collection Results
The Call Timer page is an internal page used to get internal timing statistics for Directory Editor. Some of the features on this page are disabled by default to improve Directory Editor performance. If you contact Sun Technical Support for assistance, the support representative may direct you to enable this page to access internal timing statistics.
Common Problems and SolutionsThis section describes some common problems you might encounter while using Directory Editor and explains how to remedy these problems.
Running in Non-Production Mode
You must configure the application server’s policy file to give Directory Editor permission to access the application server or Directory Editor will run in non-production mode, which means the Directory Editor cannot save it’s startup properties to the file system.
If you do not specify the appropriate write permissions, a message displays in the Directory Editor interface to let you know you are running in non-production mode.
Instructions for configuring a policy file for the different application servers are provided in Step 3: Install Directory Editor on an Application Server.
java.lang.OutOfMemoryError
An OutOfMemoryError message in the Directory Editor log file indicates the application server has run out of memory.
To increase the amount of memory available to the application server, you can add the -Xmx<size> setting to your JVM — using the <size> value to specify the maximum amount of memory the JVM is allowed to use. For example, -Xmx512M tells the server to use a maximum of 512 megabytes of memory.
Consult your application server’s product documentation for information about how to set command line arguments for the application server’s JVM.
Failed to Save Startup Configuration Properties
When Directory Editor is first started, you are prompted to enter some start-up properties that define where the configuration information for Directory Editor should be stored, how to bind to store the configuration information, and a few other options. Saving this information may fail if the application server cannot write to the <application root>/WEB-INF/startup.properties file.
You will encounter this problem if you have configured the application server to run this application in unexpanded mode or the application server’s security features do not permit access to the host file system.
- To start Directory Editor using the configuration you have specified:
Click Continue Without Saving to run the application in non-production mode (see Running in Non-Production Mode), which means your Directory Editor configuration will not be saved and you will be prompted to re-enter the configuration information every time you restart Directory Editor.- To fix this problem permanently: If you are running from an unexpanded WAR (web application archive) file, extract and manually edit the WEB-INF/startup.properties file and then repackage the WAR file with the changed startup.properties.
To manually edit the startup.properties file in an unexpanded WAR file:
- From a command prompt, navigate to the directory containing the de.war file.
- Unzip the de.war file with the following command (jar is installed with the Java Development Kit (J2SDK)):
jar xvf de.war
- Edit the startup.properties file to specify the required properties.
- Use the following command to update the de.war with the updated startup.properties:
jar uvf de.war WEB-INF/startup.properties
- Re-deploy the updated de.war file to the application server.
If you cannot save the updated startup.properties in an expanded WAR file, the application server does not have write access to the file. It might be necessary to give the user running the application server write access to startup.properties.
java.security.AccessControlException
Directory Editor requires access to some privileged operations that your application server may not allow by default. You must edit the Application Server’s policy file to give Directory Editor the required access. Instructions for editing the server.policy file are provided in Chapter 2.
If you edited the policy file when you installed Directory Editor and the Directory Editor logs still show a java.security.AccessControlException (or when a user logs in and sees an Application Error page), you may have a Java security problem.
You can resolve all access control errors if you add the following line to the application server’s server.policy file:
grant codeBase “file:${de.home}/-” { permission java.security.AllPermission; };
However, you should be aware that by adding this line to the server.policy file, you give all applications installed on the application server access to Directory Editor on that server.
WebSphere is Extremely Slow During Startup
With some platforms, there is a performance impact if you use the JCE provided with that platform. If you experience a long start-up time, use Sun’s JCE 1.2.2, which you can download from:
http://java.sun.com/products/jce/
Installation Instructions are provided at the following location:
http://java.sun.com/products/jce/jce122_install.html
If you install Sun JCE using the installation instructions provided, and you encounter exceptions during WAS startup, you may have to re-order the security providers specified in the following file so that the IBMJCE is first:
${java.home}/lib/security/java.security file
For example,
security.provider.1=com.ibm.crypto.provider.IBMJCE
security.provider.2=sun.security.provider.Sun
security.provider.3=com.sun.crypto.provider.SunJCE
Modify the ${java.home}/lib/security/java.policy file as follows:
grant codeBase "file:${java.home}/lib/ext/
sunjce_provider.jar" {permission java.io.FilePermission
"${java.home}/jre/lib/ext/jce1_2_2.jar", "read";
permission java.lang.RuntimePermission "getProtectionDomain";
permission java.security.SecurityPermission "putProviderProperty.SunJCE";
};
Changing the Object Class and Attributes Used for Configuration Objects
By default, Directory Editor stores its configuration information in applicationProcess objects located in the configuration directory under:
ou=1.0,ou=DE,ou=Services,<base context>
If you want to change the location of these objects, the object class that is used to store the object, and/or the attributes used to store configuration information perform the following steps:
- Back-up the existing configuration.
- Delete the configuration organizational unit in the directory server.
- Log into the Sun ONE Directory Server Console for the directory server that contains the configuration information.
- Navigate to the configuration organizational unit in the directory at ou=DML,ou=Services,<base context>.
- Right-click the DE entry and select Delete.
- Click Yes to confirm deletion of the DE organizational unit.
- Change the necessary properties in the
<application root>/WEB-INF/startup.properties file.
- To change the location where the configuration is stored, modify the datastore.location property so it points to the appropriate configuration organizational unit.
- To change the object class used to store configuration object, modify the datastore.objectClass property to the appropriate object class.
Note
You must define all required (MUST) attributes for the object class using the datastore.dmlIdAttribute or the datastore.xmlObjectAttribute.
- To change attributes in the object class used to store configuration information, modify the datastore.dmlIdAttribute and datastore.xmlObjectAttribute.
- Restart the application server.
- Restore the configuration you backed up in Step 1.
- In Directory Editor, select Configure > Backup/Restore.
- On the Backup/Restore page, click the Browse button to locate and select the file you saved in Step 1. Click Open.
- Click the Restore Configuration from File button to restore the file.
Short Session Timeout in Tomcat
If your Directory Editor session times out too soon, you can adjust the timeout period for Tomcat as follows:
de.war File Missing
If you are trying to upgrade or reinstall Directory Editor, and you did not uninstall the older product version first or you manually uninstalled Directory Editor, the Directory Editor installer will not provide the de.war file needed to complete the installation process.
Note
You should not uninstall Directory Editor manually unless the Directory Editor uninstaller is not operational.
You must remove the following <compid> elements and sub-elements from the productregistry file:
<compid>DE files
<compid>Directory Editor war file
<compid>Directory EditorThe productregistry file is located in the following directory: