route-explain

The route can exist and still not be the route the kernel uses.

Policy routing, multiple FIB tables, marks, VPNs, containers and overlay interfaces can make a simple question unexpectedly difficult: why did this flow leave through eth0 instead of tailscale0?

Linux already exposes the raw facts through tools such as ip route get, ip rule, fibmatch, WireGuard, Tailscale and nftables. The hard part is connecting those facts without claiming more than they actually prove.

Forensics, not a routing control plane.

A routing controller or split-tunnel manager changes the machine: it installs routes, manages policy, reconciles desired state and often keeps a privileged daemon running.route-explain does none of that.

A userspace route simulator calculates what it thinks should win from a state dump. route-explain instead asks the running Linux kernel for the selected path and treats that answer as authoritative evidence.

iproute2 remains the source of the core routing primitives. route-explain is the forensic layer above them: it correlates one flow's kernel answer with RPDB, FIB, namespace, overlay and optional runtime trace evidence.

The distinction is deliberate: a diagnostic tool should not become another component capable of changing the system it is diagnosing.

The explanation says what is known, inferred and still missing.

KERNEL statements come directly from kernel-backed lookups such as ip route get and fibmatch.

INFO is useful context derived from current route, rule, namespace and overlay state without pretending it was the exact execution trace.

CHECK marks ambiguity, a conflicting route or an evidence boundary that still needs investigation. The project rule is simple: unknown is better than confidently wrong.

A route can exist without being the kernel-selected route.

$ route-explain 10.70.0.12 --from 10.10.0.24 --mark 0x42 --why-not tailscale0

Kernel decision
  dev:    eth0
  table:  main

Why this path
  KERNEL kernel resolved the flow through table main on eth0
  CHECK  a more-specific route exists in table 52 via tailscale0

WHY NOT tailscale0?
  route exists, but the kernel selected table main on eth0

One routing question, one reviewable chain of evidence.

The main workflow starts with a kernel-backed lookup, then layers RPDB, FIB, namespace, overlay and optional runtime-trace evidence around that decision.

Snapshot replay stores the authoritative kernel lookup together with the surrounding evidence. It deliberately does not turn a route dump into a generic offline simulator.

WireGuard AllowedIPs and Tailscale route context can be added when available, while nftables runtime tracing stays read-only and never injects tracing rules automatically.

Correlate observed nftables state with a kernel routing probe.

With trace --correlate, route-explain groups native nftables packet, rule, policy and mark records by trace ID, identifies the matching flow from its packet record, carries observed interface/mark state forward, then asks the kernel again with those selectors and compares the result with the baseline decision.

The result stays explicitly forensic: the re-lookup proves what the kernel returns for the observed selector state, but it does not claim that Linux necessarily performed a reroute at that nftables hook. Missing evidence remains a CHECK, not a fabricated packet path.

No route management, no daemon, no fake kernel.

route-explain is not intended to install or remove routes, manage VPN or split-tunnel policy, reconcile network state, or maintain a privileged background service.

NAT and conntrack correlation are not yet reconstructed end to end. nftables traversal is only reported when runtime trace events exist. Advanced RPDB behavior that cannot be established from available evidence remains explicitly incomplete.

The same evidence-first approach across an outbound mail pipeline.

Install the CLI, inspect usage, or read the source.

route-explain is available on PyPI. For CLI use, the recommended install is pipx install route-explain or uv tool install route-explain.

The repository documents CLI usage, snapshot semantics, the evidence model and the boundaries of what the tool can prove.