Manage the Router

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 Manintain 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 View 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 a Previously Installed Package

You can downgrade a package to a previously installed version. By default, the subsequent previous version (version previous to the current version) is installed. Also, you can downgrade the software to a specific version of interest. To remove a bug fix RPM from the installed packages, downgrade the package to a version where the fix was not applied.

Note

While downgrading, you can choose any previous version, including the base version of the RPM. However, when downgrading a bug fix RPMs, ensure that you also consider all dependencies of the current version.

Bug fix RPM is an upgrade to the existing package. The action of removing 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 get deactivate, 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 seperated 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. 

Router#show install fixes deactivate CSCwc26944

User-requested DDTSs deactivated by this command: CSCwc26944
 
All DDTSs deactivated by this command: CSCvs01738,CSCwc26944
 
Package changes:
  xr-8000-core-7.5.2v1.0.5 -> xr-8000-core-7.5.2v1.0.4
  xr-8000-fib-ea-7.5.2v1.0.1 -> xr-8000-fib-ea-7.5.2v1.0.0           (missing)
  xr-8000-leabaofa-7.5.2v1.0.3 -> xr-8000-leabaofa-7.5.2v1.0.2
  xr-8000-mcast-7.5.2v1.0.1 -> xr-8000-mcast-7.5.2v1.0.0             (missing)
  xr-8000-utapp-blaze-7.5.2v1.0.2 -> xr-8000-utapp-blaze-7.5.2v1.0.1
  xr-fib-7.5.2v1.0.3 -> xr-fib-7.5.2v1.0.2
  xr-mcast-7.5.2v1.0.1 -> xr-mcast-7.5.2v1.0.0                       (missing)
  xr-ncs540l-core-7.5.2v1.0.14 -> xr-ncs540l-core-7.5.2v1.0.10
  xr-ncs5700-core-7.5.2v1.0.14 -> xr-ncs5700-core-7.5.2v1.0.10
  xr-ofa-7.5.2v1.0.3 -> xr-ofa-7.5.2v1.0.1
  xr-snmp-7.5.2v1.0.1 -> xr-snmp-7.5.2v1.0.0                         (missing)
 
Example install commands:
  install source any-configured xr-8000-core-7.5.2v1.0.4 xr-8000-fib-ea-7.5.2v1.0.0 xr-8000-leabaofa-7.5.2v1.0.2 xr-8000-mcast-7.5.2v1.0.0 xr-8000-utapp-blaze-7.5.2v1.0.1 xr-fib-7.5.2v1.0.2 xr-mcast-7.5.2v1.0.0 xr-ncs540l-core-7.5.2v1.0.10 xr-ncs5700-core-7.5.2v1.0.10 xr-ofa-7.5.2v1.0.1 xr-snmp-7.5.2v1.0.0
  install package downgrade xr-8000-core-7.5.2v1.0.4 xr-8000-fib-ea-7.5.2v1.0.0 xr-8000-leabaofa-7.5.2v1.0.2 xr-8000-mcast-7.5.2v1.0.0 xr-8000-utapp-blaze-7.5.2v1.0.1 xr-fib-7.5.2v1.0.2 xr-mcast-7.5.2v1.0.0 xr-ncs540l-core-7.5.2v1.0.10 xr-ncs5700-core-7.5.2v1.0.10 xr-ofa-7.5.2v1.0.1 xr-snmp-7.5.2v1.0.0
 
IMPORTANT: The above commands cannot currently be run because there are missing packages.Put the following packages in an accessible repository.
  xr-8000-fib-ea-7.5.2v1.0.0
  xr-8000-mcast-7.5.2v1.0.0   (optional package)
  xr-mcast-7.5.2v1.0.0        (optional package)
  xr-snmp-7.5.2v1.0.0
 
IMPORTANT: If the optional packages are not available, then they can be completely removed before removing the DDTS using install package remove xr-8000-mcast-7.5.2v1.0.0 xr-mcast-7.5.2v1.0.0

The following example shows the package xr-telnet-7.0.11v1.0.1 is downgraded to xr-telnet-7.0.11v1.0.0. The path to source can be a local location or a configured repository.

Before you begin

Ensure you have access to the previously installed package and its source.

Procedure

Step 1

Downgrade the package using one of the following options:

  • Downgrade the package where the fix was applied. When multiple older versions of the package are present in the configured repositories, the immediate previous version of the package is installed. Use caution when using this command as the current version of the package is removed completely.
    Router#install package downgrade xr-telnet

    Apply the changes.

    Router#install apply [reload | restart]

    Attention

     

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

  • Install a specific earlier version 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.

    		 
    Router#install source <path-to-source> xr-telnet-7.0.1v1.0.0
  • Use install RPC on the Cisco-IOS-XR-install-act.yang data model. Here is an example usage with a local repository:
    <install>
 <packages>
   <packagename>
    xr-telnet-7.0.11v1.0.0

</packagename>
 </packages>
   <source>file://<path-to-source>/</source>
</install>

    The package version xr-telnet-7.0.11v1.0.1 is downgraded to xr-telnet-7.0.11v1.0.0.

Step 2

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 1. 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