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

Anything under inventory extras section passed on to Ncclient manager.connect call except for non Ncclient specific argument.

``extras`` section non Ncclient specific argument

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.