Install Versioning functional spec

1 Problem statement
- Currently, when installing a client where the booted image doesn't match the OS bits being installed, the installation behavior will be unexpected and have undefined results. - Further, the user is given no information on why the installation may have failed because the failure is not handled gracefully or logged. - Additionally both the user and the installer application have no insight into where or why we failed. - It is also possible that the installation may succeed however the resultant installation status is undefined and we can not guarantee that it is correct.

2 Scope of Project
- The version checking project (includes all types of installs, AI, Live CD etc...): - Will be responsible for checking the version of the booted image and installer against the image being installed. - In the case where a version mismatch is found the user will be notified of the mismatch and the mismatch will be logged. - At this point a best effort will be made to complete the install however the user will be warned that the install may not be successful. - Will provide functionality to "opt out" of the attempt to install in the case of a version mismatch. - Will only track the release and build/branch numbers for determining the versions.

3 Other Documentation

Overall caiman project - http://opensolaris.org/os/project/caiman/

Slim install - http://opensolaris.org/os/project/caiman/Slim_Install/

Automated installer - http://opensolaris.org/os/project/caiman/auto_install/

Versioning (this project) information, meeting notes etc. - http://opensolaris.org/os/project/caiman/CVERS/

4 Requirements
- The packages on the resulting image from installing a version of the OS should match (whenever possible) independent of the installer method which was used to do the installation. - When a mismatch is found it must be logged and the user informed. This should include enough information for the user to know how to resolve the issue if possible. - If a mismatch is found we should make a best effort to do the installation unless the user has specified that a mismatch should cause an install failure. - We will need to provide a method that the user can choose which allows the installer to just fail if a mismatch is found. - A mismatch of the architecture (SPARC vs x86/AMD64) will always cause the install to fail.

5 Requirements on other projects
- There is a requirement on the IPS system to provide the version string that will be used to identify the version. This string includes the release number (e.g. 5.11) the build number and a date stamp for that version. (this requirement has already been met by IPS and is stated here for completeness) - There is a requirement on ZFS and IPS to include a tag in the package information that lets us know the highest zpool version supported for the bits being installed. - There is a requirement on some of the ICT's that they are moved into the installed image so they can be run on first boot. This is part of the "System Configuration Parameters Setup" project. - It is expected that the boot image and the installer will always match as discussed in the [[proposal>>Project caiman.proposal]]. - There is a requirement on replication and recovery that we be able to mount or in some other way access an image before installing it so that the versions of the packages the image contains can be checked.

6 Version definition
- The version of the bits is determined by information returned from IPS and what is part of the booted image. In both cases there is package information that can be checked to find this version. For example this is currently the version as listed by the FMRI of the packages on the currently booted image. The version string includes the release number (i.e. 5.11) and the build (or branch) number (i.e. 111) . Both of these must match for the versions to match. - For pkg-based installs all of the packages on the booted image (for example the list of packages returned by a call to pkg list) will be used to determine the overall version compatibility. We will check these package versions and on the first difference found return a mis-match. - For image based installs the image will need to be mounted or in some way made available so that the version numbers of the packages within it can be checked. - For archive (or cpio) based installs the versions can only be checked after the installation. Since this is a scenario that should never happen and is always an error it is at this point that the failure would be reported.

7 Supported configuration
- The only fully supported configuration for doing an install is when the versions of the booted image packages match the versions being installed. When a version mismatch is detected the user will be warned and an error/warning will be logged which indicates the version mismatch. The install will not fail at this point but an attempt to complete the install will be made. This will be the default behavior but a method will be provided to turn this off so that a version mismatch will cause the install to quit.

8 Components
- There is one main component for version checking but with two types of version checks. These checks are for release and build (or branch) number. These checks are separated so that they can be used in different ways going forward. Additionally this gives us the ability to provide more information on what doesn't match so that this can be given to the user as part of any warnings or error messages. - The release check determines if the version strings of the booted image and the bits being installed contain the the same release number. For example Solaris 10 vs Solaris next (5.10 vs 5.11). - The build number check determines if the version strings of the booted image and the bits being installed contain the the same build number. For example build 101b vs 111b. - At this point both types of check must match for the version check to verify a match. - Pool version discovery for attempting to install bits that are older than the booted image and possibly don't have support for the current zpool version. - We also need to check for the pool version of any existing pool and insure that the bits to be installed can support that pool version. - Grub version updater for use when attempting to install with a mismatch. - This will be something like what is done now in beadm activate where installgrub is run on the alternate root using the stage files from the alternate root. - Boot archive updater for use when attempting to install with a mismatch. - This will be something like a simple wrapper around bootadm update grub that updates the boot archive for the alternate root.

9 Deliverables
- Installer check for version (includes the checks for release number and build (or branch) number) - Error message generator which creates warning and error messages based on type of version check that fails (if it fails...) - The ability to turn off the "best effort install" so that the user can choose to have the install fail if a mismatch is found. - If installing newer bits than the installer is running on: - GRUB version updater to attempt running installgrub on newly installed bits, if needed. - Boot archive updater which will attempt to update the boot archive on newly installed bits. - If installing older bits than the installer is running on: - Pool version discovery. This will determine which pool version will be supported by the bits being installed and this information will be used when creating the root pool for that installation.

10 Use cases

    Note: The following terminology is used in these use cases.
** pkg-based-install: IPS repository based installation.
** archive install: installation of a collection of bits based on the current bits, eg: cpio archives as used in live CD installer.
** image install: installation of images built from functioning systems.

    - 1. The booted OS version matches the OS version being installed. 
        - Continue with installation (nothing to do).
    - 2. The booted version is used to install on the system using cpio or some other archiving functionality.
        - In this case the versions will always match and the install will continue.
    - 3. The architecture booted doesn't match the bits to be installed.
        - This always results in an error message that is sent to the user and logged and the install fails.
    - 4. The booted version is older than the version of the bits being installed.
        - If the install is an archive(cpio) the install should fail and report to the user and log that this is not supported. This should never actually happen since in this case the bits being installed are coping from the booted image. If this does happen then something outside the version checking has gone very wrong and we should not continue.
        - If the install is pkg-based then we will do a best effort to install the bits. However a warning message will be send to the use and logged stating that there was an unsupported mismatch and that the install may not be successful. In this case we will also make a best effort to get the correct grub version installed as well as the boot archive updated correctly.
        - If the install is image based then any configuration required will need to be done post installation. This may require that there is something available such as a transient SMF service that runs on first boot that performs the configuration required.
    - 5. The booted version is newer than the version of the bits being installed.
        - If the install is an archive(cpio) the install should fail and report to the user and log that this is not supported. This should never actually happen since in this case the bits being installed are coping from the booted image. If this does happen then something outside the version checking has gone very wrong and we should not continue.
        - If the install is pkg-based then we will do a best effort to install the bits. However a warning message will be send to the use and logged stating that there was an unsupported mismatch and that the install may not be successful. In this case we will attempt to determine the correct zpool version for the root pool and we will also make a best effort to get the correct grub version installed as well as the boot archive updated correctly.
        - If the install is image based then any configuration required will need to be done post installation. This may require that there is something available such as a transient SMF service that runs on first boot that performs the configuration required. It may also be required that we be able to obtaine the correct pool version and handle that the same as the pkg-based install.
    - 6. There is an existing root pool.
        - If the bits being installed can support this pool we continue without an error or additional warning message.
        - If the bits being installed can't support the existing pool's version then we send and error to the user, log the error and fail the install.