Additional Install Operations

Use the procedures in this section to maintain the router at optimum conditions and monitor the install operation by streaming telemetry data.

The following workflow shows the tasks involved in managing the software:

Figure 1. Workflow to Maintain and Monitor the Software Installation
Workflow to Manintain and Monitor the Software Installation

This section contains the following topics:

Install Additional RPMs and Bug Fixes

You can install individual optional packages when new features are added or software problems are fixed.

Before you begin

When you upgrade the Cisco IOS XR software, you can also install or remove optional feature packages (RPMs or bug fixes) before applying the changes in the router. You can perform this operation while an atomic change is already in progress. However, all packaging operations before this command are discarded.

You can install the packages from a remote repository or copy the files to the router. If you are using a remote repository, ensure you have created and configured an external repository to store the packages. See the Create Repository to Access Install Files topic.

Download the specific additional RPMs and latest bug fix RPMs as tarballs to the repository. If the bug fix has dependencies, we recommend that you create a bug fix tarball that contains all dependencies.The README file in the tarball provides relevant information about the bug fix and identifies any dependencies – for example, whether other bug fix RPMs may be required for a complete fix.

Option 1: Install RPMs Using Command Line Interface

Optional RPMs and bug fixes are available as TAR files on the Software Download page. Starting with Cisco IOS XR Release 7.3.1, you are no longer required to manually extract the RPMs from the TAR file; you can install the bug fix RPM directly from the TAR file.

Procedure

Step 1

Check the available packages in the repository.

Example:

Router#show install available

Trying to access repositories...
Package        Architecture        Version            Repository
xr-8000-core    x86_64             7.8.1              remote-repo
xr-core         x86_64             7.8.1              remote-repo 

Step 2

Install the packages (additional RPMs or bug fixes).

  • Option 1: Install RPMs without control over reload operation.

    Important

     

    This option is not applicable when you downgrade or remove RPMs.

    You can either specify a tarfile (with bug fixes or optional packages), or a repository containing the RPMs. Use this command:

    Router#install source full-path-to-rpm [all]

    Specify the all keyword if you want to install optional packages. Exclude the all keyword if you want to upgrade the packages that are currently installed on the system.

    The full-path-to-rpm can be one of the following locations based on where you have saved the files.

    • Local path—files located in or under /var/xr/disk1/, /harddisk:/ or /misc/disk1/

    • Remote repository or tar file—ftp://<server>[;<named-vrf>]/<remote_path>, https://<server>[;<named-vrf>]/<remote_path> or http://<server>[;<named-vrf>]/<remote_path>

      If you want to add new packages from this source, you must use the all keyword: 

      Router#install source full-path-to-rpm all sync

      Note

       

      If the remote repository is reachable through a named VRF, you must mention the named VRF in the above commands. For example,

      Router#install source http://10.105.57.27;vrf1/repoinfra/install_rpms.tar

      where vrf1 is the named VRF through which the remote repository is accessible.

    The operation adds the RPMs and applies the change via reload or restart operation, whichever is least impactful based on the update.

  • Option 2: Install RPMs with control over reload operation.

    Important

     

    This option is applicable when you downgrade, remove or rollback RPMs.

    1. Install RPMs by providing the RPM name, Cisco bug fix ID (example, CSCab12345) or add packages from a specified source. Use the install package add command if you want to add new optional packages, else use the install package upgrade command. 

      Router#install package add <pkg1> <pkg2> <pkgn>

      Or

      Router#install package upgrade <pkg1> <pkg2> <pkgn>

    2. Apply the changes.

      Router#install apply [reload | restart]

      You can use the reload or restart options based on the change that is installed. To determine whether a reload or restart is required, check the output of show install request or show install history last transaction verbose command. The output indicates the required actions. 

      Router#show install history last transaction verbose
2023-01-25 05:45:37 UTC    Transaction 87 started
2023-01-25 05:45:37 UTC      Atomic change 87.1 started
2023-01-25 05:45:37 UTC      Packaging operation 87.1.1 started
2023-01-25 05:45:37 UTC    Transaction 87 complete

Least impactful apply method: process restart

Step 3

Check the status of the install operation.

Example:

Router#show install request
User request: No user requests found
State:        Success
Current activity:    No install operation in progress

The following actions are available:

    install package add
    install package remove
    install package upgrade
    install package downgrade
    install package replace
    install package rollback
    install replace
    install rollback
    install source

Note

 

Include the keyword noprompt in the commands to enable the system to bypass your permission to reload the router.

Step 4

Verify the image and packages are activated successfully.

Example:

Router# show install request
User request: install package add xr-mcast
Operation ID: 87.1.1
State: Success

Step 5

Commit the transaction.

Example:

Router#install commit

Option 2: Install RPMs Using YANG Data Model

Use Cisco-IOS-XR-install-augmented-act.yang data model to install the RPMs or bug fixes.

Procedure

Command or Action Purpose

Use the install-package-replace RPC on the data model.

Example:


<install-package-replace>
  <source-type>remote</source-type>
  <source>remote-repo</source>
  <file>rpm-file-name</file>
</install-package-replace>

If the install operation lists the repository reachable through a VRF, you must add the VRF name for the operation to be successful. 


<install-package-upgrade xmlns=http://cisco.com/ns/yang/Cisco-IOS-XR-install-augmented-act>
  <source-type>ftp</source-type>
  <source>10.105.57.27;vrf1/repoinfra/install_rpms.tar</source>
</install-package-upgrade>

Downgrade Software Version

Before you begin

Check the FPD status and ensure that all the FPDs are in CURRENT state. 

Router#show hw-module location all fpd

If the FPDs are not in CURRENT state, upgrade the FPDs. 

Router#upgrade hw-module location all fpd all
After all the FPDs are upgraded, reload the router.
Router#reload location all
Proceed with reload? [confirm]
After the router reloads, check that all the FPDs are in CURRENT state.

Note

We do not recommend downgrading the FPDs when you downgrade the system.

For more information on upgrading FPDs, see the Upgrading Field-Programable Device chapter.

Downgrade the current software version to a previous software release in case of an upgrade failure or based on requirement.

Procedure

Step 1

Determine the supported target versions to downgrade from the current version.

Example:

Router#show install upgrade-matrix

View the hardware or software limitations, and bridging SMUs required for the version downgrade. For more information about checking compatibility between the current and target versions, see Supported upgrade and downgrade releases.

Downgrading Packages:

Customers can also downgrade user-specified packages (for example, xr-telnet). This is separate from downgrading the entire XR version, but an ISO for an earlier version of XR is used instead of a newer ISO.

Note

 

The downgrade of IOS XR from version 7.3.4 to 7.0.14 for systems with Open PID RP can cause route processor BIOS corruption. We recommend that you do not downgrade below version 7.3.16.

Step 2

Back up the file system of the current version for recovery purposes.

Example:

Copy the running configuration to the harddisk: directory on the router:
Router#copy running-config harddisk:/running_config-<mmddyyyy>
Copy the running configuration to a remote server:
Router#scp harddisk:/ running_config user@<ip-address>:<location>

Step 3

Download the target version from the Software Download Center.

Step 4

You can either install from the remote repository or copy the ISO image file to the /harddisk: of the router.

Example:

Router#scp root@<ip-address>:/<dir>/8000-x64-release.iso harddisk:

Step 5

Verify that the MD5 checksum of the copied target file matches with the MD5 value of the source on the Software Download Center.

Example:

Router#show md5 file /harddisk:/8000-x64-<target-version>.iso

Step 6

Install the base image to downgrade the system.

  • Option 1: Install ISO without control over reload timing.
    Router#install replace /harddisk:/8000-x64-release.iso
    The image is installed, the changes are applied through a reload or a restart of the system, and commits the changes. However, you do not have control over the timing of the reload or restart —these occur as soon as the package operation completes and the system is ready.

    If you want to control when your system reloads (management of a network outage), we recommend that you schedule a downgrade window and perform an install replace operation, letting the system reload without intervention.

  • Option 2: Install ISO with control over reload timing.

    1. Install the image.

      Router#install package replace /harddisk:/8000-x64-release.iso

    2. Apply the changes.

      Router#install apply [reload | restart]

      You can use either the reload or restart options based on the file that is installed. To determine whether a reload or restart is required, check the output of show install request command. The output indicates the required actions.

Step 7

After the base image is downgraded, install the additional packages. For more information, see Install Additional RPMs and Bug Fixes.

During an install operation, if the system reboots unexpectedly or an apply by reload results in the system failing to boot, it automatically recovers to its software state before the current transaction.

Downgrade to previously installed package

You can downgrade the current version of installed IOS XR software packages to an earlier version as required or to the base version of the RPM. You can also downgrade your package to an earlier IOS XR version if an upgrade fails.

Prerequisites

Before downgrading a Cisco IOS XR software package, make sure that:

  • You have access to the previously installed package and its source.

  • A repository from which the target package version can be fetched is available.

These sections provide different methods using which you can downgrade your current package:

Downgrade to a specific version

This procedure allows you to downgrade xr-telnet-7.3.1v1.0.1 to xr-telnet-7.0.1v1.0.0.

Procedure

Step 1

install source <path-to-source> <package_version_name>

Example:

Router#install source install-repo xr-telnet-7.0.1v1.0.0

Install a specific earlier version, say, xr-telnet-7.0.1v1.0.0 of the optional package. The changes are applied automatically.

Attention

 

An automatic change may trigger a reload of the router depending on the package being downgraded.

Step 2

install commit

Example:

Router# install commit

Commit the changes.

Downgrade to a specific version using install RPC

This procedure instructs the system to fetch the listed software package (in this case,xr-telnet-7.0.1v1.0.0) from the given source directory on the local file system or a mounted location and install the package onto the device.

Procedure

Step 1

Use install RPC on the Cisco-IOS-XR-install-act data model to install xr-telnet-7.0.1v1.0.0.

Example:

<install>
 <packages>
   <packagename>
 </packagename>
 </packages>
   <source>file:///harddisk:/files/</source>
</install>

Step 2

install commit

Example:

Router#install commit

Commit the changes.

Downgrade to obtain a bug fix

This procedure allows you to downgrade xr-telnet-7.3.1v1.0.1 to a previously installed version where a bug fix is applied, say, xr-telnet-7.3.2v1.0.0-1.


Note

When multiple older versions of the package are present in the configured repositories, the immediate previous version of the package is installed.


Caution

This procedure removes the current version of the package completely.

Procedure

Step 1

install package downgrade <IOS XR version with a bug fix>

Example:

Router# install package downgrade xr-telnet-7.3.2v1.0.0-1

Downgrade to xr-telnet-7.3.2v1.0.0-1, where a bug fix was applied.

Step 2

install apply [reload | restart]

Example:

Router# install apply [reload | restart]

Apply the changes.

Attention

 

To identify whether to reload the router or restart the affected processes as part of the apply operation, use either the show install history last transaction verbose command or show install request command.

Step 3

install commit

Example:

Router# install commit

Commit the changes.

Downgrade to remove a bug fix

This procedure allows you downgrade your current package with a bug fix RPM to a previously installed version where the bug fix was not applied.

A bug fix RPM is an upgrade to the existing package. When downgrading a package to remove bug fix RPMs, ensure that you also consider all dependencies of the current version. An attempt to remove a bug fix RPM either removes the entire feature or fails if the package is mandatory.

You can use the show install fixes deactivate command to view information related to removing a bug fix. This command provides information such as the package changes, other bug fixes that were deactivated, instructions for adding packages missing for the bug fix removal to be successful, command for removing the bug fix, and any recommendations, if applicable. See the following example:


Note

You can specify any number of DDTS separated by a space in the show install fixes deactivate command. For example, to know the recommendations for removing bug fix for ABC123, DEF456, and GHI789, you can use show install fixes deactivate ABC123 DEF456 GHI789 command.

Procedure

Step 1

show install fixes deactivate <bug-id>

Example:

Router# show install fixes deactivate CSCwa94577

User-requested DDTSs deactivated by this command: CSCwa94577
 
All DDTSs deactivated by this command: CSCwa94577
 
Package changes:

  xr-telnet-core-7.3.2v1.0.1 -> xr-telnet-core-7.3.2v1.0.0

Example install commands:
  install source any-configured xr-telnet-core-7.3.2v1.0.0
  install package downgrade xr-telnet-core-7.3.2v1.0.0

View the package versions where the bug fix, CSCwa94577, was deactivated.

Step 2

Downgrade to xr-telnet-core-7.3.2v1.0.0 using one of the following options:

    1. Install the xr-telnet-core-7.3.2v1.0.0 package. 

      Router# install package downgrade xr-telnet-core-7.3.2v1.0.0
Install downgrade operation 49.1.1 has started
Install operation will continue in the background
Router#

    2. Verify whether the current package, xr-telnet-core-7.3.2v1.0.1 is successfully downgraded to xr-telnet-core-7.3.2v1.0.0. 

      Router# show install fixes deactivate CSCwa94577 
User requested DDTSs that are currently not installed: CSCwa94577

  • Remove the current package xr-telnet-core-7.3.2v1.0.1-1 from the install repository. 

    Router# install package remove xr-telnet-core-7.3.2v1.0.1-1 sync

Starting:
install package remove xr-telnet-core-7.3.2v1.0.1-1
Packaging operation 49.2.1
Press Ctrl-C to return to the exec prompt. This will not cancel the install operation

Current activity: Initializing .
Current activity: Veto check .
Current activity: Package add or other package operation ..

Packaging operation 49.2.1: 'install package remove xr-telnet-core-7.3.2v1.0.1-1' completed without error
Router#

Step 3

install commit

Example:

Router# install commit

Commit the changes.

Roll back software to a previously saved installation point

You can roll your system software back to a previous version. This could be used to discard an ongoing install operation, or to undo an install operation that has already been committed. After each commit operation, the system saves a record of the committed software packages. Each record is a restoration point, and is assigned a unique ID. This ID is known as a rollback ID. You can use the rollback ID to roll back the software to a restoration point associated with this ID. Up to 900MB of space is allowed for rollback points, instead of a specific number of rollback points.

Table 1. Feature History Table

Feature Name

Release Information

Feature Description

Rollback changes with simplified install process

Release 25.3.1

Introduced in this release on: Fixed Systems (8200 [ASIC: Q200, P100], 8700 [ASIC: P100, K100], 8010 [ASIC: A100]); Centralized Systems (8600 [ASIC:Q200]) ; Modular Systems (8800 [LC ASIC: Q100, Q200, P100])

With the simplified install process that enhances upgrade robustness and scalability between IOS XR versions, rollback packages are no longer available after a release upgrade.

You can continue to use the install rollback command to reverse operations within the same XR release, and existing rollback commands remain available for reverting operations involving multiple SMUs or optional packages.

Roll back to a previously saved installation point

Release 7.4.1

A maximum of 900MB of disk space is used to store all rollback points.

You can delete older rollback points to make space for newer or smaller rollback points such as, SMUs.

This feature introduces the following commands:

  • install commit description —sets the description for a rollback ID

  • ​​​​​​​install label id id description description —adds a new description or overwrites the description of the specified rollback ID.

The following command is updated to include the keyword, oldest n :

  • clear install rollback oldest n —deletes the specified number of rollback points


Note

  • Use rollback ID 0 to roll back to the software that was present after the system booted for the first time.

  • If you commit an install transaction using the install commit command, the GISO ZTP configuration is saved along with the rest of the software changes. This means that if you use the install rollback or install package rollback command to revert the software to the state of a previous transaction, the GISO ZTP configuration is also reverted to its previous state. To undo this install operation, as well as the change in GISO ZTP configuration, use the install package abort command. If there is no GISO ZTP configuration saved at the end of the install transaction, the existing GISO ZTP configuration is reverted to the previous state when the rollback operation of that transaction is applied.

Roll back Cisco IOS XR software using a rollback ID

This procedure helps you rollback your software using a rollback ID.

Procedure

Step 1

View the list of available rollback IDs.

Example:

Router# show install rollback list-ids

Step 2

Explore the main packages that can be installed if you roll the software back to the specific rollback ID.

Example:

Router# show install rollback id <id>

Step 3

View the relative changes that are made to the currently installed software if it is rolled back to a rollback ID.

Example:

Router# show install rollback id <id> changes

To perform these tasks using data models, use the get RPC on the Cisco-IOS-XR-install-augmented-oper data model. 


<rpc>
  <get>
   <filter type="subtree">  
      <install xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-install-augmented-oper">
      <rollback/>
     </install>
   </filter>
  </get>
</rpc>

Step 4

Roll back to the software associated with the specific rollback ID.

Example:

Router# install rollback <id> [commit]

If you want to apply the change and roll back to the associated rollback ID, commit the change. You can also include the keyword noprompt in the command to enable the system to bypass your permission to reload the router.

Attention

 

This roll back operation installs the previous software and also applies the change automatically. This may reload the router depending on the package that is rolled back.

Alternatively, use the install package rollback command to only roll back the package but not apply the changes. You can check whether the router will reload or restart if you apply the change using the show install history last transaction verbose command or show install request command. Based on the command output, you can take the appropriate action using the install apply reload | restart command to either reload or restart the system. Use the install commi t command to commit the transaction.

To perform this task using data models, use the install-rollback RPC on the Cisco-IOS-XR-install-augmented-oper data model. 

<rpc>
 <install-rollback xmlns="http://cisco.com/ns/yang/Cisco-IOS-XR-install-augmented-act">
  <commit>true</commit>
   <transaction-id>0</transaction-id>
 </install-rollback>
</rpc>

To understand the data model structure and its arguments, see the Access the Install-Related Data Model.

Step 5

Commit the operation.

Example:

Router#install commit

Rollback from SONiC to Cisco IOS XR OS

This section describes how to rollback from SONiC OS to Cisco IOS XR software on the router.

Before you begin

Complete these prerequisites before you install Cisco IOS XR software on a router running SONiC:

  • Ensure all SONiC instance are running with FPD version 0.1.

    root@sonic#cardevent.py --send CV_FPDPUBLISH --slot all
root@sonic#fpd-util.py --getfpd
1.0.0.13_programed 0.1
1.0.0.3_programed 0.1
1.0.0.5_programed 0.1
1.0.0.33_programed 0.1

  • Ensure that chassis can access the DHCP or PXE server hosting the IOS XR image.

  • Check the BIOS version on RP and LC to ensure that the BIOS version required for IOS XR boot operation is available.

    RP:

    cisco@sonic#fwutil show status
Chassis    Module    Component    Version    Description
---------  --------  -----------  ---------  --------------------------------
8800-RP              BIOS         1-25       BIOS - Basic Input Output System
                     Aldrin       1.2        Marvell - Aldrin Ethernet switch
                     Aikido       1.35       Aikido - x86 FPGA
                     TAM          2.5        TAM FW - x86

    LC:

    cisco@sonic#fwutil show status
Chassis      Module    Component    Version    Description
-----------  --------  -----------  ---------  --------------------------------
8800-LC-48H            BIOS         1-25       BIOS - Basic Input Output System
                       Aldrin       -1.65535   Marvell - Aldrin Ethernet switch

  • Copy the IOS XR image to router as onie-recovery-x86_64-cisco_8000-r0.efi64.pxe image.

    RP:
    cisco@sonic#ifconfig eth0 192.0.2.254 netmask 255.255.0.0
    Linux:
    node$:scp 8000-x64-7.10.1.iso cisco@192.0.2.254:/ws/

    RP:

    cp /ws/8000-x64-7.10.1.iso /opt/cisco/var/tftp/onie-recovery-x86_64-cisco_8000-r0.efi64.pxe

Procedure

Step 1

Run the migration script.

Example:

root@sonic#xrmigration.sh
   INFO: Staging LC found : 1.0.0.3
   INFO: ipxe container start
   INFO: ipxe container service already running
   INFO: override ONIE image with XR image on staging LC
   INFO: Create dummy sonic image as onie-installer.bin on staging LC for SONiC ipxe server
   INFO: XR ethswitch upgrade on all LC
   INFO: Set migration context at staging LC0
   INFO: Set migration context at RP
   Reload all cards in 30 sec
Handling chassis reload scenario...

After two reloads, the RP reaches the iPXE server to automatically install the IOS XR image.

Step 2

Reload all line cards.

Example:

Router#reload boot media network location LC

Step 3

Verify the status of the cards.

Example:

Router#show platform
Thu Jun  1 21:38:26.276 UTC
Node              Type                     State                    Config state
--------------------------------------------------------------------------------
0/RP0/CPU0        8800-RP(Active)          IOS XR RUN               NSHUT
0/0/CPU0          88-LC0-36FH              IOS XR RUN               NSHUT
0/1/CPU0          8800-LC-48H              IOS XR RUN               NSHUT
0/5/CPU0          88-LC0-36FH-M            IOS XR RUN               NSHUT
0/FC0             8808-FC0                 OPERATIONAL              NSHUT
0/FT0             8808-FAN                 OPERATIONAL              NSHUT
0/FT1             8808-FAN                 OPERATIONAL              NSHUT
0/FT2             8808-FAN                 OPERATIONAL              NSHUT
0/FT3             8808-FAN                 OPERATIONAL              NSHUT
0/PT0             8800-HV-TRAY             OPERATIONAL              NSHUT
0/PT1             8800-HV-TRAY             OPERATIONAL              NSHUT
0/PT2             8800-HV-TRAY             OPERATIONAL              NSHUT

Step 4

After IOS XR software is installed on both RP and LC, reload all the nodes on the router.

Example:

Router#reload location all

The OS is migrated from SONiC to Cisco IOS XR software.

Stream Telemetry Data for Install Operations

Table 2. Feature History Table

Feature Name

Release Information

Description

Stream Telemetry Data about Install Operations

Release 7.5.2

You can stream telemetry data for install-related details such as active and committed packages, view the progress of install operations, retrieve the image version, and view the error messages with recovery information when an operation fails.

To stream telemetry data that is related to software installation, you must create subscriptions to the sensor paths in the YANG data models. See Obtain Data Models for Install Operation for the list of supported data models. For information about establishing a telemetry session and creating subscriptions, see the Telemetry Configuration Guide for Cisco 8000 Series Routers.

Stream Telemetry Data About

Description

YANG Path

Summary of active packages

Data is streamed after a successful apply operation. An active package is the software currently running on the system.

Cisco-IOS-XR-install-oper:

install/packages/active/summary

Summary of committed packages

Data is streamed after a successful commit operation. A package that is committed remains active following a system reload.

Cisco-IOS-XR-install-oper:

install/packages/committed/summary

Status of the last request operation

Data is streamed when starting a new request and also when entering an idle state. If the operation has failed, this includes error messages along with recovery state.

Cisco-IOS-XR-install-oper:

install/request

Image version and GISO label

Data is streamed after a successful apply operation.

Cisco-IOS-XR-install-oper:

install/version

Packaging information

Data is streamed at the start and end of a packaging operation.

Cisco-IOS-XR-install-augmented-oper:

install/history/latest-packaging-operation

Atomic information

Data is streamed at the start and end of apply operation.

Cisco-IOS-XR-install-augmented-oper:

install/history/latest-atomic-change

Transaction information

Data is streamed at the start, in progress, and end of a commit operation.

Note

 

After a transactional rollback, some of the data such as summary of active packages, image version can change. However, telemetry events are not sent after the reload operation.

Cisco-IOS-XR-install-augmented-oper:

install/history/latest-transaction