Skip to content

configuration.md

Latest commit

 

History

History
196 lines (144 loc) · 7.23 KB

configuration.md

File metadata and controls

196 lines (144 loc) · 7.23 KB
Raw

Configuration

nrx accepts configuration options in the following order of precedence:

  1. Command-line arguments
  2. Environmental variables
  3. 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)
      --nolinks             disable network links 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)
  -D, --dir DIR             save files into directory DIR (topology name is used by default).
                            nested relative and absolute paths are OK

To pass authentication token, use configuration file or environment variable:
export NB_API_TOKEN='replace_with_valid_API_token'

!!! warning "Security Notice" For security reasons, there is no command-line argument to pass an API token. Use either an environmental variable or a configuration file.

Environmental Variables

As an alternative to a configuration file, use environmental variables to provide NetBox API connection parameters.

# NetBox API URL
export NB_API_URL='https://demo.netbox.dev'

# NetBox API Token
export NB_API_TOKEN='replace_with_valid_API_token'

Several file system path parameters can also be set using environmental variables:

  • OUTPUT_DIR
  • TEMPLATES_PATH
  • PLATFORM_MAP

Configuration File

Use --config <filename> argument to specify a configuration file to use. By default, nrx uses $HOME/.nr/nrx.conf if such file exists.

The sample configuration file is provided as nrx.conf in the repository.

Configuration File Format

The configuration file uses TOML format. Here's an example with commonly used options:

# NetBox API URL. Alternatively, use --api argument or NB_API_URL environmental variable
NB_API_URL = 'https://demo.netbox.dev'

# NetBox API Token. Alternatively, use NB_API_TOKEN environmental variable
NB_API_TOKEN = ''

# Perform TLS certification validation
TLS_VALIDATE = true

# API request timeout, in seconds
API_TIMEOUT = 10

# Netbox API bulk queries optimization
[NB_API_PARAMS]
interfaces_block_size = 4
cables_block_size = 64

# Name of the topology, optional. Alternatively, use --name argument
TOPOLOGY_NAME = 'DemoSite'

# Output format to use for export: 'cyjs' | 'air' | 'clab' | 'cml' | 'graphite' | 'd2'
# Alternatively, use --output argument
OUTPUT_FORMAT = 'clab'

# Override output directory. By default, a subdirectory matching topology name will be created
# Alternatively, use --dir argument. Environment variables are supported
OUTPUT_DIR = '$HOME/nrx'

# Templates search path. Default path is ['./templates','$HOME/.nr/templates']
# Environment variables are supported
TEMPLATES_PATH = ['./templates', '$HOME/.nr/custom', '$HOME/.nr/templates']

# Platform map path. If not provided, 'platform_map.yaml' in the current directory
# is checked first, and then in the TEMPLATES_PATH folders
# Environment variables are supported
PLATFORM_MAP = '$HOME/.nr/platform_map.yaml'

# List of NetBox Device Roles to export
EXPORT_DEVICE_ROLES = ['router', 'core-switch', 'distribution-switch',
                       'access-switch', 'tor-switch', 'server']

# NetBox Site(s) to export. Alternatively, use --sites argument
EXPORT_SITES = ['DM-Akron']

# NetBox tags to export. Alternatively, use --tags argument
EXPORT_TAGS = []

# Note: All devices matching the role, site, and tag filters will be exported,
# including disconnected devices (devices without any cable connections)

# Export device configurations, when available
EXPORT_CONFIGS = true

# Export network links between devices. Alternatively, use --nolinks argument
# When false, only devices are exported without any connections/topology edges
# Useful for: device inventory, documentation, CMDB integration, simplified labs
EXPORT_LINKS = true

# Levels of device roles for visualization
[DEVICE_ROLE_LEVELS]
unknown = 0
server = 0
tor-switch = 1
access-switch = 1
leaf = 1
distribution-switch = 2
spine = 2
core-switch = 3
super-spine = 3
router = 4

Configuration Directory

By default, nrx looks for the following assets in the $HOME/.nr directory:

  • Configuration file: nrx.conf, unless overridden by --config argument
  • Templates: templates, which can be supplemented by additional paths with --templates argument

To initialize the configuration directory, run:

nrx --init

This will create the $HOME/.nr folder and populate it with:

  • A configuration file example (nrx.conf)
  • A compatible version of the templates in the templates subdirectory

Versioned Initialization

You can optionally specify a version when initializing:

nrx --init 0.8.0

This ensures you get templates compatible with a specific version of nrx.

Next Steps