Chapter 1 Sun Gathering Debug Data for Sun Java System Directory Editor

This technical note describes how to use Sun^TM Gathering Debug Data (Sun GDD or GDD) to collect data that the Sun Support Center requires in order to debug problems with Sun Java^TM System Directory Editor software.

By collecting this data before you open a Service Request, you can reduce substantially the time needed to analyze and resolve the problem. For more information on how this document and associated scripts can help you in better dealing with Directory Editor problems, see:

http://www.sun.com/services/gdd/index.html

This document is intended for anyone who needs to open a Service Request about Directory Editor software with the Sun Support Center.

This technical note contains the following sections:

• Technical Note Revision History

• About This Technical Note

• Overview of Collecting Debug Data For Directory Editor

• Creating a Service Request with the Sun Support Center

• What Directory Editor Debug Data Should You Collect?

• Reporting Problems

• Accessing Sun Resources Online

1.1 Technical Note Revision History

1.2 About This Technical Note

This document covers Sun Java System Directory Editor on all supported platforms.

You can use this document in all types of environments, including test, pre-production, and production. Verbose debugging is not used so as to avoid performance impact, except when it is deemed necessary. In some cases, it is possible that the problem could disappear when you configure logging for debug mode. However, this is the minimum to understand the problem. In the majority of cases, the debug data described in this document is sufficient to analyze the problem.

This document does not provide workarounds nor techniques or tools to analyze debug data. It provides some troubleshooting, but you should not use this guide as an approach to troubleshooting Directory Editor problems.

If your problem does not conveniently fit into any of the specific categories, supply the general information described in To Collect Required Debug Data for Any Directory Editor Problem and clearly explain your problem.

If the information you initially provide is not sufficient to find the root cause of the problem, Sun will ask for more details, as needed.

1.2.1 Prerequisites for Collecting Directory Editor Debug Data

Make sure you have superuser privileges when collecting debug data for Directory Editor.

1.2.2 Variables Used in This Technical Note

The following describes the variables used in the procedures in this document. Gather the values of the variables if you don't already know them before you try to do the procedures.

application-root

The file system location where you find the WEB-INF directory for the web application container.

app-server-root

The base file system location for Sun Java System Application Server.

server-root

The base file system location for the Configuration Directory Server for Directory Editor or for the Directory Server instance managed through Directory Editor.

tomcat-root

The base file system location for Apache Tomcat.

Many paths specified in this document use the forward slash format of UNIX. If you are running software on a Windows system, use the equivalent backslash format.

1.3 Overview of Collecting Debug Data For Directory Editor

Collecting debug data for any Directory Editor problem involves these basic operations:

1. Collecting basic problem and system information.

2. Collecting specific problem information.

3. Creating a tar.gz file of all the information and uploading the file to the Sun Support Center.

4. Creating a Service Request with the Sun Support Center.

1.4 Creating a Service Request with the Sun Support Center

When you create a Service Request with the Sun Support Center, either online or by phone, provide the following information:

• A clear problem description

• Details of the state of the system, both before and after the problem started

• Impact on end users

• All recent software and hardware changes

• Any actions already attempted

• Whether the problem is reproducible; when reproducible, provide the detailed test case

• Whether a pre-production or test environment is available

• Name and location of the archive file containing the debug data

Upload your debug data archive file to one of the following locations:

• http://supportfiles.sun.com/upload

• https://supportfiles.sun.com/upload

When opening a Service Request by phone with the Sun Support Center, provide a summary of the problem. Also provide the details in a text file named Description.txt. Be sure to include Description.txt in the archive along with the rest of your debug data.

For more information on how to upload files, see: http://supportfiles.sun.com/show?target=faq

1.5 What Directory Editor Debug Data Should You Collect?

This section describes the kinds of debug data you need to provide based on the problem you are experiencing.

This section contains the following tasks:

• To Collect Required Debug Data for Any Directory Editor Problem

• To Collect Required Debug Data for Directory Editor Installation Problems

• To Collect Required Debug Data for Directory Editor Startup Problems

• To Collect Required Debug Data for Directory Editor Login Problems

• To Collect Required Debug Data for Directory Editor Graphical User Interface Problems

1.5.1 To Collect Required Debug Data for Any Directory Editor Problem

All problems described in this technical note need basic information collected about when the problem occurred and about the system having the problem. Use this task to collect that basic information.

1. Note the time or times the problem occurred.

2. Note the name of the application server in which you run Directory Editor.

3. Note the exact version of the application server in which you run Directory Editor.

4. Note the exact version of the Java Virtual Machine which you use to run Directory Editor.

5. Note the operating system version.

   Solaris OS

   uname -a

   HP-UX

   uname -r

   Red Hat

   cat /etc/redhat-release

   Windows

   C:\Program Files\Common files\Microsoft Shared\MSInfo\msinfo32.exe /report C:\report.txt

6. Note the patch level.

   Solaris OS

   showrev -p

   HP-UX

   swlist

   Red Hat

   rpm -qa

   Windows

   Already provided in C:\report.txt.

7. Note the Directory Editor version and build number.

   The build number is available only for Directory Editor 1.

   To determine the build number, hover your mouse cursor over the Version string at the top of the Directory Editor page. Either a tooltip appears showing the build number, or the browser displays the build number as a message in the status bar at the bottom of the browser window.

   Alternatively, you can view the source of the Directory Editor web page and search for Build number.

8. Collect Directory Editor configuration files.

   application-root/WEB-INF/classes/init.xml

   application-root/WEB-INF/classes/log4j.properties

   application-root/WEB-INF/startup.properties

1.5.2 To Collect Required Debug Data for Directory Editor Installation Problems

This procedure describes what data to collect when you cannot complete Directory Editor installation.

1. Collect the security policy file for your application server.

   For Sun Java System Application Server

   app-server-root/domains/domain-name/config/server.policy

   For Apache Tomcat with Security Manager turned on

   tomcat-root/conf/catalina.policy

2. Collect error logs for your application server.

   For example, if you run Directory Editor in the first domain and instance of Sun Java System Application Server, collect app-server-root/domains/domain1/server1/logs/server.log.

3. Collect Directory Server access, errors, and audit logs.

   Collect logs from both the Directory Editor Configuration Directory Server and also Managed Directory Servers. By default, you find these logs in the following locations:

   server-root/slapd-serverID/logs/access

   server-root/slapd-serverID/logs/errors

   server-root/slapd-serverID/logs/audit (if enabled)

   If these log files are not in the default locations, examine the Directory Server configuration file, server-root/slapd-/serverID/config/dse.ldif, to find the paths to the logs. The paths are specified as the values of attributes nsslapd-accesslog, nsslapd-errorlog, and nsslapd-auditlog.

4. When using Sun Java System Application Server 7 or 8, collect the server description file.

   For example, app-server-root/domains/domain1/server1/config/server.xml.

1.5.3 To Collect Required Debug Data for Directory Editor Startup Problems

This section describes what data to collect when you cannot start Directory Editor.

1. Collect information about the port used for your application server.

   UNIX and Linux

   netstat -an | grep app-server-port

   Windows

   netstat -an

2. Collect error logs for your application server.

   For example, if you run Directory Editor in the first domain and instance of Sun Java System Application Server, collect app-server-root/domains/domain1/server1/logs/server.log.

3. Collect logs from both the Directory Editor Configuration Directory Server and also Managed Directory Servers.

   By default, you find these logs in the following locations:

   server-root/slapd-serverID/logs/access

   server-root/slapd-serverID/logs/errors

   server-root/slapd-serverID/logs/audit (if enabled)

   If these log files are not in the default locations, examine the Directory Server configuration file, server-root/slapd-/serverID/config/dse.ldif, to find the paths to the logs. The paths are specified as the values of attributes nsslapd-accesslog, nsslapd-errorlog, and nsslapd-auditlog.

4. Collect the de-startup-problem-services.ldif file generated by the ldapsearch command.

   Be sure to include the -B option, which retrieves binary attribute values as they are stored in the directory.

   UNIX and Linux

   server-root/shared/bin/ldapsearch -h hostname -p port -D "cn=Directory Manager" -w password -B -b "ou=1.0,ou=DML,ou=services,dc-root" "(objectclass=*)" > /tmp/de-startup-problem-services.ldif

   Windows

   server-root\shared\bin\ldapsearch.exe -h hostname -p port -D "cn=Directory Manager" -w password -B -b "ou=1.0,ou=DML,ou=services,dc-root" "(objectclass=*)" > C:\de-startup-problem-services.ldif

   Here, dc-root means the domain controller suffix for the configuration directory used in your environment, such as dc=example,dc=com.

1.5.4 To Collect Required Debug Data for Directory Editor Login Problems

This section describes what data to collect when you cannot login to Directory Editor.

1. Take a screen shot of the login screen.

   The screen shot should show the error message that results when you try to login.

2. Note the result of an attempt to login to Directory Editor as cn=Directory Manager.

   The cn=Directory Manager user might be able to login although other users cannot.

3. Collect the user-prob.ldif file generated by the ldapsearch command.

   UNIX and Linux

   server-root/shared/bin/ldapsearch -h hostname -p port -D "cn=Directory Manager" -w password -b "base-dn" "(uid=userID)" > /tmp/user-prob.ldif

   Windows

   server-root\shared\bin\ldapsearch.exe -h hostname -p port -D "cn=Directory Manager" -w password -b "base-dn" "(uid=userID)" > C:\user-prob.ldif

   Here, base-dn means the DN of the suffix used in your environment to store user entries, such as ou=people,dc=example,dc=com.

4. Collect the error logs for your application server.

   For example, if you run Directory Editor in the first domain and instance of Sun Java System Application Server, collect app-server-root/domains/domain1/server1/logs/server.log.

5. Collect logs from both the Directory Editor Configuration Directory Server and also Managed Directory Servers.

   By default, you find these logs in the following locations:

   server-root/slapd-serverID/logs/access

   server-root/slapd-serverID/logs/errors

   server-root/slapd-serverID/logs/audit (if enabled)

   If these log files are not in the default locations, examine the Directory Server configuration file, server-root/slapd-serverID/config/dse.ldif, to find the paths to the logs. The paths are specified as the values of attributes nsslapd-accesslog, nsslapd-errorlog, and nsslapd-auditlog.

6. Collect the de-login-problem-services.ldif file generated by the ldapsearch command for both the Configuration Directory Server and the Managed Directory Servers.

   Be sure to include the -B option, which retrieves binary attribute values as they are stored in the directory.

   UNIX and Linux

   server-root/shared/bin/ldapsearch -h hostname -p port -D "cn=Directory Manager" -w password -B -b "ou=1.0,ou=DML,ou=services,dc-root" "(objectclass=*)" > /tmp/de-login-problem-services.ldif

   Windows

   server-root\shared\bin\ldapsearch.exe -h hostname -p port -D "cn=Directory Manager" -w password -B -b "ou=1.0,ou=DML,ou=services,dc-root" "(objectclass=*)" > C:\de-login-problem-services.ldif

   Here, dc-root means the domain controller suffix for the configuration directory used in your environment, such as dc=example,dc=com.

7. Collect the de-login-problem-aci.ldif file generated by the ldapsearch command for the Managed Directory Servers.

   UNIX and Linux

   server-root/shared/bin/ldapsearch -h hostname -p port -D "cn=Directory Manager" -w password -b "base-dn" "(objectclass=*)" aci > /tmp/de-login-problem-aci.ldif

   Windows

   server-root\shared\bin\ldapsearch.exe -h hostname -p port -D "cn=Directory Manager" -w password -b "base-dn" "(objectclass=*)" aci > C:\de-login-problem-aci.ldif

   Here, base-dn means the DN of the suffix used in your environment to store user entries, such as ou=people,dc=example,dc=com.

8. Collect trace logging information showing authentication activity.

   To collect this information, perform the following steps.

   1. Open the app-server-root/WEB-INF/classes/log4j.properties file in a text editor.

   2. Add the following lines.

      log4j.logger.com.sun.dml.auth=TRACE,auth
      
      log4j.appender.auth=org.apache.log4j.RollingFileAppender
      log4j.appender.auth.layout=org.apache.log4j.PatternLayout
      log4j.appender.auth.layout.ConversionPattern=%d{ISO8601} [%t] %-5p %c - %m%n
      log4j.appender.auth.File=de-auth.log
      log4j.appender.auth.MaxFileSize=5MB
      log4j.appender.auth.MaxBackupIndex=1

   3. Restart Directory Editor.

   4. Reproduce the login problem immediately.

   5. Collect the log file or files named de-auth.log.

1.5.5 To Collect Required Debug Data for Directory Editor Graphical User Interface Problems

This section describes what data to collect when part of the Directory Editor user interface fails to comply with what you expect.

1. Collect screen shots of the affected screen or screens.

   The screen shots should show the problem you are experiencing.

2. Provide step by step instructions for reproducing the problem.

   If needed, also provide test case data.

3. Provide the browser name, version number, and operating system where you run the browser to access Directory Editor.

4. Provide information about the user who was logged in when the problem occurred.

5. Collect trace logging information showing view and web activity.

   To collect this information, perform the following steps.

   1. Open the app-server-root/WEB-INF/classes/log4j.properties file in a text editor.

   2. Add the following lines.

      log4j.logger.com.sun.dml.view=TRACE,view
      log4j.logger.com.sun.dml.web=TRACE,web
      
      log4j.appender.view=org.apache.log4j.RollingFileAppender
      log4j.appender.view.layout=org.apache.log4j.PatternLayout
      log4j.appender.view.layout.ConversionPattern=%d{ISO8601} [%t] %-5p %c - %m%n
      log4j.appender.view.File=de-view.log
      log4j.appender.view.MaxFileSize=5MB
      log4j.appender.view.MaxBackupIndex=1
      
      log4j.appender.web=org.apache.log4j.RollingFileAppender
      log4j.appender.web.layout=org.apache.log4j.PatternLayout
      log4j.appender.web.layout.ConversionPattern=%d{ISO8601} [%t] %-5p %c - %m%n
      log4j.appender.web.File=de-web.log
      log4j.appender.web.MaxFileSize=5MB
      log4j.appender.web.MaxBackupIndex=1

   3. Restart Directory Editor.

   4. Reproduce the login problem immediately.

   5. Collect the log files named de-view.log and de-web.log.

6. Collect screen shots of Directory Editor debugging screens.

   Access the following Directory Editor URL, http://hostname:port/de/Debug.do.

   Take screen shots of the following five tab pages:

   • HTTP Session

   • Directory Properties

   • Java System Properties

   • Memory

   • Call Timer

1.6 Reporting Problems

Use the following email aliases to report problems with this document and its associated scripts:

gdd-feedback@sun.com

For feedback on this document

gdd-issue-tracker@sun.com

To report problems in gathering debug data

1.7 Accessing Sun Resources Online

The docs.sun.com web site enables you to access Sun technical documentation online. You can browse the docs.sun.com archive or search for a specific book title or subject. Books are available as online files in PDF and HTML formats. Both formats are readable by assistive technologies for users with disabilities.

To access the following Sun resources, go to http://www.sun.com:

• Downloads of Sun products

• Services and solutions

• Support (including patches and updates)

• Training

• Research

• Communities (for example, Sun Developer Network)

1.8 Third-Party Web Site References

Third-party URLs are referenced in this document and provide additional, related information.

Sun is not responsible for the availability of third-party web sites mentioned in this document. Sun does not endorse and is not responsible or liable for any content, advertising, products, or other materials that are available on or through such sites or resources. Sun will not be responsible or liable for any actual or alleged damage or loss caused or alleged to be caused by or in connection with use of or reliance on any such content, goods, or services that are available on or through such sites or resources.

1.9 Sun Welcomes Your Comments

Sun is interested in improving its documentation and welcomes your comments and suggestions. To share your comments, go to http://docs.sun.com and click Send Comments. In the online form, provide the full document title and part number. The part number is a 7-digit or 9-digit number that can be found on the book's title page or in the document's URL. For example, the part number of this book is 820-0435-10.