|
| |
| Sun Java System Directory Editor 1 2004Q4 SP1 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 in Directory Editor is to figure out what went wrong. You can use information provided in this section to help 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 has more documentation about how to set logging levels, and some commonly used levels.
You can configure the log’s location and the logging levels in the log4j.properties file, which is located at
<application root>/WEB-INF/classes/log4j.properties
To change the log file location and logging levels, edit the log4j.properties file in a text editor. You must restart Directory Editor after saving your changes for the changes to take effect.
You can change the loggers in a log file to use a different appender. For example, the default log4j.properties file has an appender defined for a rolling log file that rolls with a maximum file size. To use this appender, you must change the log4j.rootLogger file to use the name of the new appender (for example, 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/
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.
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 the application server may not allow by default. This problem will become apparent when a user first attempts to log into Directory Editor and sees the Application Error page.
The Directory Editor logs will show a java.security.AccessControlException.
To remedy this problem you must edit the security policy file for your application server and grant access to certain actions, as follows:
Note
In Sun ONE Application Server you will find this file in the following location:
<App Server Home>/domains/<Domain Name>/config/server.policy
- Edit the server.policy file.
- Add the following lines to the end of the block granting access to “all remaining code”:
permission javax.security.auth.AuthPermission "getLoginConfiguration";
permission javax.security.auth.AuthPermission "setLoginConfiguration";
permission javax.security.auth.AuthPermission "createLoginContext.SunDirectoryLogin";
permission javax.security.auth.AuthPermission "modifyPrincipals";
- Save the file.
- Restart the application 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:
