UCK - documentation of building script

# Ubuntu Customization Kit

## Documentation for building script

### Introduction

Live CD building script (./remaster-live-cd) is used to build live CD image automatically.
It provides means to customize live CD image in many ways:

- Customization of root filesystem (squashFS) contents through installation or removal of packages or any other scriptable changes.
- Customization of ISO image.
- Customization of initrd image.

### Invocation

Building script should be invoked in such way:
./remaster-live-cd path-to-iso-file.iso customization-dir/
Parameters:

- path-to-iso-file.iso - path to file with image of Ubuntu Live CD which will be used as a base for building customized live CD image. It can be any image from Ubuntu family - Ubuntu, Kubuntu, Edubuntu or Xubuntu.
- customization-dir/ - path to directory containing customization scripts

### Customization directory

Customization directory can contain the following files:

- customize - script for customization of root filesystem. See customize script description.
- customize_initrd - script for customization of initrd. See customize_initrd script description.
- customize_iso - script for customization of ISO image. See customize_iso script description.
- rootfs.sort - sort file used for sorting files in SquashFS. See "man mksquashfs" option -sort.
- iso_description - Title of ISO image.
- run_manual_customizations - Tells the system that you want to do advanced customizations within the rootfs. This will stop the remastering process at a certain point and raise a menu, you'll be able to choose if you want to open a terminal or run a package manager, all within the rootfs.
- mkisofs_extra_options - Extra options passed to mkisofs command. Note that these options cannot contain strings with quotes (") as they are passed to mkisofs commandline.
- keep_initrd_extraction - If this file is present the extracted initrd won't be deleted after processing.
- keep_rootfs_extraction - If this file is present the extracted rootfs won't be deleted after processing.
- keep_iso_extraction - If this file is present the extracted ISO won't be deleted after processing.

#### Script customize

If this script is present, SquashFS root filesystem is unpacked, script is run and filesystem image repacked after customization.
Note: Packing (compressing) SquashFS filesystem is long and CPU-intensive task. Do not include this script in customization directory if you are not modifying contents of root filesystem.
This script is run in chrooted environment in directory of live CD root filesystem.
Due to this fact, there is no access to files outside of live CD root filesystem.
However, the whole contents of customization directory is copied to chroot environment, so it is accessible.
In this script, it is possible to use any commands, like in normal Ubuntu system.
In particular:

- You can use "apt-get install package-name" to install packages. All standard repositories (as enabled on CD) are available.
- You can use "apt-get remove package-name" to remove unnecessary packages.
- You can use cp, mv, sed, etc. to modify contents of files on CD.

Note: After script is run, temporary directories contents (in particular /tmp) is purged before building CD.
For examples of usage of script see customize-dir-examples/ subdirectories.

#### Script customize_initrd

If this script is present, initrd (initial ramdisk) image is unpacked, script is run and initrd image is repacked after customization.
Initrd contains kernel modules and scripts used right after boot of Linux kernel to locate and mount root filesystem.
You can exchange these modules/scripts with your customized versions or you can add some modules, for example to support some exotic hardware during boot.
This script is run in context of your system.
Location of initrd image directory is passed in INITRD_REMASTER_DIR environment variable.
In Bash scripts you can use $INITRD_REMASTER_DIR to access it.
For examples of usage of script see customize-dir-examples/ subdirectories.

#### Script customize_iso

If this script is present, it is run before repacking ISO image in order to customize contents of image.
You can add or remove files on CD, for example add some documentation, tools needed to boot CD, etc.
This script is run in context of your system.
Location of initrd image directory is passed in ISO_REMASTER_DIR environment variable.
In Bash scripts you can use $ISO_REMASTER_DIR to access it.
For examples of usage of script see customize-dir-examples/ subdirectories.

Updated for UCK v1.1, June 22nd 2006.