Nornir Execution Module
SaltStack Nornir Execution Module exposes functionally of Nornir Proxy Minion to work with devices and systems. Users can invoke Execution Modules functionality using SALT CLI or one of SALT API - Python, REST. Usually, execution modules are the modules that users work with a lot because they directly mapped to managed system functionality such as CLI or NETCONF server.
Introduction
Nornir Execution Module complements Nornir Proxy Minion Module to interact with devices over SSH, Telnet, NETCONF or any other methods supported by Nornir connection plugins.
Things to keep in mind:
execution module functions executed on same machine where proxy-minion process runs
multiprocessing
set toTrue
is recommended way of running Nornir proxy-minionwith multiprocessing on, dedicated process starts for each job
tasks executed one after another, but task execution against hosts happening in order controlled by logic of Nornir Runner in use, usually in parallel using threading.
Commands timeout
It is recommended to increase
salt command timeout
or use --timeout=60
option to wait for minion return, as all together it might take more than
5 seconds for task to complete. Alternatively, use --async
option and query results afterwards:
[root@localhost /]# salt nrp1 nr.cli "show clock" --async
Executed command with job ID: 20210211120453972915
[root@localhost /]# salt-run jobs.lookup_jid 20210211120453972915
nrp1:
----------
IOL1:
----------
show clock:
*08:17:22.691 EET Sat Feb 13 2021
IOL2:
----------
show clock:
*08:17:22.632 EET Sat Feb 13 2021
[root@localhost /]#
AAA considerations
Quiet often AAA servers (Radius, Tacacs) might get overloaded with authentication and authorization requests coming from devices due to Nornir establishing connections with them, that effectively results in jobs failures.
To overcome that problem Nornir Proxy Module uses
Nornir Salt RetryRunner plugin
by default. RetryRunner
developed to address aforementioned issue in addition to implementing
retry logic.
Targeting Nornir Hosts
Nornir can manage many devices and uses it’s own inventory,
additional filtering Fx
functions introduced in
Nornir Salt library
to narrow down tasks execution to certain hosts/devices.
Sample command to demonstrate targeting capabilities:
salt nrp1 nr.cli "show clock" FB="R*" FG="lab" FP="192.168.1.0/24" FO='{"role": "core"}'
Jumphosts or Bastions
RetryRunner
included in Nornir Salt library supports nr.cli
and nr.cfg
with plugin="netmiko"
and nr.nc
with plugin="ncclient"
functions to
interact with devices behind SSH Jumphosts.
Sample Jumphost definition in host’s inventory data of proxy-minion pillar:
hosts:
LAB-R1:
hostname: 192.168.1.10
platform: ios
password: user
username: user
data:
jumphost:
hostname: 172.16.0.10
port: 22
password: admin
username: admin
RetryRunner
on first task execution will initiate single connection to Jumphost,
and will use it to proxy connections to actual devices.
Execution Module Functions Summary
Table to summarize functions available in Nornir Proxy Execution Module and their purpose.
nr.function |
description |
supported plugins |
---|---|---|
Function to modify devices configuration over ssh or telnet connections |
napalm (default), netmiko, scrapli |
|
Function to generate devices configuration using SALT templating system with Nornir inventory, mainly for testing purposes |
||
Function for show commands output collection over ssh or telnet |
netmiko (default), scrapli |
|
To diff content of files or network with files
saved by |
||
Function to execute actions with a set of steps calling other execution functions. Allows to construct simple work flows. |
||
Function to work with files saved by
|
||
To search for various information in files saved
by |
||
Interact with devices using gNMI protocol |
pygnmi |
|
To run HTTP requests against API endpoints |
requests |
|
This function is to save task results in files
using |
||
Function to work with devices using NETCONF |
ncclient (default), scrapli_netconf |
|
Integration with Netbox DCIM |
||
Network related utilities |
||
Function to call Nornir Utility Functions |
||
Function to manage davices over SNMP protocol |
||
Function to run any Nornir task plugin |
||
Function to test show commands output produced by nr.cli function |
netmiko (default), scrapli |
|
Function to run TCP ping to devices’ hostnames |
Common CLI Arguments
A number of Command Line Interface arguments can be supplied to Nornir Proxy Module Execution Module functions to influence various aspects of task execution process.
Some of the command line options use Nornir Processor plugins. This plugins tap into task execution flow to perform additional actions or process task results.
To invoke processor plugin need to supply execution module functions with processors arguments providing required parameters to control processor plugin behavior.
All supported processors executed in this order:
event_progress ->
-> DataProcessor ->
-> iplkp ->
-> xml_flake ->
-> xpath ->
-> jmespath ->
-> match ->
-> run_ttp ->
-> ntfsm ->
-> TestsProcessor ->
-> DiffProcessor ->
-> ToFileProcessor
Name |
Description |
---|---|
Add task execution details to results |
|
Filters to target subset of devices using FFun Nornir-Salt function |
|
context |
Overrides context variables passed by render to |
Saves full task execution results to Nornir in-memory (RAM) Inventory |
|
defaults |
Default template context passed by render to |
Calls Nornir-Salt DiffProcessor to produce results difference |
|
Allows to call any function supported by Nornir-Salt DataProcessor |
|
Renders arguments content using Salt cp module |
|
Saves complete task results to local file system using Nornir-Salt DumpResults function |
|
If True, emit events on Salt Events Bus for failed tasks |
|
If True, emit events on Salt Events Bus for tasks execution progress |
|
Saves host’s task execution results to host’s in-memory (RAM) Inventory data |
|
Performs in CSV file or DNS lookup of IPv4 and IPv6 addresses to replace them in output |
|
uses JMESPath library to run query against structured results data |
|
Job data, string, list or dictionary to load using slsutil.rendered function |
|
Filters text output using Nornir-Salt DataProcessor match function |
|
Parse nr.cli output using TextFSM ntc-templates |
|
Task parameters to influence RetryRunner execution logic |
|
Renders arguments content using Salt renderer system |
|
Calls Nornir-Salt DataProcessor run_ttp function to parse results using TTP |
|
saltenv |
Salt Environment name to use with render and download to source files, default is |
Formats results to text table using Nornir-Salt TabulateFormatter |
|
template_engine |
Template Engine name to use with render to render files, default is |
Run tests for task results using Nornir-Salt TestsProcessor |
|
Saves results to local file system using Nornir-Salt ToFileProcessor |
|
Transforms results to structured data using Nornir-Salt ResultSerializer |
|
Uses Nornir-Salt DataProcessor |
|
Uses Nornir-Salt DataProcessor |
|
Worker to use for task, supported values |
add_details
Controls Nornir-Salt ResultSerializer function to form task results with or without task execution details.
add_details by default is False for most of the functions, but can be adjusted accordingly to produce desired results structure.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http, nr.gnmi
CLI Arguments:
add_details
- boolean, if True will add task execution details to the results
Sample usage:
salt nrp1 nr.cli "show clock" add_details=True
salt nrp1 nr.cli "show clock" add_details=True to_dict=False
salt nrp1 nr.cli "show clock" add_details=True to_dict=True
Fx
Uses Nornir-Salt FFun
function to form a subset of hosts to run this task for.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.test, nr.nc, nr.do, nr.http, nr.tping, nr.inventory
CLI Arguments:
Fx
- any of Nornir Salt FFun function filters
Sample usage:
salt nrp1 nr.cli "show clock" FB="R*" FG="lab" FP="192.168.1.0/24" FO='{"role": "core"}'
dcache
Saves full task execution results to Nornir defaults
in-memory (RAM) inventory data. Saved
information non-persistent across Proxy Minion reboots.
Primary usecase is to share task results between tasks for rendering, targeting or processing.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http, nr.tping, nr.gnmi
CLI Arguments:
dcache
- nornir inventorydefaults
data dictionary key name to save results under or if set to boolean True, usesdcache
as a key name
Sample usage:
salt nrp1 nr.cli "show clock" dcache="show_clock_output"
salt nrp1 nr.cli "show clock" dcache=True
To view in-memory defaults
inventory can use utility function:
salt npr1 nr.nornir inventory
To clean up cached data can either restart Proxy Minion or use utility function:
salt npr1 nr.nornir clear_dcache cache_keys='["key1", "key2"]'
diff
Uses Nornir Salt DiffProcessor
to produce difference between current task results and previous results saved by ToFileProcessor
.
Supported functions: nr.task, nr.cli, nr.nc, nr.do, nr.http, nr.gnmi
CLI Arguments:
diff
-ToFileProcessor
file group name to run difference withlast
-ToFileProcessor
file version number, default is 1
Sample usage:
salt nrp1 nr.cli "show ip route" diff="show_route" last=1
dp
Uses Nornir-Salt DataProcessor plugin designed to help with processing Nornir task results.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http, nr.gnmi
CLI Arguments:
dp
- data processor functions list to process task results
CLI argument dp
can be comma-separated string or list of DataProcessor
function names
or dictionary keyed by DataProcessor
function name with values set to dictionary which
contains arguments for DataProcessor
function.
Sample usage:
salt nrp1 nr.nc get_config dp="xml_to_json"
salt nrp1 nr.nc get_config dp="load_xml, flatten"
salt nrp1 nr.nc get_config dp='["load_xml", "flatten"]'
salt nrp1 nr.cli "show version" dp='[{"fun": "match", "pattern": "Version"}]'
salt nrp1 nr.nc get_config source=running dp='[{"fun": "xml_flatten"}, {"fun": "key_filter", "pattern": "*bgp*, *BGP*"}]'
Last example will call xml_flatten
function first following with key_filter
with
{"pattern": "*bgp*, *BGP*"}
dictionary arguments.
download
SaltStack has cp module,
allowing to download files from Salt Master, donwload
keyword can be used to indicate
arguments that should download content for.
Supported URL schemes are: salt://, http://, https://, ftp://, s3://, swift:// and file:// (local filesystem).
Keys listed in download
argument ignored by render argument even if same key contained
with render
argument. Arguments names listed in donwload
are not rendered, only loaded
from Salt Master.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http
CLI Arguments:
download
- list of arguments to download content for, default is["run_ttp", "iplkp"]
For example, to render content for filename argument:
salt nrp1 nr.cfg filename="salt://templates/logging_config.txt" download='["filename"]'
Primary use cases for this keyword is revolving around enabling or disabling downloading
and rendering for certain arguments. Execution Module Functions adjust download
keyword
list content by themselves and usually do not require manual modifications.
dump
Salt Event bus has limit on the amount of data it can transfer from Proxy Minion to Master, because of that, results produced by Proxy minion might get trimmed beyond certain threshold.
This can be addressed in several ways:
increase event bus data transmission threshold
use returner to return results to external database or other system
In addition to above option, Nornir Proxy Minion can make use of Nornir Salt DumpResults function to save complete results of task execution to local file system. That data can be later retrieved from proxy Minion machine.
Another usecase that DumpResults
function can help to solve is results logging for audit,
review or historical data purposes.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.test, nr.nc, nr.do, nr.http
CLI Arguments:
dump
-ToFileProcessor
file group name where to save results
Sample usage:
salt nrp1 nr.cli "show run" dump="show_run_output"
Results saved to proxy minion local file system under files_base_path
, default is:
/var/salt-nornir/{proxy_id}/files/{filegroup}__{timestamp}__{rand}__{proxy_id}.txt
Where:
proxy_id
- Nornir Proxy Minion IDfilegroup
-ToFileProcessor
file group name where to save resultstimestamp
- date timestamprand
- random integer between 1 and 1000
event_failed
Salt Event bus allows Proxy Minion processes to emit events, so that salt-master reactor system can act upon them and trigger execution of various actions.
event_failed
CLI argument instructs Nornir Proxy minion to emit events for failed tasks.
Event’s tag formed using this formatter:
nornir-proxy/{proxy_id}/{host}/task/failed/{name}
Where:
proxy_id
- Nornir Proxy Minion IDhost
- hostname of device that failed this taskname
- name of the failed task
Event body contains task execution results dictionary.
Failed tasks determined using results failed
or success
attributes, if failed
is True or success
is False task considered as failed.
Combining event_failed
with nr.test
function allows to implement event driven
automation in response to certain tests failure. Each test translated to a separate
task result and event_failed
emit events on a per-test basis enabling to construct
very granular react actions on Salt Master.
Sample event content:
nornir-proxy/nrp1/ceos1/task/failed/nornir_salt.plugins.tasks.nr_test {
"_stamp": "2022-02-11T11:14:16.081755",
"cmd": "_minion_event",
"data": {
"changed": false,
"connection_retry": 3,
"diff": "",
"exception": "",
"failed": true,
"host": "ceos1",
"name": "nornir_salt.plugins.tasks.nr_test",
"result": "Traceback (most recent call last):\n File "/usr/local/lib/python3.6/site-packages/nornir/core/task.py", line 99, in start\n r = self.task(self, **self.params)\n File "/usr/local/lib/python3.6/site-packages/nornir_salt/plugins/tasks/nr_test.py", line 65, in nr_test\n raise RuntimeError(excpt_msg)\nRuntimeError\n",
"task_retry": 3
},
"id": "nrp1",
"pretag": null,
"tag": "nornir-proxy/nrp1/ceos1/task/failed/nornir_salt.plugins.tasks.nr_test"
}
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.test, nr.nc, nr.do, nr.http, nr.gnmi, nr.file, nr.diff, nr.find, nr.learn
CLI Arguments:
event_failed
- boolean, default is False, if True will emit events for failed tasks.
Sample usage:
salt nrp1 nr.test suite="salt://tests/suite.txt" event_failed=True
event_progress
Argument to use Nornir-Salt SaltEventProcessor
plugin to emit task execution progress events to
SaltStack Events Bus. This is mainly useful for tracking tasks’ flow, debugging and general assurance.
For example, event_progress
used by nr.call
Runner Module function to capture and print
messages to terminal informing user about task execution progress.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.test, nr.nc, nr.do, nr.http, nr.gnmi, nr.file, nr.diff, nr.find, nr.learn
CLI Arguments:
event_progress
- boolean, default is False, if True will emit events for tasks progress.
Sample usage:
salt nrp1 nr.cli "show clock" event_progress=True
To listen to events generated by Proxy Minion when event_progress=True
can open additional session
to master server and run salt-run nr.event
runner function.
Nornir Proxy Minion pillar parameter event_progress_all
can be used to control default behavior,
event_progress
overrides event_progress_all
parameter.
hcache
Saves individual host’s task execution results in host’s in-memory (RAM) inventory data. Saved information non-persistent across Proxy Minion reboots.
Primary usecase is to share task results data between tasks for rendering, targeting or processing.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http, nr.tping, nr.gnmi
CLI Arguments:
hcache
- host’s data dictionary key name to save results under or if set to boolean True, useshcache
as a key name
Sample usage:
salt nrp1 nr.cli "show clock" hcache="show_clock_output"
salt nrp1 nr.cli "show clock" hcache=True
To view in-memory inventory can use utility function:
salt npr1 nr.nornir inventory FB="hosname-1"
To clean up cached data can either restart Proxy Minion or use utility function:
salt npr1 nr.nornir clear_hcache FB="hosname-1"
salt npr1 nr.nornir clear_hcache cache_keys='["key1", "key2"]'
iplkp
Uses Nornir-Salt DataProcessor
iplkp function
function to lookup IPv4 and IPv6 addresses using DNS or CSV file and replace
them in device output with lookup results.
Supported functions: nr.cli
CLI Arguments:
iplkp
- value can bedns
to indicate that need to use DNS or reference to a CSV file on Salt Master in a formatsalt://path/to/file.txt
First column in CSV file must be IPv4 or IPv6 address, second column should contain replacement value.
iplkp
uses this formatter to replace IP addresses in results: {ip}({lookup})
-
where ip
is the original IP address string and lookup
is the lookup
result value.
Sample usage:
salt nrp1 nr.cli "show ip int brief" iplkp="salt://lookup/ip.txt"
salt nrp1 nr.cli "show ip int brief" iplkp="dns"
Where salt://lookup/ip.txt
content is:
ip,hostname
10.0.1.4,ceos1:Eth1
10.0.1.5,ceos2:Eth1
And this would be the results produced:
nrp1:
----------
ceos1:
----------
show ip int brief:
Address
Interface IP Address Status Protocol MTU Owner
--------------- ----------------- ------------ -------------- ----------- -------
Ethernet1 10.0.1.4(ceos1:Eth1)/24 up up 1500
Loopback1 1.1.1.1/24 up up 65535
iplkp
replaced 10.0.1.4
with lookup results 10.0.1.4(ceos1:Eth1)
in device output.
jmespath
Uses Nornir-Salt DataProcessor
jmespath function
to run JMESPath query against structured data results or JSON string.
Supported functions: nr.task, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http, nr.cli, nr.gnmi
CLI Arguments:
jmespath
- JMESPath query expression string
Sample usage:
salt nrp1 nr.task nornir_napalm.plugins.tasks.napalm_get getters='["get_interfaces"]' jmespath='interfaces'
job_data
Any arbitrary data to load and make available within template under job_data
key. Uses
slsutil.renderer
execution module function. In addition, job_data
key added to Nornir host’ data["__task__"]
dictionary to make loaded data available to task plugins.
Supported functions: nr.task, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http, nr.cli, nr.gnmi, nr.snmp
Main purpose of job_data
is to load any arbitrary data from any of supported URLs -
salt://, http://, https://, ftp://, s3://, swift:// and file:// (proxy minion
local filesystem) - rendering and serializing the content using slsutil.renderer
function.
That way proxy minion pillar can contain only information required to connect
to devices and information for hosts targeting, any other parameters can be
loaded from YAML or JSON files on demand.
Job Data is analogous to SaltStack map files, but made to be more flexible.
job_data
argument accepts string, list or dictionary, proxy minion
downloads data from provided URLs.
Sample usage:
salt nrp1 nr.cfg_gen "router bgp {{ job_data.bgp.asn }}" job_data="salt://data/params.yaml"
salt nrp1 nr.cfg_gen "router bgp {{ job_data[0].bgp.asn }}" job_data='["salt://data/params.yaml", "salt://data/syslog.json"]'
salt nrp1 nr.cfg_gen "router bgp {{ job_data['bgp'].bgp.asn }}" job_data='{"bgp": "salt://data/params.yaml", "syslog": "salt://data/syslog.json"}'
salt nrp1 nr.cfg_gen "logging {{ job_data['syslog'].servers[0] }}" job_data='{"bgp": "salt://data/params.yaml", "syslog": "salt://data/syslog.json"}'
Where /etc/salt/data/params.yaml
file content is:
bgp:
asn: 65555
rid: 1.1.1.1
peers:
- ip: 1.2.3.4
asn: 65000
- ip: 4.3.2.1
asn: 65123
And /etc/salt/data/syslog.json
file content is:
#!json
{
"servers": ["1.2.3.4", "4.3.2.1"],
"facility": "local",
"bufered_size": "64242"
}
job_data
content temporarily saved into host’s inventory data
for task execution and removed afterwards. Example of how to access
job_data
within Nornir task function:
from nornir.core.task import Result, Task
def task(task):
"This task echoes back job_data content"
task.name = "job_data_echo"
job_data = task.host["job_data"]
return Result(host=task.host, result=job_data)
Assuming above task saved at /etc/salt/tasks/job_data_echo.py
,
running this command:
salt nrp1 nr.task plugin="salt://tasks/job_data_echo.py" job_data='{"foo": 123}' FB=ceos1
Returns this result:
nrp1:
----------
ceos1:
----------
job_data_echo:
----------
foo:
123
match
Uses Nornir-Salt DataProcessor
match function
to filter text results using regular expression pattern.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http
CLI Arguments:
match
- regex pattern to search forbefore
- integer indicating how many lines before match to include in results
Sample usage:
salt nrp1 nr.cli "show version" match="Version.*"
salt nrp1 nr.cli "show version" match="Version.*" before=1
ntfsm
Uses Nornir-Salt DataProcessor
ntfsm function
to parse show commands output using TextFSM ntc-templates.
Supported functions: nr.cli
CLI Arguments:
ntfsm
- bool, if True uses TextFSM ntc-templates to parse output
Sample usage:
salt nrp1 nr.cli "show version" ntfsm=True
salt nrp1 nr.cli "show version" dp=ntfsm
RetryRunner parameters
A number of Nornir-Salt Proxy Minion execution module functions support RetryRunner parameters to influence task execution logic.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http, nr.gnmi, nr.test
CLI Arguments:
run_connect_retry
- number of connection attemptsrun_task_retry
- number of attempts to run taskrun_creds_retry
- list of connection credentials and parameters to retry while connecting to devicerun_num_workers
- number of threads for tasks executionrun_num_connectors
- number of threads for device connectionsrun_reconnect_on_fail
- if True, re-establish connection on task failure
Sample usage - retry various connection parameters:
salt nrp1 nr.cfg filename="salt://templates/logging_config.txt" run_creds_retry='["local_creds", "dev_creds"]'
Sample usage - disable task and connection retries:
salt nrp1 nr.cfg filename="salt://templates/logging_config.txt" run_connect_retry=0 run_task_retry=0
Sample usage - run tasks sequentially on hosts one by one:
salt nrp1 nr.cfg filename="salt://templates/logging_config.txt" run_num_workers=1
Sample usage - set rate of device’s connections to 5 per-second:
salt nrp1 nr.cfg filename="salt://templates/logging_config.txt" run_num_connectors=5
render
SaltStack has renderers system, that system allows to render text files content while having access to all Salt Execution Module Functions and inventory data.
If render argument value points to one of supported URL schemes are: salt://, http://, https://, ftp://, s3://, swift:// and file:// (local filesystem). File content downloaded from specified URL prior to rendering.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http, nr.gnmi
CLI Arguments:
render
- list of argument to render content for, default is["config", "data", "filter", "filter_", "filters", "filename"]
For example, to render content for filename argument:
salt nrp1 nr.cfg filename="salt://templates/logging_config.txt" render='["filename"]'
Primary use cases for this keyword is revolving around enabling or disabling rendering for
certain arguments. Execution Module Functions adjust render
keyword list content by
themselves and usually do not require any modifications.
run_ttp
Uses Nornir-Salt DataProcessor
run_ttp function
to parse text results using TTP library and produce structured data.
Supported functions: nr.task, nr.cli, nr.do
CLI Arguments:
run_ttp
- TTP template referencettp_structure
- TTP results structure, supported values:flat_list
(default),list
ordictionary
Sample usage:
salt nrp1 nr.cli "show version" run_ttp="Version: {{ version }}"
salt nrp1 nr.cli "show version" run_ttp="salt://ttp/parse_version.txt"
salt nrp1 nr.cli "show ip arp" run_ttp="ttp://platform/cisco_ios_show_ip_arp.txt"
salt nrp1 nr.cli run_ttp="salt://ttp/parse_commands.txt" ttp_structure=list
TTP templates can be specified inline, sourced from salt-master using salt://path
or from
TTP Templates collection repository using ttp://path
providing that it is installed on
proxy minion machine.
run_ttp
with nr.cli
function also supports sourcing commands to collect from devices
from within TTP template input tags using commands
argument. For example:
<input name="version">
commands = ["show version"]
</input>
<input name="interfaces">
commands = ["show run"]
</input>
<group name="facts" input="version">
cEOS tools version: {{ tools_version }}
Kernel version: {{ kernel_version }}
Total memory: {{ total_memory}} kB
Free memory: {{ total_memory}} kB
</group>
<group name="interfaces" input="interfaces">
interface {{ interface }}
description {{ description | re(".*") }}
ip address {{ ip }}/{{ mask }}
</group>
Supplying above template to nr.cli
function with run_ttp
argument will result
in running show version
and show run
commands, placing output in appropriate
inputs and parsing it with dedicated groups, returning parsing results.
table
Uses Nornir Salt TabulateFormatter function to transform task results in a text table representation.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.test, nr.nc, nr.do
CLI Arguments:
table
- boolean or table type indicator, supported values: True,brief
,extend
,terse
headers
- list of table headers to form table forheaders_exclude
- list of table headers to exclude from final table resultssortby
- name of the header to sort table by, default ishost
reverse
- if True, sorts table in reverse order, False by default
Sample usage:
salt nrp1 nr.cli "show clock" table=brief
salt nrp1 nr.cli "show clock" table=True
salt nrp1 nr.cli "show clock" table=True headers="host, results"
salt nrp1 nr.cli "show clock" table=True headers="host, results" sortby="host" reverse=True
tests
Uses Nornir Salt TestsProcessor plugin to test task results.
Tests can be specified inline as a list of lists or can reference tests suite
file on salt-master using salt://path
format.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http
CLI Arguments:
tests
- reference to a list of tests to runfailed_only
- boolean, default is False, to indicate if to return results for failed tests onlyremove_tasks
- boolean, default is True, to indicate if need to remove tested task results
Sample usage:
salt nrp1 nr.cli "show version" "show clock" tests='[["show version", "contains", "5.2.9b"], ["show clock", "contains", "Source: NTP"]]'
salt nrp1 nr.cli "show version" "show clock" tests="salt://tests/suite.txt"
tf
Uses Nornir Salt
ToFileProcessor plugin
to save task execution results to proxy minion local file system under files_base_path
, default is
/var/salt-nornir/{proxy_id}/files/
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http, nr.gnmi
CLI Arguments:
tf
-ToFileProcessor
file group name where to save resultstf_skip_failed
- boolean, default is False, if True, will not save results for failed tasks
Sample usage:
salt nrp1 nr.cfg "logging host 1.1.1.1" tf="logging_config"
salt nrp1 nr.cfg "logging host 1.1.1.1" tf="logging_config" tf_skip_failed=True
tf_skip_failed
can be useful when only want to save results to file for non failed tasks.
For example, if RetryRunner
runs task and it fails on first attempt but succeed on second,
it might not make sense to store failed task results, which is the case by default, tf_skip_failed
help to alter that behavior.
to_dict
Uses Nornir Salt ResultSerializer function to transform task results in a structured data - dictionary or list.
This function used by default for all task results unless TabulateFormatter
table
argument provided.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http, nr.gnmi
CLI Arguments:
add_details
- boolean, default is False, if True will add task execution details to the resultsto_dict
- boolean, default is True, if False will produce results list structure
Sample usage:
salt nrp1 nr.cli "show clock" add_details=True
salt nrp1 nr.cli "show clock" add_details=True to_dict=False
xml_flake
Uses Nornir-Salt DataProcessor
xml_flake function
to flatten XML results structure to dictionary and filter dictionary keys using glob pattern.
Supported functions: nr.task, nr.nc, nr.do, nr.http
CLI Arguments:
xml_flake
- glob pattern to filter keys
Sample usage:
salt nrp1 nr.nc get_config xml_flake="*bgp:config*"
xpath
Uses Nornir-Salt DataProcessor
xpath function
to run xpath query against XML results.
Supported functions: nr.task, nr.nc, nr.do, nr.http
CLI Arguments:
xpath
- LXML library supported xpath expression
Sample usage:
salt nrp1 nr.nc get_config xpath='//config/address[text()="1.1.1.11"]'
Beware that XML namespaces removed from XML results before running xpath
on them. If this behavior is not desirable, need to use dp
keyword instead
with required arguments for xpath
function including namespaces map dictionary.
xpath
function processes results received from device and executed locally on the minion
machine, if you need to filter results returned from device, for nr.nc
function consider
using filter arguments. The complication is that if, for example, you running
get_config
NETCONF operation, full device config retrieved from device and passed via xpath
function on proxy minion, this could be processing intensive especially for big configurations
combined with significant number of devices simultaneously returning results.
worker
Starting with Nornir 0.9.0 support added for several Nornir Instances with dedicated worker threads,
allowing to greatly increase Proxy Minion task execution throughput. If no worker
argument provided
task can be executed by any of the workers.
Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.test, nr.nc, nr.do, nr.http, nr.gnmi, nr.file, nr.diff, nr.find, nr.learn, nr.nornir
CLI Arguments:
worker
- Worker to use for task, supported valuesall
or number from1
tonornir_workers
Proxy Minion parameter of default value 3
Sample usage:
salt nrp1 nr.cli "show clock" worker=3
salt nrp1 nr.nornir connections worker=2
salt nrp1 nr.nornir disconnect worker=all
Execution Module Functions
nr.cfg
- salt_nornir.modules.nornir_proxy_execution_module.cfg(*args, **kwargs)
Function to push configuration to devices using NAPALM, Netmiko, Scrapli or or PyATS task plugin.
- Parameters
commands – (str, list) list of commands or multiline string to send to device
filename – (str) path to file with configuration or template
config – (str, dict) configuration string or reference to configuration template or dictionary keyed by host name with value set to configuration string or template
template_engine – (str) template engine to render configuration, default is jinja2
saltenv – (str) name of SALT environment
context – Overrides default context variables passed to the template.
defaults – Default context passed to the template.
plugin – (str) name of configuration task plugin to use -
napalm
(default) ornetmiko
orscrapli
orpyats
dry_run – (bool) default False, controls whether to apply changes to device or simulate them
commit – (bool or dict) by default commit is
True
. Withnetmiko
plugin ifcommit
argument is a dictionary it is supplied to commit call as arguments
Warning
dry_run
not supported bynetmiko
andpyats
pluginsWarning
commit
not supported byscrapli
andpyats
plugins. To commit need to send commit command as part of configuration, moreover, scrapli will not exit configuration mode, need to send exit command as part of configuration commands as well.Plugins details:
napalm
- uses napalm_configure Nornir-Salt Task plugin,nr.cfg
uses this plugin by defaultnetmiko
- uses netmiko_send_config Nornir-Salt Task pluginscrapli
- uses scrapli_send_config Nornir-Salt Task pluginpyats
- uses pyats_send_config Nornir-Salt Task plugin
For configuration rendering purposes, in addition to normal context variables template engine loaded with additional context variable host, to access Nornir host inventory data.
Sample usage:
salt nrp1 nr.cfg "logging host 1.1.1.1" "ntp server 1.1.1.2" FB="R[12]" dry_run=True salt nrp1 nr.cfg commands='["logging host 1.1.1.1", "ntp server 1.1.1.2"]' FB="R[12]" salt nrp1 nr.cfg "logging host 1.1.1.1" "ntp server 1.1.1.2" plugin="netmiko" salt nrp1 nr.cfg filename=salt://template/template_cfg.j2 FB="R[12]" salt nrp1 nr.cfg filename=salt://template/cfg.j2 FB="XR-1" commit='{"confirm": True, "confirm_delay": 60}' salt nrp1 nr.cfg config="snmp-server location {{ host.location }}" salt nrp1 nr.cfg config='{"ceos1": "snmp-server location {{ host.location }}", "ceos2": "ntp server 1.2.3.4"}' salt nrp1 nr.cfg "snmp-server location {{ host.location }}"
Filename argument can be a template string, for instance:
salt nrp1 nr.cfg filename=salt://templates/{{ host.name }}_cfg.txt
In that case filename rendered to form path string, after that, path string used to download file from master, downloaded file further rendered using specified template engine (Jinja2 by default). That behavior supported for URL schemes: salt://, http://, https://, ftp://, s3://, swift:// and file:// (local filesystem). This feature allows to specify per-host configuration files for applying to devices.
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.cfg", arg=["logging host 1.1.1.1", "ntp server 1.1.1.2"], kwarg={"plugin": "netmiko"}, )
nr.cfg_gen
- salt_nornir.modules.nornir_proxy_execution_module.cfg_gen(*args, **kwargs)
Function to render configuration from template file. No configuration pushed to devices.
This function can be useful to stage/test templates or to generate configuration without pushing it to devices.
- Parameters
commands – (str, list) list of commands or multiline string to send to device
filename – (str) path to template
config – (str, dict) configuration string or reference to configuration template or dictionary keyed by host name with value set to configuration string or template
template_engine – (str) template engine to render configuration, default is jinja2
saltenv – (str) name of SALT environment
context – Overrides default context variables passed to the template.
defaults – Default context passed to the template.
For configuration rendering purposes, in addition to normal context variables template engine loaded with additional context variable host, to access Nornir host inventory data.
Sample usage:
salt nrp1 nr.cfg_gen filename=salt://templates/template.j2 FB="R[12]" salt nrp1 nr.cfg_gen config="snmp-server location {{ host.location }}" salt nrp1 nr.cfg_gen "snmp-server location {{ host.location }}" salt nrp1 nr.cfg_gen config='{"ceos1": "snmp-server location {{ host.location }}", "ceos2": "ntp server 1.2.3.4"}'
Sample template.j2 content:
proxy data: {{ pillar.proxy }} jumphost_data: {{ host["jumphost"] }} hostname: {{ host.name }} platform: {{ host.platform }}
Filename argument can be a template string, for instance:
salt nrp1 nr.cfg_gen filename="salt://template/{{ host.name }}_cfg.txt"
In that case filename rendered to form path string, after that, path string used to download file from master, downloaded file further rendered using specified template engine (Jinja2 by default). That behavior supported for URL schemes: salt://, http://, https://, ftp://, s3://, swift:// and file:// (local filesystem). This feature allows to specify per-host configuration files for applying to devices.
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.cfg_gen", kwarg={"filename": "salt://template/{{ host.name }}_cfg.txt"}, )
nr.cli
- salt_nornir.modules.nornir_proxy_execution_module.cli(*args, **kwargs)
Method to retrieve commands output from devices using
send_command
task plugin from either Netmiko or Scrapli library.- Parameters
args – (list or str) list of cli commands as arguments
commands – (list or str) list of cli commands or single command as key-word argument
filename – (str) path to file with multiline commands string
plugin – (str) name of send command task plugin to use -
netmiko
(default),scrapli
,napalm
orpyats
render – (list) list of arguments to pass through SaltStack rendering system, by default renders content of
["filename", "commands"]
arguments.use_ps – (bool) if True, uses Netmiko with promptless mode to send commands
kwargs – (dict) any additional arguments to use with specified
plugin
send command method
Sample Usage:
salt nrp1 nr.cli "show clock" "show run" FB="IOL[12]" use_timing=True delay_factor=4 salt nrp1 nr.cli commands='["show clock", "show run"]' FB="IOL[12]" salt nrp1 nr.cli "show clock" FO='{"platform__any": ["ios", "nxos_ssh", "cisco_xr"]}' salt nrp1 nr.cli commands='["show clock", "show run"]' FB="IOL[12]" plugin=napalm salt nrp1 nr.cli "show clock" use_ps=True cutoff=60 initial_sleep=10
Plugins details:
netmiko
- uses netmiko_send_commands Nornir-Salt Task plugin,nr.cli
uses this plugin by defaultscrapli
- uses scrapli_send_commands Nornir-Salt Task pluginnapalm
- uses napalm_send_commands Nornir-Salt Task pluginpyats
- uses pyats_send_commands Nornir-Salt Task pluginuse_ps
- enables promptless mode of interaction with device’s CLI, uses netmiko_send_commands_ps Nornir-Salt task plugin
Commands can be templates and rendered using Jinja2 Templating Engine:
salt nrp1 nr.cli "ping 1.1.1.1 source {{ host.lo0 }}"
Commands to run on devices can be sourced from text file on a Salt Master or any other location with supported URL schemes: salt://, http://, https://, ftp://, s3://, swift:// and file:// (local filesystem), that text file can also be a template, it is rendered using SaltStack rendering system:
salt nrp1 nr.cli filename="salt://device_show_commands.txt"
Combining above two features we can supply per-host commands like this:
salt nrp1 nr.cli filename="salt://{{ host.name }}_show_commands.txt"
Where
{{ host.name }}_show_commands.txt
file can be a template as well.Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.cli", arg=["show clock"], kwarg={"plugin": "netmiko"}, )
nr.diff
- salt_nornir.modules.nornir_proxy_execution_module.diff(*args, **kwargs)
Provide difference between current and previously learned information or between versions of files stored by
ToFileProcessor
.- Parameters
diff – (str)
ToFileProcessor
filegroup namelast – (int or list or str) filegroup file indexes to diff, default is 1
kwargs – (dict) any additional kwargs to use with
nr.file diff
call or withDiffProcessor
diff
orargs
attributes are mandatory.If last is a single digit e.g. 1, diff uses
nr.do
function to execute action named same asfilegroup
attribute and uses results to produce diff with previously savedfilegroup
files usingDiffProcessor
.If
last
is a list e.g.[2, 5]
or string1, 2
- will usenr.file diff
call to produce diff for previously saved results without retrieving data from devices.Sample usage:
salt nrp1 nr.diff interface salt nrp1 nr.diff interface last=1 salt nrp1 nr.diff interface last='[1, 5]' salt nrp1 nr.diff interface last="1,5"
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.diff", arg=["interface"], kwarg={"last": 1}, )
nr.do
- salt_nornir.modules.nornir_proxy_execution_module.do(*args, **kwargs)
Function to perform steps defined under
nornir:actions
configuration section at either minion’s pillar data or file on master file system.To retrieve actions content Salt
nr.do
usesconfig.get
execution module function withmerge
key set torecurse
.Each step definition requires these keywords to be defined:
function
- mandatory, name of any Salt-Nornir execution module function to runargs
- optional, any arguments to use with functionkwargs
- optional, any keyword arguments to use with functiondescription
- optional, used bydir
to list action description
Any other keywords defined inside the step are ignored.
- Parameters
stop_on_error – (bool) if True (default) stops execution on error in step, continue execution in error if False
filepath – (str) URL to file with actions steps supporting any of
cp.get_url
URIs: salt://, http://, https://, ftp://, s3://, swift:// and file:// (local filesystem)default_renderer – (str) shebang string to render file using
slsutil.renderer`, default ``jinja|yaml
describe – (bool) if True, returns action content without executing it, default is False
kwargs – (any) additional
kwargs
to use with actions steps,kwargs
overridekwargs
dictionary defined within each step, for example, in commandsalt nrp1 nr.do configure_ntp FB="*core*"
,FB
argument will overrideFB
arguments defined within steps.tf – (bool) if True,
ToFileProcessor
saves each step results in file named after step name if notf
argument provided within step, default is Falsediff – (bool) if True,
DiffProcessor
runs diff for each step result using files named after step name if nodiff
argument provided within step, default is False
- Returns
dictionary with keys:
failed
bool,result
list;result
key contains a list of results for steps; Ifstop_on_error
set toTrue
and error happens,failed
key set toTrue
Special action names
dir
anddir_list
used to list all actions available for proxy minion wheredir
returns table anddir_list
produces a list of actions.Note
if
filepath
argument provided, actions defined in other places are ignored; file loaded using SaltStackslsutil.renderer
execution module function, as a result file can contain any of supported SaltStack renderer content and can be located at any URL supported bycp.get_url
execution module function - supported URL schemes are: salt://, http://, https://, ftp://, s3://, swift:// and file:// (local filesystem). File content must render to a dictionary keyed by actions’ names.Sample actions steps definition using proxy minion pillar:
nornir: actions: arista_wr: function: nr.cli args: ["wr"] kwargs: {"FO": {"platform": "arista_eos"}} description: "Save Arista devices configuration" configure_ntp: - function: nr.cfg args: ["ntp server 1.1.1.1"] kwargs: {"FB": "*"} - function: nr.cfg args: ["ntp server 1.1.1.2"] kwargs: {"FB": "*"} - function: nr.cli args: ["show run | inc ntp"] kwargs: {"FB": "*"}
Sample actions steps definition using text file under
filepath
:arista_wr: function: nr.cli args: ["wr"] kwargs: {"FO": {"platform": "arista_eos"}} description: "Save Arista devices configuration" configure_ntp: - function: nr.cfg args: ["ntp server 1.1.1.1"] kwargs: {"FB": "*"} description: "1. Configure NTP server 1.1.1.1" - function: nr.cfg args: ["ntp server 1.1.1.2"] kwargs: {"FB": "*"} description: "2. Configure NTP server 1.1.1.2" - function: nr.cli args: ["show run | inc ntp"] kwargs: {"FB": "*"} description: "3. Collect NTP configuration"
Action name
arista_wr
has single step defined, whileconfigure_ntp
action has multiple steps defined, each executed in order.Multiple actions names can be supplied to
nr.do
call.Warning
having column
:
as part of action name not permitted, as:
used by Saltconfig.get
execution module function to split arguments on path items.Sample usage:
salt nrp1 nr.do dir salt nrp1 nr.do dir_list salt nrp1 nr.do arista_wr salt nrp1 nr.do configure_ntp arista_wr stop_on_error=False salt nrp1 nr.do configure_ntp FB="*core*" add_details=True salt nrp1 nr.do arista_wr filepath="salt://actions/actions_file.txt"
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.do", arg=["configure_ntp", "arista_wr"], kwarg={"FB": "R[12]"}, )
nr.file
- salt_nornir.modules.nornir_proxy_execution_module.file(*args, **kwargs)
Function to manage Nornir-salt files.
- Parameters
call – (str) files task to call - ls, rm, read, diff
kwargs – (dict) any additional kwargs such
Fx
filters or call function arguments
File tasks description:
ls
- list files of this Proxy Minions, returns list of dictionariesrm
- removes file with given name and index numberread
- displays content of file with given name and index numberdiff
- reads two files and returns diff
ls
arguments- Parameters
filegroup – (str or list)
tf
or list oftf
filegroup names of the files to list, lists all files by default- Returns
files list
rm
arguments- Parameters
filegroup – (str or list)
tf
or list oftf
filegroup names of the files to remove, if set to True will remove all files for all filegroups- Returns
list of files removed
read
arguments- Parameters
filegroup – (str or list)
tf
or list oftf
filegroup names of the files to readlast – (int) version of content to read
- Returns
results reconstructed out of files content
diff
arguments- Parameters
filegroup – (str or list)
tf
filegroup name to difflast – (int or list or str) files to diff, default is
[1, 2]
- last 1 and last 2 files
- Returns
files unified difference
Sample usage:
salt nrp1 nr.file read ip salt nrp1 nr.file rm ip interface salt nrp1 nr.file diff routes last='[1,2]'
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.file", arg=["ls"], kwarg={"filegroup": "interfaces"}, )
nr.find
- salt_nornir.modules.nornir_proxy_execution_module.find(*args, **kwargs)
Search for information stored in Proxy Minion files.
This function does not query devices but only uses information stored locally by
ToFileProcessor
.- Parameters
headers – (str or list) table headers, default is
keys
table – (str) TabulateFormatter table directive, default is
extend
headers_exclude – (str or list) table headers to exclude, default is
["changed", "diff", "failed", "name", "connection_retry", "task_retry"]
reverse – (bool) default is False, reverses table order if True
sortby – (str) column header name to sort table by
last – (int) file group version of files to search in
Fx – (str) Nornir host filters
args – (list) list of
ToFileProcessor
filegroup names to search inkwargs – (dict) key-value pairs where keys are keys to search for, values are criteria to check
- Returns
list of dictionaries with matched results
Find uses
DataProcessor
find
function to do search and supports searching in a list of dictionaries, dictionary and text.If no
args
providednr.find
fails.Sample usage:
salt nrp1 nr.find ip ip="1.1.*" salt nrp1 nr.find mac arp mac="1b:cd:34:5f:6c" salt nrp1 nr.find ip ip="1.1.*" last=5 FB="*CORE*" salt nrp1 nr.find ip mask__ge=23 mask__lt=30 FC="CORE" salt nrp1 nr.find interfaces description__contains="ID #123321"
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.find", arg=["ip"], kwarg={"ip": "1.1.*"}, )
nr.gnmi
- salt_nornir.modules.nornir_proxy_execution_module.gnmi(call, *args, **kwargs)
Function to interact with devices using gNMI protocol utilizing one of supported plugins.
- Parameters
call – (str) (str) connection object method to call or name of one of extra methods
plugin – (str) Name of gNMI plugin to use - pygnmi (default)
method_name – (str) name of method to provide docstring for, used only by
help
callpath – (list or str) gNMI path string for
update
,delete
,replace
extra methods callsfilename – (str) path to file with call method arguments content
kwargs – (dict) any additional keyword arguments to use with call method
- Returns
method call results
Available gNMI plugin names:
pygnmi
- uses pygnmi_call Nornir-Salt Task plugin that relies on PyGNMI library to interact with devices.
gNMI specification defines several methods to work with devices -
subscribe
,get
andset
.set
further supportsdelete
,update
andreplace
operations.Warning
subscribe
is not supported bynr.gnmi
function.Sample usage of
pygnmi
plugin:salt nrp1 nr.gnmi capabilities FB="*" salt nrp1 nr.gnmi get "openconfig-interfaces:interfaces/interface[name=Loopback100]" salt nrp1 nr.gnmi get path='["openconfig-interfaces:interfaces/interface[name=Loopback100]"]' salt nrp1 nr.gnmi get path="openconfig-interfaces:interfaces, openconfig-network-instance:network-instances" salt nrp1 nr.gnmi set update='[["openconfig-interfaces:interfaces/interface[name=Loopback100]/config", {"description": "Done by gNMI"}]]' salt nrp1 nr.gnmi set replace='[["openconfig-interfaces:interfaces/interface[name=Loopback1234]/config", {"name": "Loopback1234", "description": "New"}]]' salt nrp1 nr.gnmi set delete="openconfig-interfaces:interfaces/interface[name=Loopback1234]"
Extra Call Methods
dir
- returns methods supported bygNMIclient
connection object, including extra methods defined by nornir-saltpygnmi_call
task plugin:salt nrp1 nr.gnmi dir
help
- returnsmethod_name
docstring:salt nrp1 nr.gnmi help method_name=set
replace
- shortcut method toset
call withreplace
argument, first argument must be path string, other keyword arguments are configuration items:salt nrp1 nr.gnmi replace "openconfig-interfaces:interfaces/interface[name=Loopback100]/config" name=Loopback100 description=New
update
- shortcut method toset
call withupdate
argument, first argument must be path string, other keyword arguments are configuration items:salt nrp1 nr.gnmi update "openconfig-interfaces:interfaces/interface[name=Loopback100]/config" description="RID Loop"
delete
- shortcut method toset
call withdelete
argument, accepts a list of path items orpath
argument referring to list:salt nrp1 nr.gnmi delete "openconfig-interfaces:interfaces/interface[name=Loopback100]" "openconfig-interfaces:interfaces/interface[name=Loopback123]" salt nrp1 nr.gnmi delete path='["openconfig-interfaces:interfaces/interface[name=Loopback100]", "openconfig-interfaces:interfaces/interface[name=Loopback123]"]'
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.gnmi", arg=["get"], kwarg={"path": ["openconfig-interfaces:interfaces"]}, )
If
filename
argument provided it is rendered usingslsutil.renderer
function and must produce a dictionary with keys being valid arguments supported by call method. For example,pygnmi
pluginset
call can look like this:salt nrp1 nr.gnmi set filename="salt://path/to/set_args.txt"
Where
salt://path/to/set_args.txt
content is:replace: - - "openconfig-interfaces:interfaces/interface[name=Loopback35]/config" - {"name": "Loopback35", "description": "RID Loopback"} - - "openconfig-interfaces:interfaces/interface[name=Loopback36]/config" - {"name": "Loopback36", "description": "MGMT Loopback"} update: - - "openconfig-interfaces:interfaces/interface[name=Loopback35]/config" - {"name": "Loopback35", "description": "RID Loopback"} - - "openconfig-interfaces:interfaces/interface[name=Loopback36]/config" - {"name": "Loopback36", "description": "MGMT Loopback"} delete: - "openconfig-interfaces:interfaces/interface[name=Loopback35]" - "openconfig-interfaces:interfaces/interface[name=Loopback36]"
salt://path/to/set_args.txt
content will be rendered to a dictionary and supplied toset
call as**kwargs
.pygnmi
plugin order of operation for above case isdelete -> replace -> update
nr.http
- salt_nornir.modules.nornir_proxy_execution_module.http(*args, **kwargs)
HTTP requests related functions
- Parameters
method – (str) HTTP method to use
url – (str) full or partial URL to send request to
kwargs – (dict) any other kwargs to use with requests.<method> call
This function uses Nornir-Salt http_call task plugin, refer its documentation for additional details.
Sample usage:
salt nrp1 nr.http get "http://1.2.3.4/api/data/" salt nrp1 nr.http get "https://sandbox-iosxe-latest-1.cisco.com/restconf/data/" verify=False auth='["developer", "C1sco12345"]'
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.http", arg=["get", "http://1.2.3.4/api/data/"], )
nr.learn
- salt_nornir.modules.nornir_proxy_execution_module.learn(*args, **kwargs)
Store task execution results to local filesystem on the minion using
tf
(to filename) attribute to form filenames.- Parameters
fun – (str) name of execution module function to call
tf – (str)
ToFileProcessor
filegroup nametf_skip_failed – (bool) default is True, do not save failed tasks
args – (list) execution module function arguments
kwargs – (dict) execution module function key-word arguments
This task uses
ToFileProcessor
to store results and is a shortcut to calling individual execution module functions withtf
argument.Supported execution module functions are
cli, nc, do, http
. By default callsnr.do
function.tf
attribute mandatory except for cases when usingnr.do``function e.g. ``salt nrp1 nr.learn mac interface
, in that casetf
set equal to file group name -mac
andinterface
for each action call usingnr.do
functiontf=True
attribute.Sample usage:
salt nrp1 nr.learn mac salt nrp1 nr.learn mac ip interface FB="CORE-*" salt nrp1 nr.learn "show version" "show int brief" tf="cli_facts" fun="cli"
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.learn", arg=["mac", "ip"], kwarg={"FB": "CORE-*"}, )
nr.nc
- salt_nornir.modules.nornir_proxy_execution_module.nc(*args, **kwargs)
Function to interact with devices using NETCONF protocol utilizing one of supported plugins.
Available NETCONF plugin names:
ncclient
-nornir-salt
built-in plugin that usesncclinet
library to interact with devicesscrapli
- usesscrapli_netconf
connection plugin that is part ofnornir_scrapli
library, it does not usescrapli_netconf
task plugins, but rather implements a wrapper aroundscrapli_netconf
connection plugin connection object.
- Parameters
call – (str) ncclient manager or scrapli netconf object method to call
plugin – (str) Name of netconf plugin to use - ncclient (default) or scrapli
data – (str) path to file for
rpc
method call or rpc contentmethod_name – (str) name of method to provide docstring for, used only by
help
call
Plugins details:
ncclient
- uses ncclient_call Nornir-Salt Task plugin,nr.nc
uses this plugin by defaultscrapli
- uses scrapli_netconf_call Nornir-Salt Task plugin
Special
call
arguments/methods:dir
- returns methods supported by Ncclient connection manager object:salt nrp1 nr.nc dir
help
- returnsmethod_name
docstring:salt nrp1 nr.nc help method_name=edit_config
transaction
- same asedit_config
, but runs this (presumably more reliable) work flow:Lock target configuration datastore
If server supports it - Discard previous changes if any
Perform configuration edit using RPC specified in
edit_rpc
argumentIf server supports it - validate configuration if
validate
argument is TrueIf server supports it - do commit confirmed if
confirmed
argument is True usingconfirm_delay
timer withcommit_arg
argumentIf confirmed commit requested, wait for
commit_final_delay
timer before sending final commit, final commit does not usecommit_arg
argumentsIf server supports it - do commit operation
Unlock target configuration datastore
If server supports it - discard all changes if any of steps 3, 4, 5 or 7 fail
Return results list of dictionaries keyed by step name
Sample usage:
salt nrp1 nr.nc transaction target="candidate" config="salt://path/to/config_file.xml" FB="*core-1"
Warning
beware of difference in keywords required by different plugins, e.g.
filter
forncclient
vsfilter_
/filters
forscrapli_netconf
, refer to modules’ api documentation for required arguments, using, for instancehelp
call:salt nrp1 nr.nc help method_name=get_config
Examples of sample usage for
ncclient
plugin:salt nrp1 nr.nc server_capabilities FB="*" salt nrp1 nr.nc get_config filter='["subtree", "salt://rpc/get_config_data.xml"]' source="running" salt nrp1 nr.nc edit_config target="running" config="salt://rpc/edit_config_data.xml" FB="ceos1" salt nrp1 nr.nc transaction target="candidate" config="salt://rpc/edit_config_data.xml" salt nrp1 nr.nc commit salt nrp1 nr.nc rpc data="salt://rpc/iosxe_rpc_edit_interface.xml" salt nrp1 nr.nc get_schema identifier="ietf-interfaces" salt nrp1 nr.nc get filter='<system-time xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-shellutil-oper"/>'
Examples of sample usage for
scrapli_netconf
plugin:salt nrp1 nr.nc get filter_=salt://rpc/get_config_filter_ietf_interfaces.xml plugin=scrapli salt nrp1 nr.nc get_config source=running plugin=scrapli salt nrp1 nr.nc server_capabilities FB="*" plugin=scrapli salt nrp1 nr.nc rpc filter_=salt://rpc/get_config_rpc_ietf_interfaces.xml plugin=scrapli salt nrp1 nr.nc transaction target="candidate" config="salt://rpc/edit_config_ietf_interfaces.xml" plugin=scrapli
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.nc", arg=["get_config"], kwarg={"source": "running", "plugin": "ncclient"}, )
nr.netbox
- salt_nornir.modules.nornir_proxy_execution_module.netbox(*args, **kwargs)
Function to interact with Netbox DCIM.
Why? Because data is the key.
- Parameters
task – (str) name of Netbox task function to run
kwargs – (dict) any additional keyword arguments to use with task function
- Returns
task results
For nr.netbox functions to work, Netbox token and url parameters should be defined in master’s configuration
ext_pillar
section and Master’s configuration file need to havepillar_opts
set toTrue
for minion to be able to source parameters from Salt-Master configuration:pillar_opts: True ext_pillar: - salt_nornir_netbox: url: 'http://192.168.115.129:8000' token: '837494d786ff420c97af9cd76d3e7f1115a913b4'
Alternatively, Netbox parameters can be defined in proxy minion pillar settings:
salt_nornir_netbox_pillar: url: 'http://192.168.115.129:8000' token: '837494d786ff420c97af9cd76d3e7f1115a913b4'
Pillar defined parameters take precendence over master’s configuration.
Available
task
functions are listed below.dir task
Returns a list of supported tasks functions. Sample usage:
salt nrp1 nr.netbox dir
query task
Helps to retrieve data from Netbox over GraphQL API.
Supported arguments:
- Parameters
query_string – GraphQL query string to send to Netbox GraphQL API
field – name of the the fields to retirieve e.g. device_list, interface_list
filters – dictionary of filters to use
fields – dictionary of fields to retrieve
queries – dictionary keyed by GraphQL aliases with values being a dictionary of field`,
filters
andfields
parameters.
To use
query
task need to provide one ofquery_string
orfield
,filters
andfields
parameters to form query string orqueries
dictionary to form query strings with aliases
Sample usage:
salt nrp1 nr.netbox query field="device_list" filters='{"name": "ceos1"}' fields='["name", "platform {name}", "status"]' salt nrp1 nr.netbox query queries='{"devices": {"field": "device_list", "filters": {"platform": "eos"}, "fields": ["name"]}}' salt nrp1 nr.netbox query query_string='query{device_list(platform: "eos") {name}}'
rest task
Qquery Netbox REST API using requests. This task supports any requests module arguments in additiona to these arguments:
- Parameters
method – get, ports, put, patch, delete action to query
api – Netbox API endpoint to query e.g.
dcim/interfaces
Sample usage:
salt nrp1 nr.netbox rest get "dcim/interfaces" params='{"name__ic": "eth1", "device": "fceos4"}' salt nrp1 nr.netbox rest method=get api="dcim/interfaces" params='{"device": "fceos4"}'
get_interfaces task
Retrieves devices’ interfaces details from Netbox, supported arguments:
- Parameters
add_ip – boolean, if True adds IP addresses information to interfaces
add_inventory_items – boolean, if True adds inventory items information to interfaces
Sample usage:
salt nrp1 nr.netbox get_interfaces FB="ceos1" add_ip=True add_inventory_items=True
get_connections task
Retrieves devices’ interfaces connections from Netbox. Supported arguments:
- Parameters
trace – if True traces full connection path between device interfaces
Sample usage:
salt nrp1 nr.netbox get_connections FB="ceos1" salt nrp1 nr.netbox get_connections FB="ceos1" trace=True
update_config_context task
Task to parse device configuration and save results into Netbox device’s configuration context.
Dependency: TTP,
pip install ttp
Sample usage:
salt nrp1 nr.netbox update_config_context FB=ceos1
parse_config task
Task to parse device configuratoion using TTP templates and return results. This task used by
update_config_context
to retrieve configuration parsing results.Dependency: TTP,
pip install ttp
Sample usage:
salt nrp1 nr.netbox parse_config
update_vrf task
This task helps to create or update VRFs and Route-Targets in Netbox from device configuration.
Sample usage:
salt nrp1 nr.netbox update_vrf
nr.network
- salt_nornir.modules.nornir_proxy_execution_module.network(fun, *args, **kwargs)
Function to call various network related utility functions.
- Parameters
fun – (str) utility function name to call
kwargs – (dict) function arguments
Available utility functions:
resolve_dns
- resolve hosts’ hostname DNS returning IP addresses
Sample Usage:
salt nrp1 nr.network resolve_dns
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.network", arg=["resolve_dns"], )
nr.nornir
- salt_nornir.modules.nornir_proxy_execution_module.nornir_fun(fun, *args, **kwargs)
Function to call various Nornir utility functions.
- Parameters
fun – (str) utility function name to call
kwargs – (dict) function arguments
Available utility functions:
dir
- return a list of supported functionstest
- this method tests proxy minion module worker thread without invoking any Nornir coderefresh
- re-instantiates Nornir workers after retrieving latest pillar data from Salt Master, ifworkers_only=True
only refreshes Nornir workers using latest pillar data, without closing queues and killing child processes, resulting in inventory refresh but with no interruption to jobs execution process.kill
- executes immediate shutdown of Nornir Proxy Minion process and child processesshutdown
- gracefully shutdowns Nornir Proxy Minion process and child processesinventory
- interact with Nornir Process inventory data, usingInventoryFun
function, by default, forread_host, read, read_inventory, list_hosts, list_hosts_platforms
operations any Nornir worker can respond, for other, non-read operations targets all Nornir workersstats
- returns statistics about Nornir proxy process, acceptsstat
argument of stat name to returnversion
- returns a report of Nornir related packages installed versionsinitialized
- returns Nornir Proxy Minion initialized status - True or Falsehosts
- returns a list of hosts managed by this Nornir Proxy Minion, acceptsFx
arguments to return only hosts matched by filterconnections
- list hosts’ active connections for all workers, acceptsFx
arguments to filter hosts to list, by default returns connections data for all Nornir workers, usesnornir_salt.plugins.tasks.connections
ls
call, acceptconn_name
parameterdisconnect
- close host connections, acceptsFx
arguments to filter hosts andconn_name
of connection to close, by default closes all connections from all Nornir workers, usesnornir_salt.plugins.tasks.connections
close
callconnect
- initiate connection to devices, arguments:conn_name, hostname, username, password, port,
platoform, extras, default_to_host_attributes, close_open
, usesnornir_salt.plugins.tasks.connections
open
callclear_hcache
- clear task results cache from hosts’ data, acceptscache_keys
list argument of key names to remove, if nocache_keys
argument provided removes all cached data, by default targets all Nornir workersclear_dcache
- clear task results cache from defaults data, acceptscache_keys
list argument of key names to remove, if nocache_keys
argument provided removes all cached data, by default targets all Nornir workersworkers/worker
- call nornir worker utilities e.g.stats
results_queue_dump
- return content of results queue
Sample Usage:
salt nrp1 nr.nornir inventory FB="R[12]" salt nrp1 nr.nornir inventory FB="R[12]" worker="all" salt nrp1 nr.nornir inventory create_host name="R1" hostname="1.2.3.4" platform="ios" groups='["lab"]' salt nrp1 nr.nornir inventory update_host name="R1" data='{"foo": bar}' salt nrp1 nr.nornir inventory read_host FB="R1" salt nrp1 nr.nornir inventory call=delete_host name="R1" salt nrp1 nr.nornir inventory update_defaults username=foo password=bar data='{"f": "b"}' salt nrp1 nr.nornir stats stat="proxy_minion_id" salt nrp1 nr.nornir version salt nrp1 nr.nornir shutdown salt nrp1 nr.nornir clear_hcache cache_keys='["key1", "key2]' salt nrp1 nr.nornir clear_dcache cache_keys='["key1", "key2]' salt nrp1 nr.nornir workers stats salt nrp1 nr.nornir connect conn_name=netmiko username=cisco password=cisco platform=cisco_ios salt nrp1 nr.nornir connect scrapli port=2022 close_open=True salt nrp1 nr.nornir connect netmiko via=console salt nrp1 nr.nornir connections conn_name=netmiko salt nrp1 nr.nornir disconnect conn_name=ncclient salt nrp1 nr.nornir refresh workers_only=True
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.nornir", arg=["stats"], )
nr.snmp
- salt_nornir.modules.nornir_proxy_execution_module.snmp(call, *args, **kwargs)
Function to interact with devices using SNMP protocol utilizing one of supported plugins.
- Parameters
call – (str) connection object method to call or name of one of extra methods
plugin – (str) Name of SNMP plugin to use - puresnmp (default)
method_name – (str) name of method to provide docstring for, used only by
help
callkwargs – (dict) any additional keyword arguments to use with call method
- Returns
method call results
Available SNMP plugin names:
puresnmp
- uses puresnmp_callNornir-Salt Task plugin that relies on puresnmp library to interact with devices.
Sample usage of
puresnmp
plugin,plugin="puresnmp"
:salt nrp1 nr.snmp bulkget scalar_oids='["1.3.6.1.2.1.1.1.0", "1.3.6.1.2.1.1.2.0"]' repeating_oids='["1.3.6.1.2.1.3.1"]' salt nrp1 nr.snmp bulktable oid="1.3.6.1.2.1.2.2.1" salt nrp1 nr.snmp bulkwalk oids='["1.3.6.1.2.1.1.1", "1.3.6.1.2.1.1.5"]' salt nrp1 nr.snmp get oid="1.3.6.1.2.1.1.1.0" FB="*" salt nrp1 nr.snmp getnext oid="1.3.6.1.2.1.1.1.0" salt nrp1 nr.snmp multiget oids='["1.3.6.1.2.1.1.1.0", "1.3.6.1.2.1.1.2.0"]' salt nrp1 nr.snmp multiset mappings='{"1.3.6.1.2.1.1.4.0": "new contact value", "1.3.6.1.2.1.1.6.0": "new location"}' salt nrp1 nr.snmp multiwalk oids='["1.3.6.1.2.1.1.1", "1.3.6.1.2.1.1.5"]' salt nrp1 nr.snmp set oid="1.3.6.1.2.1.1.4.0" value="new contact value" salt nrp1 nr.snmp table oid="1.3.6.1.2.1.2.2.1" salt nrp1 nr.snmp walk oid="1.3.6.1.2.1.1"
By default
oid
andoids
arguments rendered and can be sourced from host inventory:salt nrp1 nr.snmp get oid="{{ host.oid.get_os }}" salt nrp1 nr.snmp multiget oids='["{{ host.oid.get_os }}", "{{ host.oid.get_hostname }}"]'
Where
host.oid.get_os
sourced from Nornir inventory:hosts: ceos1: groups: [lab] groups: lab: data: oid: get_os: "1.3.6.1.2.1.1.1.0" get_hostname: "1.3.6.1.2.1.1.5.0"
Extra Call Methods
dir
- returns call methods supported by plugin:salt nrp1 nr.snmp dir plugin=puresnmp
help
- returnsmethod_name
docstring:salt nrp1 nr.snmp help method_name=set
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.snmp", arg=["get"], kwarg={"oid": "1.3.6.1.2.1.1.1.0"}, )
nr.task
- salt_nornir.modules.nornir_proxy_execution_module.task(plugin, **kwargs)
Function to invoke any of supported Nornir task plugins. This function performs dynamic import of requested plugin function and executes
nr.run
using supplied args and kwargs- Parameters
plugin – (str)
path.to.plugin.task_fun
to runfrom path.to.plugin import task_fun
kwargs – (dict) arguments to use with specified task plugin or common arguments
plugin
attribute can refer to a file on one of remote locations, supported URL schemes are: salt://, http://, https://, ftp://, s3://, swift:// and file:// (local filesystem). File downloaded, compiled and executed.File must contain function named
task
accepting Nornir task object as a first positional argument, for example:# define connection name for RetryRunner to properly detect it CONNECTION_NAME = "netmiko" # create task function def task(nornir_task_object, *args, **kwargs): pass
Note
CONNECTION_NAME
must be defined within custom task function file if RetryRunner in use, otherwise connection retry logic skipped and connections to all hosts initiated simultaneously up to the number of num_workers.Sample usage:
salt nrp1 nr.task "nornir_napalm.plugins.tasks.napalm_cli" commands='["show ip arp"]' FB="IOL1" salt nrp1 nr.task "nornir_netmiko.tasks.netmiko_save_config" add_details=False salt nrp1 nr.task "nornir_netmiko.tasks.netmiko_send_command" command_string="show clock" salt nrp1 nr.task "salt://path/to/task.txt" salt nrp1 nr.task plugin="salt://path/to/task.py"
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.task", arg=["nornir_napalm.plugins.tasks.napalm_cli"], kwarg={"commands": ["show ip arp"]}, )
nr.test
- salt_nornir.modules.nornir_proxy_execution_module.test(*args, **kwargs)
Function to perform tests for certain criteria against show commands output from devices obtained using
nr.cli
function.nr.test
function related arguments- Parameters
name – (str) descriptive name of the test, will be added to results
test – (str) type of test to do e.g.: contains, !contains, equal, custom etc.
pattern – (str) pattern to use for testing, usually string, text or reference a text file on salt master. For instance if
test
iscontains
,pattern
value used as a pattern for containment checkfunction_file – (str) path to text file on salt master with function content to use for
custom
function testdry_run – (bool) if True, returns produced per-host tests suites content only, no tests performed,
subset
not supported with dry runsaltenv – (str) name of salt environment to download function_file from
suite – (list or str) list of dictionaries with test items or path to file on salt-master with a list of test item dictionaries
subset – (list or str) list or string with comma separated glob patterns to match tests’ names to execute. Patterns are not case-sensitive. Uses
fnmatch.fnmatch
Python built-in function to do matchingdump – (str) filegroup name to dump results using Nornir-salt
DumpResults
tests – string or list of strings with key path referring to host’s tests list
strict – boolean used with
tests
argument, ifstrict
is True raises error whentests
path item not found in any of the hosts’ invenotry data, default is Falsekwargs – (dict) any additional arguments to use with test function
nr.cli
function related arguments- Parameters
commands – (str or list) single command or list of commands to get from device
plugin – (str) plugin name to use with
nr.cli
function to gather output from devices -netmiko
(default) orscrapli
use_ps – (bool) default is False, if True use netmiko plugin experimental
PromptlesS
method to collect output from devicescli – (dict) any additional arguments to pass on to
nr.cli
function
Nornir-Salt
TestsProcessor
plugin related arguments- Parameters
failed_only – (bool) default is False, if True
nr.test
returns result for failed tests onlyremove_tasks – (bool) default is True, if False results will include other tasks output as well e.g. show commands output. By default results only contain tests results.
Nornir-Salt
TabulateFormatter
function related arguments- Parameters
table – (bool, str or dict) dictionary of arguments or table type indicator e.g. “brief” or True
headers – (list) list of headers to output table for
sortby – (str) Name of column name to sort table by
reverse – (bool) reverse table on True, default is False
Sample usage with inline arguments:
salt nrp1 nr.test "show run | inc ntp" contains "1.1.1.1" FB="*host-1" salt nrp1 nr.test "show run | inc ntp" contains "1.1.1.1" --output=table salt nrp1 nr.test "show run | inc ntp" contains "1.1.1.1" table=brief salt nrp1 nr.test commands='["show run | inc ntp"]' test=contains pattern="1.1.1.1" cli='{"enable": True}'
Sample usage with a test cases suite:
salt np1 nr.test suite=salt://tests/suite_1.txt salt np1 nr.test suite=salt://tests/suite_1.txt table=brief salt np1 nr.test suite=salt://tests/suite_1.txt table=brief subset="config_test*,rib_check*" salt np1 nr.test suite="{{ host.tests.interfaces }}" salt np1 nr.test suite='[{"task": "show clock", "test": "contains", "pattern": "NTP", "name": "Test NTP"}]'
Where
salt://tests/suite_1.txt
content is:- task: "show run | inc ntp" test: contains pattern: 1.1.1.1 name: check NTP cfg cli: FB: core-* plugin: netmiko - test: contains_lines pattern: ["1.1.1.1", "2.2.2.2"] task: "show run | inc ntp" name: check NTP cfg lines - test: custom function_file: salt://tests/ntp_config.py task: "show run | inc ntp" name: check NTP cfg pattern from file - test: custom function_file: salt://tests/ntp_config.py task: - "show ntp status" - "show ntp associations" name: "Is NTP in sync"
Sample usage with tests argument:
salt np1 nr.test tests="tests.interfaces" salt np1 nr.test tests=["tests.interfaces", "tests.bgp_peers"]
Where host’s inventory data is:
hosts: nrp1: data: tests: interfaces: - name: Test Uplink task: "show interface Ethernet1" test: contains pattern: "line protocol up" err_msg: "Primary uplink is down" bgp: - name: Test BGP peers state task: "show bgp ipv4 un sum" test: ncontains pattern: Idle err_msg: Some BGP peers are not UP
Warning
tests
paths should always refer to a list of tests dictionariesSample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.test", kwarg={"suite": "salt://tests/suite_1.txt"}, )
Returns a list of dictionaries with check results, each dictionary contains:
{ "host": name of host, "name": descriptive name of the test, "task": name of task results of which used for test, "result": PASS or FAIL, "success": True or False, "error": None or Error description, "test_type": Type of test performed, "criteria": Validation criteria used }
Reference Nornir Salt TestsProcessor documentation for more details on using tests suite.
Commands in a test suite colected only once even if multiple tests refer to same command.
In test suite,
task
argument can reference a list of tasks/commands.Commands output for each item in a suite collected using
nr.cli
function, arguments undercli
keyword passed on tonr.cli
function.List of arguments in a test suite that can refer to a text file to source from one of supported URL schemes:
salt://
,http://
,https://
,ftp://
,s3://
,swift://
andfile://
(local filesystem), for examplesalt://path/to/file.txt
:pattern
- content of the file rendered and used to run the tests together withContainsTest
,ContainsLinesTest
orEqualTest
test functionsschema
- used withCerberusTest
test functionfunction_file
- content of the file used withCustomFunctionTest
asfunction_text
argument
Using Tests Suite Jinja2 Templates
Starting with Salt-Nornir version 0.16.0 support added to dynamically render hosts’ tests suites from hosts’ data using Jinja2 templates of YAML formatted strings.
Note
tests rendering done by Nornir-Salt using Jinja2 directly and loaded using PyYAML module, SaltStack rendering and templating system not used.
Sample test suite Jinja2 template:
- task: "show version" test: contains pattern: "{{ host.software_version }}" name: check ceos version {% for interface in host.interfaces_test %} - task: "show interface {{ interface.name }}" test: contains_lines pattern: - {{ interface.admin_status }} - {{ interface.line_status }} - {{ interface.mtu }} - {{ interface.description }} name: check interface {{ interface.name }} status {% endfor %}
Given hosts’ Nornir inventory data content:
hosts: ceos1: data: interfaces_test: - admin_status: is up description: Description line_status: line protocol is up mtu: IP MTU 9200 name: Ethernet1 - admin_status: is up description: Description line_status: line protocol is up mtu: IP MTU 65535 name: Loopback1 software_version: cEOS ceos2: data: software_version: cEOS
Test suite template rendered using individual host’s data forming per-host test suite. CLI show commands to collect from host device automatically extracted from per-host test suite. For example, for above data these are commands collected from devices:
ceos1 - “show version”, “show interface Ethernet1”, “show interface Ethernet2”
ceos2 - “show version”
Collected show commands output tested using rendered test suite on a per-host basis, producing these sample results:
[root@salt-master /]# salt nrp1 nr.test suite="salt://tests/test_suite_template.j2" table=brief nrp1: +----+--------+----------------------------------+----------+-------------+ | | host | name | result | exception | +====+========+==================================+==========+=============+ | 0 | ceos2 | check ceos version | PASS | | +----+--------+----------------------------------+----------+-------------+ | 1 | ceos1 | check ceos version | PASS | | +----+--------+----------------------------------+----------+-------------+ | 2 | ceos1 | check interface Ethernet1 status | PASS | | +----+--------+----------------------------------+----------+-------------+ | 3 | ceos1 | check interface Loopback1 status | PASS | | +----+--------+----------------------------------+----------+-------------+
nr.tping
- salt_nornir.modules.nornir_proxy_execution_module.tping(ports=None, timeout=1, host=None, **kwargs)
Tests connection to TCP port(s) by trying to establish a three way handshake. Useful for network discovery or testing.
- Parameters
int) (ports (list of) – tcp ports to ping, defaults to host’s port or 22
(int) (timeout) – defaults to 1
(str) (host) – defaults to
hostname
Sample usage:
salt nrp1 nr.tping salt nrp1 nr.tping FB="LAB-RT[123]"
Returns result object with the following attributes set:
result (
dict
): Contains port numbers as keys with True/False as values
Sample Python API usage from Salt-Master:
import salt.client client = salt.client.LocalClient() task_result = client.cmd( tgt="nrp1", fun="nr.tping", kwarg={"FB": "LAB-RT[123]"}, )