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
Name |
Description |
---|---|
Method to call any Nornir Proxy Minion Execution Module function against minions |
|
Runner that uses Salt-Nornir execution module function |
|
Listen to events emitted by Nornir Proxy Minions and log progress to terminal screen |
|
Function to return brief inventory data for certain hosts in a table format |
|
Function to generate boilerplate code for Salt-Nornir plugins |
|
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 belist
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 belist
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 renderingkwargs – 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()
, ifstop_signal is None
, listens and print events until keyboard interrupt hit -ctrl+c
bars
andtree
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 Falsejob_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 30stable – (str, dict or bool) supplied to TabulateFormatter under
table
keyword to control output table formattingheaders – (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
orjob_timeout
option to shorten waiting time,job_timeout
overrides--timeout
. Alternatively, instead of targeting all nornir based proxy minions,tgt
andtgt_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 directorytest
- createsTestsProcessor
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 usingnr.file read
execution module function iffilegroup
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 outputfilegroup – (str)
filegroup
argument value fornr.file read
function to retrieve previously saved devices show commands outputlast – (int)
last
argument value fornr.file read
function, default value is 1Fx – (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 Pluginuses CDP and LLDP protocols peerings data to produce L2 diagram of the network
L3
orIP
- CLI IP Data Pluginuses IP related data to produce L3 diagram of the network
ISIS
- CLI ISIS LSDB Data Pluginuses ISIS LSDB data to produce L3 diagram of the network
OSPF
- CLI OSPFv2 LSDB Data Pluginuses 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