diff --git a/docs/extool/network_xray.md b/docs/extool/network_xray.md new file mode 100644 index 0000000000..9ced1c7080 --- /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 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. +``` + +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 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. +* 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..31b017663f 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..2240b4569c --- /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'