Configuring WinPE to Automatically Collect Crash Dumps

This article aims to assist GSS3 customers collect logs for the the niggly issue of DAgent crashes within the WinPE automation environment. This is an intermittent issue, and one which can't be reproduced by Symantec Support. Customer assistance would therefore be very much appreciated.

If your environment suffers from DAgent crashes, please follow the steps below. This will collect DAgent logs and crash dumps which can be used by Symantec support to gather data on this issue. When contacting Symantec Support, please state that this is to assist the "Known Issue of DAgent Crashes in WinPE", ETrack 3827763.

In summary the steps we'll cover are,

1. Install debug version of GSS3 HF4 dagent
   By default, the DAgent code doesn't have detailed enough logging to help target the faulting code. This updated codebase has increased logging options which will assist. This is safe to use in production as it's just the HF4 agent with extra debug output.
    
2. Adding the Debug Folder to the Deployment share
   The zip attached to this article contains the Microsoft debugger executable CDB.EXE and some other useful files. This CDB executable will be used to capture our crash dumps for us (Windows Error Reporting isn't available in WinPE) . We need to copy these over to the Deployment Share so that they can be used within WinPE.
    
3. Adding a startup script to your winPE environment to enable Crash Dump Creation
   When WinPE starts, we want the environment to be configured correctly for use with the CDB.EXE debugger. A simple startup script fulfills this need.
    
4. Test A Crash Scenario!

Easy. So let's get cracking!

Step 1: Install debug version of GSS3 HF4 DAgent

In order to collect logs for Symantec Support, you'll need a special version of the DAgent. For GSS3 HF4 customers, this can be downloaded from,

http://www.symantec.com/docs/GUIDES10215

This Symantec Support guide has two zip attachments,

1. DAgent Debug Binaries for GSS3 HF4 (x86)
2. DAgent Debug Binaries for GSS3 HF4 (x64)

The agent files in these zips need to be extracted into the Agent binary location on your GSS3 server. For a default install, this will be the following location,

   C:\Program Files (x86)\Altiris\eXpress\Deployment Server\Agents\AClient

Once these files are in place, the next time an automation environment boots it will automagically use these  (the agent load script searches for agent files with the highest version number).

Below is an example of what your Agent folder should look like on your GSS3 box. I've highlighted in red the files I've added as a result of the downloads from Guide10215.

Please note that if you cannot upgrade to HF4, Symantec support may be able to provide the debug build relevant to your hotfix.

Step 2: Adding the Debug Folder to the Deployment share

Attached to this article is the file Debug_v1.0.zip. This needs to be expanded and placed on your GSS3 server in the Deployment share. When you've done this this will look like this,

This Debug folder contains 5 files,

1. cdb.exe
   The Microsoft Console debugger
    
2. crash_action.bat
   This batch file describes the actions which we want to take when a crash is detected (in addition to creating a crash dump)
    
3. crash_text.txt
   A text file which contains some simple text that will pop up in the event of the debugger being activated.
    
4. crashme.exe
   This is a tiny app I wrote whose sole purpose is to cause a memory access violation and crash. This is to test the debugger. 
    
5. enable_dbg.bat
   This script will be called from the WinPE startup script we'll create in the next section. This script ensures the DAgent is set to fully log and also configures the debugger.

Step 3: Adding a startup script to your winPE environment to enable Crash Dump Creation

In order for WinPE to utilise the files we've made available for it on the Deployment share, we need a startup script. This script will live in WinPE's \startup folder.

To add this into PXE environments, you'll need to load up your PXE Configuration Utility and EDIT the WinPE configuration,

This will bring up the "Edit Shared Menu Option" Window. 

If you now click "Edit Boot Image" you'll be taken into Boot Disk Creator. This allows us to delve into the image configuration options. As you can see below we are taken straight into the configuration file tree,

Right-Click the startup folder and from the context menu select New -> Text File 

Call the file enable_debug.bat and enter in the following single line,

%ALTIRIS_SHARE%\Debug\enable_dbg.bat

You should at this point have something that looks like this,

At which point you can click 'Next' to begin the process of rebuilding the WinPE automation environment. Don't forget to "Save" it when it completes on the PXE Configuration Screen.

Step 4: Testing A Crash Scenario

Now we verify that everything has been setup correctly. To do this, the simplest thing is to drop a WinPE "Wait" task on a computer and get it to sit in WinPE.

When WinPE loads and waits, open up the minimised command prompt.  You should see that the startup script we added has moved the current directory into the Debug folder on the Deployment share (the M:\ drive by default),  

To test what happens in a crash, just type crashme.exe in the command window. Things should now get pretty busy...

So here we see our notepad opened letting us know we've had a crash and we've also got in the command window a fair chunk of debug output. The important files are however already safely tucked away in the .\Debug\LOGS folder on the deployment share,

So it's just a case of waiting for a real DAgent crash so you can send those logs up to Symantec Support!