Ciliumcilium-dbg bpf policy add命令详解直接写入 BPF Policy 映射的策略注入指南【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读cilium-dbg bpf policy add是 Cilium 数据面调试工具链中用于直接向指定 Endpoint 的 BPF Policy Map 添加或更新策略条目的低层命令。与通过 Kubernetes CiliumNetworkPolicyCNP等高层 API 下发策略不同该命令绕过控制面直接操作 eBPF 内核映射适合内核开发调试、故障排查和自动化脚本场景。读完本文你将掌握该命令的完整语法、参数语义、底层 BPF 映射寻址规则以及它与策略删除、列表查看命令的配合用法。命令概览与适用场景cilium-dbg是 Cilium 附带的调试工具其生成的 CLI 参考文档位于 Documentation/cmdref/cilium-dbg_bpf_policy_add.md。bpf policy子命令组的定位是 Manage policy related BPF mapscilium-dbg/cmd/bpf_policy.go其下的add子命令用于向策略映射写入条目。适用场景主要包括Datapath 级调试验证某条策略在 BPF 映射层面是否生效、键值编码是否正确故障排查当高层 API 下发的策略未按预期生效时直接检查并修正映射内容脚本化注入在测试环境或自动化流程中快速构造策略状态开发验证配合cilium-dbg bpf policy get/list/delete验证策略生命周期。需要强调的是这是一条调试命令正常运行时应优先使用 Cilium 的 Kubernetes CRD 或命令行 API 管理策略直接修改 BPF 映射不会反向同步到控制面状态。命令语法与参数说明命令的基本语法为cilium-dbg bpf policy add endpoint id traffic-direction identity [port/proto] [flags]从源码看其 Cobra 定义cilium-dbg/cmd/bpf_policy_add.go为Use: add endpoint id traffic-direction identity [port/proto], Short: Add/update policy entry, PreRun: requireEndpointID, Run: func(cmd *cobra.Command, args []string) { common.RequireRootPrivilege(cilium bpf policy add) updatePolicyKey(parsePolicyUpdateArgs(log, cmd, args, isDeny, cookie), true) },位置参数参数含义说明endpoint idEndpoint ID 或保留标签名数值 ID如123或保留身份名如host用于定位目标策略映射traffic-direction流量方向仅接受ingress或egress大小写不敏感由parseTrafficString校验identity对端安全身份 IDNumericIdentity32 位无符号整数表示与哪个身份之间的通信策略[port/proto]可选的 L4 端口与协议形如80/tcp、443/udp省略表示所有端口Flags本命令专属--cookie uint32 Sets policy log cookie --deny Sets deny mode -h, --help help for add--deny将条目置为deny 模式默认 allow对应源码中isDeny布尔变量cilium-dbg/cmd/bpf_policy_add.go--cookie设置策略日志 cookieuint32用于审计日志关联对应源码cookie变量cilium-dbg/cmd/bpf_policy_add.go。继承自父命令的全局 FlagsFlag说明--config string配置文件默认$HOME/.cilium.yaml-D, --debug启用调试消息-H, --host string服务端 API URI--log-driver strings日志端点如syslog--log-opt map日志驱动选项如formatjson此外命令通过requireEndpointID前置检查确保 Endpoint ID 参数非空并在Run中调用common.RequireRootPrivilege(cilium bpf policy add)强制要求 root 权限才能执行——因为直接操作 BPF 映射属于特权操作。参数解析的内部实现参数解析由 cilium-dbg/cmd/helpers.go 中的parsePolicyUpdateArgs/parsePolicyUpdateArgsHelper完成其核心步骤可拆解如下。1. 校验流量方向parseTrafficStringcilium-dbg/cmd/helpers.go将参数小写化后与ingress/egress匹配否则返回Invalid方向并报错。2. 解析 Endpoint ID 并定位 BPF 映射endpointToPolicyMapPathcilium-dbg/cmd/helpers.go决定目标映射路径存在两条分支数值 Endpoint ID解析为 16 位无符号整数映射名形如cilium_policy_v3_00123bpf.LocalMapName(policymap.MapName, id)补零格式化保留身份名如host通过identity.GetReservedID解析为保留身份 ID映射名形如cilium_policy_v3_reserved_1。最终经bpf.MapPath得到 BPF 文件系统中的完整路径。映射名前缀cilium_policy_v3_定义于 pkg/maps/policymap/policymap.go其版本号_v3_对应策略身份聚合的语义变更每次 BPF 格式或语义变更都必须重命名以保证新旧映射隔离。3. 解析身份与 L4 信息identity参数解析为 32 位NumericIdentity若提供了[port/proto]通过parseL4PortsSlice解析端口与协议协议省略时如仅写1会遍历u8proto.ProtoIDs展开为全部协议未指定 L4 参数时默认使用端口0与协议0ANY表示全端口通配。4. 组装参数对象解析结果封装为PolicyUpdateArgscilium-dbg/cmd/helpers.go包含路径、方向、身份、端口、协议集合、isDeny与cookie六个字段随后交给updatePolicyKey执行实际映射写入。映射写入过程与键值编码updatePolicyKeycilium-dbg/cmd/helpers.go负责真正的写入policyMap, err : policymap.OpenPolicyMap(log, pa.path) ... for _, proto : range pa.protocols { u8p : u8proto.U8proto(proto) entry : fmt.Sprintf(%d %d/%s, pa.label, pa.port, u8p.String()) mapKey : policymap.NewKeyFromPolicyKey( policyTypes.KeyForDirection(pa.trafficDirection). WithIdentity(pa.label).WithPortProto(proto, pa.port)) mapEntry : policymap.NewEntryFromPolicyEntry(mapKey, policyTypes.MapStateEntry{Cookie: pa.cookie}.WithDeny(pa.isDeny)) if err : policyMap.Update(mapKey, mapEntry); err ! nil { Fatalf(Cannot add policy key %s: %s\n, entry, err) } }几个值得注意的实现细节OpenPolicyMap 不做透明初始化源码注释明确说明即使映射缺失也不触发重建因为OpenOrCreate在映射属性变更时会引发更严重的问题pkg/maps/policymap/policymap.go 表明该函数仅用于cilium-dbg bpf policy工具多个协议展开写入当协议未指定时protocols切片包含多个协议值循环会依次为每个协议写入独立条目键的构建KeyForDirection(...).WithIdentity(...).WithPortProto(...)链式构造 LPM 键pkg/policy/types/types.go方向编码在最高位端口支持按前缀长度通配值的编码MapStateEntry{Cookie: ...}.WithDeny(...)pkg/policy/types/entry.go将 deny 语义编码进Precedence字段——deny 条目的优先级字段被设置为precedenceByteDeny从而在 datapath 查表时获得高于普通 allow 条目的优先级端口字节序NewKeyFromPolicyKeypkg/maps/policymap/policymap.go使用byteorder.HostToNetwork16将端口转为网络字节序这是 BPF 映射跨架构一致性的关键。常用命令示例基础用法# 为 Endpoint 123 添加 ingress 方向、身份 12345 的允许策略所有端口 cilium-dbg bpf policy add 123 ingress 12345 # 指定端口与协议允许身份 12345 通过 TCP 80 端口 ingress cilium-dbg bpf policy add 123 ingress 12345 80/tcp # 只写端口不写协议等价于对 TCP/UDP/SCTP 等全部协议生效 cilium-dbg bpf policy add 123 ingress 12345 80 # egress 方向示例 cilium-dbg bpf policy add 123 egress 12345 443/udpdeny 模式与 cookie# 添加 deny 条目并附加策略日志 cookie cilium-dbg bpf policy add 123 ingress 12345 --deny --cookie 0x010203--deny对应测试用例中以isDeny: true、cookie: 0x010203组合验证的路径cilium-dbg/cmd/helpers_test.go。配合查看与删除# 查看某个 Endpoint 的当前策略条目 cilium-dbg bpf policy get 123 # 删除刚才添加的条目注意 delete 语法不含 traffic-direction 参数 cilium-dbg bpf policy delete 123 12345 80/tcpbpf policy delete与add共享parsePolicyUpdateArgs解析逻辑仅将updatePolicyKey的add参数置为false转而执行DeleteKeycilium-dbg/cmd/bpf_policy_delete.go因此两者参数语义保持一致。测试验证与行为边界仓库在 cilium-dbg/cmd/helpers_test.go 中提供了针对参数解析的表格驱动测试覆盖的关键场景即上文各示例的依据输入预期结果host ingress 12345映射cilium_policy_v3_reserved_1方向 ingress端口 0协议ANY123 egress 12345 1/tcp映射cilium_policy_v3_00123方向 egress端口 1协议TCP123 ingress 12345 1端口 1协议展开为全部协议123 invalid 12345解析失败非法方向123 invalid 1/udt解析失败非法协议测试同时验证了--deny与--cookie的传递。这些用例从侧面印证了命令的行为边界方向只能是 ingress/egress协议必须是已注册的 IP 协议名非法输入会在写入前被拒绝。使用注意事项需要 root 权限命令通过RequireRootPrivilege强制检查非 root 用户无法执行直接修改 BPF 映射属于低层操作不会同步到 Cilium 控制面状态重启或策略重新下发后可能被覆盖仅作调试用途映射版本敏感cilium_policy_v3_前缀与当前 datapath 程序版本强绑定跨版本混用可能导致键值解释不一致保留身份映射当第一个参数使用host等保留名时写入的是全局保留身份的策略映射如cilium_policy_v3_reserved_1而非某个具体 Endpoint 的映射使用前需确认意图。延伸阅读命令的权威 CLI 参考cilium-dbg bpf policy addDocumentation/cmdref/cilium-dbg_bpf_policy_add.md及父命令 Documentation/cmdref/cilium-dbg_bpf_policy.md策略映射底层实现pkg/maps/policymap/policymap.go策略键值类型定义pkg/policy/types/types.go、pkg/policy/types/entry.go参数解析与写入逻辑cilium-dbg/cmd/helpers.go。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cilium `cilium-dbg bpf policy add` 命令详解：直接写入 BPF Policy 映射的策略注入指南
Ciliumcilium-dbg bpf policy add命令详解直接写入 BPF Policy 映射的策略注入指南【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium导读cilium-dbg bpf policy add是 Cilium 数据面调试工具链中用于直接向指定 Endpoint 的 BPF Policy Map 添加或更新策略条目的低层命令。与通过 Kubernetes CiliumNetworkPolicyCNP等高层 API 下发策略不同该命令绕过控制面直接操作 eBPF 内核映射适合内核开发调试、故障排查和自动化脚本场景。读完本文你将掌握该命令的完整语法、参数语义、底层 BPF 映射寻址规则以及它与策略删除、列表查看命令的配合用法。命令概览与适用场景cilium-dbg是 Cilium 附带的调试工具其生成的 CLI 参考文档位于 Documentation/cmdref/cilium-dbg_bpf_policy_add.md。bpf policy子命令组的定位是 Manage policy related BPF mapscilium-dbg/cmd/bpf_policy.go其下的add子命令用于向策略映射写入条目。适用场景主要包括Datapath 级调试验证某条策略在 BPF 映射层面是否生效、键值编码是否正确故障排查当高层 API 下发的策略未按预期生效时直接检查并修正映射内容脚本化注入在测试环境或自动化流程中快速构造策略状态开发验证配合cilium-dbg bpf policy get/list/delete验证策略生命周期。需要强调的是这是一条调试命令正常运行时应优先使用 Cilium 的 Kubernetes CRD 或命令行 API 管理策略直接修改 BPF 映射不会反向同步到控制面状态。命令语法与参数说明命令的基本语法为cilium-dbg bpf policy add endpoint id traffic-direction identity [port/proto] [flags]从源码看其 Cobra 定义cilium-dbg/cmd/bpf_policy_add.go为Use: add endpoint id traffic-direction identity [port/proto], Short: Add/update policy entry, PreRun: requireEndpointID, Run: func(cmd *cobra.Command, args []string) { common.RequireRootPrivilege(cilium bpf policy add) updatePolicyKey(parsePolicyUpdateArgs(log, cmd, args, isDeny, cookie), true) },位置参数参数含义说明endpoint idEndpoint ID 或保留标签名数值 ID如123或保留身份名如host用于定位目标策略映射traffic-direction流量方向仅接受ingress或egress大小写不敏感由parseTrafficString校验identity对端安全身份 IDNumericIdentity32 位无符号整数表示与哪个身份之间的通信策略[port/proto]可选的 L4 端口与协议形如80/tcp、443/udp省略表示所有端口Flags本命令专属--cookie uint32 Sets policy log cookie --deny Sets deny mode -h, --help help for add--deny将条目置为deny 模式默认 allow对应源码中isDeny布尔变量cilium-dbg/cmd/bpf_policy_add.go--cookie设置策略日志 cookieuint32用于审计日志关联对应源码cookie变量cilium-dbg/cmd/bpf_policy_add.go。继承自父命令的全局 FlagsFlag说明--config string配置文件默认$HOME/.cilium.yaml-D, --debug启用调试消息-H, --host string服务端 API URI--log-driver strings日志端点如syslog--log-opt map日志驱动选项如formatjson此外命令通过requireEndpointID前置检查确保 Endpoint ID 参数非空并在Run中调用common.RequireRootPrivilege(cilium bpf policy add)强制要求 root 权限才能执行——因为直接操作 BPF 映射属于特权操作。参数解析的内部实现参数解析由 cilium-dbg/cmd/helpers.go 中的parsePolicyUpdateArgs/parsePolicyUpdateArgsHelper完成其核心步骤可拆解如下。1. 校验流量方向parseTrafficStringcilium-dbg/cmd/helpers.go将参数小写化后与ingress/egress匹配否则返回Invalid方向并报错。2. 解析 Endpoint ID 并定位 BPF 映射endpointToPolicyMapPathcilium-dbg/cmd/helpers.go决定目标映射路径存在两条分支数值 Endpoint ID解析为 16 位无符号整数映射名形如cilium_policy_v3_00123bpf.LocalMapName(policymap.MapName, id)补零格式化保留身份名如host通过identity.GetReservedID解析为保留身份 ID映射名形如cilium_policy_v3_reserved_1。最终经bpf.MapPath得到 BPF 文件系统中的完整路径。映射名前缀cilium_policy_v3_定义于 pkg/maps/policymap/policymap.go其版本号_v3_对应策略身份聚合的语义变更每次 BPF 格式或语义变更都必须重命名以保证新旧映射隔离。3. 解析身份与 L4 信息identity参数解析为 32 位NumericIdentity若提供了[port/proto]通过parseL4PortsSlice解析端口与协议协议省略时如仅写1会遍历u8proto.ProtoIDs展开为全部协议未指定 L4 参数时默认使用端口0与协议0ANY表示全端口通配。4. 组装参数对象解析结果封装为PolicyUpdateArgscilium-dbg/cmd/helpers.go包含路径、方向、身份、端口、协议集合、isDeny与cookie六个字段随后交给updatePolicyKey执行实际映射写入。映射写入过程与键值编码updatePolicyKeycilium-dbg/cmd/helpers.go负责真正的写入policyMap, err : policymap.OpenPolicyMap(log, pa.path) ... for _, proto : range pa.protocols { u8p : u8proto.U8proto(proto) entry : fmt.Sprintf(%d %d/%s, pa.label, pa.port, u8p.String()) mapKey : policymap.NewKeyFromPolicyKey( policyTypes.KeyForDirection(pa.trafficDirection). WithIdentity(pa.label).WithPortProto(proto, pa.port)) mapEntry : policymap.NewEntryFromPolicyEntry(mapKey, policyTypes.MapStateEntry{Cookie: pa.cookie}.WithDeny(pa.isDeny)) if err : policyMap.Update(mapKey, mapEntry); err ! nil { Fatalf(Cannot add policy key %s: %s\n, entry, err) } }几个值得注意的实现细节OpenPolicyMap 不做透明初始化源码注释明确说明即使映射缺失也不触发重建因为OpenOrCreate在映射属性变更时会引发更严重的问题pkg/maps/policymap/policymap.go 表明该函数仅用于cilium-dbg bpf policy工具多个协议展开写入当协议未指定时protocols切片包含多个协议值循环会依次为每个协议写入独立条目键的构建KeyForDirection(...).WithIdentity(...).WithPortProto(...)链式构造 LPM 键pkg/policy/types/types.go方向编码在最高位端口支持按前缀长度通配值的编码MapStateEntry{Cookie: ...}.WithDeny(...)pkg/policy/types/entry.go将 deny 语义编码进Precedence字段——deny 条目的优先级字段被设置为precedenceByteDeny从而在 datapath 查表时获得高于普通 allow 条目的优先级端口字节序NewKeyFromPolicyKeypkg/maps/policymap/policymap.go使用byteorder.HostToNetwork16将端口转为网络字节序这是 BPF 映射跨架构一致性的关键。常用命令示例基础用法# 为 Endpoint 123 添加 ingress 方向、身份 12345 的允许策略所有端口 cilium-dbg bpf policy add 123 ingress 12345 # 指定端口与协议允许身份 12345 通过 TCP 80 端口 ingress cilium-dbg bpf policy add 123 ingress 12345 80/tcp # 只写端口不写协议等价于对 TCP/UDP/SCTP 等全部协议生效 cilium-dbg bpf policy add 123 ingress 12345 80 # egress 方向示例 cilium-dbg bpf policy add 123 egress 12345 443/udpdeny 模式与 cookie# 添加 deny 条目并附加策略日志 cookie cilium-dbg bpf policy add 123 ingress 12345 --deny --cookie 0x010203--deny对应测试用例中以isDeny: true、cookie: 0x010203组合验证的路径cilium-dbg/cmd/helpers_test.go。配合查看与删除# 查看某个 Endpoint 的当前策略条目 cilium-dbg bpf policy get 123 # 删除刚才添加的条目注意 delete 语法不含 traffic-direction 参数 cilium-dbg bpf policy delete 123 12345 80/tcpbpf policy delete与add共享parsePolicyUpdateArgs解析逻辑仅将updatePolicyKey的add参数置为false转而执行DeleteKeycilium-dbg/cmd/bpf_policy_delete.go因此两者参数语义保持一致。测试验证与行为边界仓库在 cilium-dbg/cmd/helpers_test.go 中提供了针对参数解析的表格驱动测试覆盖的关键场景即上文各示例的依据输入预期结果host ingress 12345映射cilium_policy_v3_reserved_1方向 ingress端口 0协议ANY123 egress 12345 1/tcp映射cilium_policy_v3_00123方向 egress端口 1协议TCP123 ingress 12345 1端口 1协议展开为全部协议123 invalid 12345解析失败非法方向123 invalid 1/udt解析失败非法协议测试同时验证了--deny与--cookie的传递。这些用例从侧面印证了命令的行为边界方向只能是 ingress/egress协议必须是已注册的 IP 协议名非法输入会在写入前被拒绝。使用注意事项需要 root 权限命令通过RequireRootPrivilege强制检查非 root 用户无法执行直接修改 BPF 映射属于低层操作不会同步到 Cilium 控制面状态重启或策略重新下发后可能被覆盖仅作调试用途映射版本敏感cilium_policy_v3_前缀与当前 datapath 程序版本强绑定跨版本混用可能导致键值解释不一致保留身份映射当第一个参数使用host等保留名时写入的是全局保留身份的策略映射如cilium_policy_v3_reserved_1而非某个具体 Endpoint 的映射使用前需确认意图。延伸阅读命令的权威 CLI 参考cilium-dbg bpf policy addDocumentation/cmdref/cilium-dbg_bpf_policy_add.md及父命令 Documentation/cmdref/cilium-dbg_bpf_policy.md策略映射底层实现pkg/maps/policymap/policymap.go策略键值类型定义pkg/policy/types/types.go、pkg/policy/types/entry.go参数解析与写入逻辑cilium-dbg/cmd/helpers.go。【免费下载链接】ciliumeBPF-based Networking, Security, and Observability项目地址: https://gitcode.com/GitHub_Trending/ci/cilium创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考