Install Completion Tasks Module (ICT)

h1. Installation Completion Tasks (ICT)

TOI - January 20, 2009
Joe VLcek JoeV@Sun.com

h2. Purpose of ICT

* Installation Completion Tasks (ICT) are configuration tasks performed in the later stages of installation, after transfer, to prepare the new Solaris instance for a successful boot. After the target (/a) has been populated by the install transfer, ICT configurations information on the target (/a).
* Historically Installation Completion Tasks have been referred to as Post Installation Tasks. They had been implemented in multiple places
with little error report/handling. If the installer failed because of a problem with an ICT it was difficult to determine what went wrong.
* An API which could be invoked from other tools, e.g. Distro Constructor, other special media tools.

h2. Current state.

* The ICT code has been consolidated into libict and libict_pymod
* A set of independent functions, or API, have been created. Each are able to perform a single ICT, or a small, related set, of ICT.
* The existing logging service has been used to providing progress and error reporting to improve debugging.
* Unique ICT failure status codes are returned to improved diagnostics and debugging.
* Produce a language independent interface to the independent ICT.

h2. To Do

* Some of the ICT are still implemented using "C". The plan is to convert them to Python.
* Produce a language independent interface to the independent ICT.
* Perhaps leverage finalizer, from the Distro Constructor, for flexibility on different installation styles.


h2. ICT Resources

* h4. Source code can be found at:
** hg clone ssh://anon@hg.opensolaris.org/hg/caiman/slim_source
** http://src.opensolaris.org/source/xref/caiman/slim_source

* h4. The ICT source is in the source tree at:
** usr/src/lib/libict
** usr/src/lib/libict_pymod
** usr/src/lib/libict_pymod
** usr/src/cmd/slim-install/finish/install-finish

* h4. Documentation
** http://www.opensolaris.org/os/project/caiman/files/dwarf_caiman_design.pdf
** ssh://hg.opensolaris.org/hg/caiman/caiman-docs/ICT/ict_design_doc.odt
** A guide to the ICT implemented in Python can be generated directly from the source using command: /usr/bin/pydoc.
*** e.g.: /usr/bin/pydoc usr/src/lib/libict_pymod/ict.py

* h4. Filing bugs
** use bugzilla, not bugster -
** defect.opensolaris.org
** category Development/installer/library
** helpful if "ICT" is included in Summary

* h4. Getting Help
** IRC channel - #caiman-discuss at chat.freenode.net
** Mailing list - caiman-discuss@opensolaris.org

h2. ICT implementation

* Currently some ICT are implemented in a Standard C library
* Currently some ICT are implemented in Python
* In the future the plan is to have all ICT implemented in Python
** h4. ICT Implemented in "C"
*** Source code reside in usr/src/lib/libict
*** Built into library: libict.so.1
*** usr/src/lib/libict contains the files:
**** Makefile - The Makefile used to build the libict library.
**** ict_api.h - Contains definitions needed by a user of libict.
**** ict_private.h - Contains definitions used by ict.c .
**** ict.c - Contains the ICT API code for those ICT implemented in "C".
**** ict_test.c - Contains a test exerciser for the ICT API.
** h4. ICT Implemented in Python
*** Source code reside in usr/src/lib/libict_pymod
*** Delivered in the single script ict.py
*** usr/src/lib/libict_pymod contains the files:
**** Makefile - The Makefile used to build the libict_pymod library.
**** ict.py - Contains the ICT API code for those ICT implemented in Python.
**** OOD class ICT implementation

h2. Consumers

* GUI Installer
* Automated Installer, both SPARC and x86

h2. Invoked From

* All ICT are invoked from the orchestrator.
** The orchestrator is implemented in _C_ and directly invokes those ICT which are implemented in _C_ .
** To invoke the ICT implemented in Python the orchestrator uses popen(3C) to invoke the Python script usr/src/cmd/slim-install/finish/install-finish. The _install-finish_ script, in turn, invokes all of the Python ICT.
** The orchestrator function run_install_finish_script() invokes the _install-finish_ script.
** All ICT are invoked from the orchestrator in file: usr/src/lib/liborchestrator/perform_slim_install.c

h2. ICT API

* See _Appendix Overview of each ICT_

h2. ICT Debugging

h4. The ICT developed in _C_ can be exercised by using ict_test.c
# Build ict_test by running _make_ ict_test in usr/src/lib/libict
# Log into the test system as root
# Populate a target *see Below*
# Use LD_LIBRARY_PATH to pick up any library changes not installed on the test system. For example to test a change to libict.
# Run ict_test, usage with examples is provide if no arguments are passed.

{code:title=Invoke ict_test for test execution |borderStyle=solid}
% su -
% mkdir /tmp/TEST_ICT; cd /tmp/TEST_ICT
% cp <any updated libraries needed> /tmp/TEST_ICT
% export LD_LIBRARY_PATH=/tmp/TEST_ICT
% ./ict_test help
Usage: ./ict_test <ICT> <ICT args>
ICT options:
./ict_test ict_set_host_node_name <target> <hostname> <transfer mode>
./ict_test ict_set_lang_locale <target> <localep> <transfer mode>
./ict_test ict_configure_user_directory <target> <login>
./ict_test ict_set_user_profile <target> <login>
./ict_test ict_installboot <target> <device>
./ict_test ict_set_user_role <target> [login]
./ict_test ict_snapshot <pool> <snapshot>
./ict_test ict_transfer_logs <src> <dst>
./ict_test ict_mark_root_pool_ready <pool>

ICT e.g.:
./ict_test ict_set_host_node_name "/a" "MY_HOST" 0
./ict_test ict_set_lang_locale "/a" "en_US.UTF-8" 0
./ict_test ict_configure_user_directory "/a" "guest"
./ict_test ict_set_user_profile "/a" "guest"
./ict_test ict_installboot "/a" "c5d0s0"
./ict_test ict_set_user_role "/a" "guest"
./ict_test ict_snapshot "rpool" "install"
./ict_test ict_transfer_logs "/" "/a"
./ict_test ict_mark_root_pool_ready "rpool"

./ict_test ict_set_host_node_name "/a" "MY_HOST" 0
./ict_test ict_set_lang_locale "/a" "en_US.UTF-8" 0
./ict_test ict_configure_user_directory "/a" "guest"
./ict_test ict_set_user_profile "/a" "guest"
./ict_test ict_installboot "/a" "c1t1d0s0"
./ict_test ict_set_user_role "/a" "guest"
./ict_test ict_snapshot "rpool" "install"
./ict_test ict_transfer_logs "/" "/a"
./ict_test ict_mark_root_pool_ready "rpool"
{code}
h4. The ICT developed in Python can be exercised by using ict.py member, exec_ict()
# Log into the test system as root
# Hack a fix to avoid an error validating the target directory, BASEDIR
# Populate a target *see Below*
# Run ict.py

{code:title=ict.py hack for stand alone test execution.|borderStyle=solid}
Change From:
#cmd = 'grep "^[^ ]* ' + BASEDIR + ' " /etc/mnttab | '+\
Change To:
cmd = 'grep "^[^ ]* ' + '/' + ' " /etc/mnttab | '+\
{code}

{code:title=Invoke ict.py for test execution |borderStyle=solid}
./ict.py <ICT name> <target directory>
*e.g.*
./ict.py add_other_OS_to_grub_menu /a
{code}

h4. Debugging tips
* Turning on diagnostic output in the installer:
** The level of diagnostics produced from ICT, and other components of the installer can be increased using LS_DEST, and LS_DBG_LVL environmentals.
{code:title=Producing more diagnostics|borderStyle=solid}
% export LS_DEST=3
% export LS_DBG_LVL=4
% /usr/bin/gui-install
{code}

h4. Testing changes using an existing image.
* ICT code is limited to four places:
# liborchestrator
# install-finish script
# libict
# ict.py

* Using a Live Image it is possible to diagnose changes using the following method:
** Prior to invoking /usr/bin/gui-install do:
*** For diagnosing issues in liborchestrator
**** Build a version of liborchestrator with extra diagnostics
**** Copy it to a system booted from the Live Image into /tmp.
**** Use export LD_LIBRARY_PATH=/tmp to pick up the new version.
*** For diagnosing issues in the install-finish script
**** Build a version of install-finish with extra diagnostics
**** Copy it to a system booted from the Live Image directly to /sbin/install-finish
*** For diagnosing issues in libict:
**** Build a version of libict with extra diagnostics
**** Copy it to a system booted from a Live Image in /tmp.
**** Then use export LD_LIBRARY_PATH=/tmp to pick up the new version.
*** For diagnosing issues in the ict.py
**** Build a version of ict.py with extra diagnostics
**** Copy it to a system booted from a Live Image to /tmp.
**** mount -F lofs /tmp/ict.py /usr/lib/python2.4/vendor-packages/osol_install/ict.py
** Invoke /usr/bin/gui-install

{code:title=Set Up for an alternate root|borderStyle=solid}
% zpool create -f rpoolos c1t1d0
% zfs create rpoolos/ROOT
% zfs set mountpoint=legacy rpoolos/ROOT
% zfs create rpoolos/ROOT/opensolaris
% mkdir /a
% mount -F zfs rpoolos/ROOT/opensolaris /a
{code}

* h5. _Example:_ Populating the alternate root, _/a_, from IPS.

% pkg -R ${ROOT} install slim_install
{code}