Draft Proposal Notes

Problem Statement:
- Currently 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.

Requirements:
- The resulting image from installing a version of the OS should match (whenever possible) no matter what installer method was used to do the installation.
- When a mismatch is found is must be logged.
- If mismatch is found that we can't install an error indicating the mismatch must be logged and sent to the user. This should include enough information for the user to know how to resolve the issue if possible.
- Define what types of installs can have differing versions and which can't.
- Would still need to define something to hinge the compatibility version upon (the build number would probably due) - Would need to delineate compatibility versions for different installers if ICTs don't live in the installed image.

Decisions made:
- We expect that the installer will always be part of the boot image and therefore will always match the OS that was booted.
- This was worked on for the initial AI design and that information is still applicable. I have included this information at the end of this writeup. - We will not support a newer boot image/installer with an older set of bits being installed. - This is partially due to limitations of IPS and backward compatibility. - basically IPS and zpool/zfs are meant to be backward compatible and attempting to install bits that are older than what the installer is running is asking them to be forward compatible.

Possible Dependencies:
- IPS image versioning
- Format of FMRI string needs to remain stable. (with respect to release and branch numbers) - SMF transient first boot service. - SMF enhanced profiles to handle some ICT tasks on first boot. (this eleminates and version issues for those ICT's)

Rules and use cases

Terminology:
--
pkg-based-install: IPS repository based installation.

archive install: installation of a collection of bits, eg: cpio archives.

image install: installation of images built from functioning systems.

--
Rule sets:
--
Rule 1:
The booted OS version matches the OS version being installed. (see assumptions)
- Continue with installation (nothing to do).

Rule 2:
The booted OS/installer is older than OS bits to be installed:
- If this is the type of mis-match between the Booted OS/installer and the OS being installed: - If the install is archive(cpio) the install should fail and report that this is not supported. - If the install is pkg-based then we will warn the user and log the warning. Then we will attempt to install the bits based on what was requested in the install manifest. - If the install is image based then any configuration required will need to be done post installation. This will require that there is something available such as a transient SMF service that runs on first boot that performs the configuration required.

Rule 3:
Booted OS/installer is newer than OS to be installed:
- If the install is archive(cpio) the install should fail and report that this is not supported. - If the install is pkg-based then we will warn the user and log the warning. Then we will attempt to install the bits based on what was requested in the install manifest. - If the install is image based then we will attempt to determine the correct zpool version for the bits to be installed and create the zpool based on that version. We will then attempt to install the OS. - In all other cases the installer would fail and the user would be informed that this mis-match happened and that the installer is not backward compatible.

Rule 4:
Installer booted up in X86, explicitly specify to install some SPARC bits. Should fail asap...
- In all instances the installer reports this mismatch in architecture to the user and fails...

Use Cases:
--
Use case 1
--
- User booted OS version X, user want to install an image archive that's built from a system based on OS version X+1.
- Expected result: Install will be attempted. - Rules applied: Rule 2

Use case 2
--
- User booted OS version X, user want to do a package based install of bits for OS version X+1
- Expected result: Install will be attempted. - Rules applied: Rule 2

Use case 3
--
- User booted OS version X, user want to do a archive install of bits from OS version X+1
- Expected result: Install will fail - Rules applied: Rule 2

Use case 4
--
- User booted OS version X, user want to install an image archive that's built from a system based on OS version X-1.
- Expected result: Install will be attempted - Rules applied: Rule 3

Use case 5
--
- User booted OS version X, user want to do a package based install of bits for OS version X-1
- Expected result: Install will be attempted - Rules applied: Rule 3

Use case 6
--
- User booted OS version X, user want to do a archive install of bits from OS version X-1
- Expected result: Install will fail - Rules applied: Rule 3

Use case 7
--
- User booted to x86 boot image but the OS requested to be installed is a SPARC image
- Expected result: Install will fail - Rules applied: Rule 4

Research for splitting boot image and installer

Pros and Cons of splitting the boot archive from the installer application in order to help with version incompatibility.

Pros:

1. It would enable us to dynamically update the installer application on the client in the event we detected a version incompatibility between the bits the user is installing and our current booted boot archive. Thus providing the ability to successfully install more often for the user.
2. It would allow sysadmins to maintain potentially a lesser number of client images for AI installation.
3. It would help with allowing the boot image to be separated from the AI 'service' so that one boot image could be used for multiple AI services. Thus, simplifying the service setup and maintenance for sys-admins.

Cons:

1. With a boot image that is separate from the installer and the other software required for the installer, it is possible we will have an incompatibility between the kernel and user space. For example, we could have an older version of the zfs kernel module and a version of the libzfs library that are incompatible.
2. The test coverage for allowing a boot image to be separate from the installer application could be very large.
3. Splitting the boot image from the installer application would mean another level of 'versioning' we would have to maintain. We would need this data to determine which installer application would be compatible with the current boot image that the client is booted with.
4. Debugging failed installations would become more difficult.

Possible solutions:

-Using a zone environment to update the client version of the installer and installer tools as needed.
- Doing this does not fix the possibility of an incompatible kernel and user space. A zone runs on the kernel that is currently booted.

Things we still need to think about:
- How we deal with dry-run for those ict's and other configuration items that we plan to do on first re-boot.
- what ict's will be part of the first boots tasks.