Cilium XDP CIDR 预过滤器查询与诊断cilium-dbg prefilter list 命令完整指南【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium本文以 Cilium 的cilium-dbg prefilter list命令为主线深入讲解 XDP 层 CIDR 预过滤器XDP Prefilter的查询、输出解析、底层实现与配套管理命令。该命令用于在数据面最前端XDP 挂载点列出当前拒绝deny的 CIDR 前缀集合是排查 DDoS 缓解策略、验证规则生效状态的核心诊断工具。读完本文你将掌握cilium-dbg prefilter子命令族的完整用法理解 Revision 版本号语义、LPM Trie 内核映射结构并能结合 REST API 与数据面源码定位问题。命令定位XDP 预过滤器是什么在介绍命令之前先明确其背后的功能模块。Cilium 的pkg/datapath/prefilter包提供了一种用于DDoS 缓解的 XDP 预过滤机制见 doc.go 的包注释Package prefilter provides a means of configuring XDP pre-filters for DDoS-mitigation。其思路是在报文进入常规网络协议栈之前于 XDP 钩子处以极低开销将来自已知恶意/攻击源 IP 前缀CIDR的流量直接丢弃从而保护主机与 Pod 的数据通路。cilium-dbg prefilter命令族正是这套机制的运维入口其父命令在 prefilter.go 中定义为var PreFilterCmd cobra.Command{ Use: prefilter, Short: Manage XDP CIDR filters, }父命令下共挂载三个子命令对应文档 cilium-dbg_prefilter.md 的 SEE ALSO 部分子命令作用cilium-dbg prefilter list列出当前生效的 CIDR 过滤器本文主角cilium-dbg prefilter update新增/更新 CIDR 过滤器cilium-dbg prefilter delete删除 CIDR 过滤器本文档对应的 cilium-dbg_prefilter_list.md 是该命令的自动生成参考手册接下来逐段展开。命令语法与参数详解cilium-dbg prefilter list的完整语法如下cilium-dbg prefilter list [flags]其功能一句话概括为 List CIDR filters即列出数据面当前实际生效realized的 CIDR 拒绝列表。list 专属参数参数类型说明-h, --helpbool查看该子命令的帮助信息-o, --output stringstring结构化输出格式取值json、yaml或jsonpath{}从源码 prefilter_list.go 可以看到init()中通过command.AddOutputOption(preFilterListCmd)注入--output参数别名ls也被注册Aliases: []string{ls}因此cilium-dbg prefilter ls与list等价。继承自父命令的全局参数list子命令还继承自cilium-dbg根命令的以下选项参数说明--config string配置文件路径默认$HOME/.cilium.yaml-D, --debug开启调试信息输出-H, --host string服务端 API 的 URI 地址--log-driver strings日志端点例如syslog--log-opt map日志驱动选项例如formatjson其中-H/--host用于指定 Cilium Agent 的 API 端点在非默认场景如远程调试、容器内执行下尤其常用。实战查看当前生效的 CIDR 过滤器直接执行cilium-dbg prefilter list底层逻辑见 prefilter_list.go 的listFilters函数spec, err : client.GetPrefilter() if err ! nil { Fatalf(Cannot get CIDR list: %s, err) } ... if spec.Status nil || spec.Status.Realized nil { Fatalf(Cannot get CIDR list: empty response) } w : tabwriter.NewWriter(os.Stdout, 5, 0, 3, , 0) fmt.Fprintf(w, Revision: %d\n, spec.Status.Realized.Revision) for _, pfx : range spec.Status.Realized.Deny { fmt.Fprintln(w, pfx) } w.Flush()默认非结构化输出包含两个部分Revision 行当前过滤器的版本号格式为Revision: NDeny 列表逐行输出当前拒绝的 CIDR 前缀。一个典型的输出示例如下Revision: 3 10.0.0.0/8 192.168.100.0/24 2001:db8::/32这里Revision对应的是spec.Status.Realized.Revision——即数据面**已实现Realized**状态的修订号而非用户请求的目标状态。这一点与 Kubernetes 的 spec/status 语义类似只有被 Agent 成功写入 BPF 映射的规则才会计入该版本。若返回为空响应spec.Status nil命令会直接报错Cannot get CIDR list: empty response。结构化输出JSON / YAML / JSONPath当需要将过滤列表导入自动化脚本、监控系统或 CI 流程时使用-o参数获取结构化数据cilium-dbg prefilter list -o json cilium-dbg prefilter list -o yaml cilium-dbg prefilter list -o jsonpath{.status.realized.deny}在源码中listFilters首先判断command.OutputOption()若设置了-o则调用command.PrintOutput(spec)输出整个Prefilter对象随后直接返回prefilter_list.go。这意味着-o输出的是完整的 API 响应结构包含spec与status两部分{ spec: { revision: 3, deny: [10.0.0.0/8, 192.168.100.0/24, 2001:db8::/32] }, status: { realized: { revision: 3, deny: [10.0.0.0/8, 192.168.100.0/24, 2001:db8::/32] } } }其中deny字段对应PrefilterSpec.DenyCIDR 字符串切片revision为当前修订号。借助jsonpath模板可只提取需要的字段便于在 shell 脚本中进一步加工。端到端调用链从 CLI 到数据面prefilter list并非本地命令而是一个远程过程调用。完整的调用链如下CLI 层cilium-dbg prefilter list通过client.GetPrefilter()向 Agent 的 REST API 发起GET /prefilter请求prefilter_list.goAPI 层Agent 侧由 api.go 中的getPrefilterHandler.Handle处理。处理器首先检查h.preFilter.Enabled()——若数据面未启用 XDP 预过滤则返回错误prefilter is not enabled in daemon数据面层h.preFilter.Dump(list)遍历 4 张 CIDR 映射并返回(CIDR 列表, revision)封装为Prefilter响应体展示层CLI 还原默认表格输出或按-o格式化输出。同样地update与delete分别对应PATCH /prefilter与DELETE /prefilter见 api.go。API 层会对每个 CIDR 字符串执行net.ParseCIDR校验非法前缀直接返回invalid CIDR类错误。该模块以 Hive Cell 形式注册见 cell.go模块描述即 Provides a means of configuring XDP pre-filters for DDoS-mitigation。底层实现LPM Trie 与四张 CIDR 映射prefilter list输出的内容来自数据面的 BPF 映射。核心实现在 prefilter.go 与 cidrmap.go四张映射的划分CIDR 前缀按地址族与掩码长度被划分到 4 张LPMLongest Prefix MatchTrie 映射中映射名以cilium_cidr_为前缀见 cidrmap.go映射用途容量上限prefixesV4Dyncilium_cidr_v4_dynIPv4 动态前缀掩码长度可变maxLKeys 65536prefixesV4Fixcilium_cidr_v4_fixIPv4 全长度前缀/32maxHKeys 20×1024×1024prefixesV6Dyncilium_cidr_v6_dynIPv6 动态前缀maxLKeys 65536prefixesV6Fixcilium_cidr_v6_fixIPv6 全长度前缀/128maxHKeys前缀归属由selectMap(ones, bits)决定掩码长度等于地址位宽IPv4 的 32 位或 IPv6 的 128 位时进入 Fix 映射否则进入 Dyn 映射prefilter.go。映射元素并不预分配容量上限为注释所注的“任意选定值可按需调大”。Revision 的版本控制语义revision是并发安全的乐观锁机制prefilter.go每次成功的Insert或Delete操作后p.revision调用方CLI 的--revision参数或 API 请求体可携带期望的修订号若传入的revision ! 0且与当前值不一致则拒绝操作并返回Latest revision is %d not %d插入失败时通过undoQueue回滚已插入的条目保证操作原子性删除操作则先整体校验CIDRExists再逐条删除同样带回滚。这就是list输出中Revision的含义它是规则集合的单调递增版本号供调用方判断“我要修改的基线是否已被别人改过”。编译期配置生成当预过滤启用时WriteConfig还会向 datapath 头文件写入以下编译宏prefilter.go供 BPF C 代码在 XDP 程序中内联匹配逻辑#define CIDR4_FILTER #define CIDR4_LPM_PREFILTER #define CIDR6_FILTER #define CIDR6_LPM_PREFILTER这解释了为何预过滤依赖--enable-xdp-prefilter启用后不仅加载映射还会在编译阶段生成对应的 datapath 过滤代码路径。前置条件启用 XDP 预过滤prefilter list能返回数据的前提是 Agent 已启用 XDP 预过滤功能。该开关由配置项enable-xdp-prefilter控制定义于 config.go 的EnableXDPPrefilter enable-xdp-prefilter对应 Agent 启动参数--enable-xdp-prefilter见 cilium-agent 命令参考。从 prefilter.go 可以看到newPreFilter根据config.EnableXDPPrefilter决定是否初始化映射仅启用时才会通过 Hive 生命周期钩子在启动阶段调用init()打开并固定pinned那 4 张映射。若未启用Enabled()返回falseGET /prefilter会返回prefilter is not enabled in daemonCLI 侧对应报错Cannot get CIDR list: ...。因此排查prefilter list报错时第一件事是确认 Agent 是否以--enable-xdp-prefilter启动。配套命令update 与 delete虽然本文主角是list但理解其配套命令有助于解读查询结果。两个命令共享--cidr与--revision参数prefilter_update.go、prefilter_delete.go参数说明--cidr strings要操作的一个或多个 CIDR 前缀可重复指定逗号分隔--revision uint64期望的更新基线修订号默认 0 表示不校验添加/更新过滤器cilium-dbg prefilter update --cidr 10.0.0.0/8 --cidr 192.168.100.0/24 cilium-dbg prefilter update --revision 3 --cidr 2001:db8::/32删除过滤器cilium-dbg prefilter delete --cidr 192.168.100.0/24CLI 侧在执行前会对每个 CIDR 调用net.ParseCIDR校验prefilter_update.go非法前缀直接终止并提示Cannot parse CIDR ...成功后分别输出Updated N prefilter entries或Deleted N prefilter entries。每次变更后通过cilium-dbg prefilter list即可核对 Revision 是否递增、Deny 列表是否符合预期。常见错误与排查速查现象可能原因处理建议Cannot get CIDR list: prefilter is not enabled in daemonAgent 未启用--enable-xdp-prefilter检查 Agent 启动参数与配置Cannot get CIDR list: empty responseAPI 返回的 status/realized 为空确认 Agent 版本与 CLI 版本匹配Cannot parse CIDR ...update/delete 传入非法 CIDR使用标准 CIDR 表示法如10.0.0.0/8Latest revision is N not M--revision与当前基线不一致并发修改先prefilter list获取最新 Revision 后重试No map enabled for CIDR string ...该前缀类型无对应映射未初始化确认预过滤已启用相关命令参考cilium-dbg prefilter父命令cilium-dbg prefilter updatecilium-dbg prefilter deletecilium-dbgCLI 根命令如需深入源码可继续阅读 pkg/datapath/prefilter/api.goREST API 处理器、pkg/datapath/prefilter/prefilter.go核心实现、pkg/maps/cidrmap/cidrmap.goLPM 映射封装以及 cilium-dbg/cmd/prefilter_list.goCLI 实现。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
