Installation Completion Tasks (ICT)

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

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.

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.

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.

ICT Resources

• 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

• 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

• 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

• Filing bugs

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

• Getting Help

  • IRC channel - #caiman-discuss at chat.freenode.net
  • Mailing list - caiman-discuss@opensolaris.org

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

  • 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.

  • 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

Consumers

• GUI Installer
• Automated Installer, both SPARC and x86

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

ICT API

• See Appendix Overview of each ICT

ICT Debugging

The ICT developed in C can be exercised by using ict_test.c

1. Build ict_test by running make ict_test in usr/src/lib/libict
2. Log into the test system as root
3. Populate a target see Below
4. Use LD_LIBRARY_PATH to pick up any library changes not installed on the test system. For example to test a change to libict.
5. Run ict_test, usage with examples is provide if no arguments are passed.

% 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"

The ICT developed in Python can be exercised by using ict.py member, exec_ict()

1. Log into the test system as root
2. Hack a fix to avoid an error validating the target directory, BASEDIR
3. Populate a target see Below
4. Run ict.py

Change From:
                #cmd = 'grep "^[^       ]*      ' + BASEDIR + ' " /etc/mnttab | '+\
Change To:
                cmd = 'grep "^[^        ]*      ' + '/' + '     " /etc/mnttab | '+\

./ict.py <ICT name> <target directory>
*e.g.*
./ict.py add_other_OS_to_grub_menu /a

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.
    Producing more diagnostics

    % export LS_DEST=3 
    % export LS_DBG_LVL=4 
    % /usr/bin/gui-install 
    

Testing changes using an existing image.

• ICT code is limited to four places:

1. liborchestrator
2. install-finish script
3. libict
4. 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

Populating an alternate root for testing

A scratch disk is needed. The below examples assumes disk c1t1d0 is available.
The repository specified in the example, _http://ipkg.sfbay/dev/_, was a SPARC test repo.

• Example: set up for alternate root, /a

  Set Up for an alternate root

  % 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
  

• Example: Populating the alternate root, /a, from IPS.

  Populate the alternate root

  % ROOT=/a
  % pkg image-create --full -a opensolaris=http://ipkg.sfbay/dev/ ${ROOT}
  % pkg -R ${ROOT} install SUNWcsd
  % pkg -R ${ROOT} install SUNWcs
  % pkg -R ${ROOT} install slim_install