iosfw

Automatic Cisco IOS firmware upgrades

Requires:

• Python 3.6+
• netmiko
• napalm
• tqdm

Overview

Automates the entire upgrade process:

• Determines correct upgrade image for each platform
• Transfer the new image
• Verify image integrity
• Extract archive and install
• Optionally remove old image(s)
• Set boot parameters
• Schedule reload

Auto-detects best upgrade method available:

• archive download-sw
• software install
• request platform software package install
• If those fail, plain copy followed by set boot ...

Supported platforms:

• Catalyst 3550
• Catalyst 3560
• Catalyst 3560-X
• Catalyst 3750
• Catalyst 3750-X
• Catalyst 2960-S
• Catalyst 2960-X
• Catalyst 3650
• Catalyst 3850
• ISR 2921
• ISR 4331
• C892FSP
• ME3400

Experimentally supported platforms:

• ASR920
• Catalyst 9k series

Currently unsupported platforms:

• Nexus 3k/9k series

NOTE: Use at your own risk. It works well in my environment, but serious bugs are possible. Test thoroughly in a lab environment, and see known issues below.

Usage

Preparation

1. Rename config/config.yaml.example to config.yaml, and review config/images.yaml, matching both to your requirements. Defaults are sane, but don't take any chances :)
2. Copy your IOS images defined in images.yaml to the src_image_path defined in config.yaml.

Note: Pay special attention if you have devices of the same model, but need different IOS images (e.g., ipbase vs ipservices). In that case, define both images in images.yaml and add the same model to their respective models lists. Then, change match_feature_set to true in config.yaml.

Interactive Example

>>> from iosfw import iosfw
>>> device = iosfw('ios-sw-1')
>>> device.open()
Username [austindcc]:
Password:
Enable secret:
Opening connection to ios-sw-1...
Connected to ios-sw-1 (WS-C3560X-48P) as austind via ssh
Running version: 12.2(55)SE8
Upgrade version: 15.2(4)E8
Upgrade status: NEEDS UPGRADE
>>> device.upgrade()
Starting upgrade on ios-sw-1 at 14:34:09 06/13/19...
Checking free space...
Found enough free space!
Installing new firmware...
NOTE: No status updates possible during install, which may take 10 minutes or longer.
Install successful!
Removing running image...
Deleting flash:/c3560e-universalk9-mz.122-55.SE8...
Running image deleted.
Scheduling reload...
Reload scheduled for 00:00:00 PDT Fri Jun 14 2019 (9 hours and 16 minutes away)
Upgrade on ios-sw-1 completed at 14:43:32 06/13/19
Total time elapsed: 0:09:23.224298

Automated Example

See example/batch_example.py

Known issues

• Only supports BUNDLE mode on cat9k. As of 2021-06-16, INSTALL mode reloads the device immediately, with no option to delay reload for image activation. This is not only inconvenient, but also complicates iosfw's state awareness.
• As of 0.9.0, SCP image transfer directly from iosfw no longer works. I recommend setting up an FTP server on a separate host and setting config.yaml accordingly.
• Catalyst 3k series (3650 and 3850) with IOS running in BUNDLE mode (booted directly to the .bin file), will not succeed in upgrading with request platform software package install. Upgrading them requires a different manual process that is not yet implemented:
  • Remove existing IOS packages: del /force flash:/cat*.pkg
  • Remove existing packages.conf: del /force flash:/packages.conf
  • Remove boot variables: no boot system in config mode
  • Copy upgrade image: copy <source> flash:
  • Install upgrade image: request platform software package expand switch all file flash:/<file>
  • Set boot variable: boot system flash:/<file>
  • Schedule reload: reload at 00:00
• Currently, iosfw does not check to ensure transfer_source is reachable. If not reachable, the install command will fail, but not timeout for more than 30 minutes. Most commonly, transfer_source may not be reachable due to sending the requests out the incorrect interface. You can specify the source interface for TFTP and FTP transfers with ip (ftp|tftp) source-interface <iface> in config mode.
• When using SSH proxy, iosfw throws a ProcessLookupError on exit. I have not found a way to catch or suppress this.
• When remove_old_images is set to always on platforms using request software... install method, iosfw may incorrectly remove the newly installed image files. Net result is no change to system. Workaround: use remove_old_images = as_needed.
• Totally untested on stacks.

Wishlist

• Nornir integration
• Fix native SCP image transfer option (broken as of 0.9.0)
• Accept a pre-existing napalm connection object
• Verify reachability of transfer_source, attempting fix as needed
• More consistent debug output
• N3K/N9K support

Contributions welcome.

Changelog

See CHANGELOG.md

Notes

• Expect most upgrades to take 8-10 minutes per device, with one notable exception: Catalyst 3750-X took no less than 40 minutes in testing.
• Expect devices to take between 10 and 30 minutes to come back after reload, especially if upgrading trains or major versions, due to microcode updates.
• The automated install commands (archive download-sw and request platform software package install) download the upgrade package twice, for reasons I did not determine.
• FTP and HTTP seem to be the fastest transfer methods. Even then, the download appears constrained by platform CPU resources, averaging about 4Mbps in most tests, while some newer platforms achieved 20Mbps.
• The iosfw class exposes all of NAPALM's config parameters, and stores the NAPALM session under self.napalm, so you can use all of NAPALM's features easily.
• Same goes for netmiko - stored as self.device - so you can send arbitrary commands with iosfw.device.send_command('my arbitrary command')