Upgrade the Cisco IOS XE Software

The Cisco Catalyst 8000V virtual router runs on the Cisco IOS XE platform, the same platform that has powered Cisco CSR1000V or Cisco ISRV.

To use the Cisco Catalyst 8000V router, first obtain the software image from the Cisco Software Download page. Obtain the installation files, and begin the installation or upgrade. For additional information about the installation files, see Installation files.

If you are an existing Cisco CSR1000V or a Cisco ISRV user, download the latest installation file from the Cisco Software Download page. Begin the upgrade process by by using the installation methods described in this chapter.

Software Packaging for Cisco Catalyst 8000V

The software image for Cisco Catalyst 8000V is available as a consolidated package and as optional subpackages. Each consolidated package contains a collection of software subpackages, and each software subpackage is an individual software file that controls a different element or elements of the virtual router. Using a consolidated package, you can upgrade all the individual subpackages with a single software image download.

You can upgrade an individual software subpackage, or upgrade all the software subpackages for a specific consolidated package during a complete upgrade. To run the router using individual subpackages from a consolidated package, download the image from Cisco.com and extract the subpackages.

Upgrading using subpackage consumes less memory than upgrading through a consolidated package. For this reason, upgrading through subpackages is the recommended method, especially for deployments with small footprints.

Prerequisites before upgrading the Cisco IOS XE software

Prerequisites before you upgrade the Cisco IOS XE software:

  • Obtain the Cisco Catalyst 8000V software image from the Cisco Software Download page. For instructions on obtaining the installation files, see Download the installation files.

  • Check the version of your hypervisor before performing the upgrade. The upgrade fails if your hypervisor version is not supported by the current version of Cisco IOS XE on Cisco Catalyst 8000V.

  • Verify that the VM meets the memory requirements for the Cisco Catalyst 8000V software image. If the upgraded version requires more memory than the previous version, increase the VM's memory allocation before starting the upgrade process.

Prerequisites with HSECK9 license

If you are upgrading a Cisco CSR1000V or Cisco ISRV router where throughput is greater than 250 Mbps, to Cisco Catalyst 8000V Cisco IOS XE 17.4.1 and later, a High Security (HSECK9) license is required.

If you were running a throughput level greater than 250 Mbps prior to the upgrade, you must purchase an HSECK9 license for service continuity after the upgrade. If an HSECK9 license is not available after upgrade, throughput is restricted to 250 Mbps. If you want to switch to Cisco DNA subscription-based licensing model, you must perform a fresh Cisco Catalyst 8000V deployment.

Depending on your pre-upgrade setup, ensure that you meet the corresponding HSECK9 license requirements before you upgrade.

  • If the Cisco CSR1000V or Cisco ISRV is connected to CSSM, ensure that all these requirements are met.

    • Throughput greater than 250 Mbps is part of start-up configuration.

      To check start-up configuration, enter the show running-config command in privileged EXEC mode. For example:
      Device# show running-config | include throughput 
platform hardware throughput level MB 500

    • There is a positive balance of the required number of HSECK9 licenses (DNA_HSECK9) in the corresponding Smart Account and Virtual Account in CSSM. No further pre-upgrade action is required. As long as the device is connected to CSSM, on upgrade, the device automatically triggers the HSECK9 request and installs the required Smart Licensing Authorization Code (SLAC).

If throughput is less than or equal to 250 Mbps, an HSECK9 license is not required.

Prerequisites with Specific Licensing Reservation

If the Cisco CSR1000V or Cisco ISRV is using Specific License Reservation (SLR), update the SLR authorization code to include an HSECK9 license (DNA_HSECK9) and only then upgrade the device. This ensures uninterrupted throughput after upgrade.

See this example on how to update the SLR authorization code: Example: Smart Licensing (SLR With Throughput >250 Mbps, Without Export-Controlled License) to Smart Licensing Using Policy.

Restrictions when upgrading the Cisco IOS XE software

Restrictions when upgrading the Cisco IOS XE software:

  • Only a .bin file is applicable for upgrading or downgrading your software. The .iso, .qcow2, and .ova files are used for first-time installations only.

  • You can upgrade to a new software version on the same VM only. The procedures do not describe how to install or rehost an existing router running the same or upgraded software version on a different VM.

  • If you are upgrading to Cisco Catalyst 8000V, your licenses will continue to function as is. However, if you wish to switch to the CDNA licensing model, you must perform a fresh installation.

  • The Cisco Catalyst 8000V router does not support In-Service Software Upgrade (ISSU).

  • Cisco Catalyst 8000V does not support L2TP functionality including L2TP client and L2TP Network Server (LNS).

  • The system requirements for the x86 hardware might differ from those of the hardware currently running on the router.

  • If you have freshly installed Cisco Catalyst 8000V, you cannot downgrade to Cisco ISRV or Cisco CSR1000V. If your previous installation was Cisco CSR1000V and you upgraded to Cisco Catalyst 8000V, you can downgrade to Cisco CSR1000V, but you cannot downgrade to Cisco ISRV.

Restrictions when upgrading from Cisco CSR1000V or Cisco ISRV

  • In the case of an upgrade from Cisco CSR1000V or Cisco ISRV, the disk partition structure remains the same as the previous version, and the secure object storage functionality is not available.

  • You cannot upgrade a Cisco CSR1000V running PCI pass-through to Cisco Catalyst 8000V as Cisco Catalyst 8000V does not support PCI pass-through.

  • If you want to upgrade to Cisco Catalyst 8000V from a Cisco CSR1000V or a Cisco ISRV prior to 16.12.x, you must first upgrade your current version to 16.12.x. After completing this step, upgrade to the latest version of Cisco Catalyst 8000V.

  • You can upgrade from Cisco CSR1000V to Cisco Catalyst 8000V, or from an older to a newer version of Cisco Catalyst 8000V, only by using N-2 or N-1 to N release upgrade paths. N-1 and N-2 are defined as extended maintenance releases. For example, to upgrade a CSR1000V 17.3.x instance to a Cisco Catalyst 8000V 17.11.1a release, first upgrade to version 17.6.x.

  • Upgrading a Cisco ISRV or a Cisco CSR1000V to Cisco Catalyst 8000V does not alter the file system layout nor provide any of the new features such as the Secure Object Store which rely on the file system. You must perform a fresh installation to activate these features.

Install mode process flow

The install mode process flow comprises three commands to perform installation and upgrade of software on platforms–install add , install activate , and install commit .

Table 1. List of install Commands

Command

Syntax

Purpose

install add

install add filelocation:filename.bin

Copies the contents of the image, package, and SMUs to the software repository. File location may be local or remote. This command does the following:

  • Validates the file–checksum, platform compatibility checks, and so on.

  • Extracts individual components of the package into subpackages and packages.conf

  • Copies the image into the local inventory and makes it available for the next steps.

install activate

install activate

Activates the package added using the install add command.

  • Use the show install summary command to see which image is inactive. This image will get activated.

  • System reloads on executing this command. Confirm if you want to proceed with the activation. Use this command with the prompt-level none keyword to automatically ignore any confirmation prompts.

install activate auto abort-timer

install activate auto-abort timer <30-1200>

The auto-abort timer starts automatically, with a default value of 120 minutes. If the install commit command is not executed within the time provided, the activation process is terminated, and the system returns to the last-committed state.

  • You can change the time value while executing the install activate command.

  • The install commit command stops the timer, and continues the installation process.

  • The install activate auto-abort timer stop command stops the timer without committing the package.

  • Use this command with the prompt-level none keyword to automatically ignore any confirmation prompts.

  • This command is valid only in the three-step install variant.

install commit

install commit

Commits the package activated using the install activate command, and makes it persistent over reloads.

  • Use the show install summary command to see which image is uncommitted. This image will get committed.

install abort

install abort

Terminates the installation and returns the system to the last-committed state.

  • This command is applicable only when the package is in activated status (uncommitted state).

  • If you have already committed the image using the install commit command, use the install rollback to command to return to the preferred version.

install remove

install remove {file <filename> | inactive}

Deletes inactive packages from the platform repository. Use this command to free up space.

  • file: Removes specified files.

  • inactive: Removes all the inactive files.

install rollback to

install rollback to {base | label | committed | id}

Rolls back the software set to a saved installation point or to the last-committed installation point. The following are the characteristics of this command:

  • Requires reload.

  • Is applicable only when the package is in committed state.

  • Use this command with the prompt-level none keyword to automatically ignore any confirmation prompts.

Note

 
If you are performing install rollback to a previous image, the previous image must be installed in install mode. Only SMU rollback is possible in bundle mode.

install deactivate

install deactivate file <filename>

Removes a package from the platform repository. This command is supported only for SMUs.

  • Use this command with the prompt-level none keyword to automatically ignore any confirmation prompts.

Table 2. List of show Commands

Command

Syntax

Purpose

show install log

 show install log

Provides the history and details of all install operations that have been performed since the platform was booted.

show install package

show install package <filename>

Provides details about the .pkg/.bin file that is specified.

show install summary

show install summary

Provides an overview of the image versions and their corresponding install states for all the FRUs.

  • The table that is displayed will state for which FRUs this information is applicable.

  • If all the FRUs are in sync in terms of the images present and their state, only one table is displayed.

  • If, however, there is a difference in the image or state information among the FRUs, each FRU that differs from the rest of the stack is listed in a separate table.

show install active

show install active

Provides information about the active packages for all the FRUs.

If there is a difference in the information among the FRUs, each FRU that differs from the rest of the stack is listed in a separate table.

show install inactive

show install inactive

Provides information about the inactive packages, if any, for all the FRUs.

If there is a difference in the information among the FRUs, each FRU that differs from the rest of the stack is listed in a separate table.

show install committed

show install committed

Provides information about the committed packages for all the FRUs.

If there is a difference in the information among the FRUs, each FRU that differs from the rest of the stack is listed in a separate table.

show install uncommitted

show install uncommitted

Provides information about uncommitted packages, if any, for all the FRUs.

If there is a difference in the information among the FRUs, each FRU that differs from the rest of the stack is listed in a separate table.

show install rollback

show install rollback {point-id | label}

Displays the package associated with a saved installation point.

show version

show version [rp-slot] [installed [user-interface] | provisioned | running]

Displays information about the current package, along with hardware and platform information.

The install mode process flow comprises three commands to perform installation and upgrade of software on platforms–install add, install activate , and install commit.

This flow chart explains the install process with install commands:

Figure 1. Process with install commit

The install add command copies the software package from a local or remote location to the platform. The location can be FTP, HTTP, HTTPs, or TFTP. The command extracts individual components of the .package file into subpackages and packages.conf files. It also validates the file to ensure that the image file is specific to the platform on which it is being installed.

The install activate command performs the required validations and provisions the packages previously added using the install add command. It also triggers a system reload.

The install commit command confirms the packages previously activated using the install activate command, and makes the updates persistent over reloads.


Note

Installing an update replaces any previously installed software image. At any time, only one image can be installed in a device.

Boot in install mode

You can install, activate, and commit a software package using a single command (one-step install) or multiple separate commands (three-step install).

If the platform is working in bundle mode, the one-step install procedure must be used to initially convert the platform from bundle mode to install mode. Subsequent installs and upgrades on the platform can be done with either one-step or three-step variants.

One-step Installation or convert from bundle mode to install mode


Note

  • All the CLI actions (for example, add, activate, and so on) are executed on all the available FRUs.

  • The configuration save prompt will appear if an unsaved configuration is detected.

  • The reload prompt will appear after the second step in this workflow. Use the prompt-level none keyword to automatically ignore the confirmation prompts.

  • If the prompt-level is set to None, and there is an unsaved configuration, the install fails. You must save the configuration before reissuing the command.

Use the one-step install procedure described below to convert a platform running in bundle boot mode to install mode. After the command is executed, the platform reboots in install boot mode.

Later, the one-step install procedure can also be used to upgrade the platform.

This procedure uses the install add file activate commit command in privileged EXEC mode to install a software package, and to upgrade the platform to a new version.

Procedure

Step 1

enable

Example:

Device>enable

Enables privileged EXEC mode. Enter your password, if prompted.

Step 2

installadd filelocation:filename [ activate commit ]

Example:

Device#install add file bootflash:c8000be-universalk9.BLD_V177_THROTTLE_LATEST_20211021_031123_V17_7_0_117.SSA.bin activate commit

Copies the software install package from a local or remote location (through FTP, HTTP, HTTPs, or TFTP) to the platform and extracts the individual components of the .package file into subpackages and packages.conf files. It also performs a validation and compatibility check for the platform and image versions, activates the package, and commits the package to make it persistent across reloads.

The platform reloads after this command is run.

Step 3

exit

Example:

Device#exit

Exits privileged EXEC mode and returns to user EXEC mode.

Platform is upgraded to new version.

Three-step install


Note

  • All the CLI actions (for example, add, activate, and so on) are executed on all the available FRUs.

  • The configuration save prompt will appear if an unsaved configuration is detected.

  • The reload prompt will appear after the install activate step in this workflow. Use the prompt-level none keyword to automatically ignore the confirmation prompts.

The three-step installation procedure can be used only after the platform is in install mode. This option provides more flexibility and control to the customer during installation.

This procedure uses individual install add , install activate , and install commit commands for installing a software package, and to upgrade the platform to a new version.

Procedure

Step 1

enable

Example:

Device>enable

Enables privileged EXEC mode. Enter your password, if prompted.

Step 2

installadd filelocation:filename

Example:

Device#install add file bootflash:c8000be-universalk9.BLD_V177_THROTTLE_LATEST_20211027_030841_V17_7_0_120.SSA.bin

Copies the software install package from a remote location (through FTP, HTTP, HTTPs, or TFTP) to the platform, and extracts the individual components of the .package file into subpackages and packages.conf files.

Step 3

showinstall summary

Example:

Device#show install summary

(Optional) Provides an overview of the image versions and their corresponding install state for all the FRUs.

Step 4

installactivate [ auto-abort-timer<time> ]

Example:

Device# install activate auto-abort-timer 120

Activates the previously added package and reloads the platform.

  • When doing a full software install, do not provide a package filename.

  • In the three-step variant, auto-abort-timer starts automatically with the install activate command; the default for the timer is 120 minutes. If the install commit command is not run before the timer expires, the install process is automatically terminated. The platform reloads and boots up with the last committed version.

Step 5

installabort

Example:

Device#install abort

(Optional) Terminates the software install activation and returns the platform to the last committed version.

  • Use this command only when the image is in activated state, and not when the image is in committed state.

Step 6

installcommit

Example:

Device#install commit

Commits the new package installation and makes the changes persistent over reloads.

Step 7

installrollback tocommitted

Example:

Device#install rollback to committed

(Optional) Rolls back the platform to the last committed state.

Step 8

installremove { filefilesystem: filename | inactive }

Example:

Device#install remove inactive

(Optional) Deletes software installation files.

  • file : Deletes a specific file

  • inactive : Deletes all the unused and inactive installation files.

Step 9

showinstall summary

Example:

Device#show install summary

(Optional) Displays information about the current state of the system. The output of this command varies according to the install commands run prior to this command.

Step 10

exit

Example:

Device#exit

Exits privileged EXEC mode and returns to user EXEC mode.

Sample upgrade output

This sample configuration output demonstrates an upgrade from Cisco Catalyst 8000V release 17.06.02 to Release 17.07.01. 

======================================
Upgrade steps
install add file bootflash:/ c8000v-universalk9.17.07.01a.SPA.bin
install activate
install commit
======================================

Router#show version | inc IOS XE
Cisco IOS XE Software, Version 17.06.02
Router#show version | inc mode
Router operating mode: Autonomous

Router# dir bootflash:*bin*
Directory of bootflash:/*bin*

Directory of bootflash:/

   31  -rw-   832807301   Mar 7 2022 02:07:28 +00:00  c8000v-universalk9.17.07.01a.SPA.bin
5183766528 bytes total (2348220416 bytes free)

Router#install add file bootflash:/c8000v-universalk9.17.07.01a.SPA.bin
install_add: START Mon Mar 7 02:16:30 UTC 2022
install_add: Adding PACKAGE
install_add: Checking whether new add is allowed ....

--- Starting Add ---
Performing Add on Active/Standby
  [1] Add package(s) on R0
  [1] Finished Add on R0
Checking status of Add on [R0]
Add: Passed on [R0]
Finished Add

Image added. Version: 17.07.01a.0.1883
SUCCESS: install_add  Mon Mar  7 02:20:07 UTC 2022
VK5-C8K-8G-1762-1#

Router# show install summary
[ R0 ] Installed Package(s) Information:
State (St): I - Inactive, U - Activated & Uncommitted,
            C - Activated & Committed, D - Deactivated & Uncommitted
--------------------------------------------------------------------------------
Type  St   Filename/Version
--------------------------------------------------------------------------------
IMG   C    17.06.02.0.2786
IMG   I    17.07.01a.0.1883

--------------------------------------------------------------------------------
Auto abort timer: inactive
--------------------------------------------------------------------------------

=====================
install activate
=====================

Router# show install summary
[ R0 ] Installed Package(s) Information:
State (St): I - Inactive, U - Activated & Uncommitted,
            C - Activated & Committed, D - Deactivated & Uncommitted
--------------------------------------------------------------------------------
Type  St   Filename/Version
--------------------------------------------------------------------------------
IMG   C    17.06.02.0.2786
IMG   I    17.07.01a.0.1883

Router# install activate
install_activate: START Mon Mar  7 02:50:00 UTC 2022
install_activate: Activating PACKAGE
Following packages shall be activated:
/bootflash/c8000v-rpboot.17.07.01a.SPA.pkg
/bootflash/c8000v-mono-universalk9.17.07.01a.SPA.pkg
/bootflash/c8000v-firmware_nim_xdsl.17.07.01a.SPA.pkg
/bootflash/c8000v-firmware_nim_shdsl.17.07.01a.SPA.pkg
/bootflash/c8000v-firmware_nim_ge.17.07.01a.SPA.pkg
/bootflash/c8000v-firmware_nim_cwan.17.07.01a.SPA.pkg
/bootflash/c8000v-firmware_nim_async.17.07.01a.SPA.pkg
/bootflash/c8000v-firmware_ngwic_t1e1.17.07.01a.SPA.pkg
/bootflash/c8000v-firmware_dsp_sp2700.17.07.01a.SPA.pkg
/bootflash/c8000v-firmware_dreamliner.17.07.01a.SPA.pkg

This operation may require a reload of the system. Do you want to proceed? [y/n]y
--- Starting Activate ---
Performing Activate on Active/Standby

  [1] Activate package(s) on R0
    --- Starting list of software package changes ---
    Old files list:
      Modified c8000v-firmware_dreamliner.17.06.02.SPA.pkg
      Modified c8000v-firmware_dsp_sp2700.17.06.02.SPA.pkg
      Modified c8000v-firmware_ngwic_t1e1.17.06.02.SPA.pkg
      Modified c8000v-firmware_nim_async.17.06.02.SPA.pkg
      Modified c8000v-firmware_nim_cwan.17.06.02.SPA.pkg
      Modified c8000v-firmware_nim_ge.17.06.02.SPA.pkg
      Modified c8000v-firmware_nim_shdsl.17.06.02.SPA.pkg
      Modified c8000v-firmware_nim_xdsl.17.06.02.SPA.pkg
      Modified c8000v-mono-universalk9.17.06.02.SPA.pkg
      Modified c8000v-rpboot.17.06.02.SPA.pkg
    New files list:
      Added c8000v-firmware_dreamliner.17.07.01a.SPA.pkg
      Added c8000v-firmware_dsp_sp2700.17.07.01a.SPA.pkg
      Added c8000v-firmware_ngwic_t1e1.17.07.01a.SPA.pkg
      Added c8000v-firmware_nim_async.17.07.01a.SPA.pkg
      Added c8000v-firmware_nim_cwan.17.07.01a.SPA.pkg
      Added c8000v-firmware_nim_ge.17.07.01a.SPA.pkg
      Added c8000v-firmware_nim_shdsl.17.07.01a.SPA.pkg
      Added c8000v-firmware_nim_xdsl.17.07.01a.SPA.pkg
      Added c8000v-mono-universalk9.17.07.01a.SPA.pkg
      Added c8000v-rpboot.17.07.01a.SPA.pkg
    Finished list of software package changes
  [1] Finished Activate on R0
Checking status of Activate on [R0]
Activate: Passed on [R0]
Finished Activate

Send model notification for install_activate before reload
Install will reload the system now!
SUCCESS: install_activate  Mon Mar  7 02:57:34 UTC 2022


===================================
install commit
===================================

Router# show version | inc IOS XE
Cisco IOS XE Software, Version 17.07.01a
Router# show version | inc mode
Router operating mode: Autonomous
Router# show license udi
UDI: PID:C8000V,SN:9JM01Z7G2JH

Upgrade in install mode

Use either the one-step installation or the three-step installation to upgrade the platform in install mode.

Downgrade in install mode

Use the install rollback command to downgrade the platform to a previous version by pointing it to the appropriate image, provided the image you are downgrading to was installed in install mode.

The install rollback command reloads the platform and boots it with the previous image.


Note
The install rollback command succeeds only if you have not removed the previous file using the install remove inactive command.

Alternatively, you can downgrade by installing the older image using the install commands.

Terminate a software installation

You can terminate the activation of a software package in these ways:

  • When the platform reloads after activating a new image, the auto-abort-timer is triggered (in the three-step install variant). If the timer expires before you issue the install commit command, the installation process terminates. The platform then reloads and boots with the last committed version of the software image.

    Alternatively, use the install auto-abort-timer stop command to stop this timer, without using the install commit command. The new image remains uncommitted in this process.

  • Using the install abort command returns the platform to the version that was running before installing the new software. Use this command before issuing the install commit command.

Frequently asked questions

Can I downgrade from Cisco Catalyst 8000V to Cisco CSR1000V or Cisco ISRv?

You can downgrade from Cisco Catalyst 8000V only if you've upgraded to Cisco Catalyst 8000V from a Cisco CSR1000V or a Cisco ISRv 17.3.x or a later version.


Note

You cannot downgrade to Cisco CSR1000V or Cisco ISRv if you have freshly installed Cisco Catalyst 8000V .

When I upgrade from a Cisco CSR1000V 16.12.x version or below, will Secure Object Storage be supported?

No, Secure Object Storage is not carried over through upgrades. You must perform a fresh installation or reinstall the VM to enable Secure Object Storage support.

Will my license need to change when I upgrade from a Cisco CSR1000V or a Cisco ISRv to Cisco Catalyst 8000V ?

When you upgrade to Cisco Catalyst 8000V , the licenses remain the same. However, the licenses move from SL to SLE after the upgrade. If the throughput was <=250M before the upgrade, it is retained as is after the upgrade.

If the throughput was >250M and the device was registered to CSSM, the connection stays intact and the throughput automatically triggers the SLAC installation on the device. The corresponding throughput is set once SLAC is installed.

If the device was not connected to CSSM and throughput was >250M, you must manually install SLAC in the offline mode or configure SLE commands to establish trust with CSSM. Then, configure the throughput to trigger the SLAC installation.


Note

If SLAC is not installed, the throughput remains at 250M.
Is automation available for the upgrade process?

No, automation is currently not supported for the migration.

What is the failure mode handling when I perform a downgrade?

When a Cisco CSR1000V image is booting up as a result of a downgrade, the system checks for the partition format. If the partition format does not match the requirements, the bootup is halted. If a Cisco Catalyst 8000V image is booting up as a result of an upgrade or a downgrade, it continues to boot using the existing partition format.

What is the memory and performance impact after the upgrade?

The size of the Cisco Catalyst 8000V image might be slightly larger, which could affect the overall memory footprint. However, this does not change the overall memory requirements. The minimum required RAM for this image is 4GB. This feature does not impact performance.

Troubleshooting software upgrade issues

Problem Troubleshooting common software installation upgrade issues.

Solution Run show commands to view installation summaries, logs, and software versions. Use this information to help identify issues with the upgrade.

  • Solution show install summary

  • Solution show install log

  • Solution show version

  • Solution show version running

Solution If you are unable to troubleshoot using the show commands, run these commands:

  • Solution dir <install directory>

  • Solution more location: packages.conf

  • Solution show tech-support install: This command automatically runs the show commands that display information specific to installation.

  • Solution request platform software trace archive target bootflash < location>: This command archives all the trace logs relevant to all the processes running on the system since the last reload, and saves this information in the specified location.

If your issue persists, contact the Cisco TAC to resolve the issue.