Skip to content

NetReplica Guide: Configuration and Execution with NetBox

This guide describes the necessary configurations to integrate NetReplica with NetBox. NetReplica is a tool used to replicate and analyze networks, while NetBox is a network asset management platform.

Step 1: Direct Execution with NRX

Note

Before proceeding, ensure that NetReplica and NetBox are installed. You can find more information here: Netreplica Installation

nrx is the NetReplica command-line interface that allows you to configure and execute tasks directly without the need to create a configuration file. Below are the main commands you can use:

Basic Commands

1 Command to Export a Topology:

nrx -c conf/<Topology_Name>.conf

This command uses the .conf configuration file to export the specified topology.

2 Export from a NetBox API URL:

nrx -a http://<netbox_ip>:<port> -t '<tags>' -s '<site>' -o clab

This command allows exporting using parameters directly on the command line, such as the NetBox API URL, tags, site, and output format.

3 Using Authentication Tokens:

To pass the authentication token without using a configuration file:

export NB_API_TOKEN='your_token_here'
nrx -a http://<netbox_ip>:<port> -t '<tags>' -s '<site>' -o clab

4 Specify the Output Directory:

nrx -c conf/<Topology_Name>.conf -D /path/to/output

This command allows you to define a specific directory for the output of the exported files.

5 Ignore TLS Certificate:

nrx -c conf/<Topology_Name>.conf --insecure

This command disables TLS certificate verification.

Common nrx Arguments

  • -c, --config CONFIG: Defines the configuration file to be used.
  • -a, --api API: Defines the NetBox API URL.
  • -s, --site SITE: Specifies the NetBox site to be exported.
  • -t, --tags TAGS: Defines the NetBox tags to be exported.
  • -o, --output OUTPUT: Defines the output format (e.g., 'clab', 'cyjs').
  • -D, --dir DIR: Defines the output directory.
  • --insecure: Disables TLS certificate verification.

Step 2: .conf File Configuration

The .conf configuration file provides a structured way to define the variables required for topology export. It is particularly useful when you want to reuse the same settings or when there are many options to define.

Of course, here is the configuration file with a detailed explanation for each field:

Summarized Configuration File

NB_API_URL           = 'http://localhost:8000'    # NetBox API URL or NB_API_URL env var
NB_API_TOKEN         = ''                         # API Token or NB_API_TOKEN env var
TLS_VALIDATE         = false                      # TLS certificate validation
API_TIMEOUT          = 10                         # API timeout (s)

TOPOLOGY_NAME        = 'lab'         # Topology name
OUTPUT_FORMAT        = 'clab'        # Output format: gml | cyjs | clab
OUTPUT_DIR           = 'conf/lab'    # Output directory (default: ./<topology>)
TEMPLATES_PATH       = ['templates']
PLATFORM_MAP         = 'templates/platform_map.yaml'   # Platform mapping file
EXPORT_CONFIGS       = true           # Export configs if available

EXPORT_DEVICE_ROLES  = []             # Device roles to export
EXPORT_SITES         = ['DM-Akron']   # Sites to export
EXPORT_TAGS          = []             # Tags to export

NetBox API Configurations

1. NB_API_URL

  • Description: NetBox API URL.
  • Usage: Defines the address of the NetBox instance to be queried by NetReplica.
  • Example: 'http://localhost:8000'.

2. NB_API_TOKEN

  • Description: NetBox API authentication token.
  • Usage: Required to authenticate requests to the API.
  • Example: '' (should be filled with the actual token).

3. TLS_VALIDATE

  • Description: Controls TLS certificate validation.
  • Usage: true enables validation (recommended in production); false disables (useful in testing).
  • Example: false.

4. API_TIMEOUT

  • Description: Timeout for API requests, in seconds.
  • Usage: Defines how long NetReplica waits for a response before considering the request failed.
  • Example: 10.

Export Configurations

5. TOPOLOGY_NAME

  • Description: Name of the exported topology.
  • Usage: Identifies the exported files and groups the topology.
  • Example: 'lab'.

6. OUTPUT_FORMAT

  • Description: Format of the exported data.
  • Usage: Can be 'gml', 'cyjs', or 'clab'.
  • Example: 'clab'.

7. OUTPUT_DIR

  • Description: Destination directory for exported files.
  • Usage: Overrides the default export directory.
  • Example: 'conf/lab'.

8. TEMPLATES_PATH

  • Description: List of template directories used in the export.
  • Usage: Allows locating custom templates.
  • Example: ['templates'].

9. PLATFORM_MAP

  • Description: Platform mapping file.
  • Usage: Defines how each device platform will be represented in the exported files.
  • Example: 'templates/platform_map.yaml'.

10. EXPORT_CONFIGS

  • Description: Defines whether device configurations should be exported.
  • Usage: true includes the configs, false ignores them.
  • Example: true.

Device Filter Configurations

11. EXPORT_DEVICE_ROLES

  • Description: List of device roles to be exported.
  • Usage: Filters which devices will be included.
  • Example: [] (exports all if empty).

12. EXPORT_SITES

  • Description: List of NetBox sites to be exported.
  • Usage: Filters devices by site.
  • Example: ['DM-Akron'].

13. EXPORT_TAGS

  • Description: List of tags used as a filter for export.
  • Usage: Only devices with these tags will be exported.
  • Example: [] (exports all if empty).

This configuration file allows for detailed customization of how NetReplica interacts with NetBox and exports data, helping to meet specific visualization and export needs.

Next Steps

Now to delve deeper, you can check out the next guide that shows how to create and configure new Templates and add new images to netreplica. check it out here NetReplica Creating Templates.

References