nornir-scrapli 2021.1.29

scrapli Nornir plugin

nornir_scrapli

nornir_scrapli -- scrapli's and scrapli_netconf's plugin for nornir!

Feel free to join the very awesome networktocode slack workspace here, where you will find a scrapli channel where you can discuss anything about scrapli, as well as tons of other channels covering all sorts of network/network-automation topics!

Table of Contents

• Quick Start Guide
  • Installation
  • A Simple Example
  • Additional Examples
• Supported Platforms
• Using Different Transports
• Documentation
• General Information
• Available Tasks
  • Telnet/SSH Tasks
  • NETCONF Tasks
• Available Functions

Quick Start Guide

Installation

In most cases installation via pip is the simplest and best way to install nornir_scrapli.

pip install nornir-scrapli

A Simple Example

Example config file:

---
inventory:
  plugin: YAMLInventory
  options:
    host_file: "nornir_data/hosts.yaml"
    group_file: "nornir_data/groups.yaml"
    defaults_file: "nornir_data/defaults.yaml"

Example inventory file (host/group/default, see "real" Nornir docs for lots more info!) -- please notice that there is a scrapli and a scrapli_netconf connection type here!:

---
iosxe-1:
  hostname: 172.18.0.11
  connection_options:
    scrapli:
      platform: cisco_iosxe
      port: 22
      extras:
        ssh_config_file: True
        auth_strict_key: False
    scrapli_netconf:
      port: 830
      extras:
        ssh_config_file: True
        auth_strict_key: False

NOTE: scrapli-netconf has no concept (at the moment!) of "platforms" - it simply implements RFC compliant NETCONF RPCs, so you do not need to pass iosxr, junos or anything like that to the scrapli_netconf connection options section!

from nornir import InitNornir
from nornir_scrapli.tasks import (
    get_prompt,
    send_command,
    send_configs
)

nr = InitNornir(config_file="nornir_data/config.yaml")

prompt_results = nr.run(task=get_prompt)
command_results = nr.run(task=send_command, command="show version")
config_results = nr.run(
    task=send_configs,
    configs=["interface loopback123", "description nornir_scrapli was here"],
)

print("get_prompt result:")
print(prompt_results["iosxe-1"].result)
print("send_command result:")
print(command_results["iosxe-1"].result)
print("send_configs result:")
print(config_results["iosxe-1"].result)

$ python my_scrapli_script.py
get_prompt result:
3560CX#
send_command result:
Cisco IOS Software, C3560CX Software (C3560CX-UNIVERSALK9-M), Version 15.2(4)E7, RELEASE SOFTWARE (fc2)
<SNIP>
send_configs result:

Netconf tasks are imported from the same package and in the same fashion as the "core" scrapli tasks:

from nornir_scrapli.tasks import (
    netconf_lock,
    netconf_unlock,
    netconf_edit_config,
    netconf_get,
    netconf_get_config,
    netconf_rpc
)

And are executed in the same fashion as well:

config = """<config>
    <interfaces xmlns="urn:ietf:params:xml:ns:yang:ietf-interfaces">
        <interface>
            <name>GigabitEthernet1</name>
            <description>scrapli was here!</description>
        </interface>
    </interfaces>
</config>"""
result = nr.run(task=netconf_edit_config, config=config)
print(result['iosxe1'][0].result)
print(result['iosxe1'][0].scrapli_response.xml_result)

When using the scrapli-netconf tasks the result object result will be the string of the returned data from the device. As with all other nornir-scrapli results, the scrapli_response object will be assigned to the Result object and will contain all of the "normal" scrapli response object data (or scrapli-netconf response data ), such as the elapsed_time, raw_result, xml_result, etc. -- you can see this in the above example!

Additional Examples

• NETCONF Usage
• Structured Data

Supported Platforms

nornir_scrapli supports the "core" scrapli drivers, the GenericDriver (for use with linux hosts generally speaking ), and the scrapli_community platforms as well! See scrapli core docs and the scrapli community docs for more info. The platform argument in the inventory data should use the "normal" NAPALM style platform names, generic, or the name of the scrapli_community platform (i.e. huawei_vrp)).

Example platform values (for inventory data):

platform: cisco_iosxe
platform: cisco_iosxr
platform: cisco_nxos
platform: arista_eos
platform: juniper_junos
platform: generic
platform: huawei_vrp

Using Different Transports

nornir_scrapli supports all synchronous scrapli transport plugins. By default, the "system" transport will be used, however you can change this in the extras section of your nornir inventory:

connection_options:
  scrapli:
    port: 22
    extras:
      ssh_config_file: True
      auth_strict_key: False
      transport: ssh2

Note that you will need to install scrapli_ssh2 or scrapli_paramiko if you want to use those transport plugins!

Documentation

Documentation is auto-generated using pdoc3. Documentation is linted (see Linting and Testing section) via pydocstyle.

Documentation is hosted via GitHub Pages and can be found here. You can also view this readme as a web page here.

To regenerate documentation locally, use the following make command:

make docs

General Information

Nornir has historically contained it's plugins within the actual Nornir codebase itself, this however has changed! As of mid September 2020, Nornir 3.0.0 has been officially released -- this move to the 3.x.x version now expects plugins to be external to the code base. If you are looking for pre 3.x.x support, please use the 2020.09.01 version.

If you have used Nornir before (pre 3.x.x), this package should be very similar to what you already know. Since the plugins used to live in Nornir you could simply import them from the appropriate package as such:

from nornir.plugins.tasks.networking import netconf_get_config

With nornir_scrapli you simply install this package along side "regular" Nornir, and import the tasks from nornir_scrapli directly:

from nornir_scrapli.tasks import send_command

As soon as a nornir_scrapli task is imported, it (nornir_scrapli) will register as a connection, and things should work as normal from there!

The last important difference with nornir_scrapli is that in addition to the "normal" data in the Nornir Result object, nornir_scrapli also assigns the scrapli Response object (or list of Response objects) to the scrapli_response attribute. This means that you can access all of the "normal" scrapli response data from this object -- including things like elapsed_time and textfsm_parse_output:

>>> some_nornir_result["sea-ios-1"].scrapli_response.elapsed_time
0.039469
>>> some_nornir_result["sea-ios-1"].scrapli_response.textfsm_parse_output()
[[some structured data back from the device!]]

If you would like to continue using print_result like "normal" in nornir, but would like to see structured data (if available) in the print_result output, you can use the nornir_scrapli print_structured_result function. This function can be imported from the scrapli functions module:

from nornir_scrapli.functions import print_structured_result

This function acts pretty much exactly like the "normal" print result function, but will of course try to print the structured result. By default this will try to use textfsm to parse results, but it is of course configurable via the parser keyword argument. As scrapli will return an empty data structure if parsing fails, this may cause tasks to look like they are getting skipped in the output (nornir's print result function does not print empty lists), if you would like to fall back to printing the unparsed output you can do so by setting the fail_to_string keyword argument to True as follows:

print_structured_result(my_agg_result, parser="genie", fail_to_string=True)

Available Tasks

All tasks presented here are methods that live in scrapli or scrapli_netconf -- these tasks are simply "wrapped " in such a way that they may be used within the constructs of nornir! The links below link back to the scrapli or scrapli_netconf docs for the given method -- in all (or very nearly all?) cases, the same arguments that the underlying library supports will be exposed to nornir!

Scrapli "core" Tasks

• get_prompt - Get the current prompt of the device
• send_command - Send a single command to the device
• send_commands - Send a list of commands to the device
• send_commands_from_file - Send a list of commands from a file to the device
• send_config - Send a configuration to the device
• send_configs - Send a list of configurations to the device
• send_configs_from_file - Send a list of configurations from a file to the device
• send_interactive - "Interact" with the device (handle prompts and inputs and things like that)

Scrapli Netconf Tasks

Note that not all devices will support all operations!

• netconf_capabilities - Get list of capabilities as exchanged during netconf connection establishment
• netconf_commit - Commit the configuration on the device
• netconf_discard - Discard the configuration on the device
• netconf_edit_config - Edit the configuration on the device
• netconf_delete_config - Delete a given datastore on the device
• netconf_get - Get a subtree or xpath from the device
• netconf_get_config = Get the configuration from the device
• netconf_lock - Lock the datastore on the device
• netconf_unlock - Unlock the datastore on the device
• netconf_rpc - Send a "bare" RPC to the device
• netconf_validate - Execute the validate rpc against a given datastore

Available Functions

• print_structured_result -- this function is very similar to the "normal" print_result function that now ships with the nornir_utils library (historically with nornir "core"), except it contains several additional arguments, most importantly the parser argument allows you to select textfsm or genie to decide which parser to use to parse the unstructured data stored in the results object. Please see the structured results example here for more details.