Cross Reference: /caiman/distro_constructor/README

This tool can be used to create a Live CD/DVD or a Live USB image from a
given list of packages.

The script retrieves the list of packages from the specified IPS repository
server, prepares the X86 microroot, does additional processing for
creating a bootable live CD, and then creates an ISO that can be
burned into a CD/DVD.  The script can also convert
the ISO into a USB image that is suitable for writing to a USB drive.

The following is a high-level description of the steps the Distribution
Constructor completes in order to create a bootable live CD.

The Constructor...

1) Loads your configuration file.

2) Populates the proto area with the list of packages specified.

3) Populates the microroot from the proto area

4) Completes special setup for the Live CD.  This setup is done in the
   livemedia_processing() function in src/build_dist.lib.

   The preparations includes running all the postinstall scripts
   to setup GNOME; setting up the font cache; preloading the SMF repository;
   creating symlinks between the microroot and the proto area;
   and finally creating a boot archive with all the files installed into
   the microroot.

5) Invoke mkisofs to build a bootable iso image containing the
   entire contents of our proto directory. Grub's eltorito stage2 bootloader
   is used, that enables booting directly off a CD/DVD. We violate the ISO9660
   specs somewhat to accomodate file properties essential for a proper Unix
   file/directory layout.


Pre-requisites to using the Distribution Constructor:
------------------------------------------------------
- To use this kit, you need to have root access to the system on which the
resulting image are to be created.

- The system on which you are using the kit must be a x86 system running
  Solaris Nevada build 71 or above.  Sparc is not supported at this time.

- You need to have access to an IPS repository server.

Usage:
------

To create a Live CD/DVD or USB image, invoke the "build_dist.bash"
script with your configuration file as an argument.  For example:
	# ./build_dist.bash test1.conf


Configuration file:
-------------------

The configuration file is used to specify different parameters used
for creating the image.  The "dist.conf" file is a skeleton file
containing all the parameters.  You can make a copy of this file,
and fill in your values.

To view a sample file, see test_data/test1.conf.

The following parameters are required:

DIST_PKG_LIST:
	Full path to a file containing list of packages to be
	included in distribution.  The list of package names
	should be one per line in the file.  test_data/pkg.txt
	is the file used for creating the Slim CD prototype.

DIST_PKG_SERVER:
	Name of the IPS server containing the packages.  Note:
	in this prototype release, we only support specifying
	one IPS server.

DIST_PROTO:
	The proto directory where the filesystem hierarchy for
	the distribution is created.  If this directory does not
	currently exist, it will be created.  If this directory
	exists, and there's content in it, all contents will be removed.

DIST_ISO:
	The full path to the ISO file to be created.  If this file
	already exists, it will be overwritten with the new file.

DIST_ID:
	Name of this image.

DIST_ISO_SORT:
	Sort list for the /usr file system on the CD.  This is used
	for optimizing the run time of the CD.  test_data/iso.sort
	is the file used for the Slim CD prototype release.

COMPRESSION_TYPE:
	Specifies the compression type to use when compressing solaris.zlib
	and solarismisc.zlib.
	You must specify a compression type that is allowed by lofiadm.

The following parameters are optional:

DIST_USB:
	The full path to the USB file for the USB image
	If this value is not specified, the USB image will not be
	created.  If the USB file exists, it will be overwritten
	with the new file.

QUIT_ON_PKG_FAILURES:
	Acceptible values are yes or no. Yes means that if the
	package adds fail, the entire build is aborted. No means that if
	the package adds fail, continue on. The default value is yes.

DIST_ADDITIONAL_MOD:
	If additional changes need to be made to the image before the image
	is created, these changes can be passed into the Distro Constructor
	code as an archive.

	The archive must contain at least one script with the
	name "post-process".  If no script with the name
	"post-process" is found in the root of the
	archive, the archive will be ignored.

--------------------------------------------------------
Brief Overview of the structure of the source code:
--------------------------------------------------------

The source code for the Distribution Constructor toolkit for the preview
release is a collection of scripts.  This is based on work that's
previously done in the Live Media Project.
See http://opensolaris.org/os/project/livemedia/

src:
----

The src directory contains all the code used to create the ISO image.

build_dist.bash:
	Main script
build_dist.lib:
	Supporting functions for the main script.
pkg_retrieve.lib:
	Functions for installing packages from the IPS repository.
dist.conf:
	Skeleton configuration file.  Make a copy of this file and fill it
	out to specify your own configuration.
mkrepo:
	Pre-registers SMF services for the Live CD.
generic_live.xml:
	Used by "mkrepo" script above.
usr_microroot_files:
	List of files for the /usr directory for the microroot.  This file
	is a "hack" for the prototype.  In order to reduce the size of the
	microroot, only files that are critical for the Live CD during boot
	are included.
var_microroot_files:
	List of files for the /var directory for the microroot. Only files that
	are needed for the Live CD to boot are included.
postrun_scripts:
	This directory contains some SVR4 postinstall scripts that do
	postrun.  Since IPS doesn't support postinstall scripts, and the
	postrun command depends on some SVR4 information,  this setup is
	a "hack".  This "hack" is necessary to run all
	the postinstall scripts needed to setup GNOME.

test_data/
-----------

pkgs.txt:
	List of packages used for creating the Slim CD prototype.  Note:
	slim_install is a cluster of packages defined in the IPS server.
	So, name of individual packages doesn't need to be specified.
test1.conf:
	sample configuration file.
iso.sort:
	This is used for optimizing the run time of the CD for the
	Slim CD prototype.

tools/
------
usbgen:
	Generates a USB file that is suitable for USB drives based on an ISO.

usbcopy:
	Copies the file generated by usbgen to your USB drive.

proc_slist.pl:
proc_tracedata:
	Used for generating the iso.sort file.

listusb:
	A binary used by usbgen.

extract_postrun:
	A convenience script that extracts all the postinstall scripts
	from SVR4 packages that contain postrun calls.