im0.cisco_upgrader

This role helps to deploy new software images to various Cisco network devices.

Requirements

• Ansible version 2.7 or higher
• Ansible Network Engine
• A compatible Cisco router or switch to upgrade
• Appropriate iOS/CATOS images for your device
• scp module for Python's pip installed

Role Variables

• Image: The name of the image file.
• ImagePath: The location of the image file. Default: ./.
• State: Choose stage to prepare the image for a later manual reboot, or upgrade to stage and reboot the device immediately.
• UpgradeType: Types of upgrades are ios-bin-upgrade, cat-software-install, or auto.
• BackupImage: Set to True or False to determine whether to back up the current image from the switch. Only for ios-bin-upgrade. Default: False.

Important Notes

Warning: This role will modify your network device and restart it, causing downtime. Test it thoroughly on a lab device before using it in production. Use at your own risk.

Timeouts: You may need to change some Ansible settings, such as:

timeout = 60

[persistent_connection]
command_timeout = 1800
persistent_connect_timeout = 1800

If not adjusted, tasks like the MD5 checksum may exceed the timeout, resulting in errors.

scp: The image is transferred using scp. Ensure that scp is enabled on the device. Future versions may support tftp as well.

Stack switches: Upgrading stacked switches has not been specifically tested.

MD5 Checksum: You are responsible for ensuring the safety of the image. A local MD5 checksum is calculated before the image transfer and compared afterward to confirm successful transfer.

Example Playbook

To prepare an image for manual reboot:

    - hosts: switches
      gather_facts: no
      roles:
         - { role: im0.cisco_upgrader, 
               Image: 'c2960-lanbasek9-mz.122-55.SE12.bin',
               State: stage,
               ImagePath: '/tmp',
               UpgradeType: 'ios-bin-upgrade',
               BackupImage: True
            }

To upgrade the device and reload:

- name: Upgrade device
  include_role:
    name: im0.cisco_upgrader
  vars:
    Image: 'c2960-lanbasek9-mz.122-55.SE12.bin'
    State: 'upgrade'
    ImagePath: '/tmp'
    UpgradeType: 'ios-bin-upgrade'

UpgradeType details

There are different methods for upgrading Cisco devices, depending on the model.

Currently supported methods:

• ios-bin-upgrade: Follows instructions from Cisco's website.
• cat-software-install: Follows instructions from Cisco's website.

Unsupported methods:

• nxos-upgrade
• ios-xr-upgrade

Special mention:

• auto: Attempts to choose the right upgrade method based on known models (like C881, C2960, C3750).

Limitations

Here are current limitations to consider:

• Doesn't allow filesystem paths other than flash:.
• Only supports ios and catos upgrades.
• Only supports scp for file transfers.
• Auto detection of the upgrade method is currently not available.
• Needs better control over waiting times for devices to come online after an upgrade.

License

GPLv3

Author Information

• John Imison
• Matthew Eason