# 利用 netdump(4) 进行事后内核调试 * 原文链接：[Post-Mortem Kernel Debugging with netdump(4)](https://freebsdfoundation.org/wp-content/uploads/2022/06/kernal_debugging.pdf) * 作者：**MARK JOHNSTON** FreeBSD 内核 Panic 是一个希望能尽量避免的事件，但偶尔会发生。你可能不幸地在生产系统上遇到内核错误，或者你正在开发内核补丁，然后在测试时发现了个错误。在这种情况下，重启系统将使系统重新上线，但内存中的内容会丢失，这使得无法找到 Panic 的根本原因。FreeBSD 支持内核 Panic 的实时调试和事后调试。虽然实时调试通常更简单，但由于其特性，意味着在开发人员完成调试之前，Panic 的系统无法重启。这通常是不切实际的，因此通过核心转储进行事后调试是常见的调试活动。 长期以来，FreeBSD 内核在发生 Panic 后具有保存核心转储的能力，这通常称为“内核转储”；待内核转储被保存，Panic 系统可以重新启动并恢复上线，随后可以使用该转储诊断问题。当用户空间程序崩溃并生成核心转储时，操作系统会将其状态保存为文件系统中的常规文件。然而，内核崩溃时，情况就没那么简单了：内核本身负责调解对其文件系统的访问，而在 Panic 后，内核处于不一致的状态，因此向文件写入数据是一个困难的任务。内核 Panic 已经够糟糕了，如果内核接着损坏了自己的文件系统，那就更糟糕了！ FreeBSD 传统的解决方案是将内核转储写入一个原始磁盘分区，通常是用于交换空间的同一个分区。这样做比修改文件系统要简单得多，并且由于交换的数据在重启后不会持久化，所以几乎没有覆盖重要数据的风险。配置内核转储很简单：在 `/etc/rc.conf` 中，将 dumpdev 变量设置为应保存内核转储的磁盘设备名称，或者如果要使用交换分区，则将其设置为字符串 `AUTO`。在幕后，这个机制使用 dumpon(8) 来告诉内核使用哪个磁盘设备。当系统在 Panic 后重新启动时，FreeBSD 会自动运行 savecore(8)，该命令读取保存的内核转储并将其放入目录 `/var/crash` ，以供后续使用。 基于磁盘的内核转储工作得很好，只要系统有一个备用分区来保存它们。然而，这并不总是如此：某些系统可能是无盘启动的，根本没有持久存储，或者像嵌入式设备一样，可能没有任何多余的磁盘空间。在这种情况下，过去通常不得不依赖实时调试，或者使用类似 U 盘这样的临时解决方案来存储内核转储。然而，从 FreeBSD 12.0 开始，有了更好的方法！ ## 介绍 netdump netdump(4) 是个相对较新的功能，它允许在 FreeBSD 系统发生内核 Panic 时，通过网络传输内核转储而无需重启系统。简而言之，它使用基于自定义 UDP 协议的方式将内存的内容传输到服务器，该服务器由 netdumpd(8) 实现（在 FreeBSD 的 Ports 中是 `ftp/netdumpd`）。这使得我们能够从发生 Panic 的内核获取转储，而无需在系统上配置任何本地存储。 需要明确指出的是，netdump 不执行任何加密和身份验证，因此内核内存的内容是直接通过网络传输的。由于内核内存通常包含敏感信息，因此在使用 netdump 时，必须确保只在受信网络上使用它。 netdump 有着悠久的历史：它大约在 2000 年由杜克大学的 Darrell Anderson 提出，作为 FreeBSD 4 的一个补丁，在随后的几年里由几家 FreeBSD 用户公司中的开发者进行移植。最终，它在 2018 年被提交到 FreeBSD 的源码仓库，并首次在 FreeBSD 12.0 中可用。 在内部实现上，netdump 基于 debugnet，这是一个独立的 IPv4/UDP 协议实现，专门设计用于在内核发生 Panic 时使用。特别是，debugnet 的 UDP 堆栈运行在单线程中，不执行任何堆内存分配，也不会阻塞（例如，等待中断或互斥锁）。这些限制来源于需要最小化内核在发生 Panic 后执行的代码复杂性：由于内核已经崩溃，netdump 必须避免在完成其工作时使情况变得更糟。 因为 debugnet 负责传输和接收数据包，它需要能够与网络接口控制器（NIC）硬件进行通信。因此，个别的 NIC 驱动程序需要进行修改，以便被 netdump 使用。通常，这些修改涉及为驱动程序的数据包传输和接收路径添加“轮询”模式。在实际操作中，所需的修改相对简单，通常只需为某个驱动程序添加不到 100 行 C 代码。如今，许多广泛使用的驱动程序都实现了 debugnet 支持，包括所有 Intel 驱动程序（实际上，包括所有使用 iflib 框架实现的驱动程序）、现代 Mellanox 驱动程序、VirtIO 网络驱动程序以及一些用于 GigE NIC 的驱动程序，这些驱动程序通常用于桌面系统或服务器管理端口；完整的驱动程序列表可参见 netdump(4) 手册页。 最后，debugnet 会钩入内核的包缓冲区分配器。这是因为驱动程序代码在发生 Panic 后会继续使用标准的 mbuf(9) 分配器接口来分配缓冲区，但 netdump 需要避免依赖标准的分配器。在系统初始化期间，debugnet 会预分配并保留用于内核 Panic 后的内存，从而确保 mbuf 分配会成功，并且不会过度干扰内核的状态。 ## debugnet 协议 debugnet 协议，符合 netdump 的要求，设计得非常简单并且专门化于其任务。它建立在 UDP 协议之上，目前仅支持 IPv4；尽管 IPv6 也可以得到支持，但迄今为止尚未实现。netdump 是由发生 Panic 的系统启动的，该系统充当客户端，服务器则由 netdumpd 实现。debugnet 协议有两种数据包类型：客户端消息和确认消息。 ![](https://github.com/user-attachments/assets/5716a0c8-0178-4043-bcea-5b6d0abf5319) 在启动 netdump 时，客户端首先需要发现下一跳路由器的 MAC 地址。为此，它的配置包括一个“网关”IP，debugnet 会广播 ARP 请求以获取路由器地址。待路由器地址被确定，客户端首先会向服务器发送类型为 NETDUMP\_HERALD (1) 的消息，目标端口为 20023。此操作会与服务器建立会话，服务器会绑定到一个临时端口，并向客户端的 20024 端口发送确认消息。所有后续客户端发送的消息都会发送到这个临时端口。所有客户端消息都会收到服务器的确认。 待会话完全建立，客户端就开始传输内核转储数据。包含这些数据的消息类型为 NETDUMP\_VMCORE (3)。每条消息都会获得一个唯一的序列号，并指定相对于内核转储文件起始位置的数据偏移量和长度。在接收到 `NETDUMP_VMCORE` 消息后，服务器会将数据写入转储文件的相应偏移位置，然后发送确认消息。客户端通常会一次传输一批数据块，并在所有数据块的确认消息到达后才继续传输。待所有内核转储数据被传输并确认，客户端会在一条 NETDUMP\_KDH (4) 消息中提供描述 Panic 的元数据，然后用 NETDUMP\_FINISHED (2) 消息完成会话。此时，内核转储已经保存在服务器的文件系统中，可以用于调试。 ## 配置 netdump 了解 netdump 的工作原理后，我们可以探讨它的配置。实际上，netdump 需要四个配置变量才能工作： 1. 客户端 IP 地址 2. 服务器 IP 地址 3. 网关 IP 地址 4. 使用的接口（例如 em0） 就像传统的基于磁盘的内核转储一样，netdump 可以通过 dumpon(8) 配置。例如，假设客户端 IP 为 `10.0.1.157`，位于 vtnet0 上，服务器 IP 为 `10.0.1.236`，网关 IP 为 `10.0.1.1`，配置 netdump 如下： ```sh # dumpon -c 10.0.1.157 -s 10.0.1.236 -g 10.0.1.1 vtnet0 ``` 然后，在服务器上，可以将 netdumpd 作为前台程序运行。 ```sh $ netdumpd -d . -D -P ./netdumpd.pid netdumpd: default: listening on all interfaces Waiting for clients. ``` 这将导致内核转储保存在当前目录中，路径由参数 `-d` 指定。 为了测试设置，我们可以手动触发一个 panic，并告诉内核转储核心。 ```sh # sysctl debug.kdb.panic=1 debug.kdb.panic: 0panic: kdb_sysctl_panic cpuid = 1 time = 1655412790 KDB: stack backtrace: db_trace_self_wrapper() at db_trace_self_wrapper+0x2b/frame 0xfffffe007c573af0 vpanic() at vpanic+0x151/frame 0xfffffe007c573b40 panic() at panic+0x43/frame 0xfffffe007c573ba0 kdb_sysctl_panic() at kdb_sysctl_panic+0x61/frame 0xfffffe007c573bd0 sysctl_root_handler_locked() at sysctl_root_handler_locked+0x9c/frame 0xfffffe007c573c20 sysctl_root() at sysctl_root+0x213/frame 0xfffffe007c573ca0 userland_sysctl() at userland_sysctl+0x187/frame 0xfffffe007c573d50 sys___sysctl() at sys___sysctl+0x5c/frame 0xfffffe007c573e00 amd64_syscall() at amd64_syscall+0x12e/frame 0xfffffe007c573f30 fast_syscall_common() at fast_syscall_common+0xf8/frame 0xfffffe007c573f30 --- syscall (202, FreeBSD ELF64, sys___sysctl), rip = 0x8011a773a, rsp = 0x7fffffffd938, rbp = 0x7fffffffd970 --- KDB: enter: panic [ thread pid 784 tid 100098 ] Stopped at kdb_enter+0x32: movq $0,0x1279963(%rip) db> dump debugnet: overwriting mbuf zone pointers debugnet_connect: searching for gateway MAC... netdumping to 10.0.1.236 (02:9a:88:79:b5:0a) Dumping 257 out of 4057 MB:..7%..13%..25%..32%..44%..56%..63%..75%..81%..94% netdump finished. debugnet: restoring mbuf zone pointers Dump complete ``` 在服务器上，我们应该看到类似如下内容： ```sh New dump from client devvm [10.0.1.157] (to ./vmcore.devvm.0) ................(KDH from devvm [10.0.1.157]) Completed dump from client devvm [10.0.1.157] ``` 现在，我们在通过参数 `-d` 指定的目录中得到了一个内核转储！ 在这个例子中，客户端和服务器位于同一网络段。因此，参数 `gateway` 是多余的，可以省略： ```sh # dumpon -c 10.0.1.157 -s 10.0.1.236 vtnet0 ``` 通过 `/etc/rc.conf` 配置 netdump 会稍微复杂一些。如果相关的 IP 地址是静态的，可以通过 rc.conf 变量 `dumpon_flags` 传递。如果不是静态地址，可以使用系统的 DHCP 客户端钩子，在客户端地址确定后调用 `dumpon`。手册页 `dumpon.8` 提供了如何使用 `dhclient(8)` 实现这一点的示例。自 FreeBSD 14.0 和 13.2 起，debugnet 在大多数情况下能够推断出客户端地址，从而简化配置。 ## 动态配置 netdump netdump 的一个限制是需要在 panic 之前进行配置。从 FreeBSD 13.0 开始，可以在 panic 后通过 DDB（内核调试器）配置 netdump。通过使用 DDB 的 `netdump` 命令，可以在 panic 后进行配置： ```sh # sysctl debug.kdb.panic=1 ... Stopped at kdb_enter+0x32: movq $0,0x1279963(%rip) db> netdump -s 10.0.1.236 debugnet: overwriting mbuf zone pointers debugnet_connect: searching for server MAC... netdumping to 10.0.1.236 (02:9a:88:79:b5:0a) Dumping 258 out of 4057 MB:..7%..13%..25%..31%..44%..56%..62%..75%..81%..93% netdump finished. debugnet: restoring mbuf zone pointers Dump complete ``` ## 下一步 仅有内核转储本身并不十分有用：调试器需要将核心转储与内核及其调试信息的精确副本配对。在将核心转储打包发送给开发人员时，请务必包含匹配的内核。默认情况下，内核调试信息会拆分成单独的文件，存放在目录 `/usr/lib/debug` 下。因此，通常最好包括以下内容： 1. 内核转储文件（通常是 vmcore.） 2. `/boot/kernel/` 的内容 3. `/usr/lib/debug/boot/kernel/` 的内容 `netdumpd` 提供了参数 `-i`，可以用来指定在 netdump 完成后执行的脚本。这可以用于执行内核转储的后处理。内核调试本身的讨论超出了本文的范围，但以前的文章提供了大量信息。 netdump 在某些环境下非常有用，但也有一些限制。已经提到的几个限制包括缺乏保密性、不支持 IPv6 和固定的端口号。如果你遇到这些限制（或者出现了 bug！），请务必在 FreeBSD 项目的 bug 跟踪器或项目邮件列表中报告问题。 *** **Mark Johnston** 是一位软件开发人员和 FreeBSD 源代码提交者，居住在加拿大安大略省的多伦多。他目前为 FreeBSD 基金会工作，且对操作系统开发的各个方面都有兴趣。当他不坐在电脑前时，他喜欢和朋友们一起在城市躲避球联赛中比赛。 --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://freebsd-journal-cn.bsdcn.org/20220506-zai-nan-hui-fu/netdump.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.