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 Ncclient manager.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 exception
errors - raise only when the error-type indicates it is an error
all - 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 for transport and base_url. Inventory parameters can be overridden on task call.

transport and base_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 PyGNMI gNMIclient 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 and credentials 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 and host-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