Nornir Execution Module

SaltStack execution modules serve the purpose of exposing functionally to interact with devices and systems.

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 task

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

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:

DataProcessor -> TestsProcessor -> DiffProcessor -> ToFileProcessor
Common CLI Arguments Summary

Name

Description

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

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

Emit events on Salt Events Bus for failed tasks

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

match

Filters text output using Nornir-Salt DataProcessor match function

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 download and render 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

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"}'

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

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.test, nr.nc, nr.do, nr.http

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.

Keys listed in download argument ignored by render argument even if same key contained with render argument. Arguemnts names listed in donwload are not rendered, only loaded from Salt Master.

Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.test, 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 dowloading 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.

Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.test, nr.nc, nr.do, nr.http

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

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

CLI Arguments:

  • jmespath - JMESPath query expression string

Sample usage:

salt nrp1 nr.task nornir_napalm.plugins.tasks.napalm_get getters='["get_interfaces"]' jmespath='interfaces'

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.test, 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

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.

Supported functions: nr.task, nr.cli, nr.cfg, nr.cfg_gen, nr.test, nr.nc, nr.do, nr.http

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

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="interf" 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, nr.http

CLI Arguments:

  • table - boolean or table type indicator, supported values: True, brief, extend

  • 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.test, nr.nc, nr.do, nr.http

CLI Arguments:

  • tf - ToFileProcessor file group name where to save results

Sample usage:

salt nrp1 nr.cfg "logging host 1.1.1.1" tf="logging_config"

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.test, nr.nc, nr.do, nr.http

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_detals=True
salt nrp1 nr.cli "show clock" add_detals=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.cfg, nr.cfg_gen, 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.cfg, nr.cfg_gen, nr.nc, nr.do, nr.http, nr.cli

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 confiurations combined with significant number of devices simelteniously returning results.

Execution Module Functions

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

Function to call Nornir Utility Functions

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’s hostnames

nr.cfg

salt_nornir.modules.nornir_proxy_execution_module.cfg(*commands, **kwargs)

Function to push configuration to devices using napalm_configure or netmiko_send_config or Scrapli send_config task plugin.

Parameters
  • commands – (list) list of commands or multiline string to send to device

  • filename – (str) path to file with configuration

  • template_engine – (str) template engine to render configuration, default is jinja

  • 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

  • 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 dictionary commit argument supplied to commit call using **commit

Warning

dry_run not supported by netmiko plugin

Warning

commit not supported by scrapli plugin. 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 mode as well.

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}'

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 only for filenames that start with salt://. 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(*commands, **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
  • filename – (str) path to template

  • template_engine – (str) template engine to render configuration, default is jinja

  • 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]"

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 behaviour supported only for filenames that start with salt://. 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(*commands, **kwargs)

Method to retrieve commands output from devices using send_command task plugin from either Netmiko or Scrapli library.

Parameters
  • commands – (list or str) list of commands or single command

  • filename – (str) path to file with multiline commands string

  • kwargs – (dict) any additional arguments to use with specified plugin send command method

  • plugin – (str) name of send command task plugin to use - netmiko (default) or scrapli

Sample Usage:

salt nrp1 nr.cli "show clock" "show run" FB="IOL[12]" netmiko_kwargs='{"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"]}'

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 Salt Master, that text file can also be a template and rendered using SaltStack rendering system:

salt nrp1 nr.cli filename="salt://device_show_commands.txt"

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 DiffProcessor

diff attribute 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:

  • Minion’s configuration

  • Minion’s grains

  • Minion’s pillar data

  • Master configuration (requires pillar_opts to be set to True in Minion config file in order to work)

  • File on master file system

To retrieve actions content Salt nr.do uses config.get execution module function with merge key set to True.

Each step definition requires these keywords to be defined:

  • function - mandatory, name of any 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 in error if False

  • filepath – (str) path to file with actions steps

  • 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 Saltstack supported renderers content and can be located at any url supported by cp.get_url execution module function. File content must render to a dictionary keyed by actions names.

Sample actions steps definition using proxy minion pillar:

nornir:
  actions:
    awr:
      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:

awr:
  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. Cllect ntp configuration"

Action name awr 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 premitted, 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 awr
salt nrp1 nr.do configure_ntp awr stop_on_error=False
salt nrp1 nr.do configure_ntp FB="*core*" add_details=True
salt nrp1 nr.do awr 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", "awr"],
    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 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 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 criterie 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 utilising 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:

  • pygnmi - nornir-salt built-in plugin that uses PyGNMI library to interact with devices.

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 render to a dictionary supplied to set call as a **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, reference that task plugin diocumentation 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

  • 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 exection module functions with tf argument.

Supported exection 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 utilising 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

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
    
  • locked - same as edit_config, but runs this (presumably more reliable) work flow:

    1. Lock target configuration/datastore

    2. Discard/clean previous changes if any

    3. Edit configuration

    4. Validate new confiugration if plugin and server supports it

    5. Run commit confirmed if plugin and server supports it

    6. Run final commit

    7. Unlock target configuration/datastore

    If any of steps 3, 4, 5, 6 fails, all changes discarded.

    Sample usage:

    salt nrp1 nr.nc locked 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, consult modules’ api help 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 commit
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 locked 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.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:

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

  • refresh - re-instantiates Nornir object after retrieving latest pillar data from Salt Master

  • kill - executes immediate shutdown of Nornir Proxy Minion process and child processes

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

  • inventory - retrieves Nornir Process inventory data, accepts Fx arguments to return inventory for a subset of hosts

  • 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, accepts Fx arguments to filter hosts to list

  • disconnect - close host connections, accept Fx arguments to filter hosts and conn_name of connection to close, by default closes all connections

Sample Usage:

salt nrp1 nr.nornir inventory FB="R[12]"
salt nrp1 nr.nornir stats stat="proxy_minion_id"
salt nrp1 nr.nornir version
salt nrp1 nr.nornir shutdown

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

salt_nornir.modules.nornir_proxy_execution_module.task(plugin, *args, **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) any additional argument to use with specified task plugin

plugin attribute can reference file on SALT Master with task function content, that file downloaded from master, compiled and executed. File must contain function named task accepting Nornir task object as a first positional argument, for instance:

# 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 nr_test a=b c=d add_details=False
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 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

  • saltenv – (str) name of salt environment to downoad 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.

  • kwargs – (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) or scrapli

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

  • cli – (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 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

Sample usage with inline arguments:

salt np1 nr.test "show run | inc ntp" contains "1.1.1.1" FB="*host-1"
salt np1 nr.test "show run | inc ntp" contains "1.1.1.1" --output=table
salt np1 nr.test "show run | inc ntp" contains "1.1.1.1" table=brief
salt np1 nr.test commands='["show run | inc ntp"]' test=contains pattern="1.1.1.1"

Sample usage with a suite of test cases:

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*"

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

Each item in a test suite executed individually one after another.

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 under cli keyword passed on to nr.cli function.

List of arguments in a test suite that can reference text file on salt master using 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

nr.tping

salt_nornir.modules.nornir_proxy_execution_module.tping(ports=[], 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]"},
)