netmiko-grep

Author: Kirk Byers
Date: 2021-09-16

This article was originally written on May 20th, 2016. It was updated and re-tested against the Netmiko 4.x code (develop branch) on September 21st, 2021.

Introduction

Netmiko contains a command-line utility named 'netmiko-grep'.

The basic idea behind netmiko-grep is to use Netmiko to pull configuration files from network devices and then to pattern search through these files.

For example, here I use netmiko-grep to search for the string 'interface' in the running-configs of the 'cisco' group. I will discuss groups later in this article.

$ netmiko-grep 'interface' cisco
cisco3.txt:interface GigabitEthernet0/0/0
cisco3.txt:interface GigabitEthernet0/0/1
cisco3.txt:interface GigabitEthernet0/1/0
cisco3.txt:interface GigabitEthernet0/1/1
cisco3.txt:interface GigabitEthernet0/1/2
cisco3.txt:interface GigabitEthernet0/1/3
cisco3.txt:interface Vlan1
cisco4.txt:interface GigabitEthernet0/0/0
cisco4.txt:interface GigabitEthernet0/0/1
cisco4.txt:interface GigabitEthernet0/1/0
cisco4.txt:interface GigabitEthernet0/1/1
cisco4.txt:interface GigabitEthernet0/1/2
cisco4.txt:interface GigabitEthernet0/1/3
cisco4.txt:interface Vlan1

And here I search for the string 'span' in the 'arista' group:

$ netmiko-grep 'span' arista
arista1.txt:   spanning-tree portfast
arista1.txt:   spanning-tree cost 1
arista2.txt:spanning-tree mode rapid-pvst
arista2.txt:   spanning-tree portfast
arista2.txt:   spanning-tree cost 1

By default netmiko-grep will operate on the running-config, but it also can execute arbitrary show commands using the '--cmd' argument.

$ netmiko-grep --cmd 'show arp' '10.220.88.1' cisco
cisco3.txt:Internet 10.220.88.1 100  0062.ec29.70fe ARPA GigabitEthernet0/0/0
cisco4.txt:Internet 10.220.88.1 100  0062.ec29.70fe ARPA GigabitEthernet0/0/0

Here I execute 'show arp' on the 'cisco' group and search for a pattern of '10.220.88.1' in the 'show arp' output.

Creating the Inventory

netmiko-grep uses a very simple YAML inventory.

In order to find the inventory file, netmiko-grep will first look for a file named '.netmiko.yml' in your current directory and then in your home directory.

The inventory file uses YAML and consists of both a 'hosts' section and a 'groups' section.

Hosts are created by specifying a YAML dictionary with all of the necessary Netmiko connection arguments. For example:

# Dictionaries are devices
cisco3:
  device_type: cisco_xe
  host: cisco3.lasthop.io
  username: admin
  password: cisco123

cisco4:
  device_type: cisco_xe
  host: cisco4.lasthop.io
  username: admin
  password: cisco123

Groups are created by specifying a YAML list and referring to one of the previously created hosts. For example:

# Any list is group of devices
cisco:
  - cisco3
  - cisco4

Here is a simple .netmiko.yml file:

---
# Dictionaries are devices
cisco3:
  device_type: cisco_xe
  host: cisco3.lasthop.io
  username: admin
  password: cisco123

cisco4:
  device_type: cisco_xe
  host: cisco4.lasthop.io
  username: admin
  password: cisco123

arista1:
  device_type: arista_eos
  host: arista1.lasthop.io
  username: admin
  password: notcisco123

arista2:
  device_type: arista_eos
  host: arista2.lasthop.io
  username: admin
  password: notcisco123

# Any list is group of devices
cisco:
  - cisco3
  - cisco4

arista:
  - arista1
  - arista2

A group named 'all' is created automatically.

You can see a more detailed .netmiko.yml file here.

You can also display your inventory by using the '--list-devices' argument:

$ netmiko-grep --list-devices

Devices:
----------------------------------------
arista1                     (arista_eos)
arista2                     (arista_eos)
cisco3                        (cisco_xe)
cisco4                        (cisco_xe)


Groups:
----------------------------------------
all
arista
cisco

What does netmiko-grep do Internally?

Behind the scenes netmiko-grep will automatically create a ~/.netmiko/tmp directory.

Inside this directory it will store the 'cmd' output from the remote device. By default, 'cmd' will be 'show run' or its equivalent as determined by the SHOW_RUN_MAPPER in Netmiko's utilities.py module.

In other words, Netmiko tries to automatically determine what the 'show run' equivalent is for a given platform.

netmiko-grep does not currently remove the output files from ~/.netmiko/tmp (so be aware of this if you use this utility).

Performance

netmiko-grep automatically uses threads to establish concurrent SSH connections. You can test how long a given action takes by adding the '--display-runtime' argument.

$ netmiko-grep --display-runtime 'bgp' all
cisco1.txt:router bgp 42
cisco1.txt: bgp router-id 10.220.88.20
cisco1.txt: bgp log-neighbor-changes
nxos1.txt:feature bgp
nxos1.txt:router bgp 22
nxos2.txt:feature bgp
nxos2.txt:router bgp 22
Total time: 0:00:07.183600

The above command took about 7 seconds to execute on twenty test devices. For this test, I changed the inventory to a different .netmiko.yml file that contained more devices.

netmiko-grep should scale to a relatively large number of devices (hundreds). At one point, we tested it on approximately twelve hundred devices.

netmiko-grep also has a way to use the previously saved configuration file: just add the --use-cache argument. This argument will reuse whatever output data was previously saved (by default the running-config output).

Obviously, this is a lot faster since we are just grepping local files that already exist on the system.

Installation Process

# Install the Netmiko 'develop' branch using pip
$ pip install git+https://github.com/ktbyers/netmiko.git@develop
$ pip install pyyaml

# Verify Netmiko 4.X code is being used
$ pip list | grep netmiko
netmiko       4.0.0a4

# Verify netmiko-grep is on your path
$ which netmiko-grep
~/VENV/netmiko_test/bin/netmiko-grep

# Create your .netmiko.yml inventory
$ vi ~/.netmiko.yml 

# Test that it works
$ netmiko-grep 'vlan' cisco3
vlan internal allocation policy ascending

Note, I have been testing almost exclusively on Linux; I have only done a small amount of validation on MacOS. This utility probably won't work on Windows (not sure actually).

Final Thoughts

netmiko-grep has some additional command-line arguments that I didn't cover in this article. You can see the full set of arguments by executing "--help":

$ netmiko-grep --help
usage: netmiko-grep [-h] [--cmd CMD] [--username USERNAME]
                    [--password] [--secret] [--use-cache]
                    [--list-devices] [--display-runtime]
                    [--hide-failed] [--version]
                    [pattern] [devices]

Grep pattern search on Netmiko output (defaults to running-
config)

positional arguments:
  pattern              Pattern to search for
  devices              Device or group to connect to

optional arguments:
  -h, --help           show this help message and exit
  --cmd CMD            Remote command to execute
  --username USERNAME  Username
  --password           Password
  --secret             Enable Secret
  --use-cache          Use cached files
  --list-devices       List devices from inventory
  --display-runtime    Display program runtime
  --hide-failed        Hide failed devices
  --version            Display version

Besides netmiko-grep there are two other Netmiko command-line utilities namely 'netmiko-show' and 'netmiko-cfg'. I discuss these additional tools in this article.

Kirk Byers

@kirkbyers

You might be interested in