Getting Trace from NETCFG.DLL
Stephan Wolf
Microsoft MVP – Windows Driver Development Kit (DDK)
System Software Development,
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
Follow these steps to see Windows Network
Configuration trace messages
Step 1:
Install a Debugger or a Debug Output Tool
Step 2: Copy
the CHECKED Version of "netcfgx.dll" to Your System
Replacing a System File Regardless of Windows
File Protection
Step 3:
Configure Netcfg Trace Options
Changing Netcfg Parameters Requires a Reboot
Author's Disclaimer and Copyright: Copyright © 2006 by Stephan Wolf. All rights reserved
Microsoft, Windows, Windows NT, Windows Server, and
Windows Vista are either registered trademarks or trademarks of Microsoft
Corporation in the
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
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.
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.
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.
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.
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.
·
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