Getting Trace from NETCFG.DLL

Getting Trace from NETCFG.DLL - 2

Stephan Wolf
Microsoft MVP – Windows Driver Development Kit (DDK)
System Software Development, Germany

March 17, 2006

Abstract

This paper describes how you can enable debug trace messages in the network configuration subsystem of the Microsoft® Windows® family of operating systems listed below.

This information applies for the following operating systems:
Microsoft Windows Server 2003
Microsoft Windows XP
Microsoft Windows 2000

Updated information on this whitepaper is maintained on the Web at
http://www.ndis.com/papers/

Contents

Introduction 2

Follow these steps to see Windows Network Configuration trace messages 2

Step 1: Install a Debugger or a Debug Output Tool 2

Step 2: Copy the CHECKED Version of "netcfgx.dll" to Your System 2

Replacing a System File Regardless of Windows File Protection 2

Step 3: Configure Netcfg Trace Options 3

Changing Netcfg Parameters Requires a Reboot 4

Resources 4

Windows Hardware Engineering Conference - WinHEC Sponsors’ Disclaimer: The contents of this document have not been authored or confirmed by Microsoft or the WinHEC conference co-sponsors (hereinafter “WinHEC Sponsors”). Accordingly, the information contained in this document does not necessarily represent the views of the WinHEC Sponsors and the WinHEC Sponsors cannot make any representation concerning its accuracy. THE WinHEC SPONSORS MAKE NO WARRANTIES, EXPRESS OR IMPLIED, WITH RESPECT TO THIS INFORMATION.

Microsoft, Windows, Windows NT, Windows Server, and Windows Vista are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries. The names of actual companies and products mentioned herein may be the trademarks of their respective owners.

Introduction

It is sometimes hard to analyze problems related to the installation and configuration of network drivers, protocols, and services. So it would be good if Windows could give us some hints on what is going on during network configuration.

And yes, you can actually configure the network configuration subsystem (netcfg) to generate verbose trace messages that will help you understand such problems.

What you need is the checked version of "netcfgx.dll", a "netcfg.ini" file, and a debugger or some other tool that allows for viewing and recording of debug session output.

Note: None of the information in this document is guaranteed to work in future versions of Windows (there is a good chance this will be the case for Vista and Longhorn).

Follow these steps to see Windows Network Configuration trace messages

Step 1: Install a Debugger or a Debug Output Tool

Netcfg by default outputs its trace messages to the debugger console. Thus, you need to use either a debugger or a tool that can make debug output visible.

See Debugging Tools for Windows - Overview or download and run e.g. the DebugView tool by SysInternals.

Step 2: Copy the CHECKED Version of "netcfgx.dll" to Your System

In order to see netcfg trace messages, you need to run the checked version of "netcfgx.dll". If you have installed a checked version of Windows, you are already done with that.

Otherwise, if you are running a retail/free version of Windows, you need to manually copy the checked version of "netcfgx.dll" to your system first.

You can copy the checked "netcfgx.dll" from the "Windows checked" installation CD. Make sure you copy the file from the correct Windows version or service pack.

If you have a service pack installed on your system, you can get the "netcfgx.dll" file by manually starting the service pack (SP) installation executable, which will extract all files from the SP into a temporary directory. You can now manually copy the file out of this temporary directory. If you have already installed the service pack earlier, you can then cancel installation of the SP when prompted.

For more information on checked builds, see Using Checked Builds of Windows and Build Environment for Windows Device Drivers.

Replacing a System File Regardless of Windows File Protection

But Windows won't let you replace any system file due to the Windows File Protection (WFP) feature. Reboot your system and press <F8> at the Windows boot screen and select safe mode in order to disable WFP.

Now that you booted the system in safe mode, go to the "%SystemRoot%\system32" directory, where "%SystemRoot%" is the environment variable that holds the path to the Windows directory.

Next, rename the original version of "netcfgx.dll" to some other name, e.g. "netcfgx.org". Note that you usually cannot delete the original file (because it is in use by the system). Now copy the checked "netcfgx.dll" file from your checked Windows CD or service pack. If the file is compressed, use the command "expand -r netcfgx.dl_" to get the unpacked "netcfgx.dll" file.

Finally reboot the system as usual (i.e. no safe mode required). Note that Windows will now keep and use the checked version of "netcfgx.dll". If you want to revert to the original "netcfgx.dll", simply rename the current file. WFP will then automatically restore the original.

As an alternative to booting in safe mode, see Disabling Windows File Protection, which requires you to have a debugger connected.

Step 3: Configure Netcfg Trace Options

Now that you have copied the checked "netcfgx.dll" to your "%SystemRoot%\system32" directory, it will read trace option settings from file "%SystemRoot%\netcfg.ini". Simply create this file as follows:

; netcfg.ini - place in %SystemRoot% directory
; The debug flags section enables or disables
; individual debug flags that control various things
; like the debug output format.
;
; Set to a non-zero value (e.g. "1") to enable an
; individual debug flag, otherwise set to zero to
; disable it.
[DebugFlags]
;Breaks into the debugger if an error is detected.
BreakOnError=0
;Breaks into the debugger when the net class installer
;gets called.
BreakOnNetInstall=0
;Output all traces, even on success.
ExtremeTracing=0
;Do not show error text, only error codes.
NoErrorText=0
;Displays errors that would otherwise be ignored.
ShowIgnoredErrors=0
;Displays process and thread id.
ShowProcessAndThreadId=0
;Add time stamps to tracing output.
TracingTimeStamps=0
;(XP+) Dump the call stack for all errors.
TraceCallStackOnError=0
;(XP+) Trace Function names & params for every call.
TraceFileFunc=0
;(XP+) Track object leaks.
TrackObjectLeaks=0
; The "OutputToDebug" parameter in the "default"
; section enables or disables all trace tags.
[Default]
OutputToDebug=1
; The "bind" trace tag is special in that it gets only
; enabled when explicitly specified. That is, "bind" is
; disabled by default.
; Also, "bind" is only in effect if used together with
; "TraceFileFunc=1".
; This will produce tons of messages, so use with care.
[Bind]
OutputToDebug=1

Depending on the setting of the various options, you will either get little output or tons of trace messages. Note that the latter can possibly do more harm than good because trace output can be enormous.

Changing Netcfg Parameters Requires a Reboot

If you make changes to the netcfg trace option file "netcfg.ini" in the "%SystemRoot%" directory, these changes will not immediately take effect because the options are only read once when "netcfgx.dll" gets loaded.

Thus, you should reboot the machine in order to force a reload of "netcfgx.dll" before any changes to "netcfg.ini" will take effect.

Resources

· MVP Insights: Advice and Technical Articles
http://www.microsoft.com/whdc/resources/MVP/insights.mspx

· Debugging Tools for Windows – Overview
http://www.microsoft.com/whdc/devtools/debugging/

· DebugView tool by SysInternals
http://www.sysinternals.com/Utilities/DebugView.html

· Using Checked Builds of Windows
http://www.microsoft.com/whdc/DevTools/tools/chkblds.mspx

· Build Environment for Windows Device Drivers
http://www.microsoft.com/whdc/DevTools/tools/BuildEnv.mspx

· Disabling Windows File Protection
http://www.microsoft.com/whdc/winlogo/drvsign/wfp.mspx#EMAAC

WinHEC 2006