Category: feature | Scope: Small
Description
Add a section to the troubleshooting guide that shows how to follow a live packet through the data plane with eBPF-based tracing tools such as pwru and retis. The section walks the paths the guide today can only describe statically: a FIP packet arriving on the provider bridge, entering the kernel, matching its /32 route and the policy-routing rules, and leaving through the veth pair into the provider VRF — plus the reply direction, where conntrack reverse translation and the fwmark-based return path decide the route.
For each scenario the section gives a ready-to-run command line, the output an operator sees on a healthy node, and the signature of the common failures: a packet dropped between bridge and kernel, a policy rule that never matches, a reply looping between the two VRFs, a conntrack entry in the wrong zone. It also states where the tools come from (distribution packages or upstream releases) and which kernel versions they need.
This is a documentation-only change. The agent's behavior, configuration, and packaging stay untouched.
Motivation
The data plane the agent programs spans four subsystems: OVS flows, kernel routes and policy rules, nftables chains, and a veth pair between two VRFs. When forwarding breaks, ip route, nft list ruleset, and ovs-ofctl dump-flows show the configured state — but not where a live packet actually stops. An operator debugging an asymmetric hairpin failure or a silently dropped DNAT reply has to reason about the packet path from memory.
eBPF tracing tools answer exactly that question: they show each kernel function a packet traverses and the precise point where it is dropped, and they require nothing from the agent. A guide section with worked examples turns the hardest class of support cases — "traffic disappears between the provider bridge and the VRF" — from guesswork into a repeatable procedure.
Drafted by planwerk-agent with Claude:claude-fable-5
Category: feature | Scope: Small
Description
Add a section to the troubleshooting guide that shows how to follow a live packet through the data plane with eBPF-based tracing tools such as pwru and retis. The section walks the paths the guide today can only describe statically: a FIP packet arriving on the provider bridge, entering the kernel, matching its /32 route and the policy-routing rules, and leaving through the veth pair into the provider VRF — plus the reply direction, where conntrack reverse translation and the fwmark-based return path decide the route.
For each scenario the section gives a ready-to-run command line, the output an operator sees on a healthy node, and the signature of the common failures: a packet dropped between bridge and kernel, a policy rule that never matches, a reply looping between the two VRFs, a conntrack entry in the wrong zone. It also states where the tools come from (distribution packages or upstream releases) and which kernel versions they need.
This is a documentation-only change. The agent's behavior, configuration, and packaging stay untouched.
Motivation
The data plane the agent programs spans four subsystems: OVS flows, kernel routes and policy rules, nftables chains, and a veth pair between two VRFs. When forwarding breaks,
ip route,nft list ruleset, andovs-ofctl dump-flowsshow the configured state — but not where a live packet actually stops. An operator debugging an asymmetric hairpin failure or a silently dropped DNAT reply has to reason about the packet path from memory.eBPF tracing tools answer exactly that question: they show each kernel function a packet traverses and the precise point where it is dropped, and they require nothing from the agent. A guide section with worked examples turns the hardest class of support cases — "traffic disappears between the provider bridge and the VRF" — from guesswork into a repeatable procedure.
Drafted by planwerk-agent with Claude:claude-fable-5