手动设置 KDNET 网络内核调试

项目
03/08/2024

Windows 调试工具支持通过网络进行内核调试。本文介绍如何手动设置网络调试。

重要

手动设置网络调试是一个复杂且容易出错的过程。要自动设置网络调试，请参阅自动设置 KDNET 网络内核调试。强烈建议对所有调试器用户使用 KDNET 实用工具。

运行调试器的计算机称为主计算机，正在调试的计算机称为目标计算机。主机必须运行 Windows 7 或更高版本，并且目标计算机必须运行 Windows 8 或更高版本。

相对于其他类型的连接进行调试，通过网络进行调试具有以下优势。

主机和目标计算机可以位于本地网络上的任意位置。
从一台主机调试多个目标计算机很容易。
假设有任意两台计算机，可能它们都有以太网适配器。它们都具有串行端口或 1394 端口的可能性较小。
网络调试比串行端口调试更快。

支持的网络适配器

主机可以使用任何网络适配器，但目标计算机必须使用 Windows 调试工具支持的网络适配器。有关支持的网络适配器列表，请参阅 Windows 10 中的网络内核调试支持的以太网 NIC 以及 Windows 8.1 中的网络内核调试支持的以太网 NIC。

安装 Windows 调试工具

确认主机系统上已安装适用于 Windows 的调试工具。有关下载和安装调试器工具的信息，请参阅适用于 Windows 的调试工具。

确定主机的 IP 地址。

使用以下过程之一来确定主机的 IP 地址。

在主机上打开命令提示符，输入以下命令：
```
ipconfig
```
记下打算用于调试的网络适配器的 IPv4 地址。
在目标计算机上，打开命令提示符并输入以下命令，其中 YourIPAddress 是主机的 IP 地址：
```
ping -4 <YourIPAddress>
```

选择用于网络调试的端口

选择用于在主机和目标计算机上调试的端口号。可以选择从 49152 到 65535 的任意数字。建议的范围为 50000 - 50039。选择的端口由在主机上运行的调试器打开以独占访问权限。请注意选择主机上运行的任何其他应用程序不使用的端口号。

注意

可用于网络调试的端口号范围可能受公司网络策略的限制。无法从主机中判断限制内容。要确定公司的策略是否限制了可用于网络调试的端口范围，请咨询网络管理员。

如果将多台目标计算机连接到单个主机，则每个连接必须具有唯一的端口号。例如，如果将 100 台目标计算机连接到单个主机，则可以将端口 50000 分配给第一个连接，将端口 50001 分配给第二个连接，依此类推。

注意

另一台主机可以使用相同范围的端口（50000 到 50099）连接到其他 100 台目标计算机。

设置目标计算机

验证目标计算机是否具有受支持的网络适配器。有关详细信息，请参阅：
- Windows 8.1 中的网络内核调试支持的以太网 NIC
- Windows 10 中的网络内核调试支持的以太网 NIC
使用适当的网络电缆将支持的适配器连接到网络中心或交换机。

重要

在使用 BCDEdit 更改启动信息之前，可能需要在测试电脑上暂时挂起 Windows 安全功能，例如 BitLocker 和安全启动。测试完成后重新启用这些安全功能，并在禁用安全功能时适当地管理测试电脑。

在提升的命令提示符中，输入以下命令，其中 w.x.y.z 是主机的 IP 地址，n 是所选端口号：
```
bcdedit /debug on

bcdedit /dbgsettings net hostip:w.x.y.z port:n
```
BCDEdit 显示自动生成的密钥。复制密钥并将其存储在可移动存储设备上，例如 U 盘。在主机上启动调试会话时，需要密钥。
使用设备管理器确定要用于调试的适配器的 PCI 总线、设备和函数编号。这些值显示在“常规”选项卡上的“位置”下的设备管理器中。然后在提升的命令提示符中，输入以下命令，其中 b、d 和 f 是适配器的总线编号、设备编号和函数编号：
```
bcdedit /set "{dbgsettings}" busparams b.d.f
```
附加内核调试器后，将重新启动目标电脑。

注意

如果打算在目标计算机上安装 Hyper-V 角色，请参阅设置虚拟机主机的网络调试。

注意如果目标计算机位于扩展坞中，并且已为作为扩展坞一部分的网络适配器启用网络调试，请不要从扩展坞中删除计算机。如果需要从扩展坞中删除目标计算机，请先禁用内核调试。要在目标计算机上禁用内核调试，请以管理员身份打开命令提示符并输入命令 bcdedit /debug off。重新启动目标计算机。

启动调试会话

确认主机的网络适配器使用合适的网络电缆连接到网络中心或交换机。

在主计算机上打开 WinDbg。在“文件”菜单上，选择“内核调试”。在“内核调试”对话框中，打开“Net”选项卡。输入端口号和密钥。选择“确定”。

还可以通过打开命令提示符并输入以下命令来启动与 WinDbg 的会话，其中 n 是端口号，MyKey 是 BCDEdit 在设置目标计算机时自动生成的密钥：

windbg -k net:port=<n>,key=<MyKey>

如果系统提示允许 WinDbg 通过防火墙访问端口，则允许 WinDbg 访问所有三种不同网络类型的端口。

使用 KD

在主机上，打开命令提示符。输入以下命令，其中 n 是端口号，MyKey 是 BCDEdit 在设置目标计算机时自动生成的密钥：

kd -k net:port=<n>,key=<MyKey>

如果系统提示允许 WinDbg 通过防火墙访问端口，则允许 WinDbg 访问所有三种不同网络类型的端口。

重启目标电脑

调试器连接并等待连接后，重新启动目标计算机。重启电脑的一种方法是从管理员的命令提示符处使用此命令：

shutdown -r -t 0

重新启动目标计算机后，主机操作系统中的调试器应连接。

连接到主机上的目标后，在调试器上命中中断，可以开始调试。

允许调试器通过防火墙

首次尝试建立网络调试连接时，系统可能会提示你允许调试应用程序（WinDbg 或 KD）通过防火墙进行访问。 Windows 的客户端版本显示提示，但 Windows 的服务器版本不显示提示。应通过选中所有三种网络类型的复选框来响应提示：域、专用和公共。

如果未收到提示，或者当提示可用时未选中复选框，则必须使用控制面板允许通过运行调试器的主机计算机上的防火墙进行访问。打开“控制面板”>“系统和安全”，然后选择“允许应用通过 Windows 防火墙”。

(WinDbg) 在应用程序列表中，找到 WinDbg 引擎进程 (TCP)（全部）。
（经典 WinDbg）在应用程序列表中，找到 Windows GUI 符号调试器和Windows 内核调试器。

使用复选框允许这些应用程序通过防火墙。重启调试应用程序（WinDbg 或 KD）。

加密密钥

为了使目标计算机保持安全，在主机和目标计算机之间传输的数据包必须加密。应使用自动生成的加密密钥（配置目标计算机时由 BCDEdit 提供）。建议使用自动生成的加密密钥，因为它更安全，并提供用于与特定目标建立连接的唯一值。

网络调试使用指定为 4 个 64 位值的 256 位密钥，以 36 为底数，由句点分隔。每个 64 位值最多使用 13 个字符指定。有效字符是字母 a 到 z ，数字 0 到 9。不允许使用特殊字符。

要指定自己的密钥，请在目标计算机上打开提升的命令提示符。输入以下命令，其中 w.x.y.z 是主机的 IP 地址，n 是端口号，Key 是密钥：

bcdedit /dbgsettings net hostip:w.x.y.z port:n key:Key

每当更改 dbgsettings 时，都需要重新启动目标计算机。

故障排除提示

必须允许调试应用程序通过防火墙

如果未收到提示，或者当提示可用时未选中复选框，则必须使用控制面板允许通过防火墙进行访问。打开“控制面板”>“系统和安全”，然后选择“允许应用通过 Windows 防火墙”。

(WinDbg) 在应用程序列表中，找到 WinDbg 引擎进程 (TCP)（全部）。
（WinDbg (classic)）在应用程序列表中，找到 Windows GUI 符号调试器和 Windows 内核调试器。

使用复选框允许这些应用程序通过防火墙。向下滚动并选择“确定”保存防火墙更改。重启调试程序。

端口号必须位于网络策略允许的范围内

可用于网络调试的端口号范围可能受公司网络策略的限制。要确定公司的策略是否限制了可用于网络调试的端口范围，请咨询网络管理员。在目标计算机上，以管理员身份打开命令提示符并输入命令 bcdedit /dbgsettings。输出将如下所示：

C:\> bcdedit /dbgsettings
key                     XXXXXX.XXXXX.XXXXX.XXXXX
debugtype               NET
hostip                  169.168.1.1
port                    50085
dhcp                    Yes
The operation completed successfully.

在上述输出中，端口值为 50085。如果端口的值超出了网络管理员允许的范围，请输入以下命令。 w.x.y.z 值是主机的 IP 地址，YourDebugPort 是允许范围内的端口号。

bcdedit /dbgsettings net hostip:w.x.y.z port:YourDebugPort

更改目标计算机调试器设置后，使用新端口设置重新运行主机上的调试器，然后重新启动目标计算机。

使用 ping 测试连接

如果调试器未连接，请使用目标电脑上的 ping 命令验证连接。

C:\>Ping <HostComputerIPAddress>

注意

如果主机未配置为在网络上可发现，则可能不起作用，因为防火墙可能会阻止 ping 请求。如果防火墙阻止 ping 请求，则 ping 主机时不会收到任何响应。

调试器如何获取目标计算机的 IP 地址

目标计算机上的 KDNET 尝试使用动态主机配置协议 (DHCP) 获取用于调试的网络适配器的可路由 IP 地址。如果 KDNET 获取 DHCP 分配的地址，则目标计算机可由网络上任意位置的主机进行调试。如果 KDNET 无法获取 DHCP 分配的地址，则它使用自动专用 IP 寻址（APIPA）来获取本地链接 IP 地址。本地链接 IP 地址不可路由，因此主机和目标计算机无法使用本地链接 IP 地址通过路由器进行通信。在这种情况下，如果将主机和目标计算机插入同一网络中心或交换机，网络调试将正常工作。

使用基于 PCI 的 NIC 在物理计算机上设置 KDNET 时，始终指定 busparams

如果要在具有 PCI 或基于 PCIe 的 NIC 的物理计算机上设置 KDNET，应始终为要用于 KDNET 的 NIC 指定 busparams。要指定总线参数，请打开设备管理器，找到要用于调试的网络适配器。打开网络适配器的属性页，并记下“常规”选项卡中“位置”下显示的总线编号、设备编号和函数编号。在提升的命令提示符中，输入以下命令，其中 b、d 和 f 是十进制格式的总线、设备和函数编号：

bcdedit /set "{dbgsettings}" busparams b.d.f

当调试器在主机上运行并等待连接时，请使用以下命令重新启动目标计算机：

shutdown -r -t 0

手动删除 BCDEdit 条目

通常不需要手动删除，但此处提供了异常情况下的故障排除程序。

使用 kdnet 实用工具时，不需要手动删除条目。有关详细信息，请参阅自动设置 KDNET 网络内核调试。

使用 bcdedit –deletevalue 时，必须提供有效的 bcd 元素名称。有关详细信息，请参阅 BCDEdit /deletevalue。

要手动删除 bcdedit 条目，请完成以下步骤：

在目标计算机上，以管理员身份打开命令提示符。
例如，输入以下命令以删除主机 IP 地址的 BCDEdit 调试条目：
```
bcdedit -deletevalue {dbgsettings} hostip
```

删除 hostip 时，需要在调试器命令行上指定 target=。

另一个示例是，使用以下命令删除端口条目：
```
bcdedit -deletevalue {dbgsettings} port
```

删除端口条目时，KDNET 使用默认的 ICANN 认证的调试器端口 5364。

设置 Hyper-V

如果打算在目标计算机上安装 Hyper-V 角色，请参阅设置虚拟机主机的网络调试。

有关调试 Hyper-V 虚拟机 (VM) 的信息，请参阅设置虚拟机的网络调试 - KDNET。

在运行具有外部网络连接的 VM 的 Hyper-V 主机上启用 KDNET

有时会出现导致 VM 中的网络停止工作的情况：

已在电脑上启用 Hyper-V，已创建外部网络交换机并指向计算机中的物理 NIC，且 VM 已配置为使用该外部交换机进行其网络连接。
然后，使用外部网络交换机指向的相同物理 NIC 在 Hyper-V 主机操作系统上启用 KDNET。主机已重新启动。
使用之前配置的外部交换机的所有 VM 在重新启动后会丢失其网络连接。

发生此停止情况是专门设计的，因为 KDNET 独占控制了其配置使用的 NIC。该操作系统不会加载该 NIC 的本机 NDIS 微型端口。之后，外部网络交换机无法再与本机 NDIS 微型端口驱动程序通信并停止工作。要解决这种情况，请执行下列操作：

从 Hyper-V 管理器打开虚拟交换机管理器，然后选择现有的虚拟交换机。从下拉菜单中选择外部网络 NIC，然后在“虚拟交换机管理器”对话框中选择“确定”，这样可将外部网络 NIC 更改为 Microsoft 内核调试网络适配器。
更新虚拟交换机 NIC 后，关闭并重启 VM。

当 KDNET 调试关闭时，需要遵循相同的程序将外部交换机重新指向 NIC 的本机 NDIS 微型端口。否则，在禁用调试后重启计算机时，VM 连接将丢失。

IPv6

在 Windows 版本 1809 中添加了 IPv6 支持。

要将 IPv6 与调试器配合使用，请完成以下步骤：

Ping <debughostname>，并记下输出行回复中报告的 IPv6 地址。使用此 IPv6 地址代替 x:y:z:p:d:q:r:n。
使用 BCDEdit 删除 dbgsettings 中的任何现有 IP 地址值。
```
bcdedit -deletevalue {dbgsettings} hostip
```
设置主机的 IPv6 地址。字符串 hostipv6=s:t:u:v:w:x:y:z 中不得有任何空格。 <YourPort> 是用于此目标计算机的网络端口号。 <YourKey> 是由四部分构成的安全密钥。 <b.d.f> 是要用于 KDNET 的 NIC 的总线设备功能位置编号。
```
bcdedit /dbgsettings net hostipv6:s:t:u:v:w:x:y:z port:<YourPort> key:<YourKey> busparams:<b.d.f>
```

键入此命令以确认已正确设置 dbgsettings。

C:\> bcdedit /dbgsettings
busparams               0.25.0
key                     2steg4fzbj2sz.23418vzkd4ko3.1g34ou07z4pev.1sp3yo9yz874p
debugtype               NET
hostipv6                  2001:db8:0:0:ff00:0:42:8329
port                    50010
dhcp                    Yes
The operation completed successfully.

在主机上，使用以下命令启动调试器：

Windbg -k net:port=<yournetworkportnumber>,key=<key_output_from_kdnet>,target=::<YourIPv6Address>

当调试器在主机上运行并等待连接时，请重新启动目标计算机。
调试器应在启动期间尽早连接到主机调试器。可以看到 KDNET 正在使用 IPv6 连接，因为连接消息中报告的 IP 地址是 IPv6 地址，而不是 IPv4 地址。

说明

允许指定 hostip 的每个调试器 bcd 设置都有相应的 hostipv6 元素。共有三种。

IPv4 IPv6 使用情况

hostip hostipv6 针对启动和内核调试

targethostip targethostipv6 特定于内核调试

hypervisorhostip hypervisorhostipv6 针对 hyper-v 调试
如果为任一类型的调试设置 hostipv6 样式地址，则表示需要并将获取 IPv6。
如果为任一类型的调试设置 hostip 样式地址，则表示需要并将获取 IPv4。
目标只能执行 IPv4 或 IPv6，而不是同时执行两者。所使用的 IP 协议的版本由目标计算机 dbgsettings 控制。如果已设置 hostip，则目标使用 IPv4。如果已设置 hostipv6，则目标使用 IPv6。
主机调试器通常自动选择使用 IPv4 或 IPv6。默认情况下，调试器同时侦听 IPv4 套接字和 IPv6 套接字，并在其中一个套接字上自动连接到目标计算机。
如果在主机上要强制在调试器中使用 IPv6，但希望调试器侦听来自目标的连接，则可以将 target=:: 添加到调试器命令行。 :: 是 0 的 IPv6 地址。
如果在主机上要强制在调试器中使用 IPv4 调试，但希望调试器侦听来自目标的连接，则可以将 target=0.0.0.0 添加到调试器命令行。 0.0.0.0 是 0 的 IPv4 地址。
如果在调试器命令行上指定 target= 并使用计算机名称，调试器会将该计算机名称转换为 IPv4 地址和 IPv6 地址。然后，调试器尝试在两者上进行连接。
在调试器命令行上指定 target= 并使用 IP 地址时，如果 IP 地址包含任何 : 字符，则调试器假定它是 IPv6 地址，并强制为该连接使用 IPv6。如果 IP 地址包含任何 . 字符，则调试器假定它是 IPv4 地址，并强制为该连接使用 IPv4。
如果在目标上设置了 IPv6，并在调试器命令行上强制使用 IPv4，则不会获得连接。
如果在目标上设置了 IPv4，并在调试器命令行上强制使用 IPv6，则也不会获得连接。