Activating a Debugging Client
Once the debugging server has been activated, you can start a debugging client on another computer and connect to the debugging session.
There are two ways to start a debugging client: by using the -remote command-line option, or by using the WinDbg graphical interface.
The protocol of the client must match the protocol of the server. The general syntax for starting a debugging client depends on the protocol used. The following options exist:
Recommended connection methods, with some additional security
Debugger -remote spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
Debugger -remote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
Debugger -remote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
Unsecure connection methods
Debugger -remote npipe:server=Server,pipe=PipeName[,password=Password]
Debugger -remote tcp:server=Server,port=Socket[,password=Password][,ipversion=6]
Debugger -remote tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]
Debugger -remote com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
To use the graphical interface to connect to a remote debugging session, WinDbg must be in dormant mode -- it must either have been started with no command-line parameters, or it must have ended the previous debugging session. Select the File | Connect to Remote Session menu command, or press the CTRL+R shortcut key. When the Connect to Remote Debugger Session dialog box appears, enter one of the following strings into the Connection string text box:
Recommended connection methods, with some additional security
spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]
ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]
Unsecure connection methods
npipe:server=Server,pipe=PipeName[,password=Password]
tcp:server=Server,port=Socket[,password=Password][,ipversion=6]
tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]
com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]
Alternatively, you can use the Browse button to locate active debugging servers.
Important
There are important security considerations when using remote debugging. For more information, including information on enabling secure mode, see Security During Remote Debugging and Security Considerations for Windows Debugging Tools.
Parameters
The parameters in the preceding commands have the following possible values:
Debugger
This does not have to be the same debugger as the one used by the debugging client -- WinDbg, KD, and CDB are all interchangeable for purposes of remote debugging through the debugger.
Server
This is the network name or IP address of the computer on which the debugging server was created. The two initial backslashes (\) are optional on the command line, but are not permitted in the WinDbg dialog box.
pipe= PipeName
If NPIPE or SPIPE protocol is used, PipeName is the name that was given to the pipe when the server was created.
If you are not logged on to the client computer with an account that has access to the server computer, you must provide a user name and password. On the client computer, in a Command Prompt window, enter the following command.
net use \\Server\ipc$ /user:UserName
where Server is the name of the server computer, and UserName is the name of an account that has access to the server computer.
When you are prompted, enter the password for UserName.
After this command succeeds, you can activate a debugging client by using the -remote command-line option or by using the WinDbg graphical interface.
Note You might need to enable file and printer sharing on the server computer. In Control Panel, navigate to Network and Internet > Network and Sharing Center> Advanced sharing settings. Select Turn on file and printer sharing.
port= Socket
If TCP or SSL protocol is used, Socket is the same socket port number that was used when the server was created.
clicon
Specifies that the debugging server will try to connect to the client through a reverse connection. The client must use clicon if and only if the server is using clicon. In most cases, the debugging client is started before the debugging server when a reverse connection is used.
port= COMPort
If COM protocol is used, COMPort specifies the COM port to be used. The prefix "COM" is optional -- for example, both "com2" and "2" are acceptable.
baud= BaudRate
If COM protocol is used, BaudRate should match the baud rate chosen when the server was created.
channel= COMChannel
If COM protocol is used, COMChannel should match the channel number chosen when the server was created.
proto= Protocol
If SSL or SPIPE protocol is used, Protocol should match the secure protocol used when the server was created.
Cert
If SSL or SPIPE protocol is used, you should use the identical certuser=Cert or machuser= Cert parameter that was used when the server was created.
password= Password
If a password was used when the server was created, Password must be supplied in order to create the debugging client. It must match the original password. Passwords are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005." Passwords must be twelve characters or less in length.
ipversion=6
(Debugging Tools for Windows 6.6.07 and earlier only) Forces the debugger to use IP version 6 rather than version 4 when using TCP to connect to the Internet. In Windows Vista and later versions, the debugger attempts to auto-default to IP version 6, making this option unnecessary.
Command-line options used to start new debugging sessions (like -p) cannot be used by the debugging client, but only by the server. Configuration options (like -n) will work from either the client or the server.