Nornir Runner Module

Nornir Runner module reference.

Note

Runner module functions executed on same machine where salt-master process runs.

Introduction

Nornir-runner module runs on SALT Master and allows to interact with devices behind Nornir proxy minions.

Nornir Runner module functions

Runner Functions Summary

Name	Description
nr.call	Method to call any Nornir Proxy Minion Execution Module function against minions
nr.cfg	Runner that uses Salt-Nornir execution module function nr.cfg to configure devices over CLI
nr.event	Listen to events emitted by Nornir Proxy Minions and log progress to terminal screen
nr.inventory	Function to return brief inventory data for certain hosts in a table format
nr.make_plugin	Function to generate boilerplate code for Salt-Nornir plugins
nr.diagram	Function to retrieve output from devices and produce diagram using N2G library

nr.call

salt_nornir.runners.nornir_proxy_runner_module.call(*args, **kwargs)

Method to call any Nornir Proxy Minion Execution Module function against minions. By default this function targets all Nornir Proxy Minions, allowing to simplify targeting hosts managed by them.

Parameters

• fun – (str) Nornir Proxy Minion Execution Module function name e.g. cli, cfg, nc, gnmi etc.

• tgt – (str) SaltStack Nornir Proxy Minions to target, targets all of them by default - proxy:proxytype:nornir

• tgt_type – (str) SaltStack targeting type to use, default is pillar

• job_retry – (int) how many times to retry if no results returned from all minions, default 0

• job_timeout – (int) seconds to wait for results from minions before retry, default 300s

• progress – progress display type to use - bars, raw, log, if False, no progress displayed

• ret_struct – results return structure, default is dictionary, also can be list

• args – (list) any other arguments to use with call function

• raise_no_tgt_match – (bool) if True (default) raises error if no hosts matched to target

• kwargs – (dict) any other keyword arguments to use with call function

Sample Usage:

salt-run nr.call fun="cfg" "logging host 1.2.3.4" FC="CORE"
salt-run nr.call cli "show clock" FB="*" tgt="nr-minion-id*" tgt_type="glob"

nr.cfg

salt_nornir.runners.nornir_proxy_runner_module.cfg(host_batch=0, first_batch=1, fromdir=None, fromdict=None, tgt='proxy:proxytype:nornir', tgt_type='pillar', job_timeout=300, job_retry=0, progress='log', saltenv='base', interactive=True, ret_struct='dictionary', dry_run=False, **kwargs)

Function that uses Salt-Nornir execution module nr.cfg function to configure network devices over CLI sourcing configuration from file system directory or dictionary.

In interactive mode this function requests input from user on the actions to perform for each batch of hosts, helping to apply configuration to devices in a manually controlled manner.

Parameters

• host_batch – number of hosts to target at a time, targets all by default

• first_batch – number of batch to start with, allows to skip previous batches

• fromdir – directory to source per-host configuration files from and to form host targets list based on files names. Files names must contain only device host name, but can have any extension e.g. ceos1.txt

• fromdict – (dict) dictionary keyed by host names with values of configuration to apply

• tgt – SaltStack Nornir Proxy Minions to target, targets all of them by default

• tgt_type – SaltStack targeting type to use

• job_retry – how many times to retry if no results returned from all minions within given timeout

• job_timeout – seconds to wait for results from minions before retry, default 300s

• progress – progress display type to use - bars, raw, log, if False, no progress displayed

• saltenv – SaltStack environment to pull fromdir data from

• ret_struct – results return structure, default is dictionary, also can be list

• interactive – (bool) if True (Default), asks user for input for each batch of hosts

• dry_run – (bool) if True, uses nr.cfg_gen execution module function to test configuration rendering

• kwargs – any additional arguments to pass to nr.cfg execution module function

Sample usage:

salt-run nr.cfg fromdict='{"ceos*": ["logging host 1.2.3.4", "logging host 1.2.3.5"]}'
salt-run nr.cfg fromdir="salt://templates/config_xyz/" host_batch=5
salt-run nr.cfg fromdir="salt://templates/config_xyz/" host_batch=5 first_batch=10 add_details=False

nr.event

salt_nornir.runners.nornir_proxy_runner_module.event(jid='all', tag=None, progress='log', stop_signal=None)

Function to listen to events emitted by Nornir Proxy Minions. Matched event printed to terminal.

Parameters

• tag – (str) tag regex string, default is nornir\-proxy/.*

• jid – (int, str) Job ID to listen events for, default is all

• progress – (str) progress display mode - log, raw, bars, tree

• stop_signal – (obj) thread Event object, stops listening to events if stop_signal.is_set(), if stop_signal is None, listens and print events until keyboard interrupt hit - ctrl+c

bars and tree progress display modes use Rich library, to properly display various symbols and characters need to make sure to use utf-8 encoding for your environment for example by running these commands:

[root@salt-master ~]# PYTHONIOENCODING=utf-8
[root@salt-master ~]# export PYTHONIOENCODING

nr.inventory

salt_nornir.runners.nornir_proxy_runner_module.inventory(*args, **kwargs)

Function to query inventory data for Nornir hosts and present it in various formats.

Parameters

• FB – first argument - glob pattern matching hostnames of devices behind Nornir

• Fx – additional filters to filter hosts, e.g. FG, FP, FL etc.

• tgt – nornir proxy minion target, by default targets all - “proxy:proxytype:nornir”

• tgt_type – SALT targeting type to use, by default “pillar”

• verbose – boolean, returns nr.nornir inventory output as is if True, flattens to dictionary keyed by devices hostnames if False, default False

• job_retry – how many times to retry command if no return from minions, default 0

• job_timeout – seconds to wait for return from minions, overrides --timeout option, default 30s

• table – (str, dict or bool) supplied to TabulateFormatter under table keyword to control output table formatting

• headers – (list) headers list, default ["minion", "host", "ip", "platform", "groups"]

• reverse – (bool) reverse table order if True, default is False

• sortby – (str) header to sort table by, default is host

• tree – (bool) display inventory in tree format instead of table

Sample Usage:

salt-run nr.inventory ceos1
salt-run nr.inventory FB="host_name_id" FP="10.1.2.0/24"
salt-run nr.inventory "*" tree=True
salt-run nr.inventory "ceos2" verbose=True

If it takes too long to get output because of non-responding/unreachable minions, specify --timeout or job_timeout option to shorten waiting time, job_timeout overrides --timeout. Alternatively, instead of targeting all nornir based proxy minions, tgt and tgt_type can be used to target a subset of them:

salt-run nr.inventory core-sw-31 --timeout=10
salt-run nr.inventory edge-router-42 job_timeout=10 tgt="nornir-proxy-id" tgt_type="glob"

Sample table formatted output:

[root@localhost /]# salt-run nr.inventory IOL1
+---+--------+----------+----------------+----------+--------+
|   | minion |   host   |       ip       | platform | groups |
+---+--------+----------+----------------+----------+--------+
| 0 |  nrp1  |   IOL1   | 192.168.217.10 |   ios    |  lab   |
+---+--------+----------+----------------+----------+--------+

Sample tree formatted output:

Salt-Master
├── salt-minion-nrp1 node
│   └── nrp1 proxy-minion
│       ├── ceos1 10.0.1.4; platform: arista_eos; groups: lab, eos_params
│       └── ceos2 10.0.1.5; platform: arista_eos; groups: lab, eos_params
└── salt-minion-nrp2 node
    └── nrp2 proxy-minion
        ├── csr1000v-1 sandbox-iosxe-latest-1.cisco.com; platform: cisco_ios; groups: None
        ├── iosxr1 sandbox-iosxr-1.cisco.com; platform: cisco_xr; groups: None
        └── nxos1 sandbox-nxos-1.cisco.com; platform: nxos_ssh; groups: None

nr.make_plugin

salt_nornir.runners.nornir_proxy_runner_module.make_plugin(kind, name=None)

Function to generate boilerplate code for Salt-Nornir plugins using Nornir-Salt MakePlugin utility function.

Parameters

• kind – (str) plugin kind to generate code for

• name – (str) plugin file name to use

Supported plugin kinds:

• task - creates Nornir task plugin in current directory

• test - creates TestsProcessor custom test function in current directory

Sample usage:

salt-run nr.make_plugin dir salt-run nr.make_plugin ? salt-run nr.make_plugin task name=run_check_commands

nr.diagram

salt_nornir.runners.nornir_proxy_runner_module.diagram(*args, **kwargs)

Function to retrieve output from devices and produce diagram using N2G library.

This function depends on N2G, TTP and TTP-Templates libraries to obtain list of per-platform commands to retrieve from devices, parse output and build diagram.

Alternatively, instead of getting show commands output from devices, nr.diagram can retrieve previously saved show commands output using nr.file read execution module function if filegroup name provided.

Parameters

• data_plugin – (str) data plugin name to use to process output from devices

• diagram_plugin – (str) N2G diagram plugin name - yed, drawio, v3d

• outfile – (str) OS path to save diagram file, default is ./Output/{data plugin name}_{current time}.{diagram plugin extension}

• save_data – (bool, str) if True, saves commands output results retrieve from devices in “Data” folder next to diagram file, if save_dat a is a string, it must be an OS path to folder where to save devices output. This is useful during troubleshooting to be able to check what output devices return.

• cli – (dict) arguments for nr.cli execution module function to get devices output

• filegroup – (str) filegroup argument value for nr.file read function to retrieve previously saved devices show commands output

• last – (int) last argument value for nr.file read function, default value is 1

• Fx – (str) Nornir filter functions to filter list of devices (hosts) to get output from

• tgt – (str) SaltStack Nornir Proxy Minions to target, targets all of them by default - proxy:proxytype:nornir

• tgt_type – (str) SaltStack targeting type to use, default is pillar

• job_retry – (int) how many times to retry if no results returned from all minions, default 0

• job_timeout – (int) seconds to wait for results from minions before retry, default 300s

• progress – progress display type to use - bars, raw, log, if False, no progress displayed

• kwargs – any additional arguments to use with N2G data plugins

N2G data_plugin names and details:

• L2 - CLI L2 Data Plugin

  uses CDP and LLDP protocols peerings data to produce L2 diagram of the network

• L3 or IP - CLI IP Data Plugin

  uses IP related data to produce L3 diagram of the network

• ISIS - CLI ISIS LSDB Data Plugin

  uses ISIS LSDB data to produce L3 diagram of the network

• OSPF - CLI OSPFv2 LSDB Data Plugin

  uses OSPFv2 LSDB data to produce L3 diagram of the network

Sample usage:

salt-run nr.diagram L2 v3d FB="ceos*"
salt-run nr.diagram L2 v3d FB="ceos*" cli='{"plugin": "scrapli"}' save_data=True
salt-run nr.diagram data_plugin=L2 diagram_plugin=v3d FB="ceos1" outfile="cdp_lldp_diagram.json"
salt-run nr.diagram IP drawio FM="cisco_ios" add_arp=True group_links=True label_interface=True label_vrf=True
salt-run nr.diagram L2 v3d FC="core" group_links=True add_all_connected=True
salt-run nr.diagram L2 yed filegroup="cdp_and_lldp_output" last=3