Improved documentation examples (#1816)

README.md

@@ -4,6 +4,7 @@
 ![GitHub contributors](https://img.shields.io/github/contributors/ktbyers/netmiko.svg)
 [![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)
 
+<img src="https://github.com/ktbyers/netmiko/blob/improved_examples/images/netmiko_logo_gh.png" width="320">
 
 Netmiko
 =======

examples/autodetect_snmp.py

@@ -0,0 +1,20 @@
+import sys
+from getpass import getpass
+from netmiko.snmp_autodetect import SNMPDetect
+from netmiko import ConnectHandler
+
+host = "cisco1.lasthop.io"
+device = {"host": host, "username": "pyclass", "password": getpass()}
+
+snmp_community = getpass("Enter SNMP community: ")
+my_snmp = SNMPDetect(host, snmp_version="v2c", community=snmp_community)
+device_type = my_snmp.autodetect()
+print(device_type)
+
+if device_type is None:
+    sys.exit("SNMP failed!")
+
+# Update the device dictionary with the device_type and connect
+device["device_type"] = device_type
+with ConnectHandler(**device) as net_connect:
+    print(net_connect.find_prompt())

examples/use_cases/case8_autodetect/autodetect_snmp_v3.py → examples/autodetect_snmp_v3.py

@@ -1,13 +1,14 @@
 # SNMPv3
-from netmiko.snmp_autodetect import SNMPDetect
-from netmiko import Netmiko
+import sys
 from getpass import getpass
+from netmiko.snmp_autodetect import SNMPDetect
+from netmiko import ConnectHandler
 
-device = {"host": "cisco1.twb-tech.com", "username": "pyclass", "password": getpass()}
+device = {"host": "cisco1.lasthop.io", "username": "pyclass", "password": getpass()}
 
 snmp_key = getpass("Enter SNMP community: ")
 my_snmp = SNMPDetect(
-    "cisco1.twb-tech.com",
+    "cisco1.lasthop.io",
     snmp_version="v3",
     user="pysnmp",
     auth_key=snmp_key,
@@ -18,6 +19,11 @@
 device_type = my_snmp.autodetect()
 print(device_type)
 
+if device_type is None:
+    sys.exit("SNMP failed!")
+
+# Update the device_type with information discovered using SNMP
 device["device_type"] = device_type
-net_connect = Netmiko(**device)
+net_connect = ConnectHandler(**device)
 print(net_connect.find_prompt())
+net_connect.disconnect()

examples/use_cases/case8_autodetect/autodetect_ssh.py → examples/autodetect_ssh.py

@@ -1,10 +1,10 @@
 #!/usr/bin/env python
-from netmiko import SSHDetect, Netmiko
+from netmiko import SSHDetect, ConnectHandler
 from getpass import getpass
 
 device = {
     "device_type": "autodetect",
-    "host": "cisco1.twb-tech.com",
+    "host": "cisco1.lasthop.io",
     "username": "pyclass",
     "password": getpass(),
 }
@@ -13,8 +13,8 @@
 best_match = guesser.autodetect()
 print(best_match)  # Name of the best device_type to use further
 print(guesser.potential_matches)  # Dictionary of the whole matching result
-
+# Update the 'device' dictionary with the device_type
 device["device_type"] = best_match
-connection = Netmiko(**device)
 
-print(connection.find_prompt())
+with ConnectHandler(**device) as connection:
+    print(connection.find_prompt())

examples/config_change.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+from netmiko import ConnectHandler
+from getpass import getpass
+
+device = {
+    "device_type": "cisco_ios",
+    "host": "cisco1.lasthop.io",
+    "username": "pyclass",
+    "password": getpass(),
+}
+
+commands = ["logging buffered 100000"]
+with ConnectHandler(**device) as net_connect:
+    output = net_connect.send_config_set(commands)
+    output += net_connect.save_config()
+
+print()
+print(output)
+print()

examples/config_change_file.py

@@ -0,0 +1,26 @@
+#!/usr/bin/env python
+from netmiko import ConnectHandler
+from getpass import getpass
+
+device1 = {
+    "device_type": "cisco_ios",
+    "host": "cisco1.lasthop.io",
+    "username": "pyclass",
+    "password": getpass(),
+}
+
+# File in same directory as script that contains
+#
+# $ cat config_changes.txt
+# --------------
+# logging buffered 100000
+# no logging console
+
+cfg_file = "config_changes.txt"
+with ConnectHandler(**device1) as net_connect:
+    output = net_connect.send_config_from_file(cfg_file)
+    output += net_connect.save_config()
+
+print()
+print(output)
+print()

examples/config_changes.txt

@@ -0,0 +1,2 @@
+logging buffered 100000
+no logging console

examples/use_cases/case3_multiple_devices/conn_multiple_dev.py → examples/conn_multiple_dev.py

@@ -1,37 +1,38 @@
 #!/usr/bin/env python
-from netmiko import Netmiko
+from netmiko import ConnectHandler
 from getpass import getpass
 
 password = getpass()
 
 cisco1 = {
-    "host": "cisco1.twb-tech.com",
+    "device_type": "cisco_ios",
+    "host": "cisco1.lasthop.io",
     "username": "pyclass",
     "password": password,
-    "device_type": "cisco_ios",
 }
 
 cisco2 = {
-    "host": "cisco2.twb-tech.com",
+    "device_type": "cisco_ios",
+    "host": "cisco2.lasthop.io",
     "username": "pyclass",
     "password": password,
-    "device_type": "cisco_ios",
 }
 
 nxos1 = {
-    "host": "nxos1.twb-tech.com",
+    "device_type": "cisco_nxos",
+    "host": "nxos1.lasthop.io",
     "username": "pyclass",
     "password": password,
-    "device_type": "cisco_nxos",
 }
 
 srx1 = {
-    "host": "srx1.twb-tech.com",
+    "device_type": "juniper_junos",
+    "host": "srx1.lasthop.io",
     "username": "pyclass",
     "password": password,
-    "device_type": "juniper_junos",
 }
 
 for device in (cisco1, cisco2, nxos1, srx1):
-    net_connect = Netmiko(**device)
+    net_connect = ConnectHandler(**device)
     print(net_connect.find_prompt())
+    net_connect.disconnect()

examples/conn_ssh_keys.py

@@ -0,0 +1,16 @@
+#!/usr/bin/env python
+from netmiko import ConnectHandler
+
+key_file = "~/.ssh/test_rsa"
+cisco1 = {
+    "device_type": "cisco_ios",
+    "host": "cisco1.lasthop.io",
+    "username": "testuser",
+    "use_keys": True,
+    "key_file": key_file,
+}
+
+with ConnectHandler(**cisco1) as net_connect:
+    output = net_connect.send_command("show ip arp")
+
+print(f"\n{output}\n")

examples/conn_ssh_proxy.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python
+from netmiko import ConnectHandler
+from getpass import getpass
+
+
+cisco1 = {
+    "device_type": "cisco_ios",
+    "host": "cisco1.lasthop.io",
+    "username": "pyclass",
+    "password": getpass(),
+    "ssh_config_file": "~/.ssh/ssh_config",
+}
+
+with ConnectHandler(**cisco1) as net_connect:
+    output = net_connect.send_command("show users")
+
+print(f"\n{output}\n")

examples/use_cases/case2_using_dict/conn_with_dict.py → examples/conn_with_dict.py

@@ -1,14 +1,14 @@
 #!/usr/bin/env python
-from netmiko import Netmiko
+from netmiko import ConnectHandler
 from getpass import getpass
 
 cisco1 = {
-    "host": "cisco1.twb-tech.com",
+    "host": "cisco1.lasthop.io",
     "username": "pyclass",
     "password": getpass(),
     "device_type": "cisco_ios",
 }
 
-net_connect = Netmiko(**cisco1)
+net_connect = ConnectHandler(**cisco1)
 print(net_connect.find_prompt())
 net_connect.disconnect()

examples/conn_with_dict_cm.py

@@ -0,0 +1,14 @@
+#!/usr/bin/env python
+from netmiko import ConnectHandler
+from getpass import getpass
+
+cisco1 = {
+    "device_type": "cisco_ios",
+    "host": "cisco1.lasthop.io",
+    "username": "pyclass",
+    "password": getpass(),
+}
+
+# Will automatically 'disconnect()'
+with ConnectHandler(**cisco1) as net_connect:
+    print(net_connect.find_prompt())

examples/delay_factor.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python
+from netmiko import ConnectHandler
+from getpass import getpass
+from datetime import datetime
+
+cisco1 = {
+    "device_type": "cisco_ios",
+    "host": "cisco1.lasthop.io",
+    "username": "pyclass",
+    "password": getpass(),
+}
+
+command = "copy flash:c880data-universalk9-mz.155-3.M8.bin flash:test1.bin"
+
+# Start clock
+start_time = datetime.now()
+
+net_connect = ConnectHandler(**cisco1)
+
+# Netmiko normally allows 100 seconds for send_command to complete
+# delay_factor=4 would allow 400 seconds.
+output = net_connect.send_command_timing(
+    command, strip_prompt=False, strip_command=False, delay_factor=4
+)
+if "Destination filename" in output:
+    print("Starting copy...")
+    output += net_connect.send_command("\n", delay_factor=4, expect_string=r"#")
+net_connect.disconnect()
+
+end_time = datetime.now()
+print(f"\n{output}\n")
+print("done")
+print(f"Execution time: {start_time - end_time}")

examples/enable.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+from netmiko import ConnectHandler
+from getpass import getpass
+
+password = getpass()
+secret = getpass("Enter secret: ")
+
+cisco1 = {
+    "device_type": "cisco_ios",
+    "host": "cisco1.lasthop.io",
+    "username": "pyclass",
+    "password": password,
+    "secret": secret,
+}
+
+net_connect = ConnectHandler(**cisco1)
+# Call 'enable()' method to elevate privileges
+net_connect.enable()
+print(net_connect.find_prompt())

examples/global_delay_factor.py

@@ -0,0 +1,19 @@
+#!/usr/bin/env python
+from netmiko import ConnectHandler
+from getpass import getpass
+
+cisco1 = {
+    "device_type": "cisco_ios",
+    "host": "cisco1.lasthop.io",
+    "username": "pyclass",
+    "password": getpass(),
+    # Multiple all of the delays by a factor of two
+    "global_delay_factor": 2,
+}
+
+command = "show ip arp"
+net_connect = ConnectHandler(**cisco1)
+output = net_connect.send_command(command)
+net_connect.disconnect()
+
+print(f"\n{output}\n")

examples/invalid_device_type.py

@@ -0,0 +1,13 @@
+#!/usr/bin/env python
+from netmiko import ConnectHandler
+
+cisco1 = {
+    # Just pick an 'invalid' device_type
+    "device_type": "invalid",
+    "host": "cisco1.lasthop.io",
+    "username": "pyclass",
+    "password": "invalid",
+}
+
+net_connect = ConnectHandler(**cisco1)
+net_connect.disconnect()

examples/use_cases/case11_logging/conn_with_logging.py → examples/netmiko_logging.py

@@ -1,19 +1,21 @@
 #!/usr/bin/env python
-from netmiko import Netmiko
+from netmiko import ConnectHandler
 from getpass import getpass
 
+# Logging section ##############
 import logging
 
 logging.basicConfig(filename="test.log", level=logging.DEBUG)
 logger = logging.getLogger("netmiko")
+# Logging section ##############
 
 cisco1 = {
-    "host": "cisco1.twb-tech.com",
+    "device_type": "cisco_ios",
+    "host": "cisco1.lasthop.io",
     "username": "pyclass",
     "password": getpass(),
-    "device_type": "cisco_ios",
 }
 
-net_connect = Netmiko(**cisco1)
+net_connect = ConnectHandler(**cisco1)
 print(net_connect.find_prompt())
 net_connect.disconnect()

examples/use_cases/case14_secure_copy/secure_copy.py → examples/secure_copy.py

@@ -2,13 +2,11 @@
 from getpass import getpass
 from netmiko import ConnectHandler, file_transfer
 
-password = getpass()
-
 cisco = {
     "device_type": "cisco_ios",
-    "host": "cisco1.twb-tech.com",
+    "host": "cisco1.lasthop.io",
     "username": "pyclass",
-    "password": password,
+    "password": getpass(),
 }
 
 source_file = "test1.txt"
@@ -23,6 +21,7 @@
     dest_file=dest_file,
     file_system=file_system,
     direction=direction,
+    # Force an overwrite of the file if it already exists
     overwrite_file=True,
 )