cilium-dbg

Active contributors: aanm, joestringer, christarazi, joamaki

Purpose

cilium-dbg is the in-pod debug CLI that ships with the agent image. Run via kubectl exec against a Cilium DaemonSet pod, it inspects every piece of agent state — endpoints, identities, BPF maps, policy verdicts, conntrack, NAT, services, and more.

It is a thin client over the agent's REST API plus direct BPF map readers (some commands open BPF maps from the bpffs mount inside the container).

Directory layout

cilium-dbg/
├── main.go              # entry point
├── cmd/                 # cobra command tree
└── doc/                 # generated cmdref documentation

The command tree is large; representative subtrees include:

Subcommand group	Source	Purpose
cilium endpoint ...	cilium-dbg/cmd/endpoint*.go	Endpoint listing, regenerate, log, healthz.
cilium identity ...	cilium-dbg/cmd/identity*.go	Identity listing and lookups.
cilium policy ...	cilium-dbg/cmd/policy*.go	Compiled policy and selector cache.
cilium bpf ...	cilium-dbg/cmd/bpf*.go	Direct BPF map dumps (ct, nat, lb, ipcache, policy, ...).
cilium service ...	cilium-dbg/cmd/service*.go	LB services known to the agent.
cilium fqdn ...	cilium-dbg/cmd/fqdn*.go	DNS proxy state.
cilium status	cilium-dbg/cmd/status.go	Health summary mirroring cilium-cli.
cilium monitor	cilium-dbg/cmd/monitor.go	Stream perf-event ring buffer.

How it works

graph LR
    Operator[Operator] -->|kubectl exec ds/cilium ...| Pod[Cilium pod]
    Pod --> CLI[cilium-dbg]
    CLI -->|REST| Agent[cilium-agent socket]
    CLI -->|bpf()| Maps[BPF maps on bpffs]
    Agent -->|state| CLI
    Maps -->|raw bytes| CLI

Commands like cilium endpoint list use the REST API; commands like cilium bpf ct list global open the kernel BPF map directly via pkg/bpf/. The two paths exist because BPF maps are the source of truth for the dataplane and reading them avoids any agent staleness.

Integration points

• Imports the generated agent REST client at api/v1/client/.
• Imports pkg/maps/<map>/ for direct map access.
• Output is human-friendly by default; many commands support -o json or -o yaml driven by pkg/command/output.go.

Entry points for modification

• New REST-backed commands: add a handler in daemon/restapi/ plus the OpenAPI spec, then a cobra subcommand in cilium-dbg/cmd/.
• New BPF map dumpers: implement Dump() on the map type under pkg/maps/<map>/ and add a cilium bpf <map> subcommand.

Key source files

File	Purpose
cilium-dbg/main.go	Entry point.
cilium-dbg/cmd/root.go	Cobra root.
cilium-dbg/cmd/bpf.go	BPF map command group.
cilium-dbg/cmd/monitor.go	Monitor stream.

See how-to-contribute/debugging.md for the full debugging cheatsheet.