From darrenm@sac.sfbay.sun.com Wed Jul 9 02:28:50 2008 Received: from sunmail5.uk.sun.com (sunmail5.UK.Sun.COM [129.156.85.165]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id m699SnoC001063 for ; Wed, 9 Jul 2008 02:28:50 -0700 (PDT) Received: from nwk-avmta-2.sfbay.sun.com (nwk-avmta-2.SFBay.Sun.COM [129.145.155.6]) by sunmail5.uk.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id m699Smip024922; Wed, 9 Jul 2008 10:28:48 +0100 (BST) Received: from pmxchannel-daemon.nwk-avmta-2.sfbay.sun.com by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) id <0K3Q00B03FNZ4X00@nwk-avmta-2.sfbay.sun.com>; Wed, 09 Jul 2008 02:28:47 -0700 (PDT) Received: from dm-sfbay-02.sfbay.sun.com ([129.146.11.31]) by nwk-avmta-2.sfbay.sun.com (Sun Java System Messaging Server 6.2-3.04 (built Jul 15 2005)) with ESMTP id <0K3Q007TJFNZO430@nwk-avmta-2.sfbay.sun.com>; Wed, 09 Jul 2008 02:28:47 -0700 (PDT) Received: from sac.sfbay.sun.com (new-sac.SFBay.Sun.COM [129.146.175.65]) by dm-sfbay-02.sfbay.sun.com (8.13.8+Sun/8.13.8/ENSMAIL,v2.2) with ESMTP id m699SjPV040394; Wed, 09 Jul 2008 02:28:45 -0700 (PDT) Received: from sac.sfbay.sun.com (localhost [127.0.0.1]) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8) with ESMTP id m699Si8h001058; Wed, 09 Jul 2008 02:28:44 -0700 (PDT) Received: (from darrenm@localhost) by sac.sfbay.sun.com (8.13.8+Sun/8.13.8/Submit) id m699ShtZ001054; Wed, 09 Jul 2008 02:28:43 -0700 (PDT) Date: Wed, 09 Jul 2008 02:28:43 -0700 (PDT) From: Darren J Moffat Subject: ITU construction tools [PSARC/2008/431 FastTrack timeout 07/16/2008] To: PSARC-ext@sun.com Cc: James.McPherson@sun.com, driver-discuss@opensolaris.org Message-id: <200807090928.m699ShtZ001054@sac.sfbay.sun.com> Content-transfer-encoding: 7BIT X-PMX-Version: 5.4.1.325704 Status: RO Content-Length: 19091 Template Version: @(#)sac_nextcase 1.66 04/17/08 SMI This information is Copyright 2008 Sun Microsystems 1. Introduction 1.1. Project/Component Working Name: ITU construction tools 1.2. Name of Document Author/Supplier: Author: James McPherson 1.3 Date of This Document: 09 July, 2008 4. Technical Description 1. Introduction 1.1. Project/Component Working Name: Integrate ITU construction tools 1.2. Name of Document Author/Supplier: James McPherson 1.3. Date of This Document: 07/02/2008 1.4. Name of Major Document Customer(s)/Consumer(s): 1.4.1. The Community you expect to review your project: ON 1.4.2. The ARC(s) you expect to review your project: PSARC - Open. 1.5. Email Aliases: 1.5.2. Responsible Engineer: James.McPherson@Sun.COM 1.5.4. Interest List: driver-discuss@opensolaris.org ITU construction tools ====================== Summary ------- The procedure for Solaris Install-Time-Update (ITU) is modfied based on the new boot architecture. 3rd party vendors may now deliver driver updates via floppy, CD/DVD, or USB storage. New tools are provided for modifying Solaris install media with new packages and patches. The tools will be available for internal users to deliver software updates for hardware platforms and for external developers to produce customized install media. Background ---------- Install-Time-Update (ITU) is the process by which updates to Solaris kernel and driver modules are applied upon initial installation. The history of ITU support goes back to PSARC/1993/580[1]. The original problem was summarized as: (A) How to boot from a CD through an HBA or CDROM controller for which a primary boot driver is not on the Solaris boot diskette. (B) How to install from a CD through an HBA or CDROM controller whose driver is not on the Solaris install media. (C) How to install onto a hard disk through an HBA or disk controller whose driver is not on the Solaris install media. (D) How to install drivers that are not integrated into the Solaris install media onto the system disk. (E) How to enable IHVs and OEMs to package solutions to these problems without Sun's help. In that proposal[1], a new MDB (Multiple Device Boot) floppy disk containing the required drivers was to be delivered to augment the kernel on the CD distribution media. A baseline floppy was planned for delivery to 3rd party vendors to augment with their own drivers. The proposal was rejected, but used internally by the x86 consolidation PSARC/1993/674[2]. The x86 consolidation was later merged with ON. Then came the rewrite of the x86 boot subsystem in Solaris 2.6[3]. Subsequently, a public ITU mechanism was approved[4]. An ITU floppy format was defined along with tools for 3rd parties to build their own boot floppy. Note that despite the ITU mechanism being public, it still does not permit a 3rd party ISV or IHV to override kernel components delivered by Sun, although the same mechanism is used more liberally internal to Sun. ITU under Newboot ----------------- The introduction of Solaris Boot Architecture[5] on x86 offers an opportunity to modernize the ITU mechanism. By using the open source GRUB loader[6], realmode drivers have been eliminated from the boot process. A key decision in Newboot is to download the entire miniroot in memory (at the expense of raising minimum memory requirement to 256 MB), permitting the Solaris kernel to start independent of kernel hardware support. In the new architecture, problems (A) and (B) in section 1 were solved automatically. This reduces the public ITU mechanism to a simple matter of adding device drivers after the miniroot is up and running. At this point, Solaris has access to floppy, CD/DVD, USB media, and possibly network. Furthermore, the in-memory root filesystem can be made writable. Adding hardware support became a trivial pkgadd (Problem C). While existing third-party Driver Update diskettes work fine under Newboot, the Sun internal use for patching the kernel via ITU does not match well with the new boot architecture. By the time ITU media is read, core kernel modules have already been loaded and cannot be updated. To allow install to use a patched kernel, we provide new scripts, updatemedia(1) and mkbootmedia(1), to customize install media based on standard Solaris media and OS patches. New Interfaces -------------- The following scripts are proposed for facilitating ITU related tasks. Here are the interfaces and a brief description of their usage. A more detailed explanation can be found in a Whitepaper[7]. ---------------------------------------------------------------------- Name Commitment Level Comments ---------------------------------------------------------------------- itu Committed wrapper script for ITU tools pkg2du Committed convert pkg to ITU/Driver Update (DU) format updatemedia Committed modify install media mkbootmedia Committed bootable ISO image tool ---------------------------------------------------------------------- The scripts will be installed in SUNWcsu. pkg2du(1M) and driver updates ----------------------------- The pkg2du(1M) command takes one or more driver packages and put it in ITU format[4] along with a generic install script to be invoked during the Solaris installation process to add the packages. ITU is also known to IHVs and ISVs as a Driver Update (DU). The following command builds an ISO image of two packages: # /usr/bin/pkg2du -o du.iso SUNWfoo SUNWbar The resulting du.iso file can then be burned onto a CD/DVD to be used during installation. Updating install media ---------------------- The updatemedia(1) should be used to patch OS components and to add new packages which are used while booting the install miniroot. The following command modifies Solaris install media rooted at "media_root" by adding patch 123456-07 and package SUNWfoo: # /usr/bin/updatemedia -d media_root 123456-07 SUNWfoo User may then create an ISO image, media.iso, from media_root: # /usr/bin/mkbootmedia media_root media.iso The ISO image can then be burned onto CD/DVD using cdrw(1) or cdrecord(1): # /usr/bin/cdrw -i media.iso or # /usr/bin/cdrecord media.iso When the updated media is used to install Solaris, the install miniroot will already contain patch 123456-07 and SUNWfoo. In addition, the patch and the package will be automatically applied to the target OS. Advanced users and developers may wish to customize the install miniroot manually. The root_archive(1M) command (delivered via [5]) is used for this purpose. The procedure involves unpacking the miniroot into filesystem format, making changes, and repacking the miniroot, e.g.: # /usr/sbin/root_archive unpackmedia media_root /tmp/miniroot # [ modify /tmp/miniroot ] # /usr/sbin/root_archive packmedia media_root /tmp/miniroot Manpages -------- Please see below for manpages for each of the commands itu(1), mkbootmedia(1), pkg2du(1) and updatemedia(1). References ---------- [1] Carl Hensler, PSARC 1993/580 Third Party Driver Boot/Install [2] Carl Hensler, PSARC 1993/674 x86 Driver supplement boot/install [3] Andy Rudoff, PSARC 1994/201 Solaris x86 Device Configuration [4] Tim Haley, PSARC 1997/059 Install-Time Updates [5] Shudong Zhou, PSARC 2004/454 Solaris Boot Architecture [6] GRand Unified Bootloader (http:/www.gnu.org/software/grub/grub.html) [7] Shudong Zhou, Installing Solaris on x86 with Unbundled Drivers and Patches (will be made available on opensolaris.org in the ON community area) Tracking CR ----------- 6721696 IHVs need easy ITU creation utilities ======================================================================== NAME itu - convert packages to Driver Update format and patch Solaris install media for Install Time Update (ITU) SYNOPSIS itu makedu -r solaris_release [-v] [-f] [-d output_dir] [-o iso_file] [-l iso_label] package [package ...] itu updatemedia -R media_root [-v] [-f] [-o iso_file] [-l iso_label] pkg_or_patch [pkg_or_patch ...] itu makeiso -o iso_file [-v] [-f] [-l iso_label] media_root DESCRIPTION itu converts driver packages to Driver Update (DU) format and patches a Solaris install media with driver packages and patches for Install Time Update (ITU). There are three subcommands to itu: makedu, updatemedia and makeiso. Subcommand makedu The makedu subcommand takes one or more driver packages as input and converts them to DU format. At the beginning of an interactive Solaris installation session, these driver updates can be applied to the running kernel, which will then automatically apply them also to the newly installed Solaris at the end of the installation process. The -r option is required to specify the Solaris release number for which the driver updates apply. The option argument takes the form uname -r output, for examples 5.10, 5.11, etc. If the -d option is specified, the resulting DU directory tree is placed in the directory . If the -o option is specified, a (non-bootable) ISO image of the DU directory tree is written in the file . This ISO image can be burned onto a CD/DVD using cdrw(1) or cdrecord(1). See the Examples section below for an example of creating a DU on a floppy. At least one of -d and -o option must be specified. If both are specified, then both an ISO image and a directory tree are generated. Subcommand updatemedia The updatemedia subcommand takes a list of driver packages and patches as input and applies them to the miniroot of a Solaris install media. It also places them in a subdirectory called ITUs under the Solaris install media's top-level directory: /ITUs When booting a system from the updated media, the patches and packages will be part of the booted Solaris image. They will also be applied to the target system being installed at the end of the installation process. The -R option must be given on the command line to specify the Solaris install media. Note that the install media must necessarily be on a location that's writable by itu. If the -o option is specified, a bootable ISO image of the patched install media is also created in the file . The ISO image can then be burned onto a CD or DVD. Subcommand makeiso The makeiso subcommand runs mkisofs(8) to create a bootable Solaris ISO image of the Solaris install media and writes it to the file . The ISO image file can then be burned onto a CD or DVD with utilities such as cdrw(1) or cdrecord(1). WARNING: The Solaris install media must contain the file /boot/grub/stage2_eltorito, to be written to the media boot sectors. This file will be modified with some boot information, thus it has to be writable. If necessary, save a copy first prior to running this utility. OPTIONS The following options are supported: -d output_dir Directory where the Driver Update directory should be created. -f If output_dir/DU or iso_file already exists, remove it without asking first. -l iso_label Label/volume name of the ISO image (if -o option is specified). -o iso_file Path of ISO image file to create. For subcommands updatemedia and makeiso it will be a bootable ISO image. This option must be specified for subcommand makeiso. -R media_root Top-level directory of on-disk image of Solaris installation media. This option must be specified for subcommand updatemedia. -r solaris_release Solaris release number for which the Driver Update is intended. It takes the form of 5.10. This option must be specified for subcommand makedu. -v Verbose. Multiple -v options increase verbosity." OPERANDS The following operands are supported: package [package ...] One or more driver packages. pkg_or_patch [pkg_or_patch ...] One or more patches and/or packages. media_root The top-level directory of a Solaris install media. EXAMPLES Example 1: Create a Driver Update CD/DVD containing packages SAMPLEpkg1 and SAMPLEpkg2 # itu makedu -r 5.10 -o my.iso SAMPLEpkg1 SAMPLEpkg2 # cdrw -i my.iso Example 2: Create a Driver Update floppy containing driver package MYdriver: # rmformat -F quick /dev/rdiskette # mkfs -F pcfs /dev/rdiskette # mount -F pcfs /dev/diskette /mnt # itu makedu -r 5.10 -d /mnt /export/MYdriver # umount /mnt # dd if=/dev/rdiskette of=floppy.dd The itu command above creates the DU directly onto the floppy mounted on /mnt. The dd call takes an image of the floppy and stores int the file floppy.dd. This is useful for distributing driver update floppy in a file form. From the file, the floppy can then be recreated as follows: # dd if=floppy.dd of=/dev/rdiskette Example 3: Patch the Solaris install media in /export/s10u1 with patch /opt/patches/123456-07 and driver package /opt/pkgs/MYdriver. Also create a bootable ISO image with ISO label "MyS10U1" in the file /tmp/dvd.iso. # itu updatemedia -R /export/s10u1 -o /tmp/dvd.iso -l MyS10U1 /opt/patches/123456-07 /opt/pkgs/MYdriver Example 4: Create bootable ISO image mydvd.iso of the Solaris install image /export/solaris-10u1 with ISO label "Special-S10". # itu makeiso -o mydvd.iso -l "Special-S10" /export/solaris-10u1 # cdrw -i mydvd.iso SEE ALSO cdrecord(1), cdrw(1), patchadd(1m), pkgadd(1m), mkisofs(8) ======================================================================== NAME mkbootmedia - create bootable Solaris ISO image SYNOPSIS /usr/bin/mkbootmedia [-v] [-l