nrx - netreplica exporter

nrx reads a network topology graph from NetBox DCIM system and exports as one of the following:

Containerlab topology for container-based networking labs
NVIDIA Air topology for data center digital twin labs
Cisco Modeling Labs topology for VM-based labs
Device inventory dashboard or a CSV file for sharing with users who don't have direct NetBox access
Network visualization format for Graphite or D2
Graph data as a JSON file in Cytoscape format CYJS
Any other user-defined format using Jinja2 templates

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

This project is in early phase. We're experimenting with the best ways to automate software network lab orchestration. If you have any feedback, questions or suggestions, please reach out to us via the Netreplica Discord server linked above, #netreplica channel in NetDev Community on Slack, or open a github issue in this repository.

Latest capabilities added

The latest releases have a significant set of the new capabilities:

0.9.0 Devices-only export: New --nolinks option to export device inventory without network connections (useful for inventory, documentation, CMDB integration)
0.9.0 Disconnected devices export: All devices matching site/tag/role filters are now exported, including devices without cable connections
0.8.0 NVIDIA Air support
0.7.0 NetBox v4.2 compatibility. Bug fixes. Minimum Python version 3.10.
0.6.2 NetBox v4.1 compatibility
0.6.0 Filter links between devices via interface tags
0.5.0 PyPA packaging and distribution: pip install nrx
0.4.0 Ability to create new output formats without a need for nrx code changes
0.4.0 Mapping between NetBox platform values and node parameters via platform_map.yaml file
0.4.0 $HOME/.nr configuration directory with automatic initialization using --init argument

Find detailed release notes on the Releases page.

Capabilities
Compatibility
Prerequisites
How to install
How to configure
Templates
How to use
Credits
- Original idea and implementation
- Copyright notice

Capabilities

Data sourcing capabilities:

Connects to a NetBox instance over an 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 paramater
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
Exports all device fields from NetBox - templates have access to all device data including custom fields, tags, serial numbers, and any other NetBox field
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. We no longer run tests with previously supported v3.4-4.0 versions, and underlying pynetbox library is no longer tested with these older versions.
Containerlab v0.39, but earlier and later versions should work fine
NVIDIA Air API starting with v9.15.8 (API v2 is used)
Cisco Modeling Labs v2.5
Netreplica Graphite v0.4.0

Prerequisites

Python 3.11+. In the commands below we assume you have python3.11 executable. If it is under a different name, change accordingly.

Choose one of the following installation methods:

Option 1: uv (fast)

uv is a fast Python package installer and runner. It allows running Python tools without installation, or installing them without creating and managing virtual environments manually.

curl -LsSf https://astral.sh/uv/install.sh | sh

Option 2: pip (traditional)

curl -sL https://bootstrap.pypa.io/get-pip.py | python3.11 -
pip install virtualenv

How to install

Option 1: uv

# Install nrx as a persistent tool
uv tool install nrx
nrx --version

# Or run nrx directly without installation
uv tool run nrx --version

Option 2: pip

mkdir -p ~/.venv
python3.11 -m venv ~/.venv/nrx
source ~/.venv/nrx/bin/activate
pip install nrx
nrx --version

Development: git

After running the following commands, you will have a working nrx command in the current directory.

git clone https://github.com/netreplica/nrx.git --recursive
cd nrx
python3.11 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
nrx --version

How to configure

nrx accepts the following configuration options, in the order of precedence:

Command-line arguments
Environmental variables
Configuration file

Command-line arguments

Command-line arguments take the highest priority.

nrx --help
usage: nrx [-h] [-v] [-d] [-I [VERSION]] [-c CONFIG] [-i INPUT] [-o OUTPUT] [-a API] [-s SITE] [-t TAGS] [-n NAME]
           [--noconfigs] [-k | --insecure] [-f FILE] [-M MAP] [-T TEMPLATES] [-D DIR]

nrx - network topology exporter by netreplica

online documentation: https://github.com/netreplica/nrx/blob/main/README.md

optional arguments:
  -h, --help                show this help message and exit
  -v, --version             show version number and exit
  -d, --debug               enable debug output
  -I, --init [VERSION]      initialize configuration directory in $HOME/.nr and exit. optionally, specify a VERSION to initialize with: -I 0.1.0
  -c, --config CONFIG       configuration file, default: $HOME/.nr/nrx.conf
  -i, --input INPUT         input source: netbox (default) | cyjs
  -o, --output OUTPUT       output format: cyjs | air | clab | cml | graphite | d2 or any other format supported by provided templates
  -a, --api API             netbox API URL
  -s, --site SITE           netbox site to export, cannot be combined with --sites
      --sites SITES         netbox sites to export, for multiple tags use a comma-separated list: site1,site2,site3 (uses OR logic)
  -t, --tags TAGS           netbox tags to export, for multiple tags use a comma-separated list: tag1,tag2,tag3 (uses AND logic)
      --interface-tags TAGS netbox tags to filter interfaces to export, for multiple tags use a comma-separated list: tag1,tag2,tag3 (uses OR logic)
  -n, --name NAME           name of the exported topology (site name or tags by default)
      --noconfigs           disable device configuration export (enabled by default)
  -k, --insecure            allow insecure server connections when using TLS
  -f, --file FILE           file with the network graph to import
  -T, --templates TEMPLATES directory with template files, will be prepended to TEMPLATES_PATH list in the configuration file
  -M, --map MAP             file with platform mappings to node parameters (default: platform_map.yaml in templates folder

Nrx

Install / Use

README