Manage the NCS 1010

Use the procedures in this section to maintain the NCS 1010 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 NCS 1010. 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 NCS 1010. If you are using a remote repository, ensure you have created and configured an external repository to store the packages. See the 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 24.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:

RP/0/RP0/CPU0:ios#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:

    RP/0/RP0/CPU0:ios#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: 

      RP/0/RP0/CPU0:ios#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,
      RP/0/RP0/CPU0:ios#install source http://203.0.113.1;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. 

      RP/0/RP0/CPU0:ios#install package add <pkg1> <pkg2> <pkgn>

      Or

      RP/0/RP0/CPU0:ios#install package upgrade <pkg1> <pkg2> <pkgn>

    2. Apply the changes.

      RP/0/RP0/CPU0:ios#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. 

      RP/0/RP0/CPU0:ios#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:

RP/0/RP0/CPU0:ios#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 NCS 1010.

Step 4

Verify the image and packages are activated successfully.

Example:

RP/0/RP0/CPU0:ios# show install request
User request: install package add xr-mcast
Operation ID: 87.1.1
State: Success

Step 5

Commit the transaction.

Example:

RP/0/RP0/CPU0:ios#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

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>203.0.113.1;vrf1/repoinfra/install_rpms.tar</source>
</install-package-upgrade>

Downgrade Software Version

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


Note

When downgrading the software image from release 24.4.x to an earlier version, we recommend to manually downgrade the line card firmware as well to prevent any impact on various functionalities.

Before you begin

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

RP/0/RP0/CPU0:ios#show hw-module location all fpd

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

RP/0/RP0/CPU0:ios#upgrade hw-module location all fpd all
After all the FPDs are upgraded, reload the NCS 1010.
RP/0/RP0/CPU0:ios#reload location all
Proceed with reload? [confirm]
After the NCS 1010 reloads, check that all the FPDs are in CURRENT state.

Procedure

Step 1

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

Example:

RP/0/RP0/CPU0:ios#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 .

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.

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 NCS 1010:
RP/0/RP0/CPU0:ios#copy running-config harddisk:/running_config-<mmddyyyy>
Copy the running configuration to a remote server:
RP/0/RP0/CPU0:ios#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 NCS 1010.

Example:

RP/0/RP0/CPU0:ios#scp root@<ip-address>:/<dir>/1010-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:

RP/0/RP0/CPU0:ios#show md5 file /harddisk:/1010-x64-<target-version>.iso

Step 6

Install the base image to downgrade the system.

  • Option 1: Install ISO without control over reload timing.
    RP/0/RP0/CPU0:ios#install replace /harddisk:/1010-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.

      RP/0/RP0/CPU0:ios#install package replace /harddisk:/1010-x64-release.iso

    2. Apply the changes.

      RP/0/RP0/CPU0:ios#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.

The following example shows the package xr-telnet-24.3.1v1.0.1 is downgraded to xr-telnet-24.3.1v1.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.
    RP/0/RP0/CPU0:ios#install package downgrade xr-telnet

    Apply the changes.

    RP/0/RP0/CPU0:ios#install apply [reload | restart]

    Attention

     

    To identify whether to reload the NCS 1010 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 NCS 1010 depending on the package being downgraded.

    		 
    RP/0/RP0/CPU0:ios#install source <path-to-source> xr-telnet-24.3.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-24.3.1v1.0.0
    xr-telnet-24.0.11v1.0.0
xr-telnet-24.4.1v1.0.0
</packagename>
 </packages>
   <source>file://<path-to-source>/</source>
</install>

    The package version xr-telnet-24.3.1v1.0.1xr-telnet-24.0.11v1.0.1xr-telnet-24.3.1v1.0.1 is downgraded to xr-telnet-24.3.1v1.0.0xr-telnet-24.0.11v1.0.0xr-telnet-24.4.1v1.0.0.

Step 2

Commit the operation.

Example:

RP/0/RP0/CPU0:ios#install commit

Stream Telemetry Data for Install Operations

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 .

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