This section describes the concepts and procedures for upgrading or downgrading your system, installing optional packages, and obtaining bug fixes for the Cisco NCS 540 series routers.
Cisco NCS 540 series routers use the Cisco IOS XR7 framework. This framework refers to a set of architectural enhancements to the Cisco IOS XR software around the capabilities 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, and a TAR file. The TAR file 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.
Cisco IOS 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.
![]() Note | For information on how to download the system upgrade procedures document, see the About Cisco IOS XR Software Upgrade and Downgrade Guide. |
The Cisco NCS 540 router variants that support XR7 in Cisco IOS XR Release 7.0.1 are:
-
N540-28Z4C-SYS-A
-
N540-28Z4C-SYS-D
-
N540X-16Z4G8Q2C-A
-
N540X-16Z4G8Q2C-D
-
N540-12Z20G-SYS-A
-
N540-12Z20G-SYS-D
-
N540X-12Z16G-SYS-A
-
N540X-12Z16G-SYS-D
The Cisco NCS 540 router variants that support XR7 in Cisco IOS XR Release 7.3.1 are:
-
N540X-6Z18G-SYS-A
-
N540X-6Z18G-SYS-D
-
N540X-8Z16G-SYS - A
-
N540X-8Z16G-SYS - D
The Cisco NCS 540 router variants that support XR7 in Cisco IOS XR Release 7.4.1 are:
-
N540X-4Z14G2Q-SYS-A
-
N540X-4Z14G2Q-SYS-D
-
N540-24Q8L2DD-SYS
The following Cisco NCS 540 Series Routers support XR7 in Cisco IOS XR Release 7.10.1:
Cisco NCS 540 Router Type | Product Identifier |
---|---|
Small Density Routers |
|
Medium Density Routers Supporting the XR7 Operating System |
|
Large Density Routers | N540-24Q8L2DD-SYS |
Fronthaul Routers |
|
For release specific caveats see Caveats.
Supported Packages
The base ISO image is contained within a .tar
file. Additional optional packages (RPMs) are provided as modular software deliverables to align with diverse use cases and their deployments across the network.
![]() Note | You can create a golden ISO (GISO) with optional packages and bug fixes based on your requirement. Contact Cisco Support to build a GISO. |
-
ISO image containing the base install image -
ncs540l-x64-7.0.1.iso
-
Tar file containing optional RPMs -
NCS540l-iosxr-7.0.1.tar
-
ZIP file for USB boot -
ncs540l-usb_boot-7.0.1.zip
The software deliverables can be downloaded from Cisco Software Download center.
Optional Package | Included in ISO by Default |
---|---|
ncs540l-netflow | Yes |
ncs540l-mcast | Yes |
BGP | Yes |
CDP | No |
EIGRP | No |
IPSLA | Yes |
IS-IS | Yes |
LLDP | Yes |
MCAST | Yes |
MPLS-OAM | Yes |
Netflow | Yes |
OSPF | Yes |
Perfmgmt | Yes |
RIP | No |
Telnet | No |
Track | Yes |
![]() 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. Install operation over IPv6 is not supported. |
Supported Packages for NCS 540 Small-Density Routers
Effective Cisco IOS XR Release 7.3.1, the following variants of the Cisco NCS 540 routers form the small-density routers:
-
N540X-6Z18G-SYS-A
-
N540X-6Z18G-SYS-D
-
N540X-8Z16G-SYS-A
-
N540X-8Z16G-SYS-D
The software deliverables include:
-
ISO image containing the base install image —
ncs540l-aarch64-7.3.1.iso
-
Tar file containing optional RPMs—
NCS540l-iosxr-7.3.1.tar
-
ZIP file for USB boot—
ncs540l-usb_boot-7.3.1.zip
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, mandatory RPMs. An ISO image is in
.iso
format.See AlsoHow to setup and play DCS in the Pimax CrystalOpenXR support for IL-2 and DCS for Windows Mixed Reality VR headsetsDie dritte Dimension - Pimax Crystal Review - CruiselevelFactory Reconditioned Dewalt 20V MAX XR Brushless Lithium-Ion 7-1/4 in. Cordless Circular Saw with POWER DETECT Tool Technology (Tool Only) - DCS574BR -
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. GISO can also include a custom image version. From IOS XR Release 7.5.x and later, you can build your GISO image without support from Cisco by using the Build Golden ISO (GISO) Using gisobuild.py Tool feature.
-
Source: A location where packages can be installed from. The source can be a repository, local directory or a local tar file.
-
Repository: A directory of RPMs and their metadata that a package manager uses to query the packages.
-
Active package: A package whose software is currently running on the system.
-
Committed package: A package that is committed and remains active following a system reload.
-
Atomic Change: Every packaging operation is contained within an atomic change. Atomic changes may contain multiple packaging operations. During an atomic change, any changes to install IOS XR software will not be visible to the system. To make the changes visible to the system, the atomic change must be 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 standard RPM commands 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. PressingCtrl + 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. -
Transaction: All atomic changes occur within a transaction. If the system reloads during an install transaction, the running software will be reverted to its previous state before the transaction was started. To maintain the software changes carried out during a transaction, you must commit the transaction.
-
A complete install operation to modify the system’s software requires three phases:
-
Packaging operation
-
Apply: This is required to complete an atomic change and make the software change visible to the system.
-
Commit: This is required to end a transaction and ensure that all software changes will still be present on router reload.
Note
If you perform a manual or automatic system reload without completing the transaction with the install commit command, the action will revert the system to the point before the install transaction commenced, including any configuration changes. Only the log is preserved for debugging.
This action clears all configuration rollback points available. You will not be able to rollback to, or view, any commits made until the install rollback event. Any new commits made after the install rollback event will start from commit ID ‘1000000001’.
Note
In a multinode system, any node reloads that occur during a transaction that are not initiated as part of the install 'apply by reload' phase can result in the reloaded node being in BOOT HOLD state. The node continues to be in the BOOT HOLD state until the transaction is either committed or cancelled.
-
Workflow for Installing Cisco IOS XR7 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 | ncs540-x64-<version>.docs.tar file for the release. |
Obtain Data Models for Install Operation
You can use YANG data models to install and upgrade XR7 software. The data models are packaged with the release image in the /pkg/yang directory.
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
andCisco-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
andCisco-IOS-XR-install-act.yang
are action models for the install operation.
Procedure
Step1 | View the install-related data models on the router. You can also access the supported data models to install Cisco IOS XR software from the Github repository. Example: The following table describes the function of the install-related data models:
| ||||||||||||||||||
Step2 | Use a manageability agent like NETCONF or gRPC to connect and communicate with the router. You can send Remote Procedure Calls (RPC) requests to configure or retrieve operational data from the router. The router processes the request and responds to the request through an RPC response. You use the RPCs to send requests to install the software by populating the relevant container and leaf in the data model. For more information about understanding the data model structure and using data models, see the Programmability Configuration Guide for Cisco NCS 540 Series Routers. |
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.
![]() 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>
. The path to the repository must be under /harddisk:/ location.
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
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
Step1 | Create a directory locally on the router's | ||
Step2 | Access the shell of the router using Example: | ||
Step3 | Exit from the shell. | ||
Step4 | Configure the local repository. Example: where, | ||
Step5 | Check the contents of the repository. Example:
|
Create and Configure an External Repository
Using an external repository provides a central common repository 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 release 7.0.1, 7.0.2, and 7.1.x, the external repository is available only through the Management Ethernet interface. |
Before you begin
-
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
Step1 | 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. | ||
Step2 | Convert the directory to a repository using Example: If you add new packages to the repository, change or remove packages from the repository, you must run | ||
Step3 | Configure the external repository. Example:
where, | ||
Step4 | Verify connectivity to the server, and check the contents of the repository. Example:
|
Upgrade the Current Active Version of Cisco IOS XR Software
.iso
image. The instructions in this section also apply to system downgrade. Upgrade the Current Active Version
A reboot is not always necessary. Bug fixes can be applied using a GISO that contains the current running software and the additional bugfix. These fixes may not require a reboot. Reboots are required for a system version change, if too many processes need restarting, there is configuration in the GISO to apply or if the bugfix is marked as requiring a reload.
From Cisco IOS XR Release 7.5.1, you can use the Automatic Install of Bridging Bug Fix RPMs feature to install any bridging bug fix RPMs that are prerequisite for a system upgrade or a downgrade.
You need to add the required Bridging Bug Fix RPMs into the customized ISO built using Cisco Golden ISO (GISO) build script gisobuild.py , by going through the steps in Build a Golden ISO. Ensure that you add the required bridging bug fix RPMs into your Golden ISO. The GISO can include bridging Bug Fix RPMs for multiple releases, and installs only the specific bridging Bug Fix RPMs required for the target release. The bridging bug fix RPMs can be used in the following scenarios:
-
To resolve a bug that might stop upgrade.
-
The latest version has new prerequisite requirements that are not met by the earlier version.
The install replace command adds and applies the highest version of any bridging bugfix RPMs for the currently active XR version.
Cisco IOS XR Software Release 7.5.1 introduces iso-config [ignore | replace] keywords to the install replace and install package replace commands. Before this release, the configuration file in GISO is ignored by default. If the GISO has a configuration file and it is not ignored using the iso-config ignore option, then the configuration in the file is applied, and the install operation requires a reboot. With the iso-config keyword, the default value is set to replace to replace the running configuration with the configuration in the file.
You can extract the configuration file from GISO using image.py
script that is embedded in the ISO. This script interprets the GISO, and serves as an API to the ISO content at the filesystem level. The extracted configuration file replaces the running configuration after the router reloads.
Scenario | iso-config replace | iso-config ignore | Nothing Specified |
---|---|---|---|
Configuration is present in GISO | Extracts the configuration and replaces the running configuration after the changes are applied via router reload. The output of the show install log command displays | Does not extract or apply the configuration. The output of the show install log command does not display any information that is related to the configuration. | Extracts the configuration and replaces the running configuration after the changes are applied via router reload. The behavior is similar to iso-config replace operation. |
Configuration is not present in GISO | Attempts to extract the configuration, and the operation continues as if configuration is not requested. The output of the show install log command displays | Does not extract or apply the configuration. The output of the show install log command does not display any information that is related to the configuration. | Attempts to extract the configuration, and the operation continues as if configuration is not requested. The behavior is similar to iso-config replace operation. |
Configuration extraction is not supported in target GISO (downgrade) | Attempts to extract the configuration, and the operation continues as if configuration is not requested. The output of the show install log command does not display any information that is related to the configuration. | Does not extract or apply the configuration. The output of the show install log command does not display any information that is related to the configuration. | Attempts to extract the configuration, and the operation continues as if configuration is not requested. The behavior is similar to iso-config replace operation. |
Configuration is supported but the extraction fails | Attempts to extract the configuration. But the operation fails with error | Does not extract or apply the configuration. The output of the show install log command does not display any information related to the configuration. | The behavior is similar to iso-config replace operation. |
Procedure
Step1 | Copy the ISO (or GISO) image to the | ||
Step2 | Upgrade the system to replace the current software with the .iso image. Example: | ||
Step3 | Activate the new .iso image on the router by applying the changes. Example: If you are using a configuration file in GISO, use the install apply reload command for the configuration to take effect.
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 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 cancel it with the install package abort all-since-apply command. | ||
Step4 | View the install log. Example: If configuration file is present in GISO, the output shows that the replace operation for ISO configuration is requested. | ||
Step5 | Verify that the image is activated successfully. Example: | ||
Step6 | Commit the transaction. Example:
|
Upgrade the System and Install RPMs
.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 are 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
Step1 | Copy the ISO (or GISO) image to the | ||||
Step2 | Upgrade the system to replace the current software with the .iso image. Example: | ||||
Step3 | Install other RPMs (packages) after the system upgrade operation.
| ||||
Step4 | Check the status of install operation. Example:
State changes to Success , activate the new image.
| ||||
Step5 | Activate the new .iso image or RPM on the router by applying the changes. Example: 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 | ||||
Step6 | Verify the image and packages that are activated as part of Example: | ||||
Step7 | Commit the transaction. Example: install-package-replace RPC on the Cisco-IOS-XR-install-augmented-act data model.
|
Upgrade QDD Optical Modules Through CLI
The QDD optics firmware file needs to be copied to the router manually. Contact Cisco Support to check the QDD firmware version, IOS XR release compatibility, and to obtain the QDD optics firmware file.
Limitation: When ports share a common management interface, IOS XR serializes the firmware upgrade. Serializing and deserializing may delay the upgrade process.
Procedure
Step1 | From the router, copy the QDD firmware file to the hard disk using the following command: Example:
|
Step2 | Run the following commands to upgrade the FPD for QDD optical modules: Multiport upgrade: Single port upgrade: You can check the firmware upgrade progress using the following command: |
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. The source file can be a repository name, repository url, local filepath, or path to a tar file.
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. |
This example shows the options to install the optional package xr-telnet-7.0.1v1.0.1-1.x86_64.rpm
.
Before you begin
If you are installing the packages from a local directory, ensure that the TAR file ncs540l-iosxr-7.0.1.tar
is copied to the harddisk:/ on the router. If you are installing the packages from an RPM repository, ensure you have configured the repository. For more information, see Create Repository to Access Files for Installing IOS XR Software.
Procedure
Step1 | Install one or more optional packages using one of the following options:
install RPC on the Cisco-IOS-XR-install-act data model. Here is an example with an HTTP repository:
| ||
Step2 | Commit the operation. Example: | ||
Step3 | Check the status of install operation. Example: |
Delete Optional Packages
You can remove optional packages 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
Step1 | Remove the optional package. Example: | ||
Step2 | Apply the changes to make the change active. Example:
| ||
Step3 | Commit the changes to make the change persistent after a reload operation. Example: |
Installing the Image Over the Network
Feature Name | Release Information | Feature Description |
---|---|---|
Support for loading an image over the network | Release 7.4.1 | There is no longer a need to copy an ISO image on the router to install XR7. Starting with this release, you can fetch an ISO or tar file of RPMs over the network as part of Install operation. You can also directly install the image from an FTP or HTTP server that hosts the image. The install source can also be a URL to a tar file (a file with extensions, .tar, .tgz, or .tar.gz). This feature modifies the following commands:
|
The following commands include the ftp and http keywords to enable you to install an ISO image stored at the specified FTP or HTTP server.
-
The install replace command is used to install an ISO image and apply this new installation.
Note
This command requires a manual reload of the system.
RP/0/RP0/CPU0:ios#install replace ?WORD Full local path to ISO - must be located in or under /var/xr/disk1/, /harddisk:/, or /misc/disk1/ftp: Remote ISO ftp://<server>[;<vrf>]/<remote_path>http: Remote ISO http://<server>[;<vrf>]/<remote_path>
-
The install package replace command is used to install an ISO image; however, it does not automatically apply the software change.
RP/0/RP0/CPU0:ios#install package replace ? WORD Full local path to ISO - must be located in or under /var/xr/disk1/, /harddisk:/, or /misc/disk1/ ftp: Remote ISO ftp://<server>[;<vrf>]/<remote_path> http: Remote ISO http://<server>[;<vrf>]/<remote_path>
-
The install source command is used to install and apply packages from a specified source. Effective Cisco IOS XR Release 7.4.1, you can use this command to install packages from a tarball located on a remote FTP or HTTP server.
RP/0/RP0/CPU0:ios#install source ? WORD Configured DNF repository name to use as the source WORD Full path to a local directory to use as the source - must be a subdirectory of /var/xr/disk1/, /harddisk:/, or /misc/disk1/ WORD Full path to a local tar file to use as the source - must be located in or under /var/xr/disk1/, /harddisk:/, or /misc/disk1/ any-configured Use any configured repository to obtain packages ftp: Remote repo or tar file ftp://<server>[;<vrf>]/<remote_path> http: Remote repo or tar file http://<server>[;<vrf>]/<remote_path>
-
The install package add source command is used to install packages; however, it does not automatically apply them. Effective Cisco IOS XR Release 7.4.1, you can use this command to install packages from a tarball located on a remote FTP or HTTP server.
Additional Install Operations
After you upgrade your system, based on your requirement, you can perform 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
Step1 | View the version of the Cisco IOS XR software, and its various software components that are installed on the router. Example:
Label field in the GISO image:
You can also use the |
Step2 | View the active packages. Example: You can also use the To understand the data model structure and its arguments, see the Obtain Data Models for Install Operation topic. |
Build a Golden ISO
Feature Name | Release Information | Description |
---|---|---|
Build Golden ISO (GISO) Using | Release 7.6.1 | This feature allows you to build your GISO image without support from Cisco. You can now select the install files, add your RPMs, repackage them as a custom image, and install the image. In previous releases, you had to contact Cisco to get your GISO built. |
Golden ISO (ISO) upgrades the router to a version that has a predefined set of RPMs with a single operation. For example, you can create a customized ISO with the base OS package and specific optional RPMs based on your network requirements.
GISO supports automatic dependency management, and provides these functionalities:
-
Builds RPM database of all the packages present in package repository.
-
Skips and removes Cisco RPMs that do not match the base ISO version.
-
Skips and removes third-party RPMs that are not part of already existing third-party base package in the base ISO.
![]() Note | Install operation over IPv6 is not supported. |
Procedure
Step1 | Contact Cisco Support to build the GISO image with the set of packages based on your requirement. | ||
Step2 | Build GISO image using To build GISO, provide the following input parameters to the script:
| ||
Step3 | Copy the GISO image to the | ||
Step4 | Upgrade the system to replace the current software with the <platform-architecture>.iso image, and install the RPMs. Example:
| ||
Step5 | View the version information for the GISO image. You can include a label to indicate the runing software version on the router. For example, create a label v1 for the current GISO version. When you rebuild GISO with additional RPMs, you can create a label v2 to distinguish the builds. Example: |
Upgrade the System Using the IOS XR Configuration File in GISO
Feature Name | Release Information | Description |
---|---|---|
Upgrade the system using the IOS XR configuration file in GISO | Release 7.5.2 | This feature identifies and extracts the required IOS XR configuration file in GISO, and automates the updation of IOS XR configuration files when the router is reloaded with the new GISO. This feature introduces iso-config [ignore | replace] keywords to the install replace and install package replace commands. |
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 or GISO image. Only a minimal set of changes is performed to upgrade to the new software. Packages are not removed and reinstalled if they have the same name and version. For example, an upgrade that differs by only one package, removes and install only that one modified package.
![]() Note | Even if the configuration file is bundled in a GISO, the file is not used during an upgrade of the system to Cisco IOS XR Software Release 7.5.2. When first moving the system to release 7.5.2, the configuration file is only used when the system is completely reimaged in case of disaster recovery. Upgrades from release 7.5.2 to a GISO based off release 7.5.2 (or a higher version) uses the configuration file if it is present in the GISO. |
![]() Note | The instructions in this section also apply to system downgrade. |
This section shows replacing the current software version with .iso
image.
In this scenario, you replace the current software with image, apply the changes, and commit the install operation. Committing the changes indicates the end of the current transaction. The updated software is used after the changes are applied, before the install transaction is committed.
A reboot is not always necessary. Bugfixes can be applied using a GISO that contains the current running software and the additional bugfix. These fixes may not require a reboot. Reboots are required for a system version change, if too many processes need restarting, there is configuration in the GISO to apply or if the bugfix is marked as requiring a reload.
![]() Note | The ztp.ini is an initialization file for ZTP that is provided when building a golden ISO (GISO). This file defines the GISO ZTP configuration. If the |
If you start an install replace or install package replace operation with a GISO that has a ztp.ini file, the GISO ZTP configuration is updated on both RPs when the operation is applied. To undo this install operation and also the change in GISO ZTP configuration, use install package abort command. If you replace the image using an ISO without a ztp.ini file, the GISO ZTP configuration is removed from both RPs, if it exists, when the operation is applied.
Cisco IOS XR Software Release 7.5.2 introduces iso-config [ignore | replace] keywords to the install replace and install package replace commands. Before this release, the configuration file in GISO is ignored by default. If the GISO has a configuration file and it is not ignored using the iso-config ignore option, then the configuration in the file is applied, and the install operation requires a reboot. With the iso-config keyword, the default value is set to replace to replace the running configuration with the configuration in the file.
You can extract the configuration file from GISO using image.py
script that is embedded in the ISO. This script interprets the GISO, and serves as an API to the ISO content at the filesystem level. The extracted configuration file replaces the running configuration after the router reloads.
Scenario | iso-config replace | iso-config ignore | Nothing Specified |
---|---|---|---|
Configuration is present in GISO | Extracts the configuration and replaces the running configuration after the changes are applied via router reload. The output of the show install log command displays | Does not extract or apply the configuration. The output of the show install log command does not display any information related to the configuration. | Extracts the configuration and replaces the running configuration after the changes are applied via router reload. The behavior is similar to iso-config replace operation. |
Configuration is not present in GISO | Attempts to extract the configuration, and the operation continues as if configuration is not requested. The output of the show install log command displays | Does not extract or apply the configuration. The output of the show install log command does not display any information related to the configuration. | Attempts to extract the configuration, and the operation continues as if configuration is not requested. The behavior is similar to iso-config replace operation. |
Configuration extraction is not supported in target GISO (downgrade) | Attempts to extract the configuration, and the operation continues as if configuration is not requested. The output of the show install log command does not display any information related to the configuration. | Does not extract or apply the configuration. The output of the show install log command does not display any information related to the configuration. | Attempts to extract the configuration, and the operation continues as if configuration is not requested. The behavior is similar to iso-config replace operation. |
Configuration is supported but the extraction fails | Attempts to extract the configuration. But the operation fails with error | Does not extract or apply the configuration. The output of the show install log command does not display any information related to the configuration. | The behavior is similar to iso-config replace operation. |
Procedure
Step1 | Copy the ISO (or GISO) image to the | ||
Step2 | Upgrade the system to replace the current software with the .iso image. Example: | ||
Step3 | Activate the new .iso image on the router by applying the changes. Example: If you are using a configuration file in GISO, use the install apply reload command for the configuration to take effect.
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 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 cancel it with the install package abort all-since-apply command. | ||
Step4 | View the install log. Example: If configuration file is present in GISO, the output shows that the replace operation for ISO configuration is requested. | ||
Step5 | Verify that the image is activated successfully. Example: | ||
Step6 | Commit the transaction. Example:
|
Upgrade the System to Obtain Bug Fixes
Feature Name | Release Information | Description |
---|---|---|
Install Cisco RPM Directly from TAR File | Release 7.3.1 | Cisco RPMs can be installed from one of these sources - repository name, repository URL or a local file path. Previously, to install RPMs from a TAR file, you had to manually extract the TAR file and specify the path to the locally extracted file to install the RPM. This feature extends support to install the RPM directly from the TAR file. Bug fix RPMs are available as TAR files on the Software Download page. The RPMs can be installed from the TAR file using CLI or Yang data model. |
You can upgrade the system to obtain all available bug fixes or choose specific bug fix using bug ID.
Bug fixes are available as optional RPMs. The bug fixes replace packages in the base ISO without adding up to the image size. For example, even if you add 20 RPMs to the GISO, the GISO file size will remain the same as the initial ISO.
You can download the bug fix RPMs from the Cisco Software Download portal .
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.
The following image shows the options to install the bug fix RPMs.
The software is split into modular blocks and the package manager infrastructure computes the dependencies between the blocks. Each block of software has a top-level package and various partition-level packages. Bug fixes that span multiple blocks may lead to creating multiple dependent packages that are built as part of earlier bug fixes.
![]() Note | We recommend that you leverage the GISO workflow. Contact Cisco Support to build a new GISO with the required bug fixes. The RPMs are present in the initrd, which is the initial RAM disk for the boot loader, and this requires that the package is signed by Cisco. You can install GISO using a single |
However, if you do not prefer using the GISO, here are a few alternative ways to install bug fixes:
-
Create a bug fix tarball to contain all the dependent packages. The tarball may be reasonably large for bug fixes that span mulitple blocks, but you can use this single tarball file directly to install the bug fixes without the need to check the individual packages within the file. You can also create a tarball containing all the dependent packages manually, but this method does not scale well.
-
Create tarballs to install one or more bug fixes. For example, if you are installing bug fixes CSCxx11111, CSCyy22222 and CSCzz33333, you can use the individual tarball files and create a single tarball file.
-
Use a Dandified Yum- or DNF repository to install, update, or remove relevant bug fixes. See, Create Repository to Access Files for Installing IOS XR Software.
![]() Note |
|
![]() Note | Use the RPM repository to harvest the benefits of package manager. The package manager queries the available packages, and downloads only those packages and their dependencies that are needed for installation. |
Procedure
Step1 | View the list of available bug fixes. Example: | ||||||
Step2 | Install the bug fix or package using one of the following options:
| ||||||
Step3 | View the state of the packaging operation. Example: | ||||||
Step4 | View the log to ensure that the installation is successful. Example: | ||||||
Step5 | View the history of the install operation. Example: The command can also be used to view more details if there is a failed operation. <transaction id>.<atomic id>.<packaging id> .
| ||||||
Step6 | After the operation is complete, verify that the packages Example: Example:Example: The version has changed. The version This task can also be accomplished using data models. Use the | ||||||
Step7 | Commit the changes for the changes to persist after a reload operation. Example: | ||||||
Step8 | View the list of bug IDs for which fixes are committed. Example: This task can also be accomplished using data models. Use the | ||||||
Step9 | View the list of active bug fix RPMs. Example: This task can also be accomplished using data models. Use the |
Downgrade to a Previously Installed Package
![]() 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. |
Before you begin
Procedure
Step1 | Downgrade the package using one of the following options:
| ||||
Step2 | Commit the operation. Example: |
Roll Back Software to a Previously Saved Installation Point
![]() Note | This section does not apply to the following variants of the Cisco NCS 540 routers:
|
Feature Name | Release Information | Feature Description |
---|---|---|
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. The following NCS 540 variants allow up to 900MB of disk space for rollback points:
This feature introduces the following commands:
The following command is updated to include the keyword, oldest n :
|
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. Up to 900MB of space is allowed for rollback points, instead of a specific number of rollback points.
![]() Note |
|
Procedure
Step1 | View the list of available transaction IDs. Example: | ||
Step2 | Explore the main packages that can be installed if you roll the software back to the specific transaction ID. Example: | ||
Step3 | View the relative changes that are made to the currently installed software if it is rolled back to a transaction ID. Example: To perform these tasks using data models, use the | ||
Step4 | Roll back to the software associated with the specific transaction ID. Example: If you want to apply the change and roll back to the associated transaction ID, commit the change. You can also include the keyword
To perform this task using data models, use the To understand the data model structure and its arguments, see the Access the Install-Related Data Model. | ||
Step5 | Commit the operation. Example: |
Telemetry Support for Install Operations
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 NCS 540 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. |
| ||
Summary of committed packages | Data is streamed after a successful commit operation. A package that is committed remains active following a system reload. |
| ||
Status of the last request operation | Data is streamed when starting a new request and also when entering an |
| ||
Image version and GISO label | Data is streamed after a successful apply operation. |
| ||
Packaging information | Data is streamed at the start and end of a packaging operation. |
| ||
Atomic information | Data is streamed at the start and end of apply operation. |
| ||
Transaction information | Data is streamed at the start, in progress, and end of a commit operation.
|
|
Caveats
Release 7.10.1
The following upgrade caveats are applicable for Cisco NCS 540 Series Routers listed in the Cisco NCS 540 Series Router and PIDs table for Release 7.10.1 and later.
From | To | Bridge SMUs Required (CSCwd71524) | Caveats |
---|---|---|---|
7.3.2 | 7.10.1 and later | Yes | 1*,2*,3* |
7.5.2 | 7.10.1 and later | Yes | 1*,2*,4* |
7.6.1 | 7.10.1 and later | Yes | 1*,2*,4* |
7.6.2 | 7.10.1 and later | None | 1* |
7.7.1 | 7.10.1 and later | None | 1* |
7.7.2 | 7.10.1 and later | None | 1* |
7.8.1 | 7.10.1 and later | None | 1* |
7.8.2 | 7.10.1 and later | None | 1* |
7.9.1 | 7.10.1 and later | None | 1* |
7.9.2 | 7.10.1 and later | None | 1* |
1*: You can't roll back using the install rollback command.
2*: Ensure that a reload bridging SMU (CSCwd71524) is installed.
3*: Ensure that you install the bridge SMU (CSCwd71524) manually because even if it's available inside the GISO that's replacing the existing GISO, this SMU doesn't get installed automatically.
4*: It’s applicable to the Small Density Routers listed in the Cisco NCS 540 Series Router and PIDs table. Before replacing GISO, ensure that you install the bridge SMU (CSCwd71524) manually.
![]() Note | CSCwd71524:
|
The following downgrade caveats are applicable for Cisco NCS 540 Series Routers listed in the Cisco NCS 540 Series Router and PIDs table for Release 7.10.1 and later.
From | To | Target SMUs Required (CSCwd71524) | Caveats |
---|---|---|---|
7.10.1 and later | 7.3.2 | Yes | C* |
7.10.1 and later | 7.5.2 | Yes | ***, A*, B*, D* |
7.10.1 and later | 7.6.1 | Yes | ***, A*, B*, D* |
7.10.1 and later | 7.6.2 | Yes | ***, A*, B* , D* |
7.10.1 and later | 7.7.1 | Yes | ***, A*, B*, D* |
7.10.1 and later | 7.7.2 | Yes | ***, A*, B*, D* |
7.10.1 and later | 7.8.1 | Yes | ***, A*, B*, D* |
7.10.1 and later | 7.8.2 | Yes | ***, A*, B*, D* |
7.10.1 and later | 7.9.1 | Yes | ***, D* |
7.10.1 and later | 7.9.2 | Yes | ***, D* |
***
-
You don't need to run the install commit command after a downgrade operation because the operation is automatically committed.
-
You can't roll back after a downgrade. To revert to the previous IOS XR previous version, replace or reimage to the relevant ISO.
-
IOS XR configuration history is lost after a downgrade, but the router preserves the latest configuration.
-
Install history from the last transaction is preserved after a downgrade operation.
-
Downtime takes a longer time as the operation is performed through reimage.
-
You can't downgrade using the install package replace command. Instead, use the install replace command to downgrade.
-
Ensure that you reinstall third-party application once you complete the downgrade.
-
Ensure that you disable reimage-protection feature before performing downgrade because the downgrade occurs through a reimage. You can disable the reimage-protection using the platform security reimage-protection disable command.
Note
The reimage-protection feature applies to the Cisco NCS 540 Series Routers listed in the Cisco NCS 540 Series Router and PIDs table.
-
PXE recovery is required if the image downgrading isn’t bootable.
-
You must re-install the Type 6 masterkey and reapply the configuration encrypted by it because they are lost after the downgrade.
-
You must regenerate crypto keys and certificates after a downgrade.
A*: You can't downgrade to the base ISO. You can downgrade to a GISO containing the bridge SMU (CSCwd71524).
B*: You must recover the router through PXE if a power cycle occurs during the downgrade.
C*: One-step downgrade isn’t supported. You must use either PXE/USB to downgrade or perform a two-step downgrade through Release 7.9.1 or Release 7.5.4. The first-hop downgrade to Release 7.9.1 or Release 7.5.4 still carries the same caveats.
D*: FPD upgrade may cause your router to reload an extra time during boot-up.
E*: Traffic is impacted.
Use the show install upgrade-matrix running command to view the caveats.