Cisco 8000 software manageability: Golden ISO (GISO)

13 minutes read


This tutorial will describe and illustrate how to generate a Golden ISO (GISO) image for Cisco 8000 routers. GISO can be used to stage, re-image, patch or upgrade Cisco 8000 routers.

Info: can only be used to generate 7.5.1+ images. If a pre 7.5.1 image is needed, please get in touch with TAC to generate it for you.

Software Lifecycle in a Router


It’s common to see different phases for production devices:

  • Software staging: initial router staging and deployment, first installation with qualified software.
  • Software patching: router runs same version of code, SMUs are installed to fix software defects, improve stability and reliability or patch security vulnerabilities.
  • Software upgrade: major software upgrade to new qualified version of code. Driven by new requirements (hardware, features) or software obsolescence (End Of Life).

Patching and upgrade frequency depends on operators’ software strategy.

For staging, turboboot was traditionally used for IOS-XR 32-bit (using TFTP or USB). Once staged, packages and SMUs had to be installed (triggering a second reload) and then target configuration committed.

For software patching, the usual 3-step install add, activate and commit was used to add SMUs or new packages (such MPLS, Multicast, FPD).

For software upgrades, same 3-step process was executed. Target release, packages and SMUs could be added and activated in one-shot.

The challenge is multiple processes, involving different files had to be employed. Moreover, in some cases two reboots were required to reach software target, adding more time to operations.

Golden ISO concept & use cases

Golden ISO concept was introduced with IOS-XR 64bit and extended to IOS-XR7 architecture which is used by Cisco 8000.

Golden ISO (GISO) is a self-custom-built ISO addressing customers’ needs. It contains:

  • Mandatory base image (ISO format)
  • Optional files/packages
    • optional packages
      • Some optional packages are contained within the base image, e.g: BGP
      • Additional optional packages are available on CCO, e.g: cdp, telnet, healthcheck
    • SMUs
    • ZTP config
    • XR config

Golden ISO is built with gisobuild, a Cisco provided tool available on GitHub. Files generated by gisobuild can be used for the 3 operations mentioned earlier and covers following use cases:

  • Router staging, or re-imaging (USB boot, PXE boot techniques)
  • Software upgrade (install replace technique)
  • Software patching (install replace technique)

Rest of this post will focus on how-to deploy gisobuild and how to use it to create a GISO.

Server Preparation

For this article and at the time of writing, a Debian 11.3 server is used. It’s important to respect supported Linux distributions as stated in gisobuild GitHub documentation.

cisco@debian-template:~$ lsb_release -a
No LSB modules are available.
Distributor ID:	Debian
Description:	Debian GNU/Linux 11 (bullseye)
Release:	11
Codename:	bullseye

The first step is to clone the repository:

cisco@debian-template:~$ git clone
Cloning into 'gisobuild'...
remote: Enumerating objects: 289, done.
remote: Counting objects: 100% (181/181), done.
remote: Compressing objects: 100% (117/117), done.
remote: Total 289 (delta 94), reused 144 (delta 63), pack-reused 108
Receiving objects: 100% (289/289), 6.06 MiB | 12.93 MiB/s, done.
Resolving deltas: 100% (155/155), done.

Linux and Python dependencies are required to use the various tools. If the server has access to podman and the docker repositories, then the gisobuild tool can be run within a container using the –docker option. However, if the other tooling (isols & isodiff) is required, or the server does not have access to docker, then the additional dependencies now need to be set up. The script located in the setup directory contains everything needs and is used here:

cisco@debian-template:~/gisobuild/setup$ sudo ./
Get:1 bullseye-security InRelease [48.4 kB]
Hit:2 bullseye InRelease
Get:3 bullseye-updates InRelease [44.1 kB]
Get:4 bullseye-updates/main Sources.diff/Index [9483 B]
Get:5 bullseye-updates/main amd64 Packages.diff/Index [9483 B]
Get:6 bullseye-updates/main Sources T-2022-08-18-2019.35-F-2022-08-18-2019.35.pdiff [390 B]
Get:6 bullseye-updates/main Sources T-2022-08-18-2019.35-F-2022-08-18-2019.35.pdiff [390 B]
Get:7 bullseye-updates/main amd64 Packages T-2022-08-18-2019.35-F-2022-08-18-2019.35.pdiff [284 B]
Get:7 bullseye-updates/main amd64 Packages T-2022-08-18-2019.35-F-2022-08-18-2019.35.pdiff [284 B]
Get:8 bullseye-security/main Sources [150 kB]
Get:9 bullseye-security/main amd64 Packages [180 kB]
Get:10 bullseye-security/main Translation-en [113 kB]
Fetched 555 kB in 4s (139 kB/s)
Reading package lists... Done
Reading package lists... Done
Building dependency tree... Done
Reading state information... Done
cpio is already the newest version (2.13+dfsg-4).
openssl is already the newest version (1.1.1n-0+deb11u3).
openssl set to manually installed.
python3 is already the newest version (3.9.2-3).
python3 set to manually installed.
python3-distutils is already the newest version (3.9.2-1).
python3-distutils set to manually installed.
python3-yaml is already the newest version (5.3.1-5).
python3-yaml set to manually installed.
The following additional packages will be installed:
  debugedit libarchive13 libcreaterepo-c0 libcurl4 libdrpm0 libdw1 libgomp1 liblua5.2-0 liblzo2-2 libmagic-mgc libmagic1 libmodulemd2 librpm9 librpmbuild9 librpmio9 librpmsign9 libzck1
  python3-pyparsing rpm-common rpm2cpio
Suggested packages:
  rpm-i18n wodim cdrkit-doc lrzip python-pyparsing-doc alien elfutils rpmlint rpm2html
The following NEW packages will be installed:
  createrepo-c debugedit file genisoimage libarchive13 libcreaterepo-c0 libcurl4 libdrpm0 libdw1 libgomp1 liblua5.2-0 liblzo2-2 libmagic-mgc libmagic1 libmodulemd2 librpm9 librpmbuild9
  librpmio9 librpmsign9 libzck1 python3-defusedxml python3-packaging python3-pyparsing python3-rpm rpm rpm-common rpm2cpio squashfs-tools
0 upgraded, 28 newly installed, 0 to remove and 9 not upgraded.
Need to get 16.3 MB of archives.
After this operation, 29.7 MB of additional disk space will be used.
Get:1 bullseye-security/main amd64 libcurl4 amd64 7.74.0-1.3+deb11u2 [345 kB]
Get:2 bullseye/main amd64 libmagic-mgc amd64 1:5.39-3 [273 kB]
-- Snip --
Fetched 16.3 MB in 4s (4448 kB/s)
perl: warning: Setting locale failed.
perl: warning: Please check that your locale settings:
	LANGUAGE = (unset),
	LC_ALL = (unset),
	LC_CTYPE = "UTF-8",
	LC_TERMINAL = "iTerm2",
	LANG = "en_US"
    are supported and installed on your system.
perl: warning: Falling back to a fallback locale ("en_US").
locale: Cannot set LC_CTYPE to default locale: No such file or directory
locale: Cannot set LC_ALL to default locale: No such file or directory
Selecting previously unselected package libmagic-mgc.
(Reading database ... 31728 files and directories currently installed.)
Preparing to unpack .../00-libmagic-mgc_1%3a5.39-3_amd64.deb ...
Unpacking libmagic-mgc (1:5.39-3) ...
-- Snip --
Selecting previously unselected package squashfs-tools.
Preparing to unpack .../27-squashfs-tools_1%3a4.4-2+deb11u2_amd64.deb ...
Unpacking squashfs-tools (1:4.4-2+deb11u2) ...
Setting up libdw1:amd64 (0.183-1) ...
-- Snip --
Setting up python3-rpm ( ...
Processing triggers for libc-bin (2.31-13+deb11u3) ...

After this step, is available to use:

cisco@debian-template:~/gisobuild/src$ ./ --help
usage: [-h] [--iso ISO] [--repo REPO [REPO ...]] [--bridging-fixes BRIDGE_FIXES [BRIDGE_FIXES ...]] [--xrconfig XRCONFIG] [--ztp-ini ZTP_INI] [--label LABEL]
                    [--out-directory OUT_DIRECTORY] [--yamlfile CLI_YAML] [--clean] [--pkglist PKGLIST [PKGLIST ...]] [--script SCRIPT] [--docker] [--x86-only] [--migration]
                    [--remove-packages REMOVE_PACKAGES [REMOVE_PACKAGES ...]] [--skip-usb-image] [--copy-dir COPY_DIRECTORY] [--clear-bridging-fixes] [--verbose-dep-check] [--debug]
                    [--isoinfo ISOINFO] [--image-script IMAGE_SCRIPT] [--version]

Utility to build Golden ISO for IOS-XR.

optional arguments:
  -h, --help            show this help message and exit
  --iso ISO             Path to Mini.iso/Full.iso file
  --repo REPO [REPO ...]
                        Path to RPM repository. For LNT, user can specify .rpm, .tgz, .tar filenames, or directories. RPMs are only used if already included in the ISO, or specified by
                        the user via the --pkglist option.
  --bridging-fixes BRIDGE_FIXES [BRIDGE_FIXES ...]
                        Bridging rpms to package. For EXR, takes from-release or rpm names; for LNT, the user can specify the same file types as for the --repo option.
  --xrconfig XRCONFIG   Path to XR config file
  --ztp-ini ZTP_INI     Path to user ztp ini file
  --label LABEL, -l LABEL
                        Golden ISO Label
  --out-directory OUT_DIRECTORY
                        Output Directory
  --yamlfile CLI_YAML   Cli arguments via yaml
  --clean               Delete output dir before proceeding
  --pkglist PKGLIST [PKGLIST ...]
                        Packages to be added to the output GISO. For eXR: optional rpm or smu to package. For LNT: either full package filenames or package names for user installable
                        packages can be specified. Full package filenames can be specified to choose a particular version of a package, the rest of the block that the package is in will
                        be included as well. Package names can be specified to include optional packages in the output GISO.
  --docker, --use-container
                        Build GISO in container environment.Pulls and run pre-built container image to build GISO.
  --version             Print version of this script and exit

EXR only build options:
  --script SCRIPT       Path to user executable script executed as part of bootup post activate.
  --x86-only            Use only x86_64 rpms even if other architectures are applicable.
  --migration           To build Migration tar only for ASR9k

LNT only build options:
  --remove-packages REMOVE_PACKAGES [REMOVE_PACKAGES ...]
                        Remove RPMs, specified in a comma separated list. These are matched against user installable package names, and must be the whole package name, e.g: xr-bgp
  --skip-usb-image      Do not build the USB image
  --copy-dir COPY_DIRECTORY
                        Copy built artefacts to specified directory if provided. The specified directory must already exist, be writable by the builder and must not contain a previously
                        built artefact with the same name.
                        Remove all bridging bugfixes from the input ISO
  --verbose-dep-check   Verbose output for the dependency check.
  --debug               Output debug logs to console
  --isoinfo ISOINFO     User specified isoinfo executable to use instead of the default version
  --image-script IMAGE_SCRIPT
                        User specified script to be used for packing/unpacking instead of the version extracted from the ISO. It will not be inserted into the GISO. Intended for
                        debugging purposes only.

The tool is common for IOS-XR 64bit (EXR) and IOS-XR7 (LNT) architectures. Remember Cisco 8000 runs IOS-XR7 software architecture, thus this article focuses on IOS-XR7 options and usage.

GISO Creation

For this tutorial, IOS-XR 7.5.2 base release is used (8000-x64-7.5.2.iso).

Info: can only be used to generate 7.5.1+ images. If a pre 7.5.1 image is needed, please get in touch with TAC to generate it for you.

In addition, 4 x SMUs (Software Maintenance Unit) and 2 x optional packages (telnet & cdp) are packaged in the GISO. No XR config nor ZTP config is provided for this example. While no optional packages are removed for this example (–remove-packages option), it’s technically possible to do. Refer to ‘how to add’ and ‘how to remove’ articles for more information about optional packages.

Extra packages are downloaded from Cisco website, TAR files are extracted and .rpm and .tgz files are all placed into the RPM directory:

cisco@debian-template:~/RPM$ ls -l
total 16160
-rw-r--r-- 1 cisco cisco 13594531 Jul 15 14:22 8000-x86_64-7.5.2-CSCvy99756.tgz
-rw-r--r-- 1 cisco cisco   133869 Aug 12 13:20 8000-x86_64-7.5.2-CSCwb65194.tgz
-rw-r--r-- 1 cisco cisco  2104483 Jul 14 16:08 8000-x86_64-7.5.2-CSCwb74098.tgz
-rw-r--r-- 1 cisco cisco   100946 Aug  9 11:32 8000-x86_64-7.5.2-CSCwb91492.tgz
-rw-r--r-- 1 cisco cisco    77813 Aug 31 09:18 xr-cdp-21a020d8b6d1a0b5-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5892 Aug 31 09:18 xr-cdp-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco    10594 Aug 31 09:18 xr-cdp-748523fd2516d420-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5980 Aug 31 09:18 xr-cdp-8101-32h-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5980 Aug 31 09:18 xr-cdp-8102-64h-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5980 Aug 31 09:18 xr-cdp-8111-32eh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5980 Aug 31 09:18 xr-cdp-8201-32fh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5956 Aug 31 09:18 xr-cdp-8201-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5996 Aug 31 09:18 xr-cdp-8202-32fh-m-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5956 Aug 31 09:18 xr-cdp-8202-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     6012 Aug 31 09:18 xr-cdp-8203-88h16fh-m-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5956 Aug 31 09:18 xr-cdp-8212-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5980 Aug 31 09:18 xr-cdp-8608-rp1-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5972 Aug 31 09:18 xr-cdp-88-lc0-34h14fh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5956 Aug 31 09:18 xr-cdp-88-lc0-36fh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5964 Aug 31 09:18 xr-cdp-88-lc0-36fh-m-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5956 Aug 31 09:18 xr-cdp-88-lc1-36eh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5964 Aug 31 09:18 xr-cdp-8800-lc-36fh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5956 Aug 31 09:18 xr-cdp-8800-lc-48h-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5932 Aug 31 09:18 xr-cdp-8800-rp-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco    86327 Aug 31 09:18 xr-cdp-e67eaedb0a19ef6c-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco    11746 Aug 31 09:18 xr-telnet-21a020d8b6d1a0b5-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5916 Aug 31 09:18 xr-telnet-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5968 Aug 31 09:18 xr-telnet-8101-32h-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5968 Aug 31 09:18 xr-telnet-8102-64h-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5972 Aug 31 09:18 xr-telnet-8111-32eh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5972 Aug 31 09:18 xr-telnet-8201-32fh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5944 Aug 31 09:18 xr-telnet-8201-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5988 Aug 31 09:18 xr-telnet-8202-32fh-m-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5944 Aug 31 09:18 xr-telnet-8202-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     6004 Aug 31 09:18 xr-telnet-8203-88h16fh-m-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5944 Aug 31 09:18 xr-telnet-8212-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5968 Aug 31 09:18 xr-telnet-8608-rp1-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5960 Aug 31 09:18 xr-telnet-88-lc0-34h14fh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5944 Aug 31 09:18 xr-telnet-88-lc0-36fh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5956 Aug 31 09:18 xr-telnet-88-lc0-36fh-m-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5944 Aug 31 09:18 xr-telnet-88-lc1-36eh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5948 Aug 31 09:18 xr-telnet-8800-lc-36fh-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5944 Aug 31 09:18 xr-telnet-8800-lc-48h-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco     5964 Aug 31 09:18 xr-telnet-8800-rp-7.5.2v1.0.0-1.x86_64.rpm
-rw-r--r-- 1 cisco cisco   102962 Aug 31 09:18 xr-telnet-e67eaedb0a19ef6c-7.5.2v1.0.0-1.x86_64.rpm

gisobuild help is available on GitHub webpage and with ./ –help command. The simplest command to generate a GISO is to indicate the base ISO location and the folder containing extra packages to install:

cisco@debian-template:~/gisobuild/src$ ./ --iso /home/cisco/8000-x64-7.5.2.iso --repo /home/cisco/RPM --pkglist xr- --clean
Building GISO...
^@^@^@^ --iso /home/cisco/8000-x64-7.5.2.iso --repo /home/cisco/RPM --pkglist xr- --clean
GISO build successful
ISO: /home/cisco/gisobuild/src/output_gisobuild/giso/8000-golden-x86_64-7.5.2-iso.iso
Size: 1.39 GB
USB image: /home/cisco/gisobuild/src/output_gisobuild/giso/
ISO label: iso
Further logs at /home/cisco/gisobuild/src/output_gisobuild/logs/gisobuild.log

Info: the ‘–pkglist xr-‘ argument is used because some packages (telnet and cdp) are being added to the GISO (they were not included in the ISO previously), and this is indicating that any package that starts with “xr-” regex should be included in the list. If only telnet was required, but cdp was present, then –pkglist xr-telnet could be used to filter the packages. Or, –remove-packages xr-cdp can be used to remove any reference to xr-cdp packages from the GISO.

A label is automatically generated if not provided by the operator. Network operator can use its own to differentiate multiple GISOs (e.g to specify patch level like 752-SMUs-20220830).
A debug file is also available to check operation details.

By default, generates 2 x files:

  • A golden ISO file (.iso). This can be used to patch, upgrade or PXE boot the Cisco 8000 router.
  • A compressed boot image (.zip). This can be used to USB boot the Cisco 8000 router. Refer Cisco 8000 USB boot procedure article.

If not needed, bootable USB image creation can be skipped with –skip-usb-image argument.

GISO Verification

gisobuild also contains a suite of tools to check content of a GISO. This can be handy to check a GISO file integrity or content. This article will cover will list content of a GISO. Embedded help is provided:

cisco@debian-template:~/gisobuild/src/lntmod$ ./ --help
usage: [-h] [--log-dir LOG_DIR] [--no-logs] [--json] -i ISO (--build-info | --dump-mdata | --rpms | --groups | --optional-packages | --fixes)

Helper utility to query information about an ISO

optional arguments:
  -h, --help           show this help message and exit
  --log-dir LOG_DIR    Directory to put the log file.
  --no-logs            Do not store the logs anywhere
  --json               Output data in JSON format

required options:
  -i ISO, --iso ISO    Path to ISO to query

isols options:
  --build-info         Display ISO build information
  --dump-mdata         Display ISO metadata information in JSON format
  --rpms               List all non-bridging RPMs in the ISO
  --groups             List all packages on a per-group basis.
  --optional-packages  List optional packages in the ISO
  --fixes              List bug fixes included in the ISO

Amongst these options, –fixes option confirms the 4 x SMUs are available in this sample GISO:

cisco@debian-template:~/gisobuild/src/lntmod$ ./ -i /home/cisco/gisobuild/src/output_gisobuild/giso/8000-golden-x86_64-7.5.2-iso.iso --fixes
Bugfixes in this ISO: 
{'cisco-CSCwb65194': ['xr-cds-7.5.2v1.0.1-1.x86_64'], 
'cisco-CSCvy99756': ['xr-python-7.5.2v1.0.1-1.x86_64', 'xr-security-7.5.2v1.0.1-1.x86_64'], 
'cisco-CSCwb74098': ['xr-routing-7.5.2v1.0.1-1.x86_64'], 
'cisco-CSCwb91492': ['xr-8000-dsm-7.5.2v1.0.2-1.x86_64'], 
'cisco-CSCwb25421': ['xr-8000-dsm-7.5.2v1.0.2-1.x86_64']}

Info: While 4 x SMUs have been downloaded from CCO website, CSCwb91492 supersedes CSCwb25421 (which was not downloaded), explaining why a 5th fix shows in the list.

The –optional-packages lists optional packages included in this GISO and confirms cdp and telnet packages are available:

cisco@debian-template:~/gisobuild/src/lntmod$ ./ -i /home/cisco/gisobuild/src/output_gisobuild/giso/8000-golden-x86_64-7.5.2-iso.iso --optional-packages
Group: main

Like any ISO file, Golden ISO can be mounted to explore its structure.

cisco@debian-template:~/gisobuild/src/lntmod$ sudo mkdir /mnt/giso
[sudo] password for cisco:
cisco@debian-template:~/gisobuild/src/lntmod$ sudo mount -o loop /home/cisco/gisobuild/src/output_gisobuild/giso/8000-golden-x86_64-7.5.2-iso.iso /mnt/giso

Following files and folders are present:



This post covered Golden ISO concept for Cisco 8000. The tutorial went over installation and utilization to create and verify GISO files. Those GISO files can ultimately be used to perform software staging, patching or upgrades.


I’d like to thanks Joseph Hare and Mark Sains from Cisco Ensoft team in UK for their support and review.

Leave a Comment