User
Mode Process Dump Specification (Phase 3)
Last Updated: 4/23/00
3. Command Line Process Snapshot
3.2 Dumping Running Process(es)
3.2.2 Single Process/Name Case
4.1 Magic Attention Key Sequence
5.1 Exception Processing Overview
5.4 Overhead in Monitored Processes
6.2 Setup.exe Command-Line Syntax
This document specifies a facility for creating Dr. Watson-compatible user.dmps of running processes without invading/debugging them and without terminating them when debugging is complete. Examples of situations where this is useful include applications whose GUIs have hung — or appear to have hung, but which may or may not be dead; and services that have ground to a halt (such as a socket server that is no longer accepting incoming connections). The ability to create an on-the-fly “snapshot” dump of a process would allow someone to debug the problem off-line. This could be highly desirable in those cases where customers are reluctant to allow access to their machines for live debugs, or where time is at a premium.
The User Mode Process Dump facility described in this document originally grew out of requests to help people deal with STOP 21A bugchecks. A STOP 21A occurs when winlogon.exe or csrss.exe terminates. If winlogon.exe crashes, Dr. Watson may be able to run and capture a user.dmp file which can then be used to debug the problem. However if csrss.exe crashes, Dr. Watson cannot run and there is no user.dmp. The memory.dmp that is generated (if crash dump is enabled) is nearly 100% useless for debugging STOP 21A problems. User Mode Process Dump helps with this case and much more.
Using User Mode Process Dump, dumps can be created in three ways: from the command line; via hot-key; or automatically when exceptions occur in monitored processes. The target for these dumps can be any Win32 process, including csrss.exe, winlogon.exe, services.exe, etc.
For command line dumps, the target processes are not “invaded” and apart from having threads frozen for a short period, are not affected by the dump procedure and keep running after the dumps are complete. Thus the command line facility can be thought of as a process snapshot. Hot-key dumps have similar properties. The association between hot-keys and processes is configurable via a Control Panel applet. The hot-key dump facility remains active even when user-mode components such as the shell, csrss.exe, etc., hang, which means that hot-keys can be used at such times to force key processes into user.dmp files for debugging.
Exception monitoring, for the cost of a small amount of overhead in a process, monitors the process for exceptions and generates dump files when exceptions occur. A set of per-application rules can be defined to govern the conditions under which dumps are automatically generated. Exceptions are accurately seen by the monitoring facility even when inside try/except/finally.
User Mode Process Dump consists of a device driver, a service, a DLL, a Control Panel applet, and a Setup program. The executable comprising the service is also the command line dumper. For command line dumps, only that single exe is required and apart from its presence nothing need be installed on a user’s machine. Use of the hot key and exception monitoring facilities requires an installation procedure.
Table of Contents Ý
Targeted platforms for phase 3 User Mode Process Dump are Windows NT 4.0, Service Pack 3 and later (including QFE variants, all language versions, and Terminal Server) and Windows 2000 golden release. x86 is the only supported platform.
For each binary that is part of User Mode Process Dump, a single, globalized, OS version-independent binary is used. There is not one userdump.sys for Windows NT 4.0 and another one for Windows 2000, etc.
Table of Contents Ý
Any Win32 process may be dumped from the command line via userdump.exe. The ability to take a dump of a process is subject to standard security considerations in that userdump.exe must be able to open a specified target processes and read its address space, or the operation fails. Userdump.exe will attempt to enable debug privilege but will make no other attempts to get around security-related failures.
Invoking userdump with no arguments shows usage:
C:\>userdump
User Mode Process Dumper (Version 3.0)
Copyright (c) 1999 Microsoft Corp. All rights reserved.
userdump –p
Displays a list of running processes
and process IDs.
userdump [-k] <ProcessSpec>
[<TargetDumpFile>]
Dumps one process or processes that
share an image binary file name.
-k optionally causes processes to be
killed after being dumped.
<ProcessSpec> is a decimal or
0x-prefixed hex process ID, or the
base name and extension (no
path) of the image file used to create
a process.
<TargetDumpFile> is a legal
Win32 file specification. If not specified,
dump files are generated in the
current directory using a name
based on the image file name.
userdump –m [-k] <ProcessSpec>
[<ProcessSpec>...] [–d <TargetDumpPath>]
Same as above, except dumps multiple
processes.
-d <TargetDumpPath> supplies
the directory where the dumps will go.
The default is the current
directory.
userdump -g [-k] [-d <TargetDumpPath>]
Similar to above, except dumps Win32
GUI apps that appear hung.
The sections which follow describe the command line arguments in more detail.
Table of Contents Ý
A list of currently running processes and process IDs can be displayed by specifying the -p command line parameter. If -p is specified as the first argument, any other arguments are ignored.
C:\>userdump -p
User Mode Process Dumper (Version 3.0)
Copyright (c) 1999 Microsoft Corp. All rights reserved.
0 System Idle Process
2 System
20 smss.exe
24 csrss.exe
34 WINLOGON.EXE
40 SERVICES.EXE
43 LSASS.EXE
69 SPOOLSS.EXE
92 RPCSS.EXE
96 PSTORES.EXE
124 NDDEAGNT.EXE
207 EXPLORER.EXE
208 systray.exe
200 internat.exe
117 CMD.EXE
119 CMD.EXE
163 userdump.exe
Table of Contents Ý
There are three forms of invocation that can be used to snapshot processes into user.dmp files.
The first form causes all Win32 GUI applications that appear to be hung to be dumped. Userdump determines which apps are hung similarly to the way the Windows NT Task Manager does it. The second form allows a particular process (identified by process ID) or set of processes sharing the same image binary file name to be dumped. The third form allows a set of processes (identified by process IDs or image binary file names) to be dumped. In this case, userdump assumes that the target processes are somehow related and may have interdependencies, and that therefore it is important to capture the dumps of each process as close to simultaneously as possible.
In all cases, a target process, apart from having its threads frozen while it is being read by userdump.exe, is unaffected and continues to run unaltered after the dump is complete, unless –k has been specified. In that case, a target process is terminated once the dump has been taken.
Because no actual exception occurred in a process being dumped, userdump.exe invents one. The exception record in the dump file will indicate a breakpoint exception at the address pointed to by the instruction pointer of the process’ first thread. (No actual breakpoint instruction is inserted in the application being dumped, or in the dump file generated.)
Table of Contents Ý
If –g is specified, Win32 GUI applications which appear hung are dumped.
userdump
-g [-k] [-d <TargetDumpPath>]
The determination as to which apps are hung is made similarly to the way the Windows NT Task Manager makes it. Console (and service) apps and 16 bit apps are not considered in this determination.
In this case, dump files are generated in the current directory unless overridden by specifying –d and a valid, existing directory as the last 2 arguments on the command line.
If one of –g and –m is not specified, then userdump.exe dumps either a single process identified by a process ID, or each process matching the given image binary file name.
userdump [-k] <ProcessSpec>
[<TargetDumpFile>]
If the process argument is a valid decimal or 0x-prefixed hex number, then it is interpreted as a process ID.
C:\>userdump 117 c:\x.dmp
User Mode Process Dumper (Version 3.0)
Copyright (c) 1999 Microsoft Corp. All rights reserved.
Dumping process 117 (CMD.EXE) to
C:\x.dmp...
The process was dumped successfully.
Otherwise the process argument is interpreted as the name of an image binary. The image binary name should be the base name with no path specifiers, i.e., "x.exe." Legal characters for the image name include ASCII characters in the printable range, except these characters: \ / " ? : * < > | and space. Non-printable and extended characters are not supported. A check for legal names is not explicitly done, but attempts to dump processes whose names include illegal, extended, or double-byte characters will fail. If there is more than one instance of the application running, all get dumped; userdump.exe appends the process id to the base part of the dump filename in this case.
C:\>userdump cmd.exe c:\cmd.dmp
User Mode Process Dumper (Version 3.0)
Copyright (c) 1999 Microsoft Corp. All rights reserved.
Dumping process 117 (CMD.EXE) to
C:\cmd117.dmp...
The process was dumped successfully.
Dumping
process 119 (CMD.EXE) to
C:\cmd119.dmp...
The process was dumped successfully.
If a dump file name is not specified, the dump file will be placed in the current directory using a name based on the image binary file name.
C:\foo>userdump 117
User Mode Process Dumper (Version 3.0)
Copyright (c) 1999 Microsoft Corp. All rights reserved.
Dumping process 117 (CMD.EXE) to
C:\foo\cmd.dmp...
The process was dumped successfully.
C:\foo>userdump cmd.exe
User Mode Process Dumper (Version 3.0)
Copyright (c) 1999 Microsoft Corp. All rights reserved.
Dumping process 117 (CMD.EXE) to
C:\foo\cmd117.dmp...
The process was dumped successfully.
Dumping
process 119 (CMD.EXE) to
C:\foo\cmd119.dmp...
The process was dumped successfully.
If –m is specified, then multiple processes are dumped as close to simultaneously as possible. This is useful for a set of related processes, when the dumps obtained need to reflect the interdependent state of the apps at a particular point in time. Userdump will attempt to freeze in parallel the threads in all target processes before it takes any dumps of any of them.
userdump
–m [-k] <ProcessSpec> [<ProcessSpec>...] [–d
<TargetDumpPath>]
If a process spec is a valid decimal or 0x-prefixed number, then it is interpreted as a process ID. Otherwise it is interpreted as the name of an image binary. The image binary name should be the base name with no path specifiers, i.e., "x.exe." Legal characters for the image name include ASCII characters in the printable range, except these characters: \ / " ? : * < > | and space. Non-printable and extended characters are not supported. A check for legal names is not explicitly done, but attempts to dump processes whose names include illegal, extended, or double-byte characters will fail.
Note that any combination of process IDs and image binary file names may be specified. Userdump dumps each single process specified by ID, and all running instances of each process specified by image binary file name.
Dump files are created by default in the current directory, using names that are constructed from the base name of the process’ image binary file, plus the process ID, plus the .dmp extension.
C:\foo>userdump –m 117 explorer.exe
119
User Mode Process Dumper (Version 3.0)
Copyright (c) 1999 Microsoft Corp. All rights reserved.
Dumping process 117 (CMD.EXE) to
C:\foo\cmd117.dmp...
The process was dumped successfully.
Dumping process 207 (EXPLORER.EXE) to
c:\foo\explorer207.dmp...
The process was dumped successfully.
Dumping
process 119 (CMD.EXE) to
C:\foo\cmd119.dmp...
The process was dumped successfully.
The directory where the dumps are placed can be overridden by specifying –d and a valid Win32 path to an existing directory, as the last 2 arguments on the command line.
C:\foo>userdump –m 117 explorer.exe
119 –d c:\bar
User Mode Process Dumper (Version 3.0)
Copyright (c) 1999 Microsoft Corp. All rights reserved.
Dumping process 117 (CMD.EXE) to
C:\bar\cmd117.dmp...
The process was dumped successfully.
Dumping process 207 (EXPLORER.EXE) to
c:\bar\explorer207.dmp...
The process was dumped successfully.
Dumping
process 119 (CMD.EXE) to
C:\bar\cmd119.dmp...
The process was dumped successfully.
Table of Contents Ý
Userdump supports a feature useful for developers whereby an application can cause itself to be dumped, for example in an exception handler block or a top-level unhandled exception filter. Ordinarily, userdump.exe has no knowledge of whether an exception has occurred in a process being dumped, or in which thread an exception occurred. Userdump.exe therefore cannot automatically find the EXCEPTION_POINTERS structure, which would be necessary for it to construct a dump file whose thread contexts reflected the state of the application at exception time.
To get around this, userdump.exe supports a command-line syntax allowing manual specification of the thread which encountered an exception, and the address of the corresponding EXCEPTION_POINTERS structure.
userdump
threadid*exception_pointers_addr dumpfile
threadid — supplies a decimal representation of the unique thread identifier where the exception occurred. This can be retrieved, for example, with the GetCurrentThreadId API.
* — the magic character that causes userdump to recognize that a thread id and EXCEPTION_POINTERS address is being specified. Note that there can be no spaces around the * character; threadid*exception_pointers_addr must be one single argument.
exception_pointers_addr — supplies the address of the EXCEPTION_POINTERS structure for the exception that occurred. See the examples below.
dumpfile — supplies the name of the target dump file to be created, which can be any legal Win32 file specification.
Following is a skeletal example of invoking userdump by a process to
dump itself when an exception occurs in a particular block of code guarded by
structured exception handling.
try {
// execute some code…
} except(MyFilterFunction(GetExceptionInformation())) {
//…
}
DWORD
MyFilterFunction(
IN EXCEPTION_POINTERS
*ExceptionPointers
)
{
WCHAR CommandLine[200];
PROCESS_INFORMATION ProcessInfo;
wsprintf(
CommandLine,
L"userdump %u*%u
c:\\myapp.dmp",
GetCurrentThreadId(),
ExceptionPointers
);
CreateProcess(…,CommandLine,…,&ProcessInfo);
// check for errors, etc.
WaitForSingleObject(ProcessInfo.hProcess,INFINITE);
return(EXCEPTION_EXECUTE_HANDLER); // or whatever
}
Here is another skeletal example, showing invocation of userdump
from an unhandled exception filter.
int
__cdecl
wmain(
int argc,
wchar_t *argv[]
)
{
//…
SetUnhandledExceptionFilter(MyUnhandledExceptionFilter);
//…
}
LONG
MyUnhandledExceptionFilter(
EXCEPTION_POINTERS *ExceptionInfo
)
{
// Invoke userdump here.
// The implementation is similar to
MyFilterFunction,
// above.
}
In both examples, when the dump file is loaded into windbg, the context for the thread which encountered the exception will correctly reflect the point of exception, rather than the point at which CreateProcess was called.
Note that when calling CreateProcess, the developer may wish to specify creation of a DETACHED_PROCESS to avoid creation of an unsightly console window for userdump.exe. This is entirely at the discretion of the developer and has no bearing on the functionality of userdump.exe.
The process exit code for userdump.exe will be 0 for success or non-zero (generally 2) for failure.
Table of Contents Ý
A single keystroke (in the range 0-9 and
A-Z) can be associated with one or more image binaries. When the magic attention sequence is entered at the
keyboard, the keystroke which follows the sequence is examined. If that keystroke
has been associated with one or more image binary filenames and an instance of
one of the images is running, the app is dumped. Apps that are dumped are
unaffected apart from having their threads frozen for a short period, and
continue to run after the dumps have been taken. This behavior can be
overridden somewhat, such that apps that are dumped are then terminated. Also,
configuration can be set such that the system bugchecks after processes have
been dumped. The bugcheck
code is 0x0000CAFF.
Table of Contents Ý
The default magic key sequence is as follows.
· Press SHIFT, CONTROL, and ALT in any order and continue to hold them down.
·
While SHIFT,
CONTROL, and ALT are pressedThen, press and
release in sequence each of the D, U, M, and P keys, in that order.
·
Release SHIFT, CONTROL, and ALT
in any order.
· The next keystroke triggers a dump if configured to do so and an instance of the target application is running.
NOTE: the ability
described below to override the magic key sequence is not
included with the phase 3 release. It will be
included in a future update, currently planned for Q1/2000.
The magic key sequence can be overridden by placing scan codes in the registry. The key HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\udmpdrv\Parameters can contain several REG_BINARY values:
DumpKeyShift: 32
bytes starting with
0x00, followed by 2 bytes, the “make” scan codes
for the left shift and right shift keys. Defaults to 0x00 0x2a 0x36.
Note: the first byte 0x00 is a reserved code which should not
be altered. Same rule applies to the below values too.
DumpKeyControl: 21 bytes, starting with 0x00, followed by 1 byte, the “make” scan code for the control key. Defaults to 0x00 0x1d.
DumpKeyAlt: 21 bytes, starting with 0x00, followed by 1 byte, the “make” scan code for the alt key. Defaults to 0x00 0x38.
DumpKeyDump: 54 bytes, starting with 0x00, followed by 4 bytes, the “make” code for each key to be pressed after shift+control+alt
is down. Defaults to 0x00 0x20 0x16 0x32 0x19 (i.e., D U M P).
Note that there is no provision in Setup or
other UI to allow the user to override the default magic key sequence.
Also note that all of the 8 scan codes
assigned to the above values must be unique.
For example, the values of 0x00, 0x20, 0x16, 0x32, and 0x20 (i.e., D U M D) cannot be
assigned to DumpKeyDump because “D” is repeated.
If the shell, csrss.exe, etc, hang, this sequence continues to function. Thus hot-key process dump is available as long as the underlying Windows NT kernel is running.
Table of Contents Ý
Dump files generated via the hot key mechanism will be placed in the directory specified when the user added the hotkey-app association in the control panel, and be named based on the image binary file name of the application. The extension (usually .exe) is removed from the image file name and replaced with .dmp.[tm1]
Recall that in phase 2, dumps were always placed in %windir% (unless overridden by setting a REG_SZ DumpPath value in HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\udmpsvc\Parameters). In phase 3, for compatibility, if a given hotkey-app association does not explicitly specify a path, then this phase 2 behavior is used. This could be the case, for example, if the user mode process dump binaries installed on the user’s machine are upgraded.
In the case where multiple processes with the same image binary file name are running, the process id is used to create a unique file name based on the image binary file name. For example, cmd.exe could become cmd129.dmp. This prevents dumps from clobbering each other.
In the hot-key process snapshot case the user mode process dump facility is not reacting to an actual exception in the target process. The exception record in generated dump files will indicate a breakpoint exception at the address pointed to by the instruction pointer of a dumped process’ first thread. (Note that no actual breakpoint instruction is inserted into either the process or the dump file.)
Table of Contents Ý
Configuration of the hot-key dump facility consists of the ability to associate keystrokes with one or more applications (represented by base filename + extension). The User Mode Process Dump Control Panel applet contains a property sheet page for this purpose. Only administrators can successfully run this applet and make changes (other users may view but not change settings), and the User Dump service and device driver must both be running.
The first column of the listview control shows the keystroke associated with one or more image binary filenames. The second column shows the image binary filenames. Note that the filename is the base and extension only and contains no path information. There is no provision for individually controlling separate applications that happen to share the same base filename and extension. The third column is the directory where the dump file(s) will be placed.
The fourth column specifies hung apps (“Hang”) and all processes (“All”). “Hang ” refers to all Win32 GUI applications which user mode process dump determines are not responding (similar to the Windows NT Task Manager). “All” refers to all Win32 processes from csrss.exe on up.
The fifth column specifies whether to kill the apps after they are dumped successfully. Finally, the sixth column indicates whether to bugcheck the machine after the apps are dumped successfully.
The New button causes a dialog to appear, which allows the user to select an available keystroke (in the range 0-9 and A-Z) and to select the processes (applications) to associate it with, as well as various options. Image binary names may contain only printable ASCII characters, with the exception of \ / " ? : * < > | and space (the space is the separator for the image binary names). The user may also enter a path, which is the directory where dump files will be placed. The directory must be an existing Win32 path on a local drive, and defaults to %windir%, unless overridden by setting the DumpPath value in the registry (see the previous section). Remote drives will not work.
Two additional checkboxes allow the user to indicate that processes should be killed after being dumped, and that the system should be bugchecked after the processes have been dumped. If the system is to be bugchecked, processes which are dumped are not resumed, so that the state of the machine is disturbed as little as possible between the time the processes are dumped and the time the system bugchecks. The bugcheck code is 0x0000CAFF. Both checkboxes may be checked, indicating that the processes should be terminated before the system is bugchecked. The kill processes checkbox is not available for the “all processes” case.
The edit button brings up the same dialog except the fields are already filled in with the current values from the selected line in the listview.
Reboots are not necessary for changes to take effect.
Table of Contents Ý
Running applications can be monitored for exceptions and dumps automatically generated when certain exceptions occur. The rules that dictate whether an exception triggers a dump are configured per-application via a page in the Process Dump Control Panel applet’s property sheet.
Table of Contents Ý
When an exception occurs in a user mode process, the system deals with it by carrying out the following steps.
1) If the process is being debugged, the kernel offers the exception to the debugger as a first chance exception.
2) If the process is not being debugged or the debugger does not handle the first chance exception, the kernel sets up context for the thread such that when it returns to user mode, it executes the system user mode exception dispatcher.
3) The user mode exception dispatcher searches for a frame-based handler (i.e., the except or finally part of a structured exception handling block).
4) If there is a frame-based handler in the handler chain that handles the exception, processing for the exception is done; control is not returned to the user mode exception dispatcher.
5) If there is no frame-based handler, or no frame-based handler in the chain handled the exception, the user mode exception dispatcher raises the exception again as a second chance exception.
6) If the process is being debugged, the kernel offers the second chance exception to the debugger.
7) If the process is not being debugged or the debugger does not handle the second chance exception, the exception is sent to the process’ exception port.
8) If there is no exception port or the exception port does handle the exception, the thread is terminated.
In practice, Win32 applications that are not being debugged do not make it past step 4 because Win32 protects all Win32 threads with a top-level exception handler to invoke Dr. Watson in the case where the app didn’t handle an exception. If the application is being debugged, the Win32 handler instead returns, to allow progression to step 5 and beyond so the app can be properly debugged.
Interfering with the usual system mechanisms for sending exceptions to the debugger or invoking Dr. Watson or whatever the user has configured as his Just-In-Time debugger (AEDebug in the registry) would be highly undesirable. Thus the function of the Exception Monitoring feature is to provide monitoring for first chance exceptions by getting into the system’s exception handling process between steps 2 and 3 listed above. When an exception is given to the system user mode exception dispatcher, the User Mode Process Dump exception monitoring feature examines the exception to determine if the currently defined rules for the app dictate that the exception should cause a dump to be generated.
Table of Contents Ý
The rules for exception monitoring are
straightforward. There is a default list and a set of per-application lists of
exception codes. A given application can be configured to use either the
default list or its own custom list. When an exception occurs, the relevant
list is checked and a dump is generated if
the exception code appears in the list. If the exception code does not appear
on the list, the standard system exception handling behavior occurs unmodified.
In addition, exceptions generated inside kernel32.dll can be ignored so that,
for example, applications that use IsBadReadPtr and friends will not trigger
spurious dumps. Also,
configuration can be set such that the system bugchecks after process has been
dumped. The bugcheck
code is 0x0000CAFF. (Note: this
capability is not included in phase 3; it will appear in an update release
currently scheduled for Q1/2000.)
Table of Contents Ý
When an exception occurs and the rules dictate that a dump is to be generated, a request to generate the dump is enqueued inside User Mode Process Dump’s internal data structures. The thread where the exception occurred blocks and does not continue to execute until after the request to generate the dump has been serviced and the dump created. While a dump is being generated, all threads in the process are frozen.
Dump files will be placed in the directory specified when the user added the application to the list of processes to be monitored for exceptions, in the control panel, using names based on the filename of the image binary from which a given process was created. The extension (usually .exe) is removed and .dmp is appended. There is no provision for recognition of multiple applications whose image filenames happen to be the same; they will be treated as the same app.
The default target directory is %windir%; this can be overridden by setting a REG_SZ DumpPath value in HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\udmpsvc\Parameters. Such a value is expected to be a fully-qualified Win32 path to a local directory (i.e., C:\foo\bar), which must already exist. Remote directories will not work, even if a drive letter is redirected to a remote sharepoint.
Table of Contents Ý
Exception monitoring works by intercepting process creation and inserting code into the process' copy of the system user mode exception dispatcher (in ntdll.dll) before any code in the process has run. The inserted code lives in a small dll. The user mode process dump device driver creates one section backed by this dll and maps a view of the section into each monitored process.
To any external observer, the space used by this dll in the process will appear to be simply a few pages of committed memory at one "end" of the address space (so as to minimize address space fragmentation issues). The dll does not appear in the process' loaded module list.
A monitored process will also incur overhead of one handle (opened to \Device\userdump).
Table of Contents Ý
Configuration of the exception monitoring facility consists of the ability to associate applications (represented by base filename + extension) with rules. A Process Dump Control Panel applet contains a property sheet page for this purpose. Only administrators can successfully run this applet (other users may view but not change settings), and the User Dump service and device driver must both be running. Reboots are not necessary for the changes to take effect, except that applications that are already running and being monitored will continue to be monitored until closed and restarted.
The first column lists application binary
image filenames. The second column indicates whether the application is being
monitored for exceptions according to the default rules or rules specific to an
app. The third column indicates the directory where dump files will be
generated for the app. The fourth
column indicates whether to bugcheck the
machine after the application is dumped successfully. The fifth column indicates whether to
ignore or monitor exceptions generated inside kernel32.dll.
New applications are added via the New button, which brings up a simple dialog that prompts for the name of a new application binary image filename. Image binary names may contain only printable ASCII characters, with the exception of \ / " ? : * < > | and space.
If the Rules button is clicked, the exception monitoring rules for the highlighted application are displayed and can be modified.
If “Use default rules” is selected, all the controls inside the “Use custom rules” group box are disabled. In this case, monitoring for the application uses the default rules. The user can see or modify the default rules by clicking the “Default Rules” button.
If “Use custom rules” is selected, the user
can select the exceptions that should cause a dump to be generated. Selection
is by way of a multiple-selection listbox. System standard exceptions as well
as any per-application user-defined exceptions are listed (in addition to their
code numbers, system standard exceptions are named, whereas user-defined
exceptions have codes only). “Select All” and “Clear All” are convenience
features that eliminate the need for the user to manually click on every item
in the list box should he want to monitor every exception listed or clear all
entries and start over. The Add button allows the user to add a per-application
user-defined exception code. Make Default causes this set of rules to become
the default rules. All applications that are using the default rules are
implicitly affected. Two additional checkboxes allow the user to
indicate that the system should be
bugchecked after the process has been dumped, and that A
checkbox allows exceptions that occur inside kernel32.dll to be
ignored (this is the default [note: this
capability is not included in phase 3 but will appear in an update in the
future]). The
bugcheck code is 0x0000CAFF. Finally, the path
where dump files should be created for this app can be specified (defaults to
%windir% unless overridden by setting the DumpPath value in the registry (see
previous section).
Table of Contents Ý
User Mode Process Dump is installed or removed with a simple wizard-based installation program, setup.exe. The only question the wizard asks is whether to install or remove User Mode Process Dump. The option to remove is available only if Setup determines that User Mode Process Dump is currently installed. After the user confirms his choice, files are added or removed, and services are installed or removed as appropriate. If the installation case Setup will then offer to bring up the Control Panel applet to allow configuration of User Mode Process Dump. The default configuration is no hotkeys and no monitored processes.
If User Mode Process Dump is already installed on a computer, removing it or reinstalling (ie, upgrading) may require a reboot. Installing on a computer where it is not installed does not require a reboot.
Table of Contents Ý
The user may supply a configuration in the form of a .ini file, which is used when User Mode Process Dump is installed. Any existing configuration is lost if a .ini file is applied.
[HotKeys]
;
; This section lists hotkeys. Each hotkey has its own section, listed here.
; Each section given the associated application(s) (processes=), path for
; dump files (dumpfilepath=), and flags (flags=). Valid values for the flags
; are kill, bugcheck, hung, and all. If hung or all is specified, then any
; processes= line is ignored. If dumpfilepath= is not specified, a default
; of the windows directory is assumed. Note that a section name has a
; limitation of 15 characters and the name comparison with the right hand
; sides in this section is case-sensitive.
;
m = hotkey.m
w = hotkey.w
g = hotkey.g
a = hotkey.a
[hotkey.m]
processes = myapp.exe
dumpfilepath = c:\winnt
flags = kill
[hotkey.w]
processes = winlogon.exe services.exe csrss.exe explorer.exe
dumpfilepath = c:\foobar
flags = bugcheck
[hotkey.g]
dumpfilepath = c:\foobar
flags = hung
[hotkey.a]
flags = all
[ExceptionMonitoring]
;
; This section lists names of apps to monitor for exceptions. The left side
; is the app binary image file name. The right side is the name of a section
; that contains the rules data for the app. The app name * is a special
; required entry that gives the default configuration. If a * line is not
; present then this section is ignored. The section name * means that the
; app should be monitored using the default rules.
;
* = DefaultRules
csrss.exe = *
myapp1.exe = MyRules
myapp2.exe = MyRules
[DefaultRules]
;
; Rules sections list the exception code on the left side and a 1 on the
; right side. The exception code is in hex. Lines with dumpfilepath= and flags=
; are specially recognized as in the hotkey case above. Valid values for flags
; are killkernel32 and
bugcheck. If specified,
kernel32 flag directs that
; exceptions
that
occur inside kernel32.dll should be monitored (by default,
; they
are ignored).
;
c0000005 = 1
c0000037 = 1
dumpfilepath = c:\foobar
flags = killkernel32
[MyRules]
;
; An exception code of * indicates that the default rules section
; should be included. So this example says dump on c0000005,
; c0000037, and 456 exceptions. Note that the flags= is not additive;
; the flags specified here totally replace the flags in the default
; rules. This is of course only relevant if this section has a *= line
; (which includes the default rules section).
;
* = 1
456 = 1
dumpfilepath = c:\myappdump
flags = bugcheck
Table of Contents Ý
Setup [-r] [-f:inifile] [-q | -Q]
-r — Specifies that User Mode Process Dump is to be uninstalled. If this flag is not specified then User Mode Process Dump is installed (or upgraded).
-f — Specifies a configuration ini file. Ignored if –r is specified.
-q — Quiet mode. Installs or removes (based on absence or presence of –r) with no prompts and automatically reboots if necessary. In this case the user does not see the control panel applet (but if specified, configuration from the ini file specified with –f is applied).
-Q — Same as –q except does not reboot.
Table of Contents Ý
All features of user mode process dump can be installed on a server running Windows NT Terminal Services. There are however some subtleties involved with using the features in a Terminal Services environment.
Note that if setup is run from a client session that is not in terminal server installation mode, then the files that comprise the user mode process dump feature will not actually be placed in the server's winnt tree since the winnt tree is virtualized in a Terminal Services environment. In fact it's unlikely that the client could even complete setup successfully in this case, since setup will attempt to create/modify services, which generally requires administrator access to the server.
Table of Contents Ý
Command-line process snapshot (i.e., dumping a process or processes) ignores the fact that in a Terminal Services environment, the list of processes on a machine includes processes in all sessions. Regardless of whether userdump.exe is invoked on the server itself in the console session, or on any established client session:
· Standard security considerations still apply. Userdump requires sufficient privilege to open a process and read its address space. For example attempting to dump csrss.exe of a different session or of the server's console session will fail unless the session has been granted administrator access. This is because debug privilege is required to open csrss.exe, and debug privilege is not available to non-administrators unless the administrator has enabled it for some (strange) reason.
· A list of processes displayed via userdump -p will display all processes in system space on the terminal server, as well as all processes in all sessions running on the server.
· If userdump.exe is given a process name (as opposed to a process id), then processes from any and all sessions are subject to being dumped (if the name of the process matches the argument given to userdump.exe). See sections 3.2.2 and 3.2.3.
One benefit to this model is that an administrator or helpdesk personnel can set at the terminal server or establish a session to the terminal server and get dumps of any user's processes. Remember that command-line dumping requires only userdump.exe (installation is not required).
Note that the hung applications case (userdump -g) works within its session only. This is because the enumeration of Windows applications is based on window enumeration, which is virtualized by the Terminal Services environment. Also, process self-dumping and dumping by process id are unaffected, since process ids are globally unique in the terminal server.
Table of Contents Ý
The dump hot-key sequence is meaningless when invoked on the keyboard of a machine that is not the terminal server. Hot-key dumping is relevant only on the terminal server itself. It is not possible to install user mode process dump from a client session for "private" use within that user's sessions.
When a hot-key sequence is invoked on a server, all matching processes from all sessions (as well as the server's system processes, and console session) are dumped using the same rules as described in section 4.2.
Table of Contents Ý
[Needs more investigation]
Table of Contents Ý
[tm1]We need to define a way to prevent dump files from clobbering each other. For example maybe we need to create a dump directory and then subdirs per app, and then have a maximum number of dumps that are kept around as history. Or maybe we want a way to make the dump filename unique by adding a numeric component. Or something.