Connection Plugins
Connection plugins help to connect with devices. Reference documentation for more information.
NcclientPlugin
Ncclient library connection plugin to interact with devices over NETCONF.
NcclientPlugin reference
- nornir_salt.plugins.connections.NcclientPlugin.NcclientPlugin()
Full list of inventory extras see Ncclient Docs for
manager.connect
method.Example on how to configure a device to use netconfig without using an ssh agent and without verifying the keys:
host-1: hostname: 192.168.16.20 username: admin password: admin port: 2022 connection_options: ncclient: extras: allow_agent: False hostkey_verify: False raise_mode: None
Everything under inventory
extras
section passed on to Ncclientmanager.connect
call except for non Ncclient specific arguments.``extras`` section non Ncclient specific arguments
raise_mode
- valid values are None, “all” (default) or “errors”, defines how errors indicated by RPC handled by Ncclient:None
- don’t raise any type of rpc-error as exceptionerrors
- raise only when the error-type indicates it is an errorall
- don’t look at the error-type, always raise
HTTPPlugin
HTTP Connection plugin to interact with devices over HTTP/HTTPS.
HTTPPlugin reference
- nornir_salt.plugins.connections.HTTPPlugin.HTTPPlugin()
This plugin connects to the device via HTTP using Python requests library.
Connection reference name is
http
Full list of inventory extras see here
Sample Nornir inventory:
hosts: ceos1: hostname: 10.0.1.4 platform: arista_eos groups: [lab, connection_params] ceos2: hostname: 10.0.1.5 platform: arista_eos groups: [lab, connection_params] groups: lab: username: nornir password: nornir connection_params: connection_options: http: port: 80 extras: transport: http verify: False base_url: "http://device1.lab/api/v1/" headers: Content-Type: "application/yang-data+json" Accept: "application/yang-data+json"
Anything under inventory extras section passed on to
requests.request(method, url, **kwargs)
call in a form of**kwargs
except fortransport
andbase_url
. Inventory parameters can be overridden on task call.transport
andbase_url
- used to form URL to send request to if no absolute URL provided on task call.
PyGNMIPlugin
PyGNMI library connection plugin to interact with devices over gNMI protocol.
This plugin maintains long running gNMI connection to devices, if this behavior
not desirable, consider using Nornir host’s close_connection
method to close
gNMI connection.
PyGNMIPlugin reference
- nornir_salt.plugins.connections.PyGNMIPlugin.PyGNMIPlugin()
Full list of inventory extras see PyGNMI Docs for
gNMIclient
class.Sample inventory:
host-1: hostname: 192.168.16.20 username: admin password: admin port: 2022 connection_options: pygnmi: extras: insecure: True gnmi_timeout: 10
Anything under inventory
extras
section passed on to PyGNMIgNMIclient
class object instantiation.
PyATSUnicon
PyATS connection plugin to interact with network devices.
Check supported platofrms page for platform codes.
This plugin uses Genie to load testbed inventory with single device and optional jumphosts definition, Genie itself relies on PyATS to perform lower level tasks, where PyATS relies on Unicon library to communicate with devices over CLI.
PyATSUnicon reference
- nornir_salt.plugins.connections.PyATSUnicon.PyATSUnicon()
This plugin makes use of PyATS tesbed definition to initiate device connections, testbed can be partially reconstructed out of Nornir inventory or complete testbed data can be provided under extras section.
Sample minimum inventory that reconstructed to PyATS testbed:
host-1: hostname: 192.168.16.20 username: admin password: admin port: 22 connection_options: pyats: platform: eos extras: devices: host-1: {}
connection_options:pyats:extras
section used to load PyATS testbed object.Above inventory reconstructed to this PyATS testbed data:
devices: host-1: os: eos credentials: default: username: admin password: admin connections: default: protocol: ssh ip: 192.168.16.20 port: 22 vty_1: protocol: ssh ip: 192.168.16.20
Alternatively, full testbed data can be specified using extras like this:
host-1: hostname: 192.168.16.20 username: admin password: admin connection_options: pyats: extras: testbed: name: eos_testbed devices: host-1: os: eos credentials: default: username: admin password: admin connections: default: protocol: ssh ip: 192.168.16.20 port: 22
In that case, because all mandatory parameters
os
,connections
andcredentials
provided, extras data used as is to load PyATS tesbed.It is mandatory to specify exact device cli prompt under
connection_options:pyats:extras:devices
as a dictionary key as well as for top level device key. In other words this will not work:host-1-foo: hostname: 192.168.16.20 connection_options: pyats: extras: devices: host-1-bar: {}
Where
host-1-foo
is Nornir inventory host name andhost-1-bar
is actual device prompt as seen on cli, these two keys must be of the same value.This plugin establishes all connections to device on startup.
To use connections pool instead of single connection, need to provide
pool
argument integer of value more or equal to 2 in connection’s parameters, otherwise connection ignored:host-1: hostname: 192.168.16.20 username: admin password: admin connection_options: pyats: extras: devices: host-1: os: eos connections: default: protocol: ssh ip: 192.168.16.20 pool: 3
pool
connection argument is not part of PyATS native testbed schema and only relevant in PyATSUnicon plugin context.
PureSNMPPlugin
Connection plugin to interact with devices over SNMP using puresnmp library.
If planning to use puresnmp plugin with SNMPv3 make sure to install additional dependencies on proxy minion. For example, for RedHAT Linux (CentOS, RockyLinux etc.) install gcc and Python devel packages substituting python39 with version of Python in use:
dnf install gcc python39-devel
Install pycrypto and puresnmp-crypto Python modules using crypto
extras:
pip install puresnmp[crypto]
This connection plugin based on puresnmp supports SNMP version 1, 2c and 3.
PureSNMPPlugin reference
- nornir_salt.plugins.connections.PureSNMPPlugin.PureSNMPPlugin()
This plugin connects to the device via SNMP using Python
puresnmp
library.Connection inventory reference name is
puresnmp
Sample Nornir inventory:
hosts: ceos1: hostname: 10.0.1.4 platform: arista_eos groups: [lab, connection_params_v2c] ceos2: hostname: 10.0.1.5 platform: arista_eos groups: [lab, connection_params_v3] groups: lab: username: nornir password: nornir connection_params_snmpv1: connection_options: puresnmp: port: 161 extras: version: v1 community: public connection_params_snmpv2c: connection_options: puresnmp: port: 161 extras: version: v2c community: public # this inventory uses specific passwords for auth and priv connection_params_snmpv3: connection_options: puresnmp: port: 161 username: snmpv3_user extras: version: v3 auth: password: auth_pass method: md5 priv: password: priv_pass method: des # this inventory uses "password: public" for auth and priv connection_params_snmpv3_common_password: connection_options: puresnmp: port: 161 username: snmpv3_user password: public extras: version: v3 auth: method: sha1 priv: method: aes
As an example,
connection_params_snmpv2c
inventory entry above matches this Arista cEOS SNMPv2c configuration:snmp-server community public rw
As an example,
connection_params_snmpv3
inventory entry above matches this Arista cEOS SNMPv3 configuration:snmp-server view snmpv3 iso included snmp-server group snmpview v3 priv write snmpv3 snmp-server user snmpv3_user snmpview v3 auth md5 auth_pass priv des priv_pass
NetboxConnectionPlugin
Netbox Connection plugin to communicate with Netbox.
NetboxConnectionPlugin reference
- nornir_salt.plugins.connections.NetboxConnectionPlugin.NetboxConnectionPlugin()
This plugin connects to Netbox Inventory system using pynetbox library.
Nornir inventory connection reference name is
netbox
Sample Nornir inventory:
hosts: ceos1: hostname: 10.0.1.4 platform: arista_eos groups: [lab, netbox_connection] ceos2: hostname: 10.0.1.5 platform: arista_eos groups: [lab, netbox_connection] groups: lab: username: nornir password: nornir netbox_connection: connection_options: netbox: username: admin password: admin port: 8000 extras: instances: dev: auth: ["dev", "dev123"] url: http://192.168.64.201:8000/ staging: url: http://192.168.64.202:8000/ production: url: http://192.168.64.203:8000/ token: 0123456789abcdef0123456789abcdef01234569 default: True user_defined: netbox: prod: url: http://192.168.64.203:8000/ token: 0123456789abcdef0123456789abcdef01234569
NetboxConnectionPlugin supports definition of multiple instances of Netbox parameters which are stored under
netbox
key in host connections extras dictionary and can be retrieved using below code in task plugins:def my_task(task): netboxes = task.host.get_connection("netbox", task.nornir.config)
where
netboxes
is a dictionary keyed by netbox instances names.Individual instance parameters used to instantiate
pynetbox.api
object.For a full list of inventory instance parameters refer to pynetbox.api documentation
Authentication - by default
token
takes precedence overauth
. If notoken
orauth
defined in instance parameters,auth
credentials automatically formed using host’s username and password attributes.Alternatively, Netbox connection parameters can be stored in
user_defined `` configuration instead of individual hosts, groups or defaults. Parameters in ``user_defined
configuration merged with extras configuration. Extras configuration takes precedence overuser_defined
configuration.NetboxConnectionPlugin inventory extras parameters:
- Parameters
instances – (dict) dictionary keyed by instance name with parameters
Individual instance parameters:
- Parameters
auth – (list) list of Netbox
[password, username]
default – (bool) if True, this instance is a default Netbox instance
url – (str) Netbox API URL
token – (str) Netbox API token
Netbox Task plugins use
via
attribute to refer to Netbox instance name to use for task execution,via
attribute by default points to instance marked asdefault: True
or at first instance if none of the instances indicated as default.