View source for Microsoft KB Archive/151981

<div id="nsbanner">

<div id="bannerrow1">

{|
| Knowledge Base
|
|}


</div>
<div id="TitleRow">

= <span id="KB151981"></span>How to set up a remote debug session using a null modem cable =


</div>

</div>
<div id="nstext" valign="BOTTOM">

Article ID: 151981

Article Last Modified on 12/3/2007


-----

APPLIES TO<br />
<br />

* Microsoft Windows Server 2003, Standard Edition (32-bit x86)
* Microsoft Windows Server 2003, Enterprise Edition (32-bit x86)
* Microsoft Windows Server 2003, Datacenter Edition (32-bit x86)
* Microsoft Windows 2000 Server
* Microsoft Windows 2000 Advanced Server
* Microsoft Windows 2000 Professional Edition
* Microsoft Windows 2000 Datacenter Server
* Microsoft Windows NT Workstation 3.5
* Microsoft Windows NT Workstation 3.51
* Microsoft Windows NT Workstation 4.0 Developer Edition
* Microsoft Windows NT Server 3.5
* Microsoft Windows NT Server 3.51
* Microsoft Windows NT Server 4.0 Standard Edition
* Microsoft Windows Small Business Server 2003 Premium Edition
* Microsoft Windows Small Business Server 2003 Standard Edition


-----

<div class="notice_section">

This article was previously published under Q151981

</div>
<div class="summary_section">

== SUMMARY ==

This article describes how to set up the debugger on a Windows-based computer by using a null modem cable that is attached to another Windows-based computer.

</div>
<div class="moreinformation_section">

== MORE INFORMATION ==

This section includes the following topics:
* Determine the need for the kernel debugger
* About remote debugging
* Use a null modem cable
* Change the attributes on the Boot.ini file
* Debugger options
* Configure the debugger for the computer
* Set up the null modem cable
* Configure the host computer for a Remote.exe session

=== Determine the Need for the Kernel Debugger ===

The kernel debugger that comes with Windows provides information about the computer that is typically not available without the aid of the debugger. Windows can turn on the kernel debugger from the Windows Start-Up menu (Boot.ini). When you turn on the kernel debugger, Windows debugger can output debugging information to a remote debugger for a remote user to analyze. This is typically done at the request of a Microsoft support professional for analyzing a fatal error in Windows that cannot be diagnosed from the Memory.dmp file or when a Memory.dmp file is not produced.
=== About Remote Debugging ===

For our discussion the target computer is the computer that is being debugged and the host computer is the computer doing the debugging. The process of remote debugging occurs when two computers are connected by the serial communication ports. The target computer and the host computer are running the Windows kernel debuggers, which communicate using a special debug API and protocol. To download the Debugging Tools for Windows, visit the following Microsoft Web site:
<div class="indent">

http://www.microsoft.com/whdc/devtools/debugging/default.mspx


</div>
=== Use a Null Modem Cable ===

If you connect the null modem cable to a serial port, the debugger can run at its current top speed of 19200, compared to the speed of 9600 over a modem. This configuration is generally considered more reliable than using a modem for the following reasons:
* This configuration does not involve configuring a modem.
* There is no chance of a modem or line failure.
* You can debug a computer locally.
* This configuration provides faster debugging.

The most common method is to set up a target computer for debugging and the host computer for doing the debugging by using a Remote.exe session. This configuration permits a technical support professional to connect to the Remote.exe session by means of a remote access connection and debug the target computer without physically being present at the target computer.
=== Change the Attributes on the Boot.ini File ===

To set up the target computer, edit Boot.ini in the boot partition, and then add the appropriate debugger options. Use a standard ASCII text editor. The Boot.ini file is hidden in the boot partition directory. The Boot.ini file attributes are hidden, read-only and system. Before you can edit the Boot.ini file, you must change these attributes.<br />
<br />
To change the attributes of the Boot.ini file, at the command prompt type <span class="kbd userinput"> attrib -h -r -s c:\boot.ini</span>, and then press Enter. Use Notepad or another text editor to edit the Boot.ini file.<br />
<br />
After you edit the file, type <span class="kbd userinput"> attrib +h +r +s c:\boot.ini</span> at the command prompt, and then press ENTER to restore the read-only, hidden, and system file attributes. Alternatively, you can use File Manager instead of a command prompt to change the file attributes. To do so:
<ol>
<li>In File Manager, click '''By File Type''' on the '''View''' menu.</li>
<li>Click '''Show Hidden/System Files''', and then click '''OK'''.</li>
<li>Click '''Boot.ini''', and then click '''Properties''' on the '''File''' menu.</li>
<li>Click to clear the following check boxes, and then click '''OK''':
<ul>
<li>Read Only</li>
<li>Hidden</li>
<li>System</li></ul>

<br />
</li></ol>

=== Debugger Options ===

After you open the Boot.ini file on the target computer for editing, you can add any of the following options to configure the debugger environment on the target computer:
* '''/debug''': Use this option to turn on the kernel debugger.
* '''/debugport''': Use this option to specify the serial port used by the kernel debugger. If no serial port is specified, the debugger always uses COM2.
* '''/crashdebug''': Use this option to send debug information only when a fatal system error (FSE) occurs.
* '''/baudrate''': Use this option to set the Baud rate that the kernel debugger uses. The default baud rate is 19200. A baud of 9600 is the typical rate for remote debugging over a modem.

=== Configure the Debugger for the Computer ===

There are several options available for configuring the debugger on the target computer. To add any one of the previous options to the Boot.ini file, use the following example.<br />
<br />
The following text is a typical Boot.ini. Each entry in the [operating systems] section corresponds to the options that are listed in the boot menu during a typical system startup.
<pre class="fixed_text">[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT" Version 3.5"
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT" Version 3.5 [VGA
mode]" /BASEVIDEO
C:\="MS-DOS"
                </pre>
To turn on the debugger use COM1 to perform the following procedure:
# Select the startup option that you typically use and add the '''/debug''' switch at the end of the line.
# To specify the communications port, add the '''/debugport=com1''' switch.

<pre class="fixed_text">[boot loader]
timeout=30
default=multi(0)disk(0)rdisk(0)partition(1)\WINDOWS
[operating systems]
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT" Version 3.5"
/debug /debugport=com1
multi(0)disk(0)rdisk(0)partition(1)\WINDOWS="Windows NT" Version 3.5 [VGA
mode]" /BASEVIDEO
C:\="MS-DOS"
                </pre>
=== Set Up the Null Modem Cable ===

A null modem cable is a serial cable that has been configured to allow data to be sent between two serial ports. Typically, you connect a serial port to a serial device. In this case, you must configure the target computer to accept a serial-port-to-serial-port connection. It is important that you use a null modem cable because if you use a typical serial cable the target computer expects a serial device, not another serial port, and you cannot debug the computer.<br />
<br />
When you use a null modem to make a direct serial connection between two computers, your cable must be wired as shown in the following tables.
<pre class="fixed_text">9-Pin NULL Modem Cabling

Remote host
serial port connector Host system
serial port connector

Signal
3  2  Transmit Data
2  3  Receive Data
7  8  Request to Send
8  7  Clear to Send
6, 1  4  Data Set Ready and Carrier Detect
5  5  Signal Ground
4  6, 1  Data Terminal Ready

25-Pin NULL Modem Cabling

2  3  Transmit Data
3  2  Receive Data
4  5  Request to Send
5  4  Clear to Send
6  20  Data Set Ready and Carrier Detect
7  7  Signal Ground
20  6  Data Terminal Ready


                </pre>
=== Configure the Host Computer for a Remote.exe Session ===

In this scenario, the host computer is being set up to do a debug of the target computer as if there were a technical support professional sitting at the host computer. Remote.exe runs to permit this debug session to be accessed remotely through a remote access connection.<br />
<br />
Remote.exe is a command-line utility that you can use to run command-line programs on remote computers. Remote.exe uses two parts, the server component and the client component. To use Remote.exe, you must first start the server end on the computer that you are debugging from. When you do so, other users can connect to your debugging session by using the client portion of Remote.exe. Remote.exe comes with the Resource Kit. For more details and the command syntax of this utility, see the Resource Kit online help.<br />
<br />
The Windows installation CD and the Windows Resource Kit CD is available to achieve this setup.
<ol>
<li>Set up a remote access account on the network for the technical support professional. This information, including the name of the host computer, must be documented and ready to give to the support professional.</li>
<li>The host computer must be configured as described in the following Microsoft Knowledge Base article. This article describes in detail how to set up the symbols on the host computer to debug the target computer. For additional information, click the article number below to view the article in the Microsoft Knowledge Base:
<div class="indent">

<p>[[../148659|148659]] How to Set Up Windows NT Debug Symbols</p>

</div></li>
<li>Microsoft recommends the best way to run I386KD is to copy all the files that are located in the Support\Debug\I386\ folder (assuming that you are debugging an I386 computer) to a folder on the hard disk, and change to that folder.</li>
<li>Copy Remote.exe from the Resource Kit to the same folder.</li>
<li>The I386KD relies on environment variables for information it needs to run successfully. I386KD uses many environment variables. In this scenario, the minimal I386KD must have is the _NT_SYMBOL_PATH and the _NT_DEBUG_PORT variable. Use the '''set''' command to set the environment variables. The _NT_SYMBOL_PATH variable points to the path of the symbols file that the debugger uses for the debug session. The _NT_DEBUG_PORT variable points to the active serial port being used on the host computer for debugging. If this serial port is not serial port 2, the _NT_DEBUG_PORT environment variable must be used.<br />
<br />
Example:<br />
The host computer null modem cable connects to serial port 1, and then copies the symbols to the C:\Debug\Symbols folder. At a command prompt, type the following command:
<div class="indent">

<p><span class="kbd userinput"> set _nt_debug_port=com1<br />
set _nt_symbol_path=c:\debug\symbols<br />
set _nt_debug_log_file_append=c:\temp\debug.log</span></p>

</div></li>
<li>Make sure that the debugging tools were step up correctly. To do this, follow these steps:
<ol style="list-style-type: lower-alpha;">
<li>Click '''Start''', click '''Run''', in the '''Open''' box, type <span class="kbd userinput"> Cmd</span>, and then click '''OK'''.</li>
<li>Change directory to the path location where you copied the files in step 3 of this procedure.</li>
<li>Type <span class="kbd userinput"> i386kd -v</span>, and then press '''Enter'''.</li>
<li>Press '''Ctrl'''-'''C''' to break into the Target. You will receive a '''kd''' prompt and the Target system will stop responding (hang) because you have broken into it with the debugger.</li>
<li>Type <span class="kbd userinput"> !process</span> at the '''kd''' prompt, and then press '''Enter'''. The system returns a list of processes. This lets you know that the debugger is working correctly.</li>
<li>Type <span class="kbd userinput"> g</span>, and then press '''Enter''' to tell the Target to Go. This will allow the Target to resume normal operation.</li>
<li>Type <span class="kbd userinput"> exit</span> and press <span class="kbd userinput"> Enter</span> to close the command window.</li></ol>
</li>
<li>Start the debug session, and then remote the session out. At a command prompt type the following:
<div class="indent">

<p><span class="kbd userinput"> remote /s "i386kd -v" debug</span></p>

</div></li></ol>

=== Additional Information Resources ===

* Windows Resource Kit
* The Driver Development Kit Online help
* To view the Kernel-Debug How-To series of articles search on the keyword "debugref" in the Microsoft Knowledge Base.


</div>
<br />

Additional query words: 3.50 3.51 prodnt debugref

Keywords: KB151981

<div class="footer">

<br />


-----

[mailto:TECHNET@MICROSOFT.COM Send feedback to Microsoft]

<span>© Microsoft Corporation. All rights reserved.</span>


</div>

</div>