README

here's a quick guide to using simple-cdd... 

Quick Start (from http://wiki.debian.org/Simple-CDD/Howto)

To try Simple-CDD, on a Debian system:

Install simple-cdd (as root):

 # apt-get install simple-cdd

Create a working directory (as a user):

 $ mkdir ~/my-simple-cdd
 $ cd ~/my-simple-cdd

Build a basic CD:

 $ build-simple-cdd

This will create a partial package mirror in the directory tmp/mirror,
and if all goes well, an .iso CD image in the "images" directory when
it is finished.  Logs are generated in tmp/log, and tmp/log/TOOL
documents the variables exported to each tool and the command invoked
by the corresponding module. All variables are documented in
simple_cdd/variables.py.

By default, target CDD release version is the same as the host
version. You can specify the optional argument --dist to change the
targets version. For example, it can be etch, lenny, sid, etc.

If this step doesn't work, you need to figure out why before trying more
complicated things.

Create a profile named NAME:

 $ mkdir profiles
 $ for p in list-of-packages-you-want-installed ; do echo $p >> profiles/NAME.packages ; done

Note that you should not include package dependencies, but only the packages
you actually want.

Build the CD with selected profile NAME:

 $ build-simple-cdd --profiles NAME

This should create an .iso CD image in the "images" directory when it is
finished with your custom profile.

Use qemu to test:

 # apt-get install qemu
 $ build-simple-cdd --qemu --profiles NAME

Optional features:

If you want debconf preseeding, put a debconf-set-selections compatible file
into profiles/NAME.preseed.

If you want a custom post-install script, place it in profiles/NAME.postinst.

For more options:

 $ build-simple-cdd --help


The Less Quick Start

Preparing a Simple-CDD Working Directory

 mkdir my-cdd
 cd my-cdd


Profiles

create the profiles directory:

 mkdir profiles

to make a custom profile, think of a name for it, such as "x-basic".

edit or create files in the "profiles" directory, beginning with the profile
name, and ending in .preseed, .packages, .downloads, etc. for example:

profiles/x-basic.preseed 
profiles/x-basic.packages
profiles/x-basic.downloads

 *.description

 short, one-line description of what the profile does

 *.packages
 
 packages installed when the profile is selected.  do not include packages such
 as linux-image or grub, as debian-installer will handle these specially.

 *.downloads
 
 additional packages included on a CD providing the profile, but not installed
 by simple-cdd (though debian-installer may install them)

 *.preseed
 
 debconf questions loaded if the profile is selected

 *.postinst
 
 profile-specific post-install script. runs in the "finish-install" phase of
 debian-installer.

 *.conf
 
 profile-specific configuration settings. sourced during CD build.


to build a CD image with the x-basic profile:

 build-simple-cdd --profiles x-basic

when installing from the CD, a menu should pop up asking you which profiles you
want to install. select all the profiles you want, and the debconf preseed
files will populate the debconf database, and the packages will be installed. 


Default Profile

the profile named "default" is special, because it always gets installed.

modify the profile/default.* files with care, as simple-cdd relies upon the
default profile working in certain ways (such as installing the
simple-cdd-profiles .udeb).


Debconf Preseeding

debconf preseeding is a way to pre-answer the questions asked during package
installation and debian-installer.

it uses the debconf-set-selections format. for more information on the format:

 man debconf-set-selections

profiles/default.preseed is loaded after the debian-installer CD is mounted.
other profiles preseed files are loaded when the simple-cdd-profile .udeb is
installed. some questions may have to be passed at the boot prompt(see below),
as they are asked before any of the preseed files are loaded.

the following question is used by simple-cdd, modify at your own risk:

 d-i preseed/early_command


Automatically Selecting Profiles

to automatically select profiles, in profiles/default.preseed, uncomment the
line:

 simple-cdd simple-cdd/profiles multiselect 

and add all profiles you want, separated by commas, i.e.:

 simple-cdd simple-cdd/profiles multiselect x-basic, ltsp

alternately, use the --auto-profiles commandline option:

 build-simple-cdd --profiles x-basic,ltsp --auto-profiles x-basic,ltsp


Language and Country Selection

to pre-select the language and country, it is recommended to use the --locale
commandline option:

 build-simple-cdd --locale en_US


Configuration Files

to specify a configuration file:

 build-simple-cdd --conf my-cdd.conf

in my-cdd.conf, include values like

 locale=en_US
 profiles="x-basic,ltsp"
 auto_profiles="x-basic,ltsp"
 debian_mirror="http://my.local.mirror/debian"

you can also specify configuration files on a per-profile basis, in
profiles/<profile>.conf.


Passing Boot Prompt Parameters

to pass boot parameters, set KERNEL_PARAMS in a configuration file. the
following example adds the default.preseed file (needed for simple-cdd to
function) and disables power management (acpi):

 export KERNEL_PARAMS="preseed/file=/cdrom/simple-cdd/default.preseed acpi=off"


Build the CD

 build-simple-cdd

now the mirroring tools will download lots and lots of files.

then CD image will be built, and appear as a file in the "images" directory,
such as "debian-40-i386-CD-1.iso"


Testing With Qemu

you can test that your image works using qemu...

 apt-get install qemu

 build-simple-cdd --qemu --profiles x-basic

this will build the CD image using the profile x-basic, run qemu to install it,
and then run qemu for the initial boot into the system.


Testing With Qemu in Non-Graphical Mode

i tested this code out entirely with qemu over a slow ssh connection,
so i needed to figure out how to get serial console working...

 build-simple-cdd --qemu --profiles x-basic --serial-console


More Fun and Adventures

Post and Pre Installation Hooks

if you need to do some customization that cannot be handled by debconf
preseeding, write a script doing what you need to do... and copy that script to
either:

 default.postinst (for all installs)

or

 <profile>.postinst (for profile-specific post-install)


Totally Automatic Partitioning

since automatically over-writing the data on the hard-drive could be
destructive, it is disabled by default.

to enable it, edit profiles/default.preseed and uncomment the following three
lines:

 d-i partman/confirm_write_new_label boolean true
 d-i partman/choose_partition select Finish partitioning and write changes to disk
 d-i partman/confirm   boolean true

Using contrib and non-free

if you want to add packages from contrib or non-free, add them to the
mirror_components in a configuration file:

 mirror_components="main contrib non-free"

if you're using a mirror that uses different components, add them to
mirror_components_extra in a configuration file:

 debian_mirror_extra="http://some.mirror.org/debian/"
 mirror_components_extra="contrib non-free"