			BELENIX REMASTERING TOOLKIT
				(For versions 0.4.4 and more)
					Author: Moinak Ghosh

This software consists of a set of shell scripts, utilities and config files
that allows one to customize the BeleniX ISO image and generate modified
LiveCDs also called remastering.

Remastering BeleniX requires a bit of work. Though the scripts automate most
of the process, this is the initial version of this software so some
enhancements are still in the TODO stage.

					CONTENTS

```
Requirements
```

Setting Up

```
Setting up the software
```
```
Preparing the prototype work area
```
```
How it works
```

```
Generating CD Images
```
```
Known Issues
```

Customizing

```
Removing Software
```
```
Adding Software
```

```
Other info
```
```
TODOs
```

1. Requirements

Customizing BeleniX requires two items: The BeleniX ISO image and this software.
Building a customized version of the LiveCD requires a lot of disk space. Also
generating a CD image is time consuming and I/O intensive so a system having a fast
hard disk is recommended The following system requirements are suggested:

Solaris Express build 42 or more OR BeleniX installed to harddisk.
Cdrtools package that are bundled by default in
Solaris Express and BeleniX.
Access to the 'root' user account
BeleniX 0.4.4 or higher ISO image

10GB Free Disk Space
1.5 GHz processor
512MB RAM with 1GB Swap space
7200 RPM harddisk

As a rough estimate these specs will enable the ISO generation script to finish is
less than 2 hours. Building a customized ISO in BeleniX booted from harddisk should
work fine, but has not been tried yet (time constraints).

2. Setting Up

   a. Setting up the software

	To begin with this software installs into /opt/livecdtools. You need to get 
hold of the tarball and extract it from the root directory '/'. Following directory 
hierarchy is created:

	/opt/livecdtools
		|
		|--- bin : All the executable scripts and utilities
		|
		|--- doc : Documentation including this file
		|
		|--- etc : All configuration files
		|
		`--- lib : Utility scripts

You also need a partition with 10GB free disk space where you will have to copy the 
BeleniX ISO image. It is useful to add /opt/livecdtools/bin in your PATH. The most 
important configuration file is /opt/livecdtools/etc/mkbootcd.conf . Take a momment 
to go through this file. There are lots of comments explaining the various 
configuration options which I will not duplicate here.

In essence you require two directory trees. One is called the proto area that 
contains the entire root filesystem tree of all the software in the CDROM. This is 
initially generated using the /opt/livecdtools/bin/set_proto script from a BeleniX 
ISO image. You need to do all your customizations etc. in this proto area. The 
other directory tree is called the staging area. This is dynamically created by the 
ISO generation script and the ISO filesystem tree is assembled here.

   b. Preparing the prototype work area

	The rest of the document will assume that you have extracted the livecd kit 
and the /opt/livecdtools/bin directory is in your PATH. Another assumption is that 
you have a /space directory with 10 GB of free space where you have placed the 
belenix0.4.4.iso file.

The first thing you need to do is to setup the proto area using setup_proto:

setup_proto /space/belenix0.4.4.iso /space/livecd_proto

At this point you can go and have some tea and snacks because setup_proto takes 
quite some time to extract all the contents of BeleniX ISO. The second parameter 
/space/livecd_proto is not required if you have configured it in the 
/opt/livecdtools/etc/mkbootcd.conf file.

After setup_proto finishes /space/livecd_proto will contain a complete OpenSolaris 
root filesystem tree. Take a momment to browse around. The directory 
/space/livecd_proto/usr/foss will contain all the Free and Opensource software and 
the remaining are all OpenSolaris stuff.

One important directory  to look at is /space/livecd_proto/pkgs. This contains 
minimal file lists for all the software packages in the proto area:

/space/livecd_proto/pkgs/ --

mkbootcd.files - Lists all the required OpenSolaris files.

mkbootcd.files.minimal - Lists all the required files that go into the Ramdisk 
image also called Microroot. On the CD the ramdisk image is /boot/x86.microroot.

cdpkg.list - Names of all the software packages that go into the LiveCD.

All the remaining are subdirectories, one per software package. Each package 
subdirectory contains one file having the list of files for that software. It may 
contain a file called "prefix" that mentions the installation directory prefix of 
that software. If this file is absent then the default value is picked from 
/opt/livecdtools/etc/pkgprefix.list . It may also contain a file named "depend" 
that mentions the software packages on which this package depends. The default 
dependencies are listed in /opt/livecdtools/etc/depend.list

NOTE: BeleniX 0.4.4 does not yet have full software packaging. The packaging info 
mentioned here are very minimal file/directory lists.


   b. How it works

	The setup_proto loopback mounts the ISO image and dumps the contents. The
compressed files in the ISO image are uncompressed. There are a couple of utilities 
bundled with the livecd kit: 7za and ldecompress that are used. 7za is the 7zip 
program for unix that uses very efficient alogorithms to achieve the maximum 
compression ratio. 7zip can compress in various formats including LZMA, ZIP, GZIP 
etc and achieves greater compression ratios that the native utilities.

ldecompress is used to decompress the belenix.zlib compressed filesystem image. One 
setup_proto is done. You can do your customizations in the proto area and then 
execute /opt/livecdtools/bin/mkbootcd to create the LiveCD ISO image. This script 
goes through several steps to create the image. The script is highly commented and 
all the steps are explained in detail at the beginning. It is recommended to go 
through the script to get a feel of what is being done.

3. Generating CD Images

   The script /opt/livecdtools/bin/mkbootcd is used to create LiveCD ISO images.
Executing the script without any arguments lists out and explains all the options:

/opt/livecdtools/bin/mkbootcd [-stage <CDROM Staging Directory>]
      [-iso <ISO Image path>] [-nocd]
      [-proto <Proto Directory>] [-nosort] [-ignoredep]

       -nocd will setup the <CDROM Staging Directory> but will not generate the
       compressed /usr filesystem image and the ISO image. This is to test for
       errors.

       -proto specifies the proto directory where the entire filesystem of the OS
       instance for the LiveCD is setup properly. Use setup_proto to generate an
       initial proto from an existing BeleniX ISO image.

       -stage specifies the working directory where the CDROM contents will be
       assembled.

       -nosort instructs not to use a sort file for mkisofs. The sort file
       /opt/livecdtools/etc/iso.sort indicates physical file data layout for boot
       time optimization.

       -ignoredep perform dependency check on included packages but ignore any
       dependency errors.

-proto can be omitted if the parameter ISO_PROTO is setup in mkbootcd.conf.
-iso can be omitted if the parameter ISO_FILE is setup in mkbootcd.conf.
-stage can be omitted if the parameter CD_STAGE is setup in mkbootcd.conf.

So mkbootcd can be executed without any arguments if the mkbootcd.conf file
is properly set up. An example invocation of mkbootcd :

mkbootcd -stage /space/livecd_stage -iso /space/mylivecd.iso
         -proto /space/livecd_proto -ignoredep

After setup_proto step you can try executing mkbootcd which will regenerate
the BeleniX livecd image from the proto area. This will not however include
the jdk.7z install image. The "-ignoredep" option is used due to a known
issue as mentioned below.

4. Known Issues

With the BeleniX 0.4.4 ISO image you will see the folowing dependency check
failures:

DEPENDFAIL: Package tcl required by berkeleydb missing
DEPENDFAIL: Package graphviz required by doxygen missing
DEPENDFAIL: Package tcl required by gaim missing
DEPENDFAIL: Package libgcrypt required by gnupg missing
DEPENDFAIL: Package libgcrypt required by gpgme missing
DEPENDFAIL: Package graphviz required by imagemagick missing
DEPENDFAIL: Package libgcrypt required by libksba missing
DEPENDFAIL: Package tcl required by postgresql missing
DEPENDFAIL: Package tcl required by sqlite missing

This is a known issue and has occurred due to omission of a few packages
to accomodate the JDK install image. The JDK will be removed from BeleniX
LiveCD images after 0.4.4 to be included later in the DVD edition.

You can download these missing packages from:
http://www.genunix.org/distributions/belenix_site/binfiles/pkgextra.tar.gz

Extract the archive within the proto directory - /space/livecd_proto:

cd /space/livecd_proto
gunzip -c /path/to/pkgextra.tar.gz | tar xvpf -

The mkbootcd script will also throw up other warnings and errors during the
file copy phase. These are all okay and can be ignored. These will be fixed
eventually.

5. Customizing

After you have setup the proto you'd obviously want to customize the proto area.
The important files in /space/livecd_proto/pkgs/ have already been described
above. These need to be modified.

* Removing software from LiveCD

The file /space/livecd_proto/pkgs/cdpkg.list contains a list of software package
names one on each line that go into the LiveCD. Each package name refers to a
subdirectory in /space/livecd_proto/pkgs/. You can exclude packages from the
LiveCD by removing or commenting out lines from cdpkg.list. Note that a
dependency check is by mkbootcd performed which will tell you about dependency
issues.

You can do an explicit dependency check using the script:

checkdepends -proto <CDROM prototype directory>

The dependency check generates a log file: /tmp/dependcheck.log. Note that not
all packages necessarily have dependency info since some are leaf packages that
do not depend on anything other than system libraries.

* Adding software to LiveCD

Several steps are required to add software. The convention used in BeleniX is
to use /usr/foss prefix for all Free and Opensource software. To add a new
software package by compiling it from source in my example /space/livecd_proto/
work area I can use the folowing steps:

/usr/foss is my prefix so I will do the loopback mount:

mount -F lofs /space/livecd_proto/usr/foss /usr/foss

Setup the environment:

PATH=/usr/foss/bin:${PATH}
LD_LIBRARY_PATH=/usr/foss/lib:${LD_LIBRARY_PATH}

export PATH LD_LIBRARY_PATH

                 -- OR --

Since /space/livecd_proto/ is a complete root filesystem image I can get the 
proper environment using chroot. So first copy the software source into 
/space/livecd_proto/

"chroot /space/livecd_proto /usr/bin/bash" will give me a chrooted bash shell 
with the BeleniX environment.

NOTE: The chroot mechanism is preferred.

Take a stock of all the files in /usr/foss:

find /usr/foss > /tmp/lst1

Compile and install the software using the usual steps:

./configure --prefix=/usr/foss
make
make install

Repeat the find:

find /usr/foss > /tmp/lst2

Take a diff and get the list of pathnames newly added:

diff /tmp/lst1 /tmp/lst2 | grep "> " | sed 's/> //' > /tmp/lst3

lst3 contains all the files/directories etc added by the newly compiled 
software.

Now you need to add the minimal package info so that the ISO generation 
script can pick it up. First create a subdirectory under pkgs for holding 
minimal package info eg.:

mkdir /space/livecd_proto/pkgs/mynewutil

The /opt/livecdtools/bin/prepare_flist script is provided to generate file 
list information in the proper format. You should execute the script without 
arguments to get detailed help information.

For our example here we can execute:

prepare_flist -f /tmp/lst3 -p /usr/foss
-o /space/livecd_proto/pkgs/mynewutil/mynewutil.files

/usr/foss is our prefix here and each package subdirectory must contain the 
file list info in <subdirectory name>.files.

Now put the prefix info, that is /usr/foss in 
/space/livecd_proto/pkgs/mynewutil/prefix file.

You can add names of dependency packages that are required by this software 
in /space/livecd_proto/pkgs/mynewutil/depend file, one package name per line.

Finally add the package name at the end of 
/space/livecd_proto/pkgs/cdpkg.list so the mkbootcd can pick it up.

Note that some software are essential for the LiveCD to work and must not be
omitted from cdpkg.list. These are listed in /opt/livecdtools/etc/required.list
and mkbootcd performs a check for these packages.

The file /opt/livecdtools/etc/bootcd_skel.files mentions a list of files in 
OpenSolaris that were modified for the LiveCD. It is included even though it is not 
strictly required here. It is possible to include user-specified modified files 
from a different location into the LiveCD. These are existing files that have been 
modified.

In the above example I can create the file 
/space/livecd_proto/pkgs/bootcd_skel.files that list out additional modified files 
in the proper format. The file /space/livecd_proto/pkgs/bootcd_skel.src must 
contain the directory name from where all these modified files are to be copied.

6. Other Info

Some other files in /opt/livecdtools/etc are:

archive.list - This contains a list of file/directory names that are compressed in 
archive.tar.7z in the LiveCD. These are not strictly required to make the LiveCD 
work but are required after harddisk install. The archive.tar.7z can be omitted 
from the LiveCD using -noarchive option to mkbootcd to save space for purely LiveCD 
or DemoCD usage, where harddisk install is not intended.

iso.sort - This is a sort file for mkisofs. This instructs mkisofs to layout the 
file data in the ISO image in the given order. This is used to reduce boot time. 
See the -sort option of mkisofs for more details. Sorting may be omitted using the 
-nosort option to mkbootcd.

modules_relocate.list - This file is used to relocate some kernel modules from 
/kernel and /platform/kernel to /usr/kernel. This reduces space requirements on the 
ramdisk. The modules are relocated back to their original locations by setup_proto. 
You will not need to fiddle with this file.

7. TODOs

This software is a work in progress and this initial release does have some issues 
and limitations. The following improvements are planned:

Make it easier to add new software. With the addition of packaging based on 
Pkgsrc this should become much easier.

More intelligent handling of customizations. Changes to a default BeleniX 
proto should be logged and archived, so that they can be applied easily when 
a new proto is initialized from a subsequent BeleniX release.

Make it easy to customize the ramdisk. Currently the file 
mkbootcd.files.minimal must be edited.

```
Add GUI wrappers
```

Please send your suggestions/modifications to moinakg2002 (at) yahoo (dot) com .