Activating a Smart Client (Kernel Mode)

Once the KD connection 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 KD or WinDbg with the kernel protocol kdsrv, or by using the WinDbg graphical interface.

You need to specify the remote transfer protocol used by the KD connection server. You can also specify the protocol for the actual kernel connection between the KD connection server and the target computer, or you can use the default.

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 general syntax for starting a smart client depends on the protocol used. The following options exist:

Recommended connection methods, with some additional security

Debugger -k kdsrv:server=@{spipe:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,pipe=PipeName[,password=Password]},trans=@{ConnectType} [Options]

Debugger -k kdsrv:server=@{ssl:proto=Protocol,{certuser=Cert|machuser=Cert},server=Server,port=Socket[,password=Password]},trans=@{ConnectType} [Options]

Debugger -k kdsrv:server=@{ssl:proto=Protocol,{certuser=Cert|machuser=Cert},clicon=Server,port=Socket[,password=Password]},trans=@{ConnectType} [Options]

Debugger -k kdsrv:server=@{com:port=COMPort,baud=BaudRate,channel=COMChannel[,password=Password]},trans=@{ConnectType} [Options]

Unsecure connection methods

Debugger -k kdsrv:server=@{npipe:server=Server,pipe=PipeName[,password=Password]},trans=@{ConnectType} [Options]

Debugger -k kdsrv:server=@{tcp:server=Server,port=Socket[,password=Password][,ipversion=6]},trans=@{ConnectType} [Options]

Debugger -k kdsrv:server=@{tcp:clicon=Server,port=Socket[,password=Password][,ipversion=6]},trans=@{ConnectType} [Options]

To use the graphical interface to connect to a KD connection 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 KD connection servers.

The parameters in the preceding commands have the following possible values:

Debugger
This can be KD or WinDbg.

Server
This is the network name or IP address of the computer on which the KD connection 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 KD connection 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 -k kdsrv or by using the WinDbg graphical interface.

port= Socket
If TCP or SSL protocol is used, Socket is the same socket port number that was used when the KD connection server was created.

clicon
Specifies that the KD connection 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 KD connection 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 KD connection server was created.

channel= COMChannel
If COM protocol is used, COMChannel should match the channel number chosen when the KD connection server was created.

proto= Protocol
If SSL or SPIPE protocol is used, Protocol should match the secure protocol used when the KD connection 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 KD connection server was created.

password= Password
If a password was used when the KD connection 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.

trans=@{ ConnectType }
Tells the debugger how to connect to the target. The following kernel connection protocols are permitted:

com:port=ComPort,baud=BaudRate 
usb2:targetname=String 
com:pipe,port=\\VMHost\pipe\PipeName[,resets=0][,reconnect]
com:modem 

For information about these protocols, see Getting Set Up for Debugging. You can omit any of the parameters for these protocols -- for example, you can say trans=@{com:} -- and the debugger will default to the values specified by the environment variables on the computer where KdSrv is running.

Options
Any additional command-line parameters can be placed here. See Command-Line Options for a full list.

Since the KD connection 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 kernel debugger on computer where KdSrv is running. The exception to this is any option that specifies a path or filename will be taken as a path on the computer where the smart client is running.