Installation using Golden ISO
Golden ISO (GISO) is a
customized ISO that a user can build to suit the installation requirement. The
user can customize the installable image to include the standard base image
with the basic functional components, and add additional RPMs, SMUs and
configuration files based on requirement.
The ease of
installation and the time taken to seamlessly install or upgrade a system plays
a vital role in a cloud-scale network. An installation process that is
time-consuming and complex affects the resiliency and scale of the network. The
GISO simplifies the installation process, automates the installation workflow,
and manages the dependencies in RPMs and SMUs automatically.
GISO is built using a
gisobuild.py available on the box in
/pkg/bin location in XR domain. For more information
about the build script and the steps to build GISO, see
Build Golden ISO.
When a system boots
with GISO, additional SMUs and RPMs in GISO are installed automatically, and
the router is pre-configured with the XR configuration in GISO. For more
information about downloading and installing GISO, see
Install Golden ISO.
The capabilities of
GISO can be used in the following scenarios:
Migration from IOS
XR 32-bit to IOS XR 64-bit
of the router
from one base version to another
System upgrade from same base version but with additional SMUs
Install update to
identify and update dependant packages
The following are
the known problems and limitations with the customized ISO:
booting GISO for asynchronous package (a package of different release than the
ISO) is not supported.
gisobuild.py does not support verifying the XR
Renaming a GISO
build and then installing from the renamed GISO build is not supported.
The following image
shows the workflow for building and installing golden ISO.
The customized ISO
is built using Cisco Golden ISO (GISO) build script
gisobuild.py available on the box in
/pkg/bin location in XR domain.
The GISO build
script supports automatic dependency management, and provides these
To build GISO,
provide the following input parameters to the script:
database of all the packages present in package repository.
removes Cisco RPMs that do not match the mini-x.iso version.
removes third-party RPMs that are not SMUs of already existing third-party base
package in mini-x.iso.
error and exits build process if there are multiple base RPMs of same release
but different versions.
Performs compatibility check and dependency check for all the RPMs. For example, the child RPM
is dependent on the parent RPM
. If only the child RPM is included, the Golden ISO build fails.
configuration file (optional)
one or more
Cisco-specific SMUs for host, XR and System admin
one or more
third-party SMUs for host, XR and System admin
Label for golden
Use the following
naming convention when building GISO:
Golden ISO can
be built only from mini ISO. The full or fullk9 bundle ISO is not supported.
without k9sec RPM
with k9sec RPM
successfully add k9sec RPM to GISO, change the permission of the file to
644 using the
chmod 644 [k9 sec rpm]
To build GISO,
perform the following steps:
Before You Begin
To upgrade from non-GISO to GISO version, it is mandatory to first upgrade to mini ISO with GISO support.
The system where GISO is built must meet the following requirements:
System must have Python version 2.7 and later.
System must have free disk space of minimum 3 to 4 GB.
Verify that the Linux utilities mount, rm, cp, umount, zcat, chroot, mkisofs are present in the system. These utilities will be used by the script. Ensure privileges are available to execute all of these Linux commands.
Kernel version of the system must be later than 3.16 or later than the version of kernel of Cisco ISO.
Verify that a libyaml rpm supported by the Linux kernel is available to successfully import yaml in the tool.
User should have proper permission for security rpm(k9sec-rpm) in rpm repository, else security rpm would be ignored for Golden ISO creation.
The system from where the gisobuild script is executed must have root credentials.
||From the XR
prompt, find the directory path of the build script
Router# run ls -l /pkg/bin | grep giso
gisobuild.py from the router to an offline system or
external server where the GISO will be built. Ensure that this system meets the
pre-requisites described above in the
- Go to shell prompt of IOS XR and copy the script gisobuild.py to harddisk:
Mon Jul 10 13:14:43.606 UTC
[Router]$cp /pkg/bin/gisobuild.py /harddisk\:/
- Go to EXEC mode of IOS XR and check the script gisobuild.py in harddisk:
Router#dir harddisk:/ | inc gisobuild.py
Mon Jul 10 13:15:20.542 UTC
13 -rwxr-xr-x 1 77203 Jul 10 13:14 gisobuild.py
- Copy the script gisobuild.py from harddisk:/ to any desired location (outside the router where ISO will be built) that is supported. Use any of the supported protocol.
Router#copy harddisk:/ ?
WORD Copy to file
apphost: Copy to apphost: file system
config: Copy to config: file system
disk0: Copy to disk0: file system
ftp: Copy to ftp: file system
harddisk: Copy to harddisk: file system
http: Copy to http: file system
https: Copy to https: file system
location location to copy from
rootfs: Copy to rootfs: file system
running-config Update (merge with) current system configuration
tftp: Copy to tftp: file system
The following example shows the script copied from one harddisk to another with a new name gisobuild_new.py:
Router#copy harddisk:/gisobuild.py harddisk:/gisobuild_new.py
Mon Jul 10 13:19:28.912 UTC
Destination filename [/harddisk:/gisobuild_new.py]?
77203 bytes copied in 0 sec
Router#dir harddisk:/ | inc gisobuild_new.py
Mon Jul 10 13:19:48.557 UTC
14 -rwxr-xr-x 1 77203 Jul 10 13:19 gisobuild_new.py
|| Run the script gisobuild.py as a root user and provide parameters to build the golden ISO off the router. Ensure that all RPMs and SMUs are present in the same directory. The number of RPMs and SMUs that can be used to build the Golden ISO is 128.
The -i option is mandatory, and either or both -r or -c options must be provided.
-i is the path to mini-x.iso
-r is the path to RPM repository
-c is the path to XR config file
-l is the golden ISO label
-h shows the help message
-v is the version of the build tool gisobuild.py
-m is to build the migration tar to migrate from IOS XR to IOS XR 64 bit
GISO is built with the RPMs placed in respective folders in the specified directory and also includes the log files giso_summary.txt and gisobuild.log-<timestamp>. The XR configuration file is placed as router.cfg in the directory.
What to Do Next
The GISO script
does not support verification of XR configuration.
Install the golden
ISO on the router.
Golden ISO (GISO)
automatically performs the following actions:
and system admin RPMs.
repository and TFTP boot on RP.
profile in system admin and XR modes.
active command to see the list of RPMs.
running-config command in XR mode to verify.
|| Download GISO
image to the router using one of the following options:
- PXE boot: when the router is booted, the boot mode is identified. After detecting PXE as boot mode, all available ethernet interfaces are brought up, and DHClient is run on each interface. DHClient script parses HTTP or TFTP protocol, and GISO is downloaded to the box.
- System Upgrade when the
system is upgraded, GISO can be installed using
activate, or using
system upgrade from a non-GISO (image that does not support
GISO) to GISO image: If a system is running a version1 with an image that
does not support GISO, the system cannot be upgraded directly to version2 of an
image that supports GISO. Instead, the version1 must be upgraded to version2
mini ISO, and then to version2 GISO.
system upgrade in a release from version1 GISO to version2 GISO: If both the GISO images have the same base version but different labels, install add and install activate commands does not support same version of two images. Instead, using install update command installs only the delta RPMs. System reload is based on restart type of the delta RPMs.
system upgrade across releases from version1 GISO to version2 GISO: Both the GISO images have different base versions. Use install add and install activate commands, or install update command to perform the system upgrade. The router reloads after the upgrade with the version2 GISO image.
show install repository
all command in System Admin mode to view the RPMs and base ISO
for host, system admin and XR.
show install package
<golden-iso> command to display the list of RPMs, and
packages built in GISO.
The ISO, SMUs and packages
in GISO are installed on the router.