SSH client for network devices built on ssh2-python
Library focusing on connecting to and communicating with network devices via SSH. Built on ssh2-python which provides bindings to libssh2.
ssh2net is focused on being lightweight and pluggable so that it should be flexible enough to be adapted to handle connecting to, sending commands, and reading output from most network devices.
Documentation is auto-generated using pdoc3. Documentation is linted (see Linting and Testing section) via pydocstyle.
To regenerate documentation locally, use the following make command:
In theory ssh2net should be able to connect to lots of different network devices. At the moment the following devices are included in the "functional" tests and should be pretty reliable:
- Cisco IOS-XE
- Cisco NX-OS
- Juniper JunOS
I would like to add functional tests for:
- Cisco IOS-XR
- Arista EOS
Any additional platforms would likely not be included in the "core" platform (and therefore functional testing). Additional platforms could be considered, however a pre-requisite for additional platforms would be the capability to create vrnetlab containers for that platform.
As for platforms to run ssh2net on -- it has and will be tested on MacOS and Ubuntu regularly and should work on any POSIX system. It has never been tested on Windows, but I don't see any reason it should not work, however I have no plans on supporting Windows as I don't have access or desire to do so.
To install from this repository:
pip install git+https://github.com/carlmontanari/ssh2net
To install from source:
git clone https://github.com/carlmontanari/ssh2net cd ssh2net python setup.py install
I've also attempted to add this to PyPI, so you should be able to pip install it "normally":
pip install ssh2net
TBA, probably things though!
This was created as a learning project, so contributions are not expected, but are very welcome! Feel free to open PRs or Issues as needed. Any contributions would need to at a minimum successfully complete a tox run since there is no CI at this point.
Between tox and the Makefile, I hope that testing should be pretty easy, with a big caveat that you will need to get vrnetlab setup and working for functional testing to occur in a reasonable and repeatable fashion.
Linting and Testing
This project uses black for auto-formatting. In addition to black, tox will execute pylama, and pydocstyle for linting purposes. I have began playing with adding type hinting and testing this with mypy, however I've not added this to tox at this point.
I broke testing into two main categories -- unit and functional. Unit is what you would expect -- unit testing the code. Functional testing connects to virtual devices in order to more accurately test the code.
Unit tests can be executed via pytest or using the following make command:
This will also print out a coverage report as well as create an html coverage report. The long term goal would be >=75% coverage with unit tests, and more if possible of course! Right now that number is more like >=50%.
Setting up Functional Test Environment
Executing the functional tests is a bit more complicated! First, thank you to Kristian Larsson for his great tool vrnetlab! All functional tests are built on this awesome platform that allows for easy creation of containerized network devices.
So far, basic functional tests exist for Cisco IOS-XE and Cisco NX-OS, these use the CSR1000v and Nexus 9000v virtual platforms respectively. vrnetlab currently only supports the older emulation style NX-OS devices, and not the newer VM image n9kv. I have made some very minor tweaks to vrnetlab locally in order to get the n9kv image running -- I hope to raise a PR to add this to vrnetlab in the near future. Minus the n9kv tweaks, getting going with vrnetlab is fairly straightforward -- simply follow Kristian's great readme docs. After creating the image(s) that you wish to test, rename the image to the following format:
The docker-compose file here will be looking for the container images matching this pattern, so this is an important bit! Right now for IOS-XE and NX-OS the container image names need to be:
You can tag the image names on creation (following the vrnetlab readme docs), or create a new tag once the image is built:
docker tag [TAG OF IMAGE CREATED] ssh2netnxos
Once you have created the images, you can start the containers with a make command:
Conversely you can terminate the containers:
The containers don't take too long to fire up, maybe a few minutes (running on my old macmini with Ubuntu, so not exactly a powerhouse!). Once booted up you can connect to their console or via SSH:
The console port for all devices is 5000, so to connect to the console of the iosxe device you can simply telnet to that port locally:
telnet 172.18.0.11 5000
Credentials for all devices use the default vrnetlab credentials:
Username: vrnetlab Password: VR-netlab9
Once the containers are ready, you can use the make commands to execute tests as needed:
test_functional will execute all currently implemented functional tests
test_all will execute all currently implemented functional tests as well as the unit tests
test_iosxe will execute all unit tests and iosxe functional tests
test_nxos will execute all unit tests and nxos functional tests
Release history Release notifications
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
|Filename, size||File type||Python version||Upload date||Hashes|
|Filename, size ssh2net-2019.9.2-py3-none-any.whl (15.5 kB)||File type Wheel||Python version py3||Upload date||Hashes View hashes|
|Filename, size ssh2net-2019.9.2.tar.gz (15.7 kB)||File type Source||Python version None||Upload date||Hashes View hashes|
Hashes for ssh2net-2019.9.2-py3-none-any.whl