Activating a Smart Client
Once the DbgSrv process server has been activated, you can create a smart client on another computer and begin a debugging session.
There are two ways to start a smart client: by starting CDB or WinDbg with the -premote command-line option, or by using the WinDbg graphical interface.
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.
The protocol of the smart client must match the protocol of the process server. The general syntax for starting a smart client depends on the protocol used. The following options exist:
Recommended connection methods, with some additional security
Debugger -premote spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password] [Options]
Debugger -premote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password] [Options]
Debugger -premote ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password] [Options]
Debugger -premote com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password] [Options]
Unsecure connection methods
Debugger -premote npipe:server=Server,pipe=PipeName[,password=Password] [Options]
Debugger -premote tcp:server=Server,port=Socket[,password=Password][,ipversion=6] [Options]
Debugger -premote tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6] [Options]
To use the graphical interface to connect to a process server, 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 Stub menu command. When the Connect to Remote Stub Server 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]
com:port=COMPort,baud=BaudRate,channel=COMChannel[,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]
Alternatively, you can use the Browse button to locate active process servers.
Parameters
The parameters in the preceding commands have the following possible values:
Debugger
This can be CDB or WinDbg.
Server
This is the network name or IP address of the computer on which the process 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 process 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 smart client by using the -premote 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 process server was created.
clicon
Specifies that the process server will try to connect to the smart client through a reverse connection. The client must use clicon if and only if the server is using clicon. In most cases, the smart client is started before the process 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 process server was created.
channel= COMChannel
If COM protocol is used, COMChannel should match the channel number chosen when the process server was created.
proto= Protocol
If SSL or SPIPE protocol is used, Protocol should match the secure protocol used when the process 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 process server was created.
password= Password
If a password was used when the process server was created, Password must be supplied in order to create the smart client. It must match the original password. Passwords are case-sensitive. If the wrong password is supplied, the error message will specify "Error 0x80004005."
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.
Options
Any additional command-line parameters can be placed here. See Command-Line Options for a full list. If you are using CDB, this must specify the process you wish to debug. If you are using WinDbg, you can specify the process on the command line or through the graphical interface.
Since the process server simply acts as a gateway for the smart client, the additional Options will be the same as those you would use if you were starting a user-mode debugger on the same machine as the target application.
If you are using the -premote option with .attach (Attach to Process) or .create (Create Process), the parameters are the same as those listed above.
Troubleshooting
If you see this message: The client is not using same version of remoting protocol as the server this indicates that the version of DbgSrv that you are attempting to connect to is using a different protocol version than the version of WinDbg.
It is uncommon that protocol changes are made. When this does happen, be sure you are using the matching versions of the latest available version of DbgSrv and WinDbg (Classic) or WinDbg. For information on downloading the latest version, see Debugging Tools for Windows.