cilium/pwru

pwru 镜像文档

概述

pwru（packet, where are you?）是一款基于 eBPF 的 Linux 内核网络数据包追踪工具，具备高级过滤能力。它允许对内核状态进行细粒度检查，从而帮助调试网络连接问题，例如追踪数据包在何处被丢弃、分析网络路径等。

!logo

以下示例展示了在添加 iptables 规则后，curl 请求的数据包被丢弃的位置：

!demo

核心功能与特性

• eBPF 技术实现：基于 eBPF 实现高效内核数据包追踪，对系统性能影响小
• 高级过滤能力：支持 pcap 过滤规则（参见 man 7 pcap-filter），可按内核函数名、网络接口、网络命名空间等多维度过滤
• 多追踪后端：支持 kprobe 和 kprobe-multi 两种追踪后端，可根据内核版本自动选择
• 细粒度状态检查：可追踪数据包在内核中的完整路径，包括经过 NAT、隧道解封装、网桥转发等场景
• 丰富输出选项：支持输出数据包元数据、L4 元组、TCP 标志位、调用栈、skb（socket buffer）详情等

适用场景

• 调试网络数据包丢失问题（如 iptables 规则、安全组导致的丢包）
• 追踪数据包在内核中的处理路径
• 分析 XDP/TC BPF 程序对数据包的处理逻辑
• 排查涉及 NAT、隧道（VXLAN/Geneve）、网桥等复杂网络场景的问题
• 验证内核网络功能或自定义内核模块的正确性

使用要求

内核版本要求

• 基础运行：需 Linux 内核版本 ≥ 5.3
• 使用 --output-skb 选项：需内核版本 ≥ 5.9
• 使用 --backend=kprobe-multi 选项：需内核版本 ≥ 5.18

debugfs 要求

pwru 可选依赖 debugfs，需挂载至 /sys/kernel/debug。若该目录为空，可通过以下命令挂载：

bash
mount -t debugfs none /sys/kernel/debug

内核配置要求

需启用以下内核配置选项，可通过 zgrep $OPTION /proc/config.gz 验证是否启用：

Docker 部署与使用

镜像获取

pwru 官方 Docker 镜像托管于 Docker Hub：cilium/pwru

基本运行命令

bash
docker run --privileged --rm -t --pid=host -v /sys/kernel/debug/:/sys/kernel/debug/ cilium/pwru pwru [选项] [pcap-filter]

参数说明：

• --privileged：提供特权模式，确保容器能访问内核调试资源
• --rm：容器退出后自动删除
• -t：分配伪终端，确保输出格式正常
• --pid=host：共享主机 PID 命名空间，便于追踪内核进程
• -v /sys/kernel/debug/:/sys/kernel/debug/：挂载主机 debugfs，供工具访问内核调试信息

使用示例

追踪目标为 1.1.1.1 的网络流量，并输出 L4 元组：

bash
docker run --privileged --rm -t --pid=host -v /sys/kernel/debug/:/sys/kernel/debug/ cilium/pwru pwru --output-tuple 'host 1.1.1.1'

详细使用选项

命令格式

bash
pwru [选项] [pcap-filter]

• pcap-filter：pcap 过滤规则，语法参见 man 7 pcap-filter
• 选项：支持以下主要参数（通过 pwru --help 获取完整列表）：

主要选项说明

选项示例

• 过滤特定内核函数：--filter-func=".*iptables.*"（追踪所有包含 iptables 的内核函数）
• 追踪特定网络接口：--filter-ifname=eth0
• 输出调用栈和 skb 信息：--output-stack --output-skb
• 使用 JSON 格式输出：--output-json

Kubernetes 部署示例

以下示例在指定 Kubernetes 节点上运行 pwru：

bash
#!/usr/bin/env bash
NODE=kind-control-plane  # 目标节点名称
PWRU_ARGS="--output-tuple 'host 1.1.1.1'"  # pwru 运行参数

trap "kubectl delete --wait=false pod pwru" EXIT  # 退出时清理 pod

kubectl apply -f - <<EOF
apiVersion: v1
kind: Pod
metadata:
  name: pwru
spec:
  nodeSelector:
    kubernetes.io/hostname: ${NODE}  # 调度到目标节点
  containers:
  - image: docker.io/cilium/pwru:latest
    name: pwru
    volumeMounts:
    - mountPath: /sys/kernel/debug  # 挂载 debugfs
      name: sys-kernel-debug
    securityContext:
      privileged: true  # 特权模式
    command: ["/bin/sh"]
    args: ["-c", "pwru ${PWRU_ARGS}"]  # 运行 pwru
  volumes:
  - name: sys-kernel-debug
    hostPath:
      path: /sys/kernel/debug
      type: DirectoryOrCreate
  hostNetwork: true  # 使用主机网络
  hostPID: true  # 共享主机 PID 命名空间
EOF

kubectl wait pod pwru --for condition=Ready --timeout=90s  # 等待 pod 就绪
kubectl logs -f pwru  # 查看追踪日志

社区支持

可通过 Slack 频道 中的 #pwru 与开发者、维护者及其他用户交流，获取帮助或分享使用经验。

Logo 说明：侦探地鼠（Detective Gopher）基于 Renee French 设计的 Go 地鼠形象创作。