What are the key changes for XR7
For starters you have one single install command now, that can be used with a golden iso.
install replace <source location> <repository name.iso> is all you need now!
also error handling and disk maintenance are part of install operations so you dont need 3 PHD's anymore to do an XR upgrade.
Also there is a very easy to handle YANG model for xr install now.
XR provides for all methods one might want!
- using (g)ISO
- traditional way of adding packages (RPM's) and activating/deactivating them
- power mode of having a repository and install from there a-la a "YUM" or apt-get similar way
But what is an ISO really, and what does a golden one mean?
Understanding the ISO format
ISO is a standardized formatting used by many vendors. what it provides is a single bootable image structured file with the complete 'manual' on how to construct a disk with an operating system. The best(?) analogy i can draw here is a CDROM with windows on it, you put in your cdrom player, it asks to upgrade or replace the disk and when you select erase, it wipes the disk from all content and creates a fresh install of the OS forward.
An ISO contains lots of pieces of detail for the operating system. But first it is important also to understand how a LINUX based operating system boots.
There are 3 critical pieces to the boot process:
- BIOS
- GRUB
- initRD
A few simplified words on these pieces:
BIOS is similar to BIOS of a PC or what rommon was for classic XR. it provides the basic instructions for the cpu on what is where in terms of hw resources and how to access them. Obviously space is limited so the drivers are minimal and not that much features either, but good enough to get to the next stage!
GRUB stands for GRand Unified Bootloader. See this similar as the bootloader image from the old 7200 days. it provides for more drivers and a mini operating system that allows us to get to the initial stages of the actual operating system we want to run.
initRD is the initial ram disk, this is the most critical piece which is basically the operating system with kernel. it explodes this content (OS) into memory and starts the kernel. This now also gives access to additional mount points.
After the OS is deployed there are some abilities to load optional packages and execute scripts (a-la an autoexec.bat) and or deploy a config for the device.
The basic structure of the ISO looks like this
[root@nb-server3 giso]# mount -o loop ncs5500-mini-x-6.3.3.iso /mnt/g1
[root@nb-server3 twitch]# tree /mnt/g1
/mnt/g1
├── boot
│ ├── bzImage
│ ├── certs
│ │ ├── CertFile
│ │ ├── crl.der
│ │ └── Root_Certificate_Store.bin
│ ├── grub
│ │ ├── device.map
│ │ ├── e2fs_stage1_5
│ │ ├── fat_stage1_5
│ │ ├── ffs_stage1_5
│ │ ├── iso9660_stage1_5
│ │ ├── jfs_stage1_5
│ │ ├── menu.lst
│ │ ├── menu.lst.install
│ │ ├── menu.lst.ucs
│ │ ├── menu.lst.ucs.install
│ │ ├── menu.lst.xboard
│ │ ├── minix_stage1_5
│ │ ├── reiserfs_stage1_5
│ │ ├── stage1
│ │ ├── stage2
│ │ ├── stage2_eltorito
│ │ ├── ufs2_stage1_5
│ │ ├── vstafs_stage1_5
│ │ └── xfs_stage1_5
│ ├── grub2
│ │ ├── bootx64.efi
│ │ ├── grub.cfg
│ │ ├── grub-usb.cfg
│ │ ├── grub-usb.efi
│ │ ├── NCS-55xx_pubkey.der
│ │ ├── README
│ │ └── swims_client.log
│ ├── initrd.img
│ ├── NCS-55xx_pubkey.der
│ ├── signature.initrd.img
│ └── swims_client.log
├── boot.catalog
├── giso_info.txt
├── giso_summary.txt
├── iosxr_image_mdata.yml
├── iso_info.txt
├── release-rpms-admin-arm.txt
├── release-rpms-admin-x86_64.txt
├── release-rpms-xr-x86_64.txt
├── router.cfg
└── xr_rpms
└── ncs5500-k9sec-4.2.0.0-r633.x86_64.rpm
In this example you can see how to mount an ISO on eg your MAC or linux system or an ISO viewer to see how it is built. Remember the iso is really a file system hence it can be mounted.
When you're downloading a full ISO from CCO it contains the base image with all optional packages. It would not contain smu's.
Using such a full ISO allows you to do a basic single file upgrade from one release to the other.
At times you want to do the upgrade with a set of smu's for instance or you want a base OS package with only your selected optional RPMs.
When you are recreating an ISO like that, eg base release, optional packages and smu's and you want to make this an ISO, this is what we refer to as Golden ISO or gISO for short.
Building a gISO
How to make a gISO yourself, there are 2 options. the manual way (it is still super simple) and using a GUI based approach eg through CSM.
To use the manual approach, it is as simple as dumping all your files in a directory of choice and run the giso build script over it!
Benefits of gISO
there are huge benefits to using gISO. you can include a label depicting the sw version running!
for instance: my-XR663-plusSMUs-v1, when you later decide to rebuild it with more smu's you can call it v2
and this will show in "show version"
Also it allows you to in a very simple way replace packages with newer versions, remove packages that you want to exclude. More on that later how gISO replaces, adds and removes packages.
What do you need?
A Linux machine meets following requirements
'mount','rm','cp','umount','zcat','chroot','mkisofs' tools should be available
User should have privilege to execute all of the above linux tool/cmd
Minimum python version 2.7
system should have at least 4 GB free disk space
gisobuild.py script (available on all eXR running routers in the location: /pkg/bin/gisobuild.py)
mini iso is mandatory on file system [mandatory]
Desired rpms to build GISO [mandatory]
config file or running configuration [optional]
auto-run script are optional [optional] -> 653
Script helps to execute right after install automatically
Right (rx) permissions for the rpms and the other files
Note: Kernel version of the system should be greater than 3.16 or greater than the version of kernel of cisco iso because of the initrd.img file creation during gisobuild process
2 files required to be downloaded from Cisco locations:
- 1. gisobuild.py
- 2. create_usb_zip
Download gisobuild.py from the cisco location
usage: gisobuild.py [-h] -i BUNDLE_ISO [-r RPMREPO] [-c XRCONFIG][-s SCRIPT] [-l GISOLABEL] [-m] [-o] [-x] [-v]
Utility to build Golden/Custom iso. Please provide atleast repo path or config
file along with bundle iso
optional arguments:
-h, --help show this help message and exit
-r RPMREPO, --repo RPMREPO
Path to RPM repository
-c XRCONFIG, --xrconfig XRCONFIG
Path to XR config file
-s SCRIPT, --script SCRIPT
Path to user executable script
-l GISOLABEL, --label GISOLABEL
Golden ISO Label
-m, --migration To build Migration tar only for ASR9k
-o, --optimize Optimize GISO by recreating and resigning initrd
-x, --x86_only Use only x86_64 rpms even if arm is applicable for the platform
-v, --version Print version of this script and exit
required arguments:
-i BUNDLE_ISO, --iso BUNDLE_ISO
Path to Mini.iso/Full.iso file
Example run of a gISO build
[root@nb-server3 giso]# /router/bin/python gisobuild.py -i ncs5500-mini-x-6.3.3.iso -r . -c running.cfg
System requirements check [PASS]
Info: Golden ISO label is not specified so defaulting to 0
Golden ISO build process starting...
Platform: ncs5500 Version: 6.3.3
XR-Config file (/auto/tftp-vista/narvenka/core/633/giso/running.cfg) will be encapsulated in Golden ISO.
Scanning repository [/auto/tftp-vista/narvenka/core/633/giso]...
Building RPM Database...
Total 1 RPM(s) present in the repository path provided in CLI
Following XR x86_64 rpm(s) will be used for building Golden ISO:
(+) ncs5500-k9sec-4.2.0.0-r633.x86_64.rpm
...RPM compatibility check [PASS]
Building Golden ISO...
Exception why ? = [Errno 39] Directory not empty: '/auto/tftp-vista/narvenka/core/633/giso/tmpdxF3_E/iso'
Summary .....
XR rpms:
ncs5500-k9sec-4.2.0.0-r633.x86_64.rpm
XR Config file:
router.cfg
...Golden ISO creation SUCCESS.
Golden ISO Image Location: /auto/tftp-vista/narvenka/core/633/giso/ncs5500-goldenk9-x.iso-6.3.3.0 à GISO
Detail logs: /auto/tftp-vista/narvenka/core/633/giso/Giso_build.log-2019-03-26:21:17:06.957192
Using CSM for gISO build
its super simple, go to the gISO build page, select the directory, click on the files you want to include and press go for it!
If you dont have CSM running yet, you can easily install it with this single line:
sudo -E bash -c "$(curl -sL https://devhub.cisco.com/artifactory/software-manager-install-group/install.sh)"
Optimized vs non-Optimized
There are 2 types of gISO's we can use as depicted in this chapter. The key difference is this.
when you are building a non optimized gISO, you take the CCO base version for the initRD and your optional packages are *outside* this initRD.
When you are building an optimized gISO, you recreate the initRD to lump in your packages, smu's and optional RPM's inside the initRD.
Why would that matter and what are the trade offs?
When you are building the gISO optimized, hence putting everything in the initRD you basically have to resign the initRD. Remember that initRD is the operating system, and this resigning has stipulations.
When you are running the gISO build and the initRD has to be resigned, you'll be using your own signature.
Now normally that is not a problem, if you are already running XR and you want to deploy the gISO everything can be validated as is, as you are likely (or SHOULD :)) be including cisco packages only. every package to be deployed is validated for security and if authentic will get deployed. in other words, you dont really need the initRD or grub here because the OS is already running.
However, when you do something like a ZTP or a USB boot, then the initRD is used to explode the image and install it, then the image security is very critical and a "self-signed" gISO in this case will fail the security check (your sig is not CSCO sig) and can't be deployed.
You can instead build a non-optimized gISO, that leaves the packages outside the initRD hence doesnt need to be resigned, but in this case you get the scenario thata on the firsts baking process, initRD is getting deployed and now we need to validate and deploy the optional packages.
In order to do this securely, the gISO is downloaded again!
This delays the ZTP operation and installation but it is fine to do.
The alternative to that is you ask a CSCO rep to build the gISO for you and post it somewhere.
We are looking into enhancements for a user to upload his cert to the device so the self signed gISO can be validated against that. This puts the "trust" in your hands hence if you are building a rogue gISO with your sig and is deployed on your device, you can do nasty things. Not in terms of rpm content, but in terms of config and scripts.
Your gISO is not deployable by another user, because they dont hold (hopefully) your cert.
Deploying gISO and upgrade scenarios
Now that you have your gISO, and want to deploy it on a system that is running a version of XR already
there are a few critical pieces to understand how install handles a giso.
Mind you, the (g)ISO is the complete package how you want your system to look after the install operation.
This means that
Packages not part of the gISO will be removed.
Packages running on the system, but your gISO holds a downrev will get downgraded.
Packages that are not on the system but part of your gISO will get added
Basically it looks like this:
Hopefully this all unravels a bit the power of gISO and the general concept.
Note that gISO works with prior versions of eXR also before XR7.
It is just that XR7 has improved handling of content management of the ISO and easier install operations in general.
cheers!!
xander