From 03a2b10aab56e59a22e577e12e22effd22c77872 Mon Sep 17 00:00:00 2001 From: rclab-dev <86867650+rclab-dev@users.noreply.github.com> Date: Mon, 19 Oct 2026 14:17:36 +0900 Subject: [PATCH 1/2] Add network-xray external tool network-xray (https://github.com/rclab-dev/network-xray) displays a containerlab topology and routing state collected from FRR and SR Linux routers. Adds the tool definition, the tool description, and an entry in the list of external tools. --- docs/extool/network-xray.md | 26 ++++++++++++++++++++++++++ docs/extools.md | 1 + netsim/tools/network-xray.yml | 19 +++++++++++++++++++ 3 files changed, 46 insertions(+) create mode 100644 docs/extool/network-xray.md create mode 100644 netsim/tools/network-xray.yml diff --git a/docs/extool/network-xray.md b/docs/extool/network-xray.md new file mode 100644 index 0000000000..2988340506 --- /dev/null +++ b/docs/extool/network-xray.md @@ -0,0 +1,26 @@ +(extool-network-xray)= +# network-xray + +[network-xray](https://github.com/rclab-dev/network-xray) displays a containerlab topology and routing state collected from FRR and Nokia SR Linux routers. + +```{warning} +network-xray receives the Docker socket, which provides control over the host's Docker daemon and is effectively root access on a typical lab host. Its web interface listens on all host interfaces and has no login. Use it only on a trusted lab host and restrict access to the published port. +``` + +Add the following lines to a lab topology file to use network-xray with _netlab_: + +``` +tools: + network-xray: +``` + +The URL is printed during **netlab up**. Use **netlab connect network-xray** to display it again. The web port is 8600, or 8600 plus the lab instance ID when using the [multilab plugin](plugin-multilab). + +**Notes:** + +* network-xray requires the *clab* provider: it reads the lab name from the generated `clab.yml` file and expects the default `clab--` container names (a custom `prefix` is not supported). +* network-xray only reads the router state through Docker (`vtysh -c 'show ...'` on FRR, `sr_cli 'info from state ...'` on SR Linux); it does not change the router configuration. The lab directory is mounted read-only. +* Router-state collection supports FRR and SR Linux, with limits on supported features and topology layouts. Other devices can appear in the topology without router-state details. _netlab_ does not check whether network-xray supports all the devices used in the lab topology. +* Only nodes connected by two-endpoint links are collected. SR Linux collection uses the default network instance and IPv4 unicast routes. +* This tool definition does not export validation data or integrate **netlab validate** results. +* The network-xray container is stopped and removed when the lab is shut down with **netlab down**. diff --git a/docs/extools.md b/docs/extools.md index 959a6c3cec..0d86507d3f 100644 --- a/docs/extools.md +++ b/docs/extools.md @@ -60,6 +60,7 @@ _netlab_ includes definitions for the following tools: extool/edgeshark.md extool/nso.md extool/nuts.md + extool/network-xray.md ``` It's relatively easy to add your own tools to the **defaults.tools** dictionary. Read [](dev/extools.md) for more details. diff --git a/netsim/tools/network-xray.yml b/netsim/tools/network-xray.yml new file mode 100644 index 0000000000..513d5dfa5f --- /dev/null +++ b/netsim/tools/network-xray.yml @@ -0,0 +1,19 @@ +# +# network-xray tool +# https://github.com/rclab-dev/network-xray +# +--- +runtime: docker # Default: start in a Docker container +docker: + up: + docker run -d --rm + --name "{name}_network_xray" + -v /var/run/docker.sock:/var/run/docker.sock + -v "$(pwd)":/lab:ro + -p { 8600 + defaults.multilab.id if defaults.multilab.id else 8600 }:8600 + ghcr.io/rclab-dev/network-xray:1 + --topo /lab/clab.yml + message: >- + Open http://{sys.ipurl}:{ 8600 + defaults.multilab.id if defaults.multilab.id else 8600 }/ in your browser + down: + docker kill '{name}_network_xray' From d333e3c8e90bd1144255ed8d11daed3dfdf87159 Mon Sep 17 00:00:00 2001 From: rclab-dev <86867650+rclab-dev@users.noreply.github.com> Date: Thu, 22 Oct 2026 04:39:14 +0900 Subject: [PATCH 2/2] Rename the network-xray tool to network_xray A tool name containing a dash cannot be enabled with an environment variable. Rename the tool definition and its documentation page, and update the references in the documentation. Reword the tool description to emphasize that network-xray works with FRRouting and Nokia SR Linux containers only, and that it works only with containerlab-only topologies. --- docs/extool/{network-xray.md => network_xray.md} | 10 +++++----- docs/extools.md | 2 +- netsim/tools/{network-xray.yml => network_xray.yml} | 2 +- 3 files changed, 7 insertions(+), 7 deletions(-) rename docs/extool/{network-xray.md => network_xray.md} (78%) rename netsim/tools/{network-xray.yml => network_xray.yml} (96%) diff --git a/docs/extool/network-xray.md b/docs/extool/network_xray.md similarity index 78% rename from docs/extool/network-xray.md rename to docs/extool/network_xray.md index 2988340506..9ced1c7080 100644 --- a/docs/extool/network-xray.md +++ b/docs/extool/network_xray.md @@ -1,7 +1,7 @@ -(extool-network-xray)= +(extool-network_xray)= # network-xray -[network-xray](https://github.com/rclab-dev/network-xray) displays a containerlab topology and routing state collected from FRR and Nokia SR Linux routers. +[network-xray](https://github.com/rclab-dev/network-xray) displays a lab topology and routing state collected from FRRouting and Nokia SR Linux containers. ```{warning} network-xray receives the Docker socket, which provides control over the host's Docker daemon and is effectively root access on a typical lab host. Its web interface listens on all host interfaces and has no login. Use it only on a trusted lab host and restrict access to the published port. @@ -11,14 +11,14 @@ Add the following lines to a lab topology file to use network-xray with _netlab_ ``` tools: - network-xray: + network_xray: ``` -The URL is printed during **netlab up**. Use **netlab connect network-xray** to display it again. The web port is 8600, or 8600 plus the lab instance ID when using the [multilab plugin](plugin-multilab). +The URL is printed during **netlab up**. Use **netlab connect network_xray** to display it again. The web port is 8600, or 8600 plus the lab instance ID when using the [multilab plugin](plugin-multilab). **Notes:** -* network-xray requires the *clab* provider: it reads the lab name from the generated `clab.yml` file and expects the default `clab--` container names (a custom `prefix` is not supported). +* network-xray works only with containerlab-only topologies and expects the default `clab--` container names (a custom `prefix` is not supported). * network-xray only reads the router state through Docker (`vtysh -c 'show ...'` on FRR, `sr_cli 'info from state ...'` on SR Linux); it does not change the router configuration. The lab directory is mounted read-only. * Router-state collection supports FRR and SR Linux, with limits on supported features and topology layouts. Other devices can appear in the topology without router-state details. _netlab_ does not check whether network-xray supports all the devices used in the lab topology. * Only nodes connected by two-endpoint links are collected. SR Linux collection uses the default network instance and IPv4 unicast routes. diff --git a/docs/extools.md b/docs/extools.md index 0d86507d3f..31b017663f 100644 --- a/docs/extools.md +++ b/docs/extools.md @@ -60,7 +60,7 @@ _netlab_ includes definitions for the following tools: extool/edgeshark.md extool/nso.md extool/nuts.md - extool/network-xray.md + extool/network_xray.md ``` It's relatively easy to add your own tools to the **defaults.tools** dictionary. Read [](dev/extools.md) for more details. diff --git a/netsim/tools/network-xray.yml b/netsim/tools/network_xray.yml similarity index 96% rename from netsim/tools/network-xray.yml rename to netsim/tools/network_xray.yml index 513d5dfa5f..2240b4569c 100644 --- a/netsim/tools/network-xray.yml +++ b/netsim/tools/network_xray.yml @@ -1,5 +1,5 @@ # -# network-xray tool +# network_xray tool # https://github.com/rclab-dev/network-xray # ---