Print-friendly Version

Sun Gathering Debug Data for Sun Connection

Peter Charpentier, October 11, 2007
Updated Drew Gilbert, May 2008

This Tech Note is intended for anyone who needs to open a Service Request for a Sun Connection issue with the Sun Support Center.

Introduction

Sun Connection is a Solaris and Linux life cycle management tool that allows you to provision new systems, manage their updates and configuration changes, and eventually redeploy systems for new purposes. You can subscribe to update and provisioning channels to manage Solaris, Red Hat, and SUSE systems. If you have an active Sun service plan you can access to the Solaris 10 Update Channel.

This technical note describes how to collect data that the Sun Support Center requires to debug problems with a Sun Connection system. By collecting this data before you open a Service Request, you can substantially reduce the time needed to analyze and resolve a problem.

This technical note covers Sun Connection 1.0.x 1.1 and 1.1.x on the Solaris Operating System and Linux platforms. The information applies to all types of environments, including test, pre-production, and production. To reduce performance impact, verbose debugging is used only when necessary. It is possible that the problem might disappear when you configure logging for debug mode. In most cases, the debug data described here is sufficient to analyze the problem.

If your problem does not conveniently fit into any of the specific categories that are presented here, supply the general information described in Collecting Basic Debug Data for Sun Connection and clearly explain your problem.

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

Overview of Collecting Debug Data

There are five basic steps for collecting debug data for a Sun Connection problem. This document provides information about the first and last Step below.

1. Collect the basic problem and system information.

2. Collect the specific problem information (for example, installation logs, output, and other data).

3. Enable and disable debug modes for the various parts of the product.

4. Create a tar.gz file of all the information and upload it to the Sun Support Center.

5. Create a Service Request with the Sun Support Center.

Collecting Basic Debug Data for Sun Connection

This section describes the kinds of debug data that you need to provide based on the kind of problem that you are experiencing. Note that the script will detect which OS you are running, but also which parts are installed on a specific machine, such as agent, server, engine, and console software.

To Enable and Restore Debugging for the Agent

1. Go to the Sun Gathering Debug Data web page and click Sun GDD - Sun Connection.
2. Download the SUN-GDD_sun-connection-collect_noarch.tar.gz file.
3. Expand the file and install the SUN-GDD_SunConnection.sh script.

   This gives you access to the actual script that is used to collect data and enable or restore debugging.

   Note - Run all scripts in this procedure as root.

4. Run the script with the following attribute to enable debugging for the agent.

   # ./SUN-GDD_SunConnection.sh -debugAgent

5. Run the script with the following attribute to restore the debug level to that set prior to installing the SUN-GDD_SunConnection.sh script.

   # ./SUN-GDD_SunConnection.sh -restoreAgent

6. The agent software will automatically restart to effect the changes.

To Enable and Restore Debugging for the Server

1. Go to the Sun Gathering Debug Data web page and click Sun GDD - Sun Connection.
2. Download the SUN-GDD_sun-connection-collect_noarch.tar.gz file.
3. Expand the file.
4. Install the SUN-GDD_SunConnection.sh script.

   This gives you access to the actual script that is used to collect data and enable or restore debugging.

   Note - Run all scripts in this procedure as root.

5. Run the script with the following attribute to enable debugging for the server.

   # ./SUN-GDD_SunConnection.sh -debugServer

6. Run the script with the following attribute to restore the debug level to that set prior to installing the SUN-GDD_SunConnection.sh script.

   # ./SUN-GDD_SunConnection.sh -restoreServer

7. The server software will automatically restart to effect the changes.

To Enable and Restore Debugging for the Engine

1. Go to the Sun Gathering Debug Data web page and click Sun GDD - Sun Connection.
2. Download the SUN-GDD_sun-connection-collect_noarch.tar.gz file.
3. Expand the file.
4. Install the SUN-GDD_SunConnection.sh script.

   This gives you access to the actual script that is used to collect data and enable or restore debugging.

   Note - Run all scripts in this procedure as root.

5. Run the script with the following attribute to enable debugging for the engine.

   # ./SUN-GDD_SunConnection.sh -debugEngine

6. Run the script with the following attribute to restore the debug level to that set prior to installing the SUN-GDD_SunConnection.sh script.

   # ./SUN-GDD_SunConnection.sh -restoreEngine

7. The engine software will automatically restart to effect the changes.

To Enable and Restore Debugging for the Console

1. Go to the Sun Gathering Debug Data web page and click Sun GDD - Sun Connection.

2. Download the SUN-GDD_sun-connection-collect_noarch.tar.gz file.

3. Expand the file.

4. Install the SUN-GDD_SunConnection.sh script.

   This gives you access to the actual script that is used to collect data and enable or restore debugging.

   Note - Run all scripts in this procedure as root.

5. Run the script with the following attribute to enable debugging for the console.

   # ./SUN-GDD_SunConnection.sh -debugConsole

6. Run the script with the following attribute to restore the debug level to that set prior to installing the SUN-GDD_SunConnection.sh script.

   # ./SUN-GDD_SunConnection.sh -restoreConsole

7. Restart the console software for the changes to take effect

To Enable and Restore Debugging for the CLI

1. Go to the Sun Gathering Debug Data web page and click Sun GDD - Sun Connection.

2. Download the SUN-GDD_sun-connection-collect_noarch.tar.gz file.

3. Expand the file.

4. Install the SUN-GDD_SunConnection.sh script.

   This gives you access to the actual script that is used to collect data and enable or restore debugging.

   Note - Run all scripts in this procedure as root.

5. Run the script with the following attribute to enable debugging for the console.

   # ./SUN-GDD_SunConnection.sh -debugCli

6. Run the script with the following attribute to restore the debug level to that set prior to installing the SUN-GDD_SunConnection.sh script.

   # ./SUN-GDD_SunConnection.sh -restoreCli

7. The changes will be in effect the next time a Cli command is executed

To Collect Data Regarding the Agent, Engine, Server, and Console

1. Ensure that the SUN-GDD_SunConnection.sh script is installed.
2. To collect the debug data, run one of the following scripts with the indicated attributes and answer the prompts.

   Note - Run the following scripts as root.

   • To collect data on the agent, engine, server, and console:

     # ./SUN-GDD_SunConnection.sh -collectAll

   • To collect data only on the agent:

     # ./SUN-GDD_SunConnection.sh -collectAgent

   • To collect data only on the engine:

     # ./SUN-GDD_SunConnection.sh -collectEngine

   • To collect data only on the server:

     # ./SUN-GDD_SunConnection.sh -collectServer

   • To collect data only on the CLI:

     # ./SUN-GDD_SunConnection.sh -collectCli

   • To collect data only on the console:

     # ./SUN-GDD_SunConnection.sh -collectConsole

3. These scripts create a dump file in /var/tmp (or designated path) that should be uploaded to Sun after a Service Request is logged.

   Note - These scripts automatically detect if an agent, server, engine, or console is installed, and copies all the files that are found.

Additional Command-Line Options

Specify an output directory

When using any of the -collect options, the user will be prompted to enter a location to save the output file. Utilizing the -o <output-dir> option, this step can be bypassed, for example:

#  ./SUN-GDD_SunConnection.sh -collectAgent -o /var/tmp 

In this case, the agent data will be collected without prompting for a location and the resultant file will be located at:

• /var/tmp/SUN-GDD_SC_`hostname`_`date "+%d-%m-%y--%H.%M.%S"`.tar.gz

Specify a user

As data is logged to each console or CLI user's home directory when the software is in use, it is necessary to specify the location of those files. When using the -collectConsole , -collectCli or -collectAll options, the user will be prompted for the home directory that is to be collected, it will attempt to autodetect the root user's directory and use that as a default if no option is specified. To disable the collection of user logs, the string none should be entered. Utilizing the -u <user-dir> option, this step can be bypassed, for example:

#  ./SUN-GDD_SunConnection.sh -collectConsole -u /root 

#  ./SUN-GDD_SunConnection.sh -collectCli -u none 

#  ./SUN-GDD_SunConnection.sh -collectAll -u /home/scuser 

In the first example, data from the console user will be collected from the /root directory. The second example will collect basic data for the CLI, but user logs will not be collected. In the third example, -collectAll assumes the same user for both the CLI and console, data is collected from /home/scuser.

Disable restart of processes

When any -debug or -restore options are used, the script automatically restarts the relevant processes. If there is a requirement to delay restarting, this behavior can be bypassed with the -r option, for example:

#  ./SUN-GDD_SunConnection.sh -debugAgent -r 

The user will then be prompted to manually restart the agent processes.

Disable filesystem space check

When the -collectServer or -collectAll options are used, the script will check for sufficient space in the target output directory. If there is insufficient space available, the user will be prompted. If the user is certain that there will be sufficient space during collection, then this behavior can be bypassed with the -s option, for example:

# ./SUN-GDD_SunConnection.sh -collectServer -s 

Automatic debug, collect and restore

When using any of the -debug options, it is possible to have the script perform the collection and restoration steps automatically after a defined wait period through use of the -auto <time> option, where <time> is a value in seconds, for example:

#  ./SUN-GDD_SunConnection.sh -debugAll -auto 3600 

When invoked as above, the user will be prompted for an output directory and user home directory, then all installed components will have debug enabled and the user will be prompted to reproduce any issues that have been noticed. The collection will resume after the specified time has elapsed, 1 hour (3600 seconds), once this has completed, all installed components will be restored to their original state.

Putting it all together:

#  ./SUN-GDD_SunConnection.sh -debugAll -auto 3600 -s -u /home/scuser -o /var/tmp 

#  ./SUN-GDD_SunConnection.sh -debugAgent -auto 3600 -o /var/tmp 

When the above commands are run simultaneously on the server and an agent system and any issue reproduced during the wait time, the collected data will provide a valuable view of the environment to a support engineer.

Note - The -auto and -r options are not compatible

Help Screen Example From the Sun GDD Sun Connection Script

The following help screen is provided by the script. It is displayed if no options are provided. At least one option is always required to be able to use the script.

Usage: ./SUN-GDD_SunConnection.sh [option][-auto][-u -o -r -s]
Options:
  -collectAll             Collect Data from all
  -collectAgent           Collect Data from Agent only
  -collectServer          Collect Data from Server only
  -collectEngine          Collect Data from Engine only
  -collectConsole         Collect Data from Console only
  -debugAgent             Enable Agent Debug
  -debugServer            Enable Server Debug
  -debugEngine            Enable Engine Debug
  -debugAll               Enable Debug for All
  -restoreAgent           Restore Agent Debug
  -restoreServer          Restore Server Debug
  -restoreEngine          Restore Engine Debug
  -restoreAll             Restore Debug for All
  -h or -help             Print this Information.
  -u <user-dir> / none              Specify the user's home directory
                                    for -collectConsole and -collectCli functions,
                                    or “none” to disable user data collection
                               
  -o <output-dir>                   Specify output directory for -collect functions

  -auto <time>                      Automatic debug and collection
                                    Used with any debug option
                                    A time in seconds must be specified   

  -r                                Disable restart of processes
  -s                                Disable free space check when collecting server files

One debug/collect/restore option is mandatory or the script will just exit.
-debugConsole function has no effect on Sun Connection below version 1.1
Running any debug or restore option will restart Sun Connection processes unless -r is specified 

Technical Script Details

The following debug information is required for the various software elements.

Debug Information for the Agent

The following information is added to the .uce.rc file.

• A copy of the original .uce.re file to the .uce.rc.SunGDD file to enable debugging.

• The following lines are added:

  ( all ) ( log.__file.default_logger-level, "DETAILED" 
  { "SEVERE","ERROR","WARNING","INFO","DEBUG","FINE","DETAILED" } );

  ( all ) ( log.__file.uce_agent_app-level, "DETAILED" 
  { "SEVERE","ERROR","WARNING","INFO","DEBUG","FINE","DETAILED" } );

• The agent is restarted automatically.

  To restore to previous debug level, copy back the .uce.rc.SunGDD file if it exists.

Debug Information for the Server

The following information is added to the .uce.rc file.

• A copy of the original .uce.re file to the .uce.rc.SunGDD file to enable debugging.

• The following lines are added:

  ( all ) ( log.__file.uce_server_cgi-level, "DETAILED" 
  { "SEVERE","ERROR","WARNING","INFO","DEBUG","FINE","DETAILED" } );

  ( all ) ( log.__file.uce_server_cgi_publisher-level, "DETAILED" 
  { "SEVERE","ERROR","WARNING","INFO","DEBUG","FINE","DETAILED" } );

  ( all ) ( log.__file.uce_server_scheduler-level, "DETAILED" 
  { "SEVERE","ERROR","WARNING","INFO","DEBUG","FINE","DETAILED" } );

  ( all ) ( log.__file.default_logger-level, "DETAILED" 
  { "SEVERE","ERROR","WARNING","INFO","DEBUG","FINE","DETAILED" } );

  ( all ) ( invisible.debug.__group1.debug_mode, true );

• The server is restarted automatically.

Debug Information for the Engine

The following information is added to the .uce.rc file.

• A copy of the original .uce.re file to the .uce.rc.SunGDD file to enable debugging.

• The following lines are added:

  ( all ) ( log.__file.default_logger-level, "DETAILED" 
  { "SEVERE","ERROR","WARNING","INFO","DEBUG","FINE","DETAILED" } );

  ( all ) ( invisible.debug.__group1.debug_mode, true );

• The engine is restarted automatically.

Creating a Service Request With the Sun Support Center

When you create a Service Request through 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 preproduction or test environment is available

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

Upload your debug data archive file to the following locations:

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

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

For more information on how to upload files to this site, see the following web page: http://supportuploads.sun.com/show?target=faq

Note - When opening a Service Request by phone with the Dispatch Team, provide a summary of the problem, then send 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.

Reporting Problems

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

• To provide feedback: mailto:gdd-feedback@sun.com

• To report problems: mailto:gdd-issue-tracker@sun.com

More Information

For more information about Sun Connection, go to the Sun Connection information hub.

To get an inside perspective of Sun Connection, Sun Management Center software, Sun N1 Service Provisioning System, and Sun N1 System Manager, visit the Sun Connection blog. Contributors to this blog include members of the Sun Connection Field Enablement team. The goal of this blog is to share information with customers who either have already implemented or will implement these products in the future. The blog also provides important information around training and other key enablement activities.

Unless otherwise licensed, code in all technical manuals herein (including articles, FAQs, samples) is provided under this License.