Upgrades

Overview

The OpenXT platform supports upgrades from previous versions, both remote (Over The Air) and with local install media. The mechanisms and functionality of the upgrade feature are discussed in this Wiki. If you are (or are planning to be) a contributor or committer on the OpenXT project, please see the Contributors and Committers section below.

Upgrade Details

In OpenXT, all user data are stored in two partitions (actually logical volumes or LVs):

/config - Primarily contains the host configuration database and VM specific configuration files as well as number of other miscellaneous files.

/storage - Primarily contains user VM virtual disk files and ISO images. It is also home to the UIVM and NDVM VHDs and is the location where upgrades are downloaded.

These two partitions are left intact during an upgrade with the exception of UIVM/NDVM VHDs and the xc-tools.iso, which are updated. The entire dom0 root file system is replaced.

The version file

The version file found in the root of the openxt.git repository contains the following variable:

UPGRADEABLE_RELEASES="6.0.0"

This variable indicates what versions the current version of OpenXT is up-gradable from (in this example it is only upgradable from 6.0.0). This value is a space separated list multiple versions that can be upgraded from. This value is set in the XC-REPOSITORY installation meta file (see the next section).

The Control Package

The control package (also known as the installer part 2) is the package that does the actual installation or upgrade. During a fresh install it will reformat the entire disk and configure the host. During an upgrade the control package will preserve the /config LV, updating just a few files (e.g. installing a new xenclient.conf). During an upgrade the control package will preserve the /storage LV  and all the user created VM virtual disks. It will however update the UIVM/NDVM VHDs and the xc-tools.iso which reside in this LV. The control package will create a new LV called root.new and unpack the new dom0 rootfs into this LV. If the operation succeeds, it will rename the current root LV to root.old and rename root.new to root.

All of the meta information and packages needed (package repository) to do an install or upgrade are found either on the install media or hosted on a web server in a directory called packages.main. The control package (also found here) processes this repository to do installs and upgrades. The repository is also conviniently available as a tarball (update/update.tar).

The upgrade-db application

The upgrade-db application is run after the control package has finished and rebooted the system. This application contains a number of modules called migration scripts that are built into each version of it. They can be seen here:

https://github.com/OpenXT/manager/tree/master/upgrade-db/Migrations

The host configuration database contains a field that indicates what the current db version is. E.g. in 6.0.0 it looks like:

db:  "db-version": "32"

If a newer version of the upgrade-db is run with newer migration scripts than the current db's version, these migration scripts will be applied at startup. The migration scripts are code that can perform whatever updates or transformations to the host configuration that is necessary for a given upgrade. A new migration script is created by using the next highest version value available. See the Sample.hs migration script for a basic boiler plate for writing one.

There is one limitation that is a result of the linear application of migration scripts. Once a new one is created in a newer version of OpenXT, no more migration scripts can be inserted for earlier release version. For example, say 6.0.0 is released with scripts up to 31 and then 6.1.0 adds a script 32. Shortly after say a 7.0.0 release is done and adds a script 33. This means that no more releases in the 6.x line can be done that introduce migration scripts.

Signature Verification

By default, the build system will generate an RSA 2048 bit development key and certificate and sign the output repository during the build process. The build scripts will automatically generate this key pair and certificate. The certificate will be packaged on the dom0 root file system here:

/usr/share/xenclient/repo-certs/dev/cert.pem

The answer files for the installer will make dev certificate validation of the install/update repository allowable. This is done by writing this setting to /config/repo-cert.conf:

ALLOW_DEV_REPO_CERT='true'

For production builds of derived products, the dev signing can be disabled and actual production keys and certificates can be used to sign and verify the install/update repository. The production certificate in this case would be packaged on the dom0 root file system here:

/usr/share/xenclient/repo-certs/prod/cert.pem

See the example config file for the build for more information on certificates (TODO the information there is somewhat lacking):

https://github.com/OpenXT/openxt/blob/master/example-config

Media Based Upgrades

The installer ISO on CD/DVD/USB media or using PXE over the network can be used to upgrade OpenXT. The installer part 1 is used to boot the media, optionally intereact with a user and load the control package. It then uses the control package (the installer part 2) as described above in Upgrade Details to initiate the upgrade.

OTA Upgrades

OTA upgrades are initiated from the client using the UIVM. Under "Settings" -> "Software Update" an HTTP URL can be entered for a location where the upgrades package repository packages.main resides. This information is passed to the update manager daemon.

updatemgr

The updatemgr daemon runs in dom0 and listens for requests to initiate an OTA upgrade. The first thing the updatemgr does is to download the meta files from the remote package repository to verify the repository signature and that it is a version that is upgradable from. It will then download main packages in the repository and then use the control package (the installer part 2) as described above in Upgrade Details to initiate the upgrade.

Guest Tools Upgrades

Both Windows and Linux guests may have the guest tools package installed. The guest tools should also be upgraded with an OpenXT upgrade. Both the Windows and Linux tools packages do not currently support upgrading. The recommended method to upgrade these tools is to uninstall them prior to the OpenXT upgrade and then re-install them after the upgrade.

Contributors and Committers

Contributors and committers in the OpenXT community must be conscientious about how the upgrade mechanism works in OpenXT and take care to not break it (or allow it to get broken). Here are some areas of development where breakage could occur:

• Changes to host settings for VMs via the VM template files or policy changes for daemons such as the vusb-daemon or xcpmd. If changes are made in these areas, migration scripts will probably need to be created.
• The updatemgr must be able to perform OTA upgrades with SELinux enforcing. Prior to a release, it must be validated that OTA upgrades work and any SELinux fixes are made.
• Because the updatemgr is running on the version of OpenXT being upgraded from, it has to be future compatible with the new version. This future compatibility must not be broken by changes in the new version.