Skip to content

nrx reads data center inventory from NetBox and exports as one of:

It can also read a topology data previously saved as a CYJS file to convert it into other formats.

Latest Updates

  • 0.8.0 - NVIDIA Air export format.
  • 0.7.0 - NetBox v4.2 compatibility. Bug fixes. Minimum Python version 3.10
  • 0.6.0 - Filter links between devices via interface tags

Find detailed release notes on the Releases page.

Quick Start

Install

For detailed installation instructions, see the Installation Guide.

uv tool install nrx
nrx --init

Connect to NetBox

In this example we're using NetBox Demo instance to source data. Login to the demo instance, create an API token and set it as an environment variable:

export NB_API_URL='https://demo.netbox.dev'
export NB_API_TOKEN='replace_with_valid_API_token'

Export Containerlab topology

Run nrx --output clab to export a topology graph from NetBox in Containerlab format. Here's an example exporting the "DM-Albany" site:

nrx --output clab --site DM-Albany

This will create:

  • DM-Albany/DM-Albany.clab.yaml - Containerlab topology file

Deploy the Topology

Deploy the topology using Containerlab:

sudo -E clab deploy -t DM-Albany/DM-Albany.clab.yaml

Key Capabilities

Data Sourcing

  • Connects to a NetBox instance over API using a user-provided authentication token
  • Exports a network topology graph with Devices that:
    • belong to a Site specified with --site parameter
    • have a list of Tags specified with --tags parameter
  • A combination of the two methods above is possible
  • Only Devices with Roles from a customizable list will be exported
  • Direct connections between Devices via Cables will be exported as topology edges
  • Connections via Patch Panels and Circuits will be exported as well with help of NetBox Cable Tracing API
  • Only Ethernet connections will be exported
  • Device configurations will be rendered and exported if not empty
  • As an alternative to sourcing live data from NetBox, imports a graph from a previously exported file in CYJS format

Export Capabilities

  • Exports the graph as a Containerlab (Clab) topology definition file in YAML format
  • Exports the graph as a NVIDIA Air topology definition file in JSON format
  • Exports the graph as a Cisco Modeling Labs (CML) topology definition file in YAML format
  • Exported device configurations can be used as startup-config for Containerlab and CML
  • Exports the graph in formats for visualization with Graphite or D2
  • User-defined output formats using Jinja2 templates
  • Uses NetBox Device Platform slug field to identify node templates when rendering the export file
  • Customizable mapping between NetBox Platform values and node parameters via platform_map.yaml file
  • Creates mapping between real interface names and interface names used by the supported lab tools
  • Calculates level and rank values for each node based on Device Role to help visualize the topology
  • Exports the graph into CYJS format that can be later converted into a topology definition file, or used by 3rd party software

Compatibility

The following software versions were tested for compatibility with nrx:

  • NetBox v4.1-v4.2 (previously supported v3.4-4.0 versions are no longer tested)
  • Containerlab v0.39 (earlier and later versions should work fine)
  • NVIDIA Air API v9.15.8+ (API v2 is used)
  • Cisco Modeling Labs v2.5
  • Netreplica Graphite v0.4.0

Next Steps