You can read show ip bgp. You can read show ip ospf neighbor. But when a lab has five routers and something is off, the picture of what the whole lab is doing still lives only in your head — you build it router by router, command by command.
network-xray draws that picture for you. It reads the state your routers actually report and shows, in the browser, what is happening inside each router: who it is adjacent to, which routes it installed, and why a BGP best path won.
It is open source (MIT): https://github.com/rclab-dev/network-xray
What it shows
Start from the topology graph you already use (for example containerlab graph). Click a router, and its DeepDive opens: forwarding direction, OSPF / BGP adjacencies, the routing table — and the best-path decision.
It is not a simulator. It draws the state the routers returned, so when you change a config or take a link down, the picture changes with it.
Why did BGP pick that path?
For BGP it lines up the candidate paths and shows which comparison decided the winner. In the lab below, two ISPs advertise 8.8.8.0/24. Change the LocalPref and the best path flips in place — no lab rebuild.
Links go down, the picture follows
The collector (see Try it below) runs with --watch and re-reads the lab every few seconds. Shut an interface and you watch the adjacency drop and the route disappear; bring it back and it recovers.
Example: break it, look inside, fix it
Every practice problem starts from a lab that is broken on purpose. Take the two-ISP lab above in its broken version: r1 hears 8.8.8.0/24 from a fast ISP (r2) and a slow one (r3), yet traffic takes the slow one. Open r1's DeepDive and the Best-Path Decision gives the reason in one line: best path by LocPrf (100 > 50) — something is lowering the LocalPref of the fast path.
Fix the route-map on r1 (set local-preference 150 for the path from r2), and the picture re-decides from the routers' new state a few seconds later: the best path moves to r2 (150 > 100), the forwarding arrow follows, and the problem banner turns to ✓ Solved.
Each problem marks the route that matters, so whichever router's DeepDive you open, that route is selected automatically (when the router has it) and its forwarding arrow is drawn.
Update: it also works on ipSpace BGP Labs
Labs you build yourself rarely have just two neighbors per router, so I also tried a lab I did not write: "Use BGP Route Reflectors" from Ivan Pepelnjak's BGP Labs, started with netlab. The route reflector s1 has four neighbors (l1–l4); its DeepDive draws all four links at once, each coming in from where that neighbor sits on the overview, and the angles follow when you drag s1 (interactive template xray-graph-nextui.html).
Since v1.0.3, netlab can also start network-xray for you as a tool: add three lines to the topology and run netlab up
(how).
Topology: BGP Labs "Use BGP Route Reflectors" (Ivan Pepelnjak / ipSpace.net, MIT license, https://bgplabs.net/ibgp/3-rr/). Started with netlab, drawn with network-xray.
Try it
The shortest way: one script
With containerlab installed, one command deploys the two-ISP lab from the LocalPref GIF above, keeps collecting its state, and opens the graph:
git clone https://github.com/rclab-dev/network-xray
cd network-xray
./demo.sh examples/q21-bgp-lp/q21.clab.yml
Then open http://<your machine>:8080/ (port busy? add one: ./demo.sh examples/q21-bgp-lp/q21.clab.yml 8081). The script calls sudo containerlab deploy; if your user can run containerlab without sudo, start it as SUDO= ./demo.sh …. Stop with Ctrl-C, then sudo containerlab destroy -t examples/q21-bgp-lp/q21.clab.yml --cleanup.
In your own containerlab lab
Two steps: start the collector, then open containerlab graph with the network-xray template.
git clone https://github.com/rclab-dev/network-xray
# 1. collect the lab's state and keep re-reading it (use ospf or bgp for your lab)
node ./network-xray/clab-xray-collect.js lab.clab.yml ./network-xray bgp --exclude-mgmt --watch &
# 2. open your usual topology graph with the X-ray template
containerlab graph \
--topo lab.clab.yml \
--template ./network-xray/xray-graph.html \
--static-dir ./network-xray
--exclude-mgmt leaves the management network out of the picture. containerlab graph serves on port 50080 by default (http://<your machine>:50080/; change it with -s 0.0.0.0:<port>). Click any router to look inside it. Verified with FRR and Nokia SR Linux (a mixed FRR + SR Linux lab renders the same way).
Want to drag nodes around and have the open DeepDive follow? Use --template ./network-xray/xray-graph-nextui.html instead (an opt-in interactive graph built on NeXt UI).
No containerlab? Use a Codespace
The README has an Open in GitHub Codespaces button. It deploys a 3-router FRR lab and opens the X-ray view on port 8600 in about 2–3 minutes. It runs on a 4-core machine from your own Codespaces quota, so delete the codespace when you are done.
Or just paste output
The gallery draws from show output you paste in (FRR and SR Linux today). No install. Handy if you write about networking and want a "this is what the router is doing right now" picture next to your text.
Practice problems with a pass check
network-xray also comes with troubleshooting problems from RouteCrushLab, packaged for containerlab. Each problem has a broken starting version and a fixed version (GitHub releases). Fix the lab, and when the routers' state meets the condition — adjacency up, route installed, the ping target reachable — the problem banner shows ✓ Solved. It checks state, not config lines, so a different fix from the write-up usually passes too. q1–q21 are out.
You can add the same check to your own lab by writing a check in problem.json (docs/problem-format.md).
What's next
Today: containerlab with FRR and SR Linux. CML2 and IOS-XE support is in progress — not released yet. If you run another NOS, a sanitized sample of its show output in an issue helps a lot.
It is far from finished. If something is drawn wrong, or you want it to look different, please open an issue: https://github.com/rclab-dev/network-xray/issues
- GitHub: https://github.com/rclab-dev/network-xray
- Gallery: https://rclab-dev.github.io/network-xray/
- network-xray is an independent project and is not affiliated with, endorsed by, or sponsored by ipSpace.net.
Top comments (0)