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 to True is recommended way of running Nornir proxy-minion

  • with 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

nr.cfg

Function to modify devices configuration over ssh or telnet connections

napalm (default), netmiko, scrapli

nr.cfg_gen

Function to generate devices configuration using SALT templating system with Nornir inventory, mainly for testing purposes

nr.cli

Function for show commands output collection over ssh or telnet

netmiko (default), scrapli

nr.diff

To diff content of files or network with files saved by ToFileProcessor

nr.do

Function to execute actions with a set of steps calling other execution functions. Allows to construct simple work flows.

nr.file

Function to work with files saved by ToFileProcessor - read, delete, list etc.

nr.find

To search for various information in files saved by ToFileProcessor

nr.gnmi

Interact with devices using gNMI protocol

pygnmi

nr.http

To run HTTP requests against API endpoints

requests

nr.learn

This function is to save task results in files using ToFileProcessor and nr.do actions

nr.nc

Function to work with devices using NETCONF

ncclient (default), scrapli_netconf

nr.netbox

Integration with Netbox DCIM

nr.network

Network related utilities

nr.nornir

Function to call Nornir Utility Functions

nr.snmp

Function to manage davices over SNMP protocol

nr.task

Function to run any Nornir task plugin

nr.test

Function to test show commands output produced by nr.cli function

netmiko (default), scrapli

nr.tping

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
Common CLI Arguments Summary

Name

Description

add_details

Add task execution details to results

Fx

Filters to target subset of devices using FFun Nornir-Salt function

context

Overrides context variables passed by render to file.apply_template_on_contents exec mod function

dcache

Saves full task execution results to Nornir in-memory (RAM) Inventory defaults data

defaults

Default template context passed by render to file.apply_template_on_contents exec mod function

diff

Calls Nornir-Salt DiffProcessor to produce results difference

dp

Allows to call any function supported by Nornir-Salt DataProcessor

download

Renders arguments content using Salt cp module

dump

Saves complete task results to local file system using Nornir-Salt DumpResults function

event_failed

If True, emit events on Salt Events Bus for failed tasks

event_progress

If True, emit events on Salt Events Bus for tasks execution progress

hcache

Saves host’s task execution results to host’s in-memory (RAM) Inventory data

iplkp

Performs in CSV file or DNS lookup of IPv4 and IPv6 addresses to replace them in output

jmespath

uses JMESPath library to run query against structured results data

job_data

Job data, string, list or dictionary to load using slsutil.rendered function

match

Filters text output using Nornir-Salt DataProcessor match function

ntfsm

Parse nr.cli output using TextFSM ntc-templates

RetryRunner parameters

Task parameters to influence RetryRunner execution logic

render

Renders arguments content using Salt renderer system

run_ttp

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 base

table

Formats results to text table using Nornir-Salt TabulateFormatter

template_engine

Template Engine name to use with render to render files, default is jinja

tests

Run tests for task results using Nornir-Salt TestsProcessor

tf

Saves results to local file system using Nornir-Salt ToFileProcessor

to_dict

Transforms results to structured data using Nornir-Salt ResultSerializer

xml_flake

Uses Nornir-Salt DataProcessor xml_flake function to filter XML output

xpath

Uses Nornir-Salt DataProcessor xpath function to filter XML output

worker

Worker to use for task, supported values all or number from 1 to nornir_workers Proxy Minion parameter of default value 3

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:

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 inventory defaults data dictionary key name to save results under or if set to boolean True, uses dcache 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 with

  • last - 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 ID

  • filegroup - ToFileProcessor file group name where to save results

  • timestamp - date timestamp

  • rand - 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 ID

  • host - hostname of device that failed this task

  • name - 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, uses hcache 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 be dns to indicate that need to use DNS or reference to a CSV file on Salt Master in a format salt://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 for

  • before - 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 attempts

  • run_task_retry - number of attempts to run task

  • run_creds_retry - list of connection credentials and parameters to retry while connecting to device

  • run_num_workers - number of threads for tasks execution

  • run_num_connectors - number of threads for device connections

  • run_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 reference

  • ttp_structure - TTP results structure, supported values: flat_list (default), list or dictionary

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 for

  • headers_exclude - list of table headers to exclude from final table results

  • sortby - name of the header to sort table by, default is host

  • 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 run

  • failed_only - boolean, default is False, to indicate if to return results for failed tests only

  • remove_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 results

  • tf_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 results

  • to_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:

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 values all or number from 1 to nornir_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) or netmiko or scrapli or pyats

  • dry_run – (bool) default False, controls whether to apply changes to device or simulate them

  • commit – (bool or dict) by default commit is True. With netmiko plugin if commit argument is a dictionary it is supplied to commit call as arguments

Warning

dry_run not supported by netmiko and pyats plugins

Warning

commit not supported by scrapli and pyats 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:

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 or pyats

  • 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:

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 name

  • last – (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 with DiffProcessor

diff or args attributes are mandatory.

If last is a single digit e.g. 1, diff uses nr.do function to execute action named same as filegroup attribute and uses results to produce diff with previously saved filegroup files using DiffProcessor.

If last is a list e.g. [2, 5] or string 1, 2- will use nr.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 uses config.get execution module function with merge key set to recurse.

Each step definition requires these keywords to be defined:

  • function - mandatory, name of any Salt-Nornir execution module function to run

  • args - optional, any arguments to use with function

  • kwargs - optional, any keyword arguments to use with function

  • description - optional, used by dir 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 on 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 override kwargs dictionary defined within each step, for example, in command salt nrp1 nr.do configure_ntp FB="*core*", FB argument will override FB arguments defined within steps.

  • tf – (bool) if True, ToFileProcessor saves each step results in file named after step name if no tf argument provided within step, default is False

  • diff – (bool) if True, DiffProcessor runs diff for each step result using files named after step name if no diff argument provided within step, default is False

Returns

dictionary with keys: failed bool, result list; result key contains a list of results for steps; If stop_on_error set to True and error happens, failed key set to True

Special action names dir and dir_list used to list all actions available for proxy minion where dir returns table and dir_list produces a list of actions.

Note

if filepath argument provided, actions defined in other places are ignored; file loaded using SaltStack slsutil.renderer execution module function, as a result file can contain any of supported SaltStack renderer content and can be located at any URL supported by cp.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, while configure_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 Salt config.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

  • base_url – (str) base path to files, default is /var/salt-nornir/{proxy_id}/files/

  • index – (str) index filename within base_url folder to read files info from, default value is equal to proxy id

  • 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 dictionaries

  • rm - removes file with given name and index number

  • read - displays content of file with given name and index number

  • diff - reads two files and returns diff

ls arguments

Parameters

filegroup – (str or list) tf or list of tf 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 of tf 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 of tf filegroup names of the files to read

  • last – (int) version of content to read

Returns

results reconstructed out of files content

diff arguments

Parameters
  • filegroup – (str or list) tf filegroup name to diff

  • last – (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 in

  • kwargs – (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 provided nr.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 call

  • path – (list or str) gNMI path string for update, delete, replace extra methods calls

  • filename – (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:

gNMI specification defines several methods to work with devices - subscribe, get and set. set further supports delete, update and replace operations.

Warning

subscribe is not supported by nr.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 by gNMIclient connection object, including extra methods defined by nornir-salt pygnmi_call task plugin:

    salt nrp1 nr.gnmi dir
    
  • help - returns method_name docstring:

    salt nrp1 nr.gnmi help method_name=set
    
  • replace - shortcut method to set call with replace 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 to set call with update 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 to set call with delete argument, accepts a list of path items or path 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 using slsutil.renderer function and must produce a dictionary with keys being valid arguments supported by call method. For example, pygnmi plugin set 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 to set call as **kwargs.

pygnmi plugin order of operation for above case is delete -> 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 name

  • tf_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 with tf argument.

Supported execution module functions are cli, nc, do, http. By default calls nr.do function.

tf attribute mandatory except for cases when using nr.do``function e.g. ``salt nrp1 nr.learn mac interface, in that case tf set equal to file group name - mac and interface for each action call using nr.do function tf=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 uses ncclinet library to interact with devices

  • scrapli - uses scrapli_netconf connection plugin that is part of nornir_scrapli library, it does not use scrapli_netconf task plugins, but rather implements a wrapper around scrapli_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 content

  • method_name – (str) name of method to provide docstring for, used only by help call

Plugins details:

Special call arguments/methods:

  • dir - returns methods supported by Ncclient connection manager object:

    salt nrp1 nr.nc dir
    
  • help - returns method_name docstring:

    salt nrp1 nr.nc help method_name=edit_config
    
  • transaction - same as edit_config, but runs this (presumably more reliable) work flow:

    1. Lock target configuration datastore

    2. If server supports it - Discard previous changes if any

    3. Perform configuration edit using RPC specified in edit_rpc argument

    4. If server supports it - validate configuration if validate argument is True

    5. If server supports it - do commit confirmed if confirmed argument is True using confirm_delay timer with commit_arg argument

    6. If confirmed commit requested, wait for commit_final_delay timer before sending final commit, final commit does not use commit_arg arguments

    7. If server supports it - do commit operation

    8. Unlock target configuration datastore

    9. If server supports it - discard all changes if any of steps 3, 4, 5 or 7 fail

    10. 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 for ncclient vs filter_/filters for scrapli_netconf, refer to modules’ api documentation for required arguments, using, for instance help 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 have pillar_opts set to True 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.

Starting with version 0.20.0 support added to cache data retrieved from Netbox on a per-device basis. For this functionality to work need to have diskcache library installed on salt-nornir proxy minion. Cache is persistant and stored on the minion’s local filesystem.

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 and fields parameters.

To use query task need to provide one of

  • query_string or

  • field, filters and fields parameters to form query string or

  • queries 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

  • cache – True (default) - use cache for Netbox data, refresh - delete cached data, False - ignore cache

  • cache_ttl – integer indicating cache time to live

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

  • cache – True (default) - use cache for Netbox data, refresh - delete cached data, False - ignore cache

  • cache_ttl – integer indicating cache time to live

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 function

resolves hosts’ hostname DNS returning IP addresses using nornir_salt.plugins.tasks.network.resolve_dns Nornir-Salt function.

ping function

Function to execute ICMP ping to host using nornir_salt.plugins.tasks.network.ping Nornir-Salt function.

Sample Usage:

salt nrp1 nr.network resolve_dns ipv4=True ipv6=False servers='["8.8.8.8", "1.1.1.1"]'
salt nrp1 nr.network ping count=10 df=true size=1000 timeout=1 interval=0.1

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 functions

  • test - this method tests proxy minion module worker thread without invoking any Nornir code

  • refresh - re-instantiates Nornir workers after retrieving latest pillar data from Salt Master, if workers_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 processes

  • shutdown - gracefully shutdowns Nornir Proxy Minion process and child processes

  • inventory - interact with Nornir Process inventory data, using InventoryFun function, by default, for read_host, read, read_inventory, list_hosts, list_hosts_platforms operations any Nornir worker can respond, for other, non-read operations targets all Nornir workers

  • stats - returns statistics about Nornir proxy process, accepts stat argument of stat name to return

  • version - returns a report of Nornir related packages installed versions

  • initialized - returns Nornir Proxy Minion initialized status - True or False

  • hosts - returns a list of hosts managed by this Nornir Proxy Minion, accepts Fx arguments to return only hosts matched by filter

  • connections - list hosts’ active connections for all workers, accepts Fx arguments to filter hosts to list, by default returns connections data for all Nornir workers, uses nornir_salt.plugins.tasks.connections ls call, accept conn_name parameter

  • disconnect - close host connections, accepts Fx arguments to filter hosts and conn_name of connection to close, by default closes all connections from all Nornir workers, uses nornir_salt.plugins.tasks.connections close call

  • connect - initiate connection to devices, arguments: conn_name, hostname, username, password, port, platoform, extras, default_to_host_attributes, close_open, uses nornir_salt.plugins.tasks.connections open call

  • clear_hcache - clear task results cache from hosts’ data, accepts cache_keys list argument of key names to remove, if no cache_keys argument provided removes all cached data, by default targets all Nornir workers

  • clear_dcache - clear task results cache from defaults data, accepts cache_keys list argument of key names to remove, if no cache_keys argument provided removes all cached data, by default targets all Nornir workers

  • workers/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 inventory read_host_data keys="['hostname', 'platform', 'circuits']"
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.service

salt_nornir.modules.nornir_proxy_execution_module.service(name, *args, **kwargs)

Function to interact with services definitions.

Parameters
  • name – service name

  • action – what action to do with service - activate, list, deactivate, verify

Service Actions Description

activate - implements service into the network

Sample usage:

salt nrp1 nr.service ntp apply

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 call

  • kwargs – (dict) any additional keyword arguments to use with call method

Returns

method call results

Available SNMP plugin names:

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 and oids 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 - returns method_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 run from 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 by default.

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 is contains, pattern value used as a pattern for containment check

  • function_file – (str) path to text file on salt master with function content to use for custom function test

  • dry_run – (bool) if True, returns produced per-host tests suites content only, no tests performed, subset not supported with dry run

  • saltenv – (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 matching

  • dump – (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, if strict is True raises error when tests path item not found in any of the hosts’ invenotry data, default is False

  • worker – (int) Nornir worker ID to render and execute tests, all not supported, only interger to indicate particular worker, default is None - can run on any worker

  • job_data – (dict, list) job_data argument used for tests rendering

  • return_tests_suite – (bool) if True returns dictionary with test results and suite keys allowing to view the content of fully rendered per-host tests suite

nr.cli function related arguments

nr.test calls nr.cli function with tests argument containing provided tests suite content, it is possible to pass any nr.cli arguments while calling nr.test execution module function. Notable arguments are:

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) or scrapli

  • use_ps – (bool) default is False, if True uses netmiko plugin experimental PromptlesS method to collect output from devices

  • kwargs – (dict) any additional arguments to use with nr.cli function to run tests

Nornir-Salt TestsProcessor plugin related arguments

Parameters
  • failed_only – (bool) default is False, if True nr.test returns result for failed tests only

  • remove_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" 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
  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 dictionaries

Sample 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.

Below is a 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:// and file:// (local filesystem), for example salt://path/to/file.txt

  • pattern - content of the file rendered and used to run the tests together with ContainsTest, ContainsLinesTest or EqualTest test functions

  • schema - used with CerberusTest test function

  • function_file - content of the file used with CustomFunctionTest as function_text argument

Rendering Tests Suite using 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     |             |
    +----+--------+----------------------------------+----------+-------------+

Starting with Salt-Nornir 0.20.0 support added to run test suites not only using nr.cli function but also with these Salt-Nornir execution module functions: nr.tping, nr.task, nr.http, nr.nc, nr.gnmi, nr.network, nr.file, nr.snmp. Other functions are prohibited and suite execution will fail with validation error.

Sample suite that uses salt argument to customize execution module function to collect output from devices:

- name: Check version using NAPALM get_facts
  test: custom
  function: salt://test/test_software_version.py
  salt:
    function: nr.task
    plugin: nornir_napalm.plugins.tasks.napalm_get
    getters: ["get_facts"]
- name: Check NTP configuration
  test: contains_lines
  pattern: ["1.1.1.1", "2.2.2.2"]
  task: "show run | inc ntp"
  salt:
    function: nr.cli
    plugin: scrapli
    use_timing: True
    read_timeout: 300
 - name: Check ceos tping
   test: eval
   task: nornir_salt.plugins.tasks.tcp_ping
   expr: assert result[22] is True
   err_msg: SSH Port 22 not reachable
   salt:
     function: nr.tping

As an optimisation technique, all tests that use nr.cli with same set of arguments are grouped together and commands retrieved from devices in a single nr.cli call.

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]"},
)