ktbyers / netmiko

Multi-vendor library to simplify Paramiko SSH connections to network devices

Netmiko

Multi-vendor library to simplify CLI connections to network devices

Contributing to Netmiko

CONTRIBUTING.md

Why Netmiko?

Network automation to screen-scraping devices is primarily concerned with gathering output from show commands and with making configuration changes.

Netmiko aims to accomplish both of these operations and to do it across a very broad set of platforms. It seeks to do this while abstracting away low-level state control (i.e. eliminate low-level regex pattern matching to the extent practical).

Getting Started

• Getting Started

Examples

You really should look here.

• Netmiko Examples

Supported Platforms

PLATFORMS

Installation

To install netmiko, simply us pip:

$ pip install netmiko

API-Documentation

API-Documentation

Common Issues/FAQ

Answers to some common questions

Tutorials

• Netmiko Overview
• Secure Copy
• Netmiko through SSH Proxy
• Netmiko and TextFSM
• Netmiko and what constitutes done

Getting Started:

Create a dictionary representing the device.

Supported device_types can be found in ssh_dispatcher.py, see CLASS_MAPPER keys.

from netmiko import ConnectHandler

cisco_881 = {
    'device_type': 'cisco_ios',
    'host':   '10.10.10.10',
    'username': 'test',
    'password': 'password',
    'port' : 8022,          # optional, defaults to 22
    'secret': 'secret',     # optional, defaults to ''
}

Establish an SSH connection to the device by passing in the device dictionary.

net_connect = ConnectHandler(**cisco_881)

Execute show commands.

output = net_connect.send_command('show ip int brief')
print(output)

Interface                  IP-Address      OK? Method Status                Protocol
FastEthernet0              unassigned      YES unset  down                  down
FastEthernet1              unassigned      YES unset  down                  down
FastEthernet2              unassigned      YES unset  down                  down
FastEthernet3              unassigned      YES unset  down                  down
FastEthernet4              10.10.10.10     YES manual up                    up
Vlan1                      unassigned      YES unset  down                  down

Execute configuration change commands (will automatically enter into config mode)

config_commands = [ 'logging buffered 20000',
                    'logging buffered 20010',
                    'no logging console' ]
output = net_connect.send_config_set(config_commands)
print(output)

pynet-rtr1#config term
Enter configuration commands, one per line.  End with CNTL/Z.
pynet-rtr1(config)#logging buffered 20000
pynet-rtr1(config)#logging buffered 20010
pynet-rtr1(config)#no logging console
pynet-rtr1(config)#end
pynet-rtr1#

API-Documentation

API Documentation

Below are some of the particularly handy Classes/functions for easy reference:

• Base Connection Object
• SSH Autodetect
• SSH Dispatcher
• Redispatch

Contributing

Contributors are welcome.

You can contribute to Netmiko in a variety of ways: answering questions on Slack (see below in Questions/Discussions), responding to issues, adding to the common issues, reporting/fixing bugs, or even adding your own device type.

Before contributing a new vendor/platform device type, remember that any code added needs to be supported in some fashion. To add a vendor/platform you can follow the outline here. Once you've worked on your first pass of your driver and have it functional, you'll need to include test data in order for it to be merged into develop, you can see the general flow of how to do that here.

For all code contributions, please ensure that you have ran black against the code or your code will fail the Travis CI build.

Questions/Discussion

If you find an issue with Netmiko, then you can open an issue on this projects issue page here: https://github.com/ktbyers/netmiko/issues. Please make sure you've read through the common issues and examples prior to opening an issue. Please only open issues for bugs, feature requests, or other topics related to development of Netmiko. If you simply have a question, join us on Slack...

If you have questions or would like to discuss Netmiko, a #netmiko channel exists in this Slack workspace. To join, use this invitation. Once you have entered the workspace, then you can join the #netmiko channel.

---

Kirk Byers
Python for Network Engineers
https://pynet.twb-tech.com

netmiko's Issues

Paramiko uses id_rsa/id_dsa and does not use username/password

If ~ssh/id_rsa.pub or ~ssh/id_dsa.pub Paramiko will try to use these and will not use the username/password that you specify.

Juniper - re-write unit tests

These tests need improved

Problem ending IOX XR config mode without commit command

The following question will occur when you end the config mode at IOS XR without commit:

RP/0/0/CPU0:ios-xrv(config)#end
Uncommitted changes found, commit them before exiting(yes/no/cancel)? [cancel]:

F5 LTM prompt handling (find_prompt) needs fixed

Need a unit test for F5 LTM

setup.py fails to install hp

setup.py fails to install hp package, leading to ImportError exception when importing netmiko.

Fixed by adding 'netmiko/hp' to packages list in setup.py

Static Analysis

Invest in static analysis tools which will help improve code readability, maintainability, and extensibility.

As an example, here's the final output of pylint against Netmiko's (current) master branch:

Global evaluation
-----------------
Your code has been rated at 6.08/10 (previous run: 6.08/10, +0.00)

Besides the CLI tool pylint, other tools that integrate with GitHub include:

• Travis CI
• Scrutinizer CI
• Landscape

There are many other tools, but those are ones I've used. They do things like:

• Run unit tests for you
• Analyze code health
• Graph results over time
• Suggest ways to clean up code
• Review pull requests and perform all of the above for every pull request
• Review all branches

send_command_expect() is not behaving correctly

send_command_expect() should stop at the expect_string() and return only up to the end of the expect_string.

strip_prompt parameter should be renamed to give you the option of stripping the expect_string which is normally the prompt.

It currently stops on the expect_string, but catches all the data in the output buffer including after the expect_string.

Need tests for Comware

Need unit tests for Comware (located in the netmiko/tests directory).

Design spec for Junos and IOS-XR on commit/confirm/rollback

This issue will be the design spec for Junos and IOS-XR on commit/confirm/rollback

What needs to be included here (please add items I am missing):

1. Standard commit (no confirm):
   a. Messages on exit when no commit (JunOS and IOS-XR are opposite here)
2. Commit with confirm
   a. Should have a parameter for how many minutes the confirm must come in
3. Rollback
   a. Default is rollback 0. Should have a parameter for rollback number
4. Lock / unlock mechanism
5. Juniper Private config mechanism
6. Should be probably cover / consider new Arista commit/confirm/locking mechanism.
7. Unit tests including (Junos and IOS-XR where appropriate)
   a. commit
   b. rollback
   c. failed commit / no commit
   d. commit confirm
   e. lock / unlock
   f. Juniper shared / exclusive / private
   g. IOX-XR exclusive
   h. commit message

F5 LTM needs normalize ANSI escape codes.

What is the purpose of the find_prompt string

What does it do, when does it get updated, is it named properly.

Placeholder as I am concerned how I am currently using this is going to cause problems/confusion.

Need explicit test on IOS XR for calling .commit() directly.

Juniper doesn't implement `check_config_mode()`

The Juniper methods do not implement check_config_mode(). This causes unexpected behavior and unnecessary duplication of code when trying to implement other features. The current config_mode() method in the Juniper file, for example, could be eliminated and a config_mode(config_command="configure") (from ssh_connection.py) could be used instead. I can work on this later, but here are a few notes.

The existing check_config_mode() method should be usable like this: check_config_mode(check_string='[edit'). That should enable certain methods to be written like this:

def config_mode(self):
    '''
    First check whether currently already in configuration mode.

    Enter config mode (if necessary)
    '''

    if not self.check_config_mode(check_string='[edit'):
        output += self.send_command('configure\n', strip_prompt=False, strip_command=False)
        if 'unknown command' in output:
            raise ValueError("Failed to enter configuration mode")
        if not '[edit' in output:
            raise ValueError("Failed to enter configuration mode")

    return output

Other methods could be written as well to take advantage of the check_config_mode() method, such as exit_config_mode(). commit() could probably be rewritten to use check_config_mode() as well as it doesn't make much sense to check to see if you're in config mode, then enter config mode if you're not, then commit the config. That's typically not a valid workflow, and there typically isn't a use case for committing nothing. Maybe there's one I haven't considered, though.

Should the strip ansi_escape_codes be raw strings

This is used for HP ProCurve switches.

Brocade support

1. Check enable mode needs added/integrated
2. Exit enable mode needs added/integrated

F5 LTM still has \r in the output.

Implement a login method for Cisco ASA

Juniper - how am I handling [edit] string in output

Strip Additional Juniper Prompts

There are Juniper prompts that are currently not stripped from output. See below.

 ❯ ssh 10.10.1.1
--- JUNOS 12.1X44-D25.5 built 2013-10-24 20:59:21 UTC
No alarms currently active

{primary:node0}
[email protected]> start shell
% rlogin -T node1
�
--- JUNOS 12.1X44-D25.5 built 2013-10-24 20:59:21 UTC

No alarms currently active

{secondary:node1}
[email protected]>

The method strip_context_items() does not currently strip these from output. I will submit a PR for this.

Update the base normalize_linefeeds to handle different cases

IOS-XR case
NX-OS case
HP ProCurve case

Multiple Configuration Modes

Juniper's CLI supports multiple configuration modes. The more common ones:

• private
• exclusive
• shared

The config_mode() method should incorporate these three common modes. I can work on this later, but an (untested) example is below.

def config_mode(self, mode=''):
    '''
    First check whether currently already in configuration mode.

    Enter config mode (if necessary), specifying the appropriate mode.  `mode` is blank
    by default (global config mode).
    '''

    supported_modes = ("", "private", "exclusive")
    if mode not in supported_modes:
        raise ValueError("Unsupported mode: {0}".format(mode))

    output = self.send_command('\n', strip_prompt=False, strip_command=False)
    if not '[edit' in output:
        command = "configure " + mode + "\n"
        output += self.send_command(command, strip_prompt=False, strip_command=False)
        if 'unknown command' in output:
            raise ValueError("Failed to enter configuration mode")
        if not '[edit' in output:
            raise ValueError("Failed to enter configuration mode")

    return output

establish_connection verbose message inaccurate.

establish_connection method in BaseSSHConnection prints "SSH connection established to {0}:{1}" even if the device the session is attempting to connect to is not a valid host on the network. Perhaps this message should be moved down right before line 96:

self.remote_conn = self.remote_conn_pre.invoke_shell()

Add asynchronous capabilities to connect to several devices in parallel (non-blocking)

find_prompt test needs renamed

This is not what this test does anymore and should be renamed.

Add a way to read commands from a file for send_command_set()

auto add SSH keys policy

Not a secure way to do this. Should allow for a secure way for this to be accomplished.

Error installing netmiko under Python 3.4

python3.4 setup.py install

Traceback (most recent call last):
File "setup.py", line 3, in
import netmiko
File "/home/c102/c1021058/devel/netmiko/netmiko/init.py", line 1, in
from ssh_dispatcher import ssh_dispatcher
ImportError: No module named 'ssh_dispatcher'

Fix find prompt so that it always first calls clear_buffer()

Cleaner to do it this way.

Boolean return values versus string return values

I am currently returning strings instead of booleans for some functions like enable(), config_mode() would returning booleans be more logical?

Juniper output prompt not stripped when output is xml.

Add tests that use SSH keys

Checkpoint device_type ?

What about adding checkpoint device_type. I can test on :
1.CP 1100
2.Edge UTM-1
3. VSX

Commit Confirm

Both Junos and IOS XR support the Commit Confirm feature. This may be a feature worth implementing it as it can save you from a lot of things. One use case is a commit confirm with a sufficient timeout to run automated tests, at which point the automated tests (or scripts or whatever) can commit the configuration permanently. This can save you from committing a bad change that kills connectivity to the box.

Should add commit message to IOS XR

Also probably a commit confirm time

Commit on IOS-XR

Add a rollback mechanism for IOS-XR

Issue with not updating find_prompt when you enter/exit enable, config mode

send_command_expect() method

Should improve to all for regular expression patterns.

Fix ASA paging so not a config command change

Use this instead so not a config command change:

terminal pager 0

Cisco IOS has no exit enable mode (that actually does anything)

Add NetMiko to PIP

Pip is generally the default ecosystem for installing Python modules. Putting NetMiko in pip could make it easier/more familiar to install and update NetMiko for end users.

Cisco WLC support

1. Do I need to re-enable paging before I disconnect from device (i.e. is the paging change actually stored in config)?
2. Verify WLC has no enable mode.
3. Verify WLC has no config mode.
4. Prompt typically ends in '>'
5. Need unit tests.

Extra \n in output for show commands on Juniper

Might also exist in other contexts as well.

Improve unit test on going into enable mode

This changed because of changing find_prompt() behavior and now the unit tests need corrected.

Allow Key-Based Authentication

Key-based SSH authentication can be highly desirable, particularly for automation. In #1, though, it was explicitly and statically disabled.

I propose that this be parameterized with a sane default of disabling SSH keys. I will be working on an implementation as I require this functionality for an upcoming project. It will probably be poorly considered as it is strictly for demonstrative purposes, but I may submit a PR with that change within the next week.

Improve tests for send_command_expect()

I added some tests into the test_cisco_ios.py, but the tests should be more robust (for example, cover alternate search_patterns than the router prompt; verify that exceptions are actually generated correctly for failure).

check_config_mode '(config' string will fail for Cisco IOS and potentially other vendors

Potentially use ')#' as a solution.

Look at what HP ProCurve does in config mode and wider sample of what Cisco does.

Explain what delay_factor is for?

Just wondering what the delay_factor in send_command() is for?

It seems to me it is a delay to wait for output from the device, before receiving it.

My issue lays with grabbing running configuration from Cisco gear - as it seems with a small delay factor all that is received is "Building configuration...\n". Some of the older Sup 720's etc with large configurations can take 40 seconds + to display the running configuration.

Is there no way to wait till a command is processed, instead of a delay factor?

Improve Test Suite for Other Users

Currently, tests require a module that's not part of the repository (for security reasons). However, there's no documentation (other than a note in an issue) as to how to supply the necessary information. Additionally, the tests have hard-set expectations for prompts (and possibly other items). See excerpt below.

    module.EXPECTED_RESPONSES = {
        'base_prompt'      : 'pynet-rtr1',
        'user_exec_prompt' : 'pynet-rtr1>',
        'enable_prompt'    : 'pynet-rtr1#',
        'interface_ip'     : '10.220.88.20',
        'config_mode'      : '(config)',
    }

This means that if a user contributing code (and new tests) wants to actually test his/her changes, he/she must have a device setup precisely this way. Being able to parse a YAML file (in .gitignore) with credentials, expected prompts, IPs, etc. would significantly increase the flexibility and accessibility of these tests.