bugtool

Active contributors: aanm, christarazi, joestringer

Purpose

cilium-bugtool is the diagnostic bundle collector that runs inside the Cilium pod and produces a tarball of every piece of state needed to debug a customer issue: BPF map dumps, log files, kernel info, the agent's REST state, ip / iproute2 output, network namespaces of every endpoint, Hubble flows, and more.

Directory layout

bugtool/
├── Makefile
└── cmd/
    └── (cobra root + collectors)

How it works

graph TD
    User[Operator] -->|kubectl exec| Pod[Cilium pod]
    Pod --> Bug[cilium-bugtool]
    Bug -->|exec ip / iproute2 / iptables| OS[OS commands]
    Bug -->|REST| Agent[cilium-agent]
    Bug -->|read| Maps[BPF maps]
    Bug -->|read| Logs[/var/log + journald]
    Bug --> Tarball[/tmp/cilium-bugtool-*.tar]

The tool runs a fixed list of "collectors" in series, each writing into a working directory; at the end it tars everything and prints the tarball path.

cilium sysdump (in cilium-cli/sysdump/) wraps cilium-bugtool: it execs cilium-bugtool in every Cilium pod, copies the resulting tarballs out, and bundles them with cluster-wide state (CRDs, DaemonSet specs, events) into a single archive.

Key source files

File	Purpose
bugtool/cmd/root.go	Cobra root + flag definitions.
bugtool/cmd/bugtool.go	The collector orchestration.
bugtool/cmd/configmap.go	ConfigMap collector.
bugtool/cmd/cilium-bugtool*.json	Embedded list of commands to run.

See how-to-contribute/debugging.md and the cilium sysdump command in apps/cilium-cli.md.