Understanding Software Modularity and Installation

This section describes the concepts and procedures for upgrading or downgrading your system, installing optional packages, and obtaining bug fixes for the Cisco 8000 series routers.

Cisco 8000 series routers use the XR7 framework. This framework refers to a set of architectural enhancements to the Cisco IOS XR software around the capablities of modularity, simplified platform infrastructure, and programmability at various software layers.

The Cisco IOS XR software is composed of a base image (ISO) that provides the XR infrastructure. The ISO image is made up of a set of packages (also called RPMs). These packages comprise mandatory and optional RPMs that can be deployed based on specific requirements. This software modularity approach provides a flexible consumption model that allows you to install a subset of IOS XR packages on devices based on your individual requirements. All critical components are modularized as packages so that you can select the features that you want to run on your router. For example, components like CDP and Telnet are modularized as packages and separated from the base image. These packages can be individually installed, upgraded or removed based on your requirements.

XR7 install is Dandified Yum- or DNF-based software package manager that is used to install, update, and remove packages on the RPM-based Linux distributions. The package manager is used to automatically compute dependencies and determine the actions required to install packages.

Software Deliverables and Terminologies

This section provides an understanding of the terms that are associated with installing the software.

  • Package: The primary mechanism for changing the install image on a system. A package, also known as an RPM, contains the software and metadata. A package is in .rpm format. A package can be mandatory or optional. Mandatory packages are part of the install image and cannot be removed. Optional packages are not required for the software to work, but can be installed to provide additional functionalities, and can be installed or removed based on requirement.

  • ISO image: A bootable image that contains the installable files of the base operating system (OS). The image contains the IOS XR (XR7) infrastructure for fixed and distributed platforms in the form of base ISO image, madatory RPMs and optional RPMs. An ISO image is in .iso format.

  • Golden ISO (GISO): A customizable ISO image that is built to contain preferable packages to suit diverse installation requirements. GISO can be customized to include a standard base image with the basic functional components, additional RPMs, bug fixes, and configuration files based on your requirement. Contact Cisco Support to build a GISO.

  • Source: A location from where packages and images are installed. The source can be a repository or a local directory.

  • Repository: A directory of RPMs and their metadata that a package manager uses to query the packages.

  • Active package: The software in the package that is currently running on the system.

  • Atomic change: An instantaneous switch from old software to new software after the changes are applied.

  • Top-level package: Each block of software has a top-level package and various partition-level packages. The top-level package can be installed or upgraded directly, whereas the partition-level packages cannot be changed directly. The partition-level packages are installed or upgraded automatically as dependencies of the top-level package. The top-level package has the name format xr-<feature>-<release>.x86_64.rpm, whereas the dependent partition-level packages have the longer name format containing information about the partition. You can also use the RPM to check the summary or description metadata of the package, which will identify whether it is a top-level or a partition-level package.

  • Package manager: An entity that handles the semantics to resolve dependencies in packaging operations.

  • Packaging operations: The actions performed to change the packages that are installed on the system. The semantics are inherited from the underlying package manager. Examples of packaging operations are upgrade, downgrade, replace, add, or remove packages.

  • Synchronous action: Synchronous action requests are supported for install actions using CLI command. Specify synchronous keyword in the install commands, and the prompt will only be returned when either the request has completed, Ctrl + C keys are pressed or a reload occurs. Pressing Ctrl + C keys during a synchronous action request will return the prompt to the user but will not halt the install operation. During the synchronous action request, the user is updated with the status of the request whenever it changes.

  • A packaging operation has these phases:
    • Install: A packaging operation where software is manipulated (installed, changed, removed) in the file system. However, the new software is not activated until the atomic operation is applied.

    • Apply: A packaging operation that indicates an end of the atomic operation, making the update visible to the system. The system takes the appropriate action to start running the update. The action can either be to restart the process or reload the system. All the packaging operations performed under an atomic operation is active after the changes are applied. However, the changes are reverted with a reload operation.

    • Commit: An install operation where all the atomic operations performed are successfully installed to the router. A committed package is active on a system when the router reloads and sustains through reload operations. A commit operation completes the install transaction. Excluding any system reload that is initiated to complete an atomic operation, if the system reloads during an install transaction, it is automatically restored to its previous state. If a node (RP or LC), reloads during a install transaction, it will be held down and prevented from booting until the commit operation is executed.


      Note

      A manual or automatic system reload without the transaction being completed by the install commit command successfully executed, reverts the system to the point before the install transaction commenced, including any configuration changes. Only the log is preserved for debugging.


Supported Packages

The base ISO image is contained within a file in .iso format. Additional optional packages (RPMs) are provided as modular software deliverables to align with diverse use cases and their deployments across the network.

The software deliverables can be downloaded from Cisco Software Download center.

Optional Package

Included in Base ISO Image

Release Introduced

8000-netflow

Yes

Release 7.0.11

8000-mcast

Yes

Release 7.0.11

BGP

Yes

Release 7.0.11

CDP

No

Release 7.0.11

EIGRP

No

Release 7.0.11

IPSLA

Yes

Release 7.0.11

IS-IS

Yes

Release 7.0.11

LLDP

Yes

Release 7.0.11

MCAST

Yes

Release 7.0.11

MPLS-OAM

Yes

Release 7.0.11

Netflow

Yes

Release 7.0.11

OSPF

Yes

Release 7.0.11

Perfmgmt

Yes

Release 7.0.11

RIP

No

Release 7.0.11

Telnet

No

Release 7.0.11

Track

Yes

Release 7.0.11


Note

The telnet package is not part of the ISO image. You must manually install the telnet optional package to use telnet for client or server. This applies to all packages that are not part of the ISO image.

SSH is part of the ISO image.


Workflow for Installing Cisco IOS XR Software

The router is shipped with a pre-installed version of the Cisco IOS XR (XR7) software. When the router is powered ON for the first time, the pre-installed software starts functioning automatically. You configure the router for network capabilities. When a new version of the software is available, you can upgrade the system using these tasks:


Note

For instructions to upgrade image-specific software, navigate to the CCO Software Download portal, select the product and refer to the 8000-x64-7.x.x.docs.tar file for the release.

Obtain Data Models for Install Operation

XR7 can be installed using one of these two methods:
  • CLI

  • Cisco Software Manager Server

  • YANG data models

To install using data models, you must first obtain the data models.

Procedure


Step 1

Access the supported data models to install Cisco IOS XR software from the Github repository.

The models are in the .yang format. Each data model can be identified as one of the following functionalities:

  • -oper in the model name indicates an operational model. For example, Cisco-IOS-XR-install-oper.yang and Cisco-IOS-XR-install-augmented-oper.yang are operational models for the install operation.

  • -cfg indicates a configuration model. For example, Cisco-IOS-XR-install-cfg.yang is a configuration model for the install operation.

  • -act indicates an action model. For example, Cisco-IOS-XR-install-augmented-act.yang and Cisco-IOS-XR-install-act.yang are action models for the install operation.
Step 2

Explore the install-related data models.

Data Model

Description

Release Introduced

Cisco-IOS-XR-install-oper

Operational data model to view details that are related to basic package information, active and committed packages, and fixes.

Release 7.0.11

Cisco-IOS-XR-install-cfg

Configuration data model to specify the location of the install source.

Release 7.0.11

Cisco-IOS-XR-install-act

Action model to perform basic install operations and software upgrade.

Release 7.0.11

Cisco-IOS-XR-install-augmented-oper

Augmented operational model that displays information about packaging, atomic changes, and history of the install operation on the router.

Release 7.0.11

Cisco-IOS-XR-install-augmented-act

Action model to perform flexible install operations, including controlling the exact timing of system reloads and rolling back to a previous commit.

Release 7.0.11

Cisco-IOS-XR-shellutil-copy-act

Action model to copy files on the router from a source location.

Release 7.0.11


Create Repository to Access Files for Installing IOS XR Software


Note

If only Golden ISO (GISO) is used, you do not need to create a repository.


To install packages (RPM), code upgrades, and updates in XR7, you need a repository of RPMs for the router to download the RPMs for installation. The repository can be local to the router, or accessed remotely through FTP, HTTP, or HTTPS. The remote repository is the recommended method to access the RPMs.

Important

The repository must be created specific to each platform and release. Do not create repositories with a mix of platforms and releases.


When the repository is accessed remotely, you must provide a repository URL from where the install files are fetched. The URL contains:
  • IP address of the server

  • Port number of the server

  • (Optional) Virtual Routing and Forwarding (VRF) name

The repository can be configured to be reachable using a non-default VRF table. If the repository is reachable through an address in a VRF, specify the name of the VRF.
The format of the repository URL is one of the following:
  • FTP: ftp://<server>[;<vrf>]/<path-to-repository>

  • HTTP: http://<server>[;<vrf>]/<path-to-repository>

  • HTTPS: https://<server>[;<vrf>]/<path-to-repository>

  • Local: file:///<path-to-repository>

For example, the URL for HTTP server is http://172.16.0.0:3333/.

Note

Username and password are not supported for HTTP and FTP repositories.


Create and Configure a Local Repository

The router can serve as repository to host the RPMs. You must be a root-lr user with access to the router shell. Remote repository is the recommended method to access the RPMs. However, if remote repository is not your preferred option, then you can use the router as a repository to host the RPMs.

Using a local repository removes the need to setup an external server for software installation. In this method, the image files are copied directly to the router, and used to create a repository locally. However, on the downside, the files for future updates must be copied to each router individually.

This section provides the procedure for setting up a local RPM repository on the router.
Procedure

Step 1

Create a directory on remote server and copy the RPM files to that directory. This directory must be reachable to FTP, HTTP, HTTPS, SSH, or TFTP server that the router uses to access the files.

Step 2

Create a directory locally on the router's /harddisk:. Copy the required RPMs and ISO files (using copy or scp command) from the server to the local directory on the router.

Step 3

Access the shell of the router using run command and untar the RPMs.

Example:
Router#run
[node:~]$cd <directory-with-rpms>
[node:~]$tar -xvzf <rpm-name>.tgz
Step 4

Exit from the shell.

Step 5

Configure the local repository.

Example:
Router#config   
Router(config)#install repository local-repo url file:///harddisk:/<directory-with-rpms>
Router(config)#commit
<data and time stamp> UTC: config[67543]: Configuration committed by user.
Router(config)#end

where, local-repo is the repository name, file:///harddisk:/<directory-with-rpms> is the local repository URL.

Step 6

Check the contents of the repository.

Example:
Router#show install available
Trying to access repositories...
Package                Architecture          Version          Repository      
--------------------  ---------------  ------------------ ---------------  
xr-8000-core          x86_64        7.0.11v1.0.1-1     local-repo 
                                         
xr-core               x86_64        7.0.11v1.0.1-1     local-repo

Note 

Only the top-level packages are displayed. The contents of the repository is displayed only when the configured repository is valid and the RPMs are present in the repository. It displays only the packages that are available in the repository and not part of active system.


Create and Configure an External Repository

To create an external repository, use a server that can be reached over HTTP, HTTPS or FTP. The following instructions are applicable to Linux distribution systems.

Using an external repository provides a central common repostiory to be used across devices. This eliminates the need to copy files for future updates to each router individually. It also serves as a single source when new RPMs (bug fixes, packages, updates) are made available. This is the recommended method to setup a repository.


Note

For releases 7.0.11, the external repository is available only through the Management Ethernet interface.



Note

For releases 7.0.12 and later, the server hosting the external repository must be able to reach the router using the address of the loopback interface in the VRF. If a VRF has more than one loopback interface, the loopback with the lowest-numbered loopback name is selected. For example, Loopback1 is selected over Loopback2.


Before you begin
Ensure that you have completed the following tasks:
  • Set up your HTTP, HTTPS or FTP server. Ensure that the server is reachable as specified in the note above.

  • Install createrepo utility on the Linux distribution system (if not installed already).

Procedure

Step 1

Create a directory on the server and copy all the RPMs to a directory. This directory hosts the repository and must be accessible to the HTTP, HTTPS or FTP server that the router will use to access the repository. For example, /var/www/html, is the directory where the repository will be created.

If the RPM files are archived (.tar format) or compressed (.tgz or .gz format), extract the files. The files hierarchically arrange in sub directories under the main directory that is used as a repository.

Step 2

Convert the directory to a repository using createrepo utility on the Linux server. This creates a directory named repodata with the metadata of all the RPMs.

Example:
[node]$ createrepo --database /var/www/html/
Saving Primary metadata
Saving file lists metadata
Saving other metadata
Generating sqlite DBs
Sqlite DBs complete

[node]$ cd /var/www/html/
[node]$ ls
repodata
[node]$ 

If you add new packages to the repository, change or remove packages from the repository, you must run createrepo command again to update the metadata. This ensures that the package manager chooses the correct packages.

Step 3

Configure the external repository.

Example:
Router#config   
Router(config)#install repository remote-repo url http://10.194.88.104/<directory-with-rpms> 
Router(config)#commit
<data and time stamp> UTC: config[67542]: Configuration committed by user 'cisco'.    
Router(config)#end
For FTP, the repository is configured as follows:
Router#config   
Router(config)#install repository remote-repo url ftp://repouser:cisco@10.194.88.104/<directory-with-rpms>     
Router(config)#commit
<data and time stamp> UTC: config[67543]: Configuration committed by user 'cisco'.    
Router(config)#end

where, remote-repo is the repository name, http://10.194.88.104/<directory-with-rpms> is the HTTP repository URL, and ftp://repouser:cisco@10.194.88.104/<directory-with-rpms> is the FTP repository URL.

Step 4

Verify connectivity to the server, and check the contents of the repository.

Example:
Router#show install available
Trying to access repositories...
Package                Architecture          Version          Repository      
--------------------  ---------------  ------------------ ---------------  
xr-8000-core          x86_64        7.0.11v1.0.1-1     remote-repo 
                                         
xr-core               x86_64        7.0.11v1.0.1-1     remote-repo

Note 

Only the top-level packages are displayed. The contents of the repository are displayed only when the configured repository is valid and the RPMs with the updated metadata are present in the repository. It displays only the packages that are available in the repository and not part of active system.


Upgrade the Current Active Version of Cisco IOS XR Software

You can upgrade the system when a newer version is available. A system upgrade replaces the existing version of the software with a newer version. By keeping the software up-to-date, you can ensure that the device works with the latest features and bug fixes.

You can replace the currently active software on your system with the software from a specified ISO image. When you replace the packages, the impact on the system is minimal. Only a minimal set of changes is performed to upgrade to the new software. Packages are not removed and reinstalled if there are no changes between the two versions.


Note

Even if the configuration file is bundled in a GISO, the file will not be used during an upgrade of the system. It is only used when the system is completely reimaged in case of disaster recovery.



Note

The instructions in this section also apply to system downgrade.


This section shows replacing the current software version with 8000-x64.iso image. To understand the phases of install operation, see Software Deliverables and Terminologies. For information about repositories, see Create Repository to Access Files for Installing IOS XR Software.

Upgrade the System

In this scenario, you replace the current software with 8000-x64.iso image, apply the changes, and commit the configuration. Committing the changes indicates the end of the current transaction. The updated software is used after subsequent reboots.
Procedure

Step 1

Copy the ISO (or GISO) image to a location on the router. It is a best practice to place the image in /harddisk: location on the router.

Step 2

Upgrade the system to replace the current software with the 8000-x64.iso image.

Example:
Router#install package replace /harddisk:/8000-x64.iso
Step 3

Activate the new .iso image on the router by applying the changes.

Example:
Router#install apply {reload | restart} [noprompt]

To identify whether a reload is required or only process restart is needed, use either show install history last transaction verbose command or show install request command.

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

Applying the change gives you the flexibility to test the operation of the new software before committing the changes. If you reload the router, the router reverts the software to its previous software state.

All operations that automatically apply the new software are prohibited when an atomic change is already in progress. You must address the current atomic-change before performing this operation. To address the change, apply the current atomic-change, or abort it with the install package abort all-since-apply command.

Step 4

Verify that the image is activated successfully.

Example:
Router#show install request
Step 5

Commit the transaction.

Example:
Router#install commit
Note 
Any action requests may be run synchronously from the CLI. During this request, you will be updated with the status of the request whenever it changes. The following example shows the output from a synchronous action request:

Router#install commit synchronous
Starting:
  install commit
Transaction 4
The install operation will continue in the background
Press Ctrl-C to return to the exec prompt. This will not cancel the install operation

Current activity: Initializing ....
Current activity: Commit transaction ......

Transaction 4: 'install commit' completed without error

Upgrade the System and Install RPMs

In this scenario, you replace the current software with the 8000-x64.iso image and have the possibility to install or remove optional RPMs before applying the changes. You can perform this operation while an atomic-change is already in progress. However, all packaging operations before this command is discarded. The installed software is an exact copy of the software in the ISO after this packaging operation is complete. You can perform all additional packaging operations after this operation and before applying and committing the changes.
Procedure

Step 1

Copy the ISO (or GISO) image to a location on the router. Best practice is to place the image in /harddisk: on the router.

Step 2

Upgrade the system to replace the current software with the 8000-x64.iso image.

Example:
Router#install package replace /harddisk:/8000-x64.iso
Step 3

Install additional RPMs (packages) after the system upgrade operation.

  1. Configure a repository on the router. For instructions to create a local or a remote repository, see Create Repository to Access Files for Installing IOS XR Software.

  2. Check the available packages in the repository.

    Example:
    Router#show install available
  3. Install the RPMs.

    Example:
    Router#install package add <pkg1> <pkg2> <pkgn>
Step 4

Check the status of install operation.

Example:
Router#show install request
User request: install package replace /misc/disk1/8000-x64.iso
Operation ID: 2.1.1
State:        In progress 
Current activity:    Package add or other package operation
Next activity:       Await user input
Time started:        <date and time>
Timeout in:          35m 53s
Locations responded: 3/4
Location          Packaging operation stage Notification Phase Clients responded
----------------- ------------------------- ------------------ -----------------
0/0/CPU0          None in progress          None in progress                 N/A
0/11/CPU0         None in progress          None in progress                 N/A
0/RP0/CPU0        Operation complete        None in progress                 N/A
0/RP1/CPU0        None in progress          None in progress                 N/A
Note 

The operation ID is a unique ID for each user request. This is constructed from the transaction ID, atomic change ID and packaging operation ID that was already used in the commands. For example, if the request is install commit, the operation ID is the transaction ID. If the request includes applying an atomic change but not committing the transaction (for example, install replace /harddisk:/8000_x64.iso), the operation ID will be the atomic change ID. An operation ID of 4.2 indicates a second atomic change in the fourth transaction.

This operation ID is also returned in the action RPC. If an error occurs while the request is initiated, an empty string is returned instead of an operation ID.

When the State changes to Success, activate the new image.
Step 5

Activate the new .iso image or RPM on the router by applying the changes.

Example:
Router#install apply {reload | restart} [noprompt]

To identify whether a reload is required or only process restart is needed, use either show install history last transaction verbose command or show install request command.

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

Step 6

Verify that the image is activated successfully.

Example:
Router#show install request
Step 7

Commit the transaction.

Example:
Router#install commit
To perform the same step using data models, use the install-replace RPC on the Cisco-IOS-XR-install-act data model.

<install-replace>
   <file>iso-name</file>
   <source-type>local</source-type>
   <source>directory-containing-iso</source>
   <commit>true</commit>
</install-replace>

Install Optional Packages to Provide Additional Functionality

You can install one or more packages (RPM) that are not already present on the system. The packages are not mandatory for the software to function, but provide additional functionality. Based on your requirement, you can install or remove these optional packages.

You must specify only the top-level package name that you want to install. The associated dependencies of this package, in the form of card and partition-specific packages, are included automatically. By default, the latest available version of each package is installed. You can also explicitly install a specific version of a package.

Note

All Cisco IOS XR images are signed to ensure the authenticity of the software.


Consider a router setup with the following packages that are copied to a local directory:
Router#dir /harddisk:/files
xr-eigrp-7.0.11v1.0.1-1.x86_64.rpm
xr-infra_tpa-7.0.11v1.0.1-1.x86_64.rpm
xr-ipsla-7.0.11v1.0.0-1.x86_64.rpm
xr-is-is-7.0.11v1.0.0-1.x86_64.rpm
xr-lldp-7.0.11v1.0.0-1.x86_64.rpm                                                     
xr-mcast-7.0.11v1.0.0-1.x86_64.rpm

This example shows the options to install the optional package xr-ipsla-7.0.11v1.0.1-1.x86_64.rpm.

Procedure


Step 1

Install one or more optional packages using one of the following options:

  • Option 1: Install the package from the local directory:
    Router#install source /harddisk:/files xr-ipsla-7.0.11v1.0.1-1.x86_64.rpm
    Note 

    The install source command automatically applies the changes. Use this command to install optional packages. To upgrade existing packages, see Upgrade the System to Obtain Bug Fixes.

  • Option 2: Install the package from a configured remote repository:
    Router#install source install-repo xr-ipsla

    Here, install-repo is the name of the repository. For repository configuration, see Create Repository to Access Files for Installing IOS XR Software.

  • Option 3: Install the package from a repository URL:
    Router#install source http://72.16.0.0:3333/remote-repo xr-ipsla
Note 

The IP address of the repository must be accessible from the Management Ethernet port. In-band interfaces on linecards cannot be used to reach the repository.

More than one package can be installed using a single packaging operation. Use the following command:
Router#install source <path-to-source> <package 1> <package 2> … <package n>
For example,
Router#install source /harddisk:/files xr-ipsla-7.0.11v1.0.0-1.x86_64.rpm xr-mcast-7.0.11v1.0.0-1.x86_64.rpm 
To perform this task using data models, use the install RPC on the Cisco-IOS-XR-install-act data model. Here is an example with an HTTP repository:

<install>
   <packages>
     <packagename>pkg1</packagename>
     <packagename>pkg2</packagename>
     …
     <packagename>pkgn</packagename>    
   </packages>
   <source-type>http</source-type>
   <source><path-to-source></source>
</install>
Step 2

Commit the operation.

Example:

Router#install commit

Delete Optional Packages

You can delete optional packages that you that you no longer require. An optional package is not mandatory for the operating system to function, and based on your requirement, it can be installed or removed.

Procedure

Step 1

Remove the optional package.

Example:
Router#install package remove <optional-package-name>
Step 2

Apply the changes to make the change active.

Example:
Router#install apply [reload | restart]
Attention 

To identify whether to reload or restart the system after applying the changes, use either show install history last transaction verbose command or show install request command.

Step 3

Commit the changes to make the change persistent after a reload operation.

Example:
Router#install commit

Additional Install Operations

View the Version of Installed Packages

The router is shipped with a pre-installed operating system. You can view the version of the installed software and the active packages. If you have upgraded your system, installed additional packages or bug fixes, you can view the version of the committed packages.

Review the software version information:

  • Package name and version
  • User who built the package
  • Time the package was built
  • Build workspace
  • Build host
  • ISO label:
    • Label is present if GISO boots using PXE boot

    • Label is present if GISO is installed using the install replace method

    • Label reverts to default (only release version) if there is any change since the time the image with the label was installed.

    • Label is nullified and reverts to default if an RPM is added or removed on top of an existing GISO.

    • Label is repopulated if an RPM from the GISO is added or removed and a rollback operation is performed.

  • Copyright information
  • Hardware information

Procedure


Step 1

View the version of the Cisco IOS XR software, and its various software components that are installed on the router.

Example:

The following example shows the version information for a non-GISO image:

Router#show version
Cisco IOS XR Software, Version 7.0.11 LNT
Copyright (c) 2013-2019 by Cisco Systems, Inc.

Build Information:
 Built By     : xyz
 Built On     : Sat Jun 29 22:45:27 2019
 Build Host   : iox-lnx-064
 Workspace    : ../7.0.11/8000/ws/
 Version      : 7.0.11
 Label        : 7.0.11

cisco 8000
System uptime is 41 minutes
The following example shows the version information for a GISO image. The customer label is appended to the Label field in the GISO image:

Router#show version
Cisco IOS XR Software, Version 7.0.11 LNT
Copyright (c) 2013-2019 by Cisco Systems, Inc.

Build Information:
 Built By     : xyz
 Built On     : Sat Jun 29 22:45:27 2019
 Build Host   : iox-lnx-064
 Workspace    : ../7.0.11/8000/ws/
 Version      : 7.0.11
 Label        : 7.0.11-CUSTOMER_LABEL

cisco 8000
System uptime is 41 minutes

You can also use the get RPC on the install.version data model.

Step 2

View the active packages.

Example:


Router# show install active summary
Active Packages:    XR: 112    All: 1088
Label:              7.0.11

Optional Packages                          Version
--------------------------           ----------------------
xr-8000-mcast                            7.0.11v1.0.0-1
xr-8000-netflow                          7.0.11v1.0.0-1
xr-bgp                                   7.0.11v1.0.0-1
xr-ipsla                                 7.0.11v1.0.0-1
xr-is-is                                 7.0.11v1.0.0-1
xr-lldp                                  7.0.11v1.0.0-1
xr-mcast                                 7.0.11v1.0.0-1
xr-mpls-oam                              7.0.11v1.0.0-1
xr-netflow                               7.0.11v1.0.0-1
xr-ospf                                  7.0.11v1.0.0-1
xr-perfmgmt                              7.0.11v1.0.0-1
xr-track                                 7.0.11v1.0.0-1

You can also use the get RPC on the install.packages.active.node and the install.packages.active.node.summary data models.

To understand the data model structure and its arguments, see Obtain Data Models for Install Operation.


Upgrade the System to Obtain Bug Fixes

You can upgrade the system to obtain all available bug fixes or choose a specific bug fix using a bug ID.

Bug fixes deliver remedy that fix gaps in existing functions introduced in a previous release. Bug fixes are available as optional RPMs. You can install a bug fix using configured repositories.

You can download the bug fix RPMs from the CCO Software Download portal for the Cisco 8000 product line.

Navigate to the RPM using one of the following options in the CCO Software Download page:
  • Option 1: Enter the product ID

  • Option 2: Identify the product:
    • Click Routers > Service Provider > Cisco 8000 Series Routers .

    • Select the Product Series, and click IOS XR Software Maintenance Upgrades (SMU).

    From this page, download the latest bug fix RPMs as tarballs to the install repository. Untar the tarball into RPMs. The README file provides the relevant information about the bug fix and also identifies the dependencies, if any, where other bug fix RPMs may be required for a complete fix.


Note

Use the RPM repository to harvest the benefits of package manager. The package manager provides the flexibility to query the available package, and download only those packages and their dependencies that are needed for installation.



Note

If you are using GISO, you can also rebuild a new GISO containing the desired bugfixes, and install it using install replace operation. If the bugfixes do not require a reload to apply the changes, then this operation will also not require a reload.


Procedure


Step 1

View the list of available bug fixes.

Example:

Router#show install fixes available 
Bug Id             Packages                      Repository          
-----------    -----------------------------  ----------------  
CSCxx12345     xr-8000-core-7.0.11v1.0.1-1       <repository-name> 
               xr-core-7.0.11v1.0.1-1            <repository-name> 
Step 2

Install the bug fix or package using one of the following options:

  • Install the package where the bug fix is applied.
    Router#install package upgrade xr-8000-core-7.0.11v1.0.1-1 xr-core-7.0.1v1.0.1-1 
    Packaging operation 1.1.1 started - xr-8000-core-7.0.11v1.0.1-1 xr-core-7.0.1v1.0.1-1 
    
    Apply the changes.
    Router#install apply [reload | restart]
    Note 
    To identify if you need to reload or restart the system while applying the changes, use one of these two methods:
    • History of last transaction
      
      Router#show install history last transaction verbose
      2019-09-11 17:01:46 UTC    Transaction 3 started
      2019-09-11 17:01:46 UTC      Atomic change 3.1 started
      2019-09-11 17:01:46 UTC      Packaging operation 3.1.1 startedtion cleanup in progress
      2019-09-11 17:16:46 UTC    Transaction 3 complete
      
      Least impactful apply method: process restart

      The command also displays the information about the changes to files and processes as a result of the install operation, and the package operations that were carried out on each node.

    • Show install request
      
      Router#show install request
      
      User request: install package upgrade xr-8000-core-7.0.11v1.0.1-1 
      Operation ID: 2.1.1
      State: Success 
      
      Current activity: Await user input
      Time started: 
      
      The following actions are available:
      install package add
      install package remove
      install package upgrade
      install package downgrade
      install package replace
      install package rollback
      install package abort latest
      install package abort all-since-apply
      install apply restart
      install apply reload 
      
      Here, both install apply restart and install apply reload options are available. In this case, use install apply restart command because the impact on the system is the least. But when only install apply reload option is available, then reload is the only option to apply the change.
  • Install the optional package. Changes are applied automatically.
    Attention 

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

    Router#install source /harddisk:/files xr-8000-core-7.0.11v1.0.1-1.x86_64.rpm
    Note 
    Packages can also be installed using only the package name.
    Router#install source /harddisk:/files xr-8000-core 
  • This task can also be performed using YANG data models. Use install RPC on the Cisco-IOS-XR-install-act data model. Here is an example usage with an HTTP repository:
    
    <install>
       <packages>
         <packagename>pkg1</packagename>
       </packages>
       <source-type>http</source-type>
       <source><path-to-source></source>
    </install>
Step 3

View the state of the packaging operation.

Example:

Router#show install request 
User request: install package upgrade xr-8000-core-7.0.11v1.0.1-1  xr-core-7.0.1v1.0.1-1
Operation ID: 2.1.2
State:        In progress since

Current activity:    Initiate operation
Next activity:       Begin transaction
Time started:        2019-06-25 07:41:06

No per-location information.
Step 4

View the log to ensure that the installation is successful.

Example:

Router#show install log   
2019-06-25 07:41:06 UTC    Transaction 1 started
2019-06-25 07:45:08 UTC    Upgrade (Success)
2019-06-25 07:45:08 UTC    xr-8000-core-7.0.11v1.0.1-1  
2019-06-25 07:45:08 UTC    xr-core-7.0.1v1.0.1-1
2019-06-25 07:57:02 UTC    Atomic change 1.1 successfully applied by reload
Step 5

View the history of the install operation.

Example:

Router#show install history table 
  Transaction             Atomic Change          Packaging Operations
–––––––––––––––––––––  ––––––––––––––––––––––––––  –––––––––––––––––––––––––––––––––--
Id   Status          Id  Method   Status      Id  Operation   Inputs Status
–––––––––––––––––––––  ––––––––––––––––––––––––––  –––––––––––––––––––––––––––––––––--
 1   In progress     1   Reload   Success      1   Upgrade        1  Success

The command can also be used to view more details in case of a failed operation.

Use show install history id <operation-id> command to filter the history of install information by ID. IDs are of the form <transaction id>.<atomic id>.<packaging id>.
Router#show install history id ? 
  WORD Specify an operation ID (e.g. 1, 1.2, 1.2.3)
Use show install history last command to view the last packaging operation, atomic change or transaction.
Router#show install history last ?
     atomic-change  Show the last atomic change
     package        Show the last packaging operation
     transaction    Show the last transaction
Step 6

After the operation is complete, verify that the packages xr-8000-core-7.0.11v1.0.1-1 and xr-core-7.0.11v1.0.1-1 are installed and active.

Example:

Router#show install active summary
xr-8000-bfd                                                   7.0.11v1.0.0-1
xr-8000-bmc                                                   7.0.1v11.0.0-1
xr-8000-bundles                                               7.0.1v11.0.0-1
xr-8000-card-support                                          7.0.1v11.0.0-1
xr-8000-core                                                  7.0.11v1.0.1-1
xr-8000-x64-core                                              7.0.11v1.0.1-1
xr-core                                                       7.0.11v1.0.1-1
xr-core-calv                                                  7.0.11v1.0.0-1
xr-host-core                                                  7.0.11v1.0.0-1
xr-ip-core                                                    7.0.11v1.0.0-1
xr-spi-core                                                   7.0.11v1.0.0-1

Note that the version has changed. The version 1.0.1-1 indicates that the bug fix is installed.

This task can also be accomplished using data models. Use the get RPC for install.fixes.active operation using Cisco-IOS-XR-install-augmented-oper data model.

Step 7

Commit the changes for the changes to persist after a reload operation.

Example:

Router# install commit
Step 8

View the list of bug IDs for which fixes are committed.

Example:

Router# show install fixes committed

This task can also be accomplished using data models. Use the get RPC for install.fixes.committed operation using Cisco-IOS-XR-install-augmented-oper data model.

Step 9

View the list of active bug fix RPMs.

Example:

Router#show install fixes active

This task can also be accomplished using data models. Use the get RPC for install.fixes.active operation using Cisco-IOS-XR-install-augmented-oper data model.


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

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.


If a system fails to boot successfully, or reboots unexpectedly when the package is undergoing a version change, it is automatically recovered to its old software state.

This 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 or restart the system after applying the changes, 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.11v1.0.0
  • Use install RPC on the Cisco-IOS-XR-install-act 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

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 transaction ID. You can use the transaction ID to roll back the software to a restoration point associated with this ID. Only two roll back IDs are supported. The first roll back ID is last historical commit ID, and the second roll back ID is the current transaction (irrespective of whether the transaction is committed or not committed).


Note

  • You can only roll back to the last commit (transaction ID).

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


Procedure


Step 1

View the list of available transaction 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 transaction 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 transaction 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 transaction ID.

Example:

Router# install rollback <id> [commit]

If you want to apply the change and roll back to the associated transaction 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 install apply reload | restart command to either reload or restart the system. Use the install commit 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 Obtain Data Models for Install Operation.

Step 5

Commit the operation.

Example:

Router#install commit