Skip to content

Platform Support Matrix

OS upgrades are driven by pyntc device drivers. The app resolves the pyntc driver for a device from Platform.network_driver_mappings["pyntc"], which Nautobot populates from netutils. This page documents each supported platform and its platform-specific upgrade behavior.

Platform pyntc Device Type Reboot Behavior Platform-Specific Notes
Cisco IOS / IOS-XE cisco_ios_ssh Install mode: the device reboots automatically as part of the install — the Reboot toggle cannot disable it. Bundle mode: controlled by the Reboot toggle. Install mode vs. bundle mode is detected automatically from the device's boot configuration.
Cisco IOS-XE WLC (9800) cisco_iosxewlc_ssh Always reboots as part of the install; cannot be disabled. Upgrades always use install mode.
Cisco IOS-XR (eXR / 64-bit) cisco_iosxr_ssh Always reloads during install activate; cannot be disabled. Requires a golden ISO. The Save Device Configuration job is automatically skipped (software is committed during install).
Cisco NX-OS cisco_nxos_nxapi Controlled by the Reboot toggle. Pyntc performs OS upgrade operations over SSH, not NX-API.
Cisco ASA cisco_asa_ssh Controlled by the Reboot toggle.
Arista EOS arista_eos_eapi Controlled by the Reboot toggle.
Juniper Junos juniper_junos_netconf Controlled by the Reboot toggle. Standalone and Virtual Chassis (EX) deployments are supported. The image checksum from the Software Image File is validated before install. NSSU/ISSU can be enabled via the Extra Options job input on Virtual Chassis and chassis cluster deployments.

Reboot Behavior

The Install OS on Device job exposes a Reboot toggle (enabled by default) that controls whether the job reboots the device after the new image is installed.

Disabling the Reboot toggle does not guarantee the device won't reboot

On several platforms the operating system itself reboots the device as an integral part of the install procedure, regardless of the job's Reboot toggle:

  • Cisco IOS/IOS-XE in install mode — install add file ... activate commit reloads the device. The job fails up front if the Reboot toggle is disabled for an install-mode upgrade.
  • Cisco IOS-XE WLC — the install always reloads the controller.
  • Cisco IOS-XR — install activate always reloads the device.

On these platforms, only schedule the install job inside a maintenance window.

The Execute OS Upgrade Workflow job always runs the install step with reboot enabled.

Cisco IOS/IOS-XE Install Mode Detection

Whether an IOS/IOS-XE device is upgraded using the newer install mode procedure or the traditional bundle mode procedure is determined automatically: pyntc reads the device's current boot configuration and selects install mode when the device boots from packages.conf. There is no job input for this. Devices are upgraded in the mode they are already running in.

Cisco IOS-XR

This app upgrades Cisco IOS-XR (eXR / 64-bit) devices via pyntc's cisco_iosxr_ssh driver (IOSXRDevice). The upgrade uses the asynchronous native install workflow (install add → poll → install activate → poll → reload → install commit → verify).

IOS-XR upgrades require a golden ISO

IOS-XR upgrades in this app are performed from a single golden ISO image.

On eXR a bare base ISO cannot be activated on its own when optional feature packages (IS-IS, OSPF, MPLS, multicast, etc.) are active: install activate aborts demanding the matching-version RPMs be activated in the same operation. A golden ISO solves this by bundling the base XR image and the matching feature RPMs into one file, so it activates cleanly without supplying separate packages.

Installing a base ISO plus separate feature RPMs is not supported.

Golden ISO files cannot be renamed

The golden ISO must keep the exact filename produced by the build tool (e.g. ncs5k-golden-x-7.11.1-NTC711.iso). IOS-XR validates the image against metadata embedded at build time, and a renamed golden ISO will fail to install.

If you need to distinguish builds, use the --label option at build time — the label becomes part of the generated filename. Set image_file_name on the Software Image File in Nautobot to the filename exactly as the build tool produced it, and publish the file to your software repository under that same name.

Building a golden ISO with gisobuild

Build a golden ISO with Cisco's gisobuild tool. Provide the platform's base (mini) ISO, a repository of the matching feature RPMs you want bundled, a label (which becomes part of the resulting filename), and an output directory:

ntc@linux-server:~/xr/gisobuild$ mkdir -p /home/ntc/xr/7.11.1/giso_out

./src/gisobuild.py \
  --iso /home/ntc/xr/7.11.1/ncs5k-mini-x-7.11.1.iso \
  --repo /home/ntc/xr/7.11.1/ \
  --pkglist ncs5k-isis-1.0.0.0-r7111.x86_64.rpm \
            ncs5k-ospf-1.0.0.0-r7111.x86_64.rpm \
            ncs5k-mpls-1.0.0.0-r7111.x86_64.rpm \
            ncs5k-mpls-te-rsvp-1.0.0.0-r7111.x86_64.rpm \
            ncs5k-mcast-1.0.0.0-r7111.x86_64.rpm \
            ncs5k-mgbl-1.0.0.0-r7111.x86_64.rpm \
            ncs5k-m2m-1.0.0.0-r7111.x86_64.rpm \
  --label NTC711 \
  --out-directory /home/ntc/xr/7.11.1/giso_out \
  --create-checksum \
  --clean \
  --docker

On success gisobuild writes the golden ISO (e.g. ncs5k-golden-x-7.11.1-NTC711.iso) into the output directory. Publish that file to the software repository the Transfer Software Image to Device job pulls from, keeping the generated filename unchanged.

Configuring Nautobot for an IOS-XR upgrade

  1. Platform — The device's Platform must use the cisco_xr network driver, which resolves to pyntc's cisco_iosxr_ssh device type.
  2. Software Version — Set SoftwareVersion.version to the exact value the device reports from show version (e.g. 7.11.2). The Check Running Version job compares the device's running version against this value with an exact string match (no version normalization), so a mismatch here will report the upgrade as failed even when it succeeded. See Built-In Version Checks.
  3. Software Image File — Set image_file_name to the golden ISO filename exactly as the build tool produced it (e.g. ncs5k-golden-x-7.11.2-NTC7112.iso) and download_url to where the file is published.

Running the jobs

Job IOS-XR behavior
Transfer Software Image to Device Stages the golden ISO onto harddisk:.
Save Device Configuration Not applicable — automatically skipped for IOS-XR devices. eXR commits software atomically during install (install commit); there is no standalone save step.
Install OS on Device Runs install add → install activate → reload → install commit → verify from the golden ISO. The device always reloads during activation; the Reboot toggle cannot disable it.
Check Running Version Reads show version and compares to the target SoftwareVersion.version.

IOS-XR caveats

The IOS-XR upgrade workflow currently:

  • Does not validate RP/RSP redundancy (show redundancy, show platform vm).
  • Does not upgrade FPGAs (upgrade hw-module location all fpd all).
  • Does not reload redundant RP/RSPs or perform a redundancy switchover.

Juniper Junos

Junos upgrades support both standalone devices and EX Virtual Chassis deployments. In a Virtual Chassis, the software is installed across the members and the reboot applies to the whole chassis.

Upgrading with NSSU or ISSU

Nonstop Software Upgrade (NSSU) and In-Service Software Upgrade (ISSU) can be enabled through the Extra Options JSON input on the Install OS on Device and Execute OS Upgrade Workflow jobs:

{"nssu": true}

or

{"issu": true}
  • nssu and issu are mutually exclusive — setting both to true fails the install. Choosing neither will perform the upgrade on all members at the same time, read below for more details!
  • NSSU/ISSU only applies to multi-member setups — an EX Virtual Chassis or an SRX chassis cluster. pyntc detects the members from the device facts; on a standalone device the option is ignored and a standard package install is performed instead.
  • With NSSU/ISSU, members are upgraded in sequence by Junos rather than the whole chassis rebooting at once, avoiding the full outage of the standard install. The device must meet Juniper's NSSU/ISSU prerequisites for the platform and target release.

Virtual Chassis upgrade behavior (without NSSU/ISSU)

Without the nssu/issu options, the app performs a standard package install. The image is installed on every member and the entire Virtual Chassis reboots at once, so plan for a full outage of the chassis during the upgrade.

As part of the install, Junos validates the running configuration against the target release on every member. A configuration statement the target release does not accept — for example, chassis redundancy graceful-switchover on releases that reject it — causes validation, and therefore the install, to fail on that member.

A partial install can leave a member parked Inactive on the old version

If the install fails on one member but succeeds on others, the Virtual Chassis reboots into a mixed-version state: the master comes up on the target version, while a member whose install failed rolls back to its previous version and is held Inactive by the master (visible in show virtual-chassis status). An Inactive member does not forward traffic.

Unless virtual-chassis auto-sw-update is configured, the master will never push software to an Inactive version-mismatched member — it stays Inactive indefinitely until you intervene, either by configuring auto software update on the master:

set virtual-chassis auto-sw-update

or by manually installing on the member from the master (after resolving the original validation failure, or with no-validate):

request system software add /var/tmp/<package>.tgz member <id> no-validate reboot

Note that Junos removes the package from /var/tmp after an install/rollback cycle, so it may need to be re-transferred first. A mixed-version Virtual Chassis also fails the Check Running Version post-check.

Before upgrading a Virtual Chassis, it is recommended to:

  • Validate the running configuration against the target image up front (request system software validate <package>), paying particular attention to chassis redundancy graceful-switchover.
  • Consider configuring virtual-chassis auto-sw-update with the target package path so that a version-mismatched member is automatically brought back to the master's version.