Introduction

The process of customizing or "remastering" Ubuntu install CDs is not especially complex, but it is a little tedious and finicky. This page documents all the problems you might find; if it doesn't, please edit it!

The Ubuntu install CD (since Ubuntu 6.06, the 'alternative install' or 'server' CD) has three main parts: a bootloader (ISOLINUX on amd64/i386 systems, yaboot on powerpc) and its configuration, which start everything up; debian-installer (also known as d-i), which in this case is really a specialised miniature Ubuntu system; and a Debian-style repository structure, which is what takes up all that space on the disk in the directories "pool" and "dists". Building a new CD may involve modifications to all three parts.

Copy the CD to your hard drive

Copy the entire installation CD to a directory on your hard drive. This guide will assume your CD image is in /opt/cd-image/, but you can put it wherever you like. It will take around 1GB of hard drive space.

If you have an ISO file, you can mount it and copy files out of it without burning it to CD: mount -o loop /path/to/iso /some/mountpoint.

You can use rsync to copy the CD, or just

mkdir -p /opt/cd-image
cp -rT /cdrom /opt/cd-image

Be sure to catch the folder .disk - if you try and copy /cdrom/*, it will ignore the .disk folder, as Bash expands the * to mean "everything it can see".

Modify installer behaviour using a Preseed file

When the CD boots up, a Linux kernel is started and the installation tasks are initiated. The installer's default behaviour can be modified through the use of a "preseed" file, which feeds d-i answers to questions normally asked by debconf, or in other contexts. If you look closely at your install CD, you'll see that certain options (e.g. "server", "expert", "oem") already have preseed files assigned to them.

Suppose you are installing Ubuntu on a bunch of identical computers, and you already know the answers to certain questions (what country and time zone you're in, what keyboard you have, how the network should be configured, how you want to partition the hard disk, etc). You can "preseed" the answers to these questions in a very simple configuration file.

Changing isolinux.cfg to identify your preseed

We will create a preseed file called 'firewall.seed', which will live in the /preseed folder of the CD-ROM. We tell d-i where to find this file by modifying the bootloader configuration file, located in isolinux/isolinux.cfg, to pass appropriate parameters on the kernel command line. In /opt/cd-image/isolinux/isolinux.cfg, add a new section labelled like this:

Ubuntu 5.10 and older:

LABEL firewall
  kernel /install/vmlinuz
  append preseed/file=/cdrom/preseed/firewall.seed preseed/locale=en_NZ kbd-chooser/method=us vga=normal initrd=/install/initrd.gz ramdisk_size=12288 root=/dev/rd/0 rw --

Ubuntu 6.06 and newer:

LABEL firewall
  menu label ^Firewall installation
  kernel /install/vmlinuz
  append  preseed/file=/cdrom/preseed/firewall.seed debian-installer/locale=en_NZ kbd-chooser/method=us initrd=/install/initrd.gz ramdisk_size=16384 root=/dev/ram rw quiet --

If you want to set the default action to booting with your custom seed, change the DEFAULT line to read 'DEFAULT firewall'.

You must specify a locale and keyboard on the command line, as these questions are asked before the seed is loaded. You can also set DEBCONF_PRIORITY here to ensure you don't see any unnecessary debconf questions.

Writing the preseed file

A preseed file looks something like this (from the default ubuntu-server.seed on the 6.06 CD):

• # Always install the server kernel.
  d-i     base-installer/kernel/override-image    string linux-server
  # Don't install usplash.
  d-i     base-installer/kernel/linux/extra-packages-2.6  string
  # Desktop system not installed; don't waste time and disk space copying it.
  d-i     archive-copier/desktop-task     string ubuntu-standard
  d-i     archive-copier/ship-task        string
  # Only install the standard system and language packs.
  d-i     pkgsel/install-pattern  string ~t^ubuntu-standard$
  d-i     pkgsel/language-pack-patterns   string
  # No language support packages.
  d-i     pkgsel/install-language-support boolean false

attachment:IconsPage/note.png The version of this file on some Breezy CD images was buggy: it set base-config/package-selection to "~tubuntu-standard" rather than "~t^ubuntu-standard$". Use the new format in preference; the old one will break with Ubuntu 6.06 and newer.)

First notice the format. There are 4 fields:

1. identity of the program which will pick up this command
2. name of the variable whose value will be passed
3. variable type
4. value of variable

attachment:IconsPage/important.png d-i expects there to be [:http://d-i.alioth.debian.org/manual/en.i386/apbs03.html:exactly one tab or space between variable type and variable value] (any other space is seen as being part of the value)

attachment:IconsPage/important.png The version of d-i used in 5.10 does not allow lines to be broken by the '\' character - this was introduced as of 6.06.

The easiest way to create a preseed file is to start with an example and modify it. There is a good [http://archive.ubuntu.com/ubuntu/dists/breezy/main/installer-i386/current/doc/manual/en/apcs01.html preseed example in the Breezy installation manual]. You could also check out [http://wiki.debian.org/DebianInstaller/Preseed Debian's wiki page on preseeding the installer] - 6.06 and higher use the Etch version of the Debian installer.

If you can't find the option you're looking for, try executing the following commands:

debconf-get-selections --installer > somefile.txt
debconf-get-selections >> somefile.txt

This will output a list of all debconf options you've chosen throughout your install; you can pick options out of this and put them into your preseed file.

attachment:IconsPage/warning.png debconf-get-selections prints 2 spaces between variable type and variable value. For Breezy, you need to change this to one space before putting the line in a preseed file.

Installing extra packages in your preseed file

Ubuntu 5.10 and older:

Package installation is controlled by the base-config/package-selection directive in the preseed. To install nothing, you can leave the value blank; to instruct d-i to install extra packages, or a minimal set, set this to an aptitude pattern. (To learn about patterns, see the aptitude documentation -- install aptitude-doc and read /usr/share/doc/aptitude/html/index.html).

For instance, to install an SSH server along with the standard installation, use this line:

base-config base-config/package-selection string ~t^ubuntu-standard$|~n^openssh-server$

Ubuntu 6.06 and newer:

base-config has been removed from debian-installer, so you have to install packages using a different directive. Set preseed/early_command to run apt-install package1 package2.

Installing language support

A different mechanism is used to install additional languages. Preseed the detailed locale question asked by the installer in expert mode. See the first column of /usr/share/i18n/SUPPORTED for the locale names you can use here. For example, to add support for Bengali and Tamil, use this line:

d-i localechooser/supported-locales multiselect bn_IN, ta_IN

Modify pool structure to include/delete packages

Probably the prime motivation to build your own install CDs is to modify which packages are installed; in particular you may want to add some packages to the CD.

The easiest way to do this is to build an 'extras' repository structure, containing only your extra .debs, and merge these into the CD file hierarchy before rebuilding the .ISO image. This guide will step you through how to do this.

This requires you to generate the Packages files that defines what files are in your repository; the Release file that indexes your Packages files, and the signed Release.gpg file, approving the repository as being official.

Create an "Extras" component

Create directories for your new component (substituting your version where appropriate):

cd /opt/cd-image
mkdir -p dists/dapper/extras/binary-i386 pool/extras/ isolinux preseed

Put all the extra .debs you want on your CD into pool/extras.

Create the file dists/dapper/extras/binary-i386/Release with the following content:

• Archive: dapper
  Version: 6.06
  Component: extras
  Origin: Ubuntu
  Label: Ubuntu
  Architecture: i386

On the [:/Scripts:scripts page] there is a useful script that will strip out all of the packages from your CD image that are not currently installed.

Generating a new ubuntu-keyring .deb to sign your CD

In order to sign the Release file, we need to use GPG. The install system will then check the signature against the public keys held in the package ubuntu-keyring. You do not have a private key that matches one of the ones in the shipped ubuntu-keyring, so we need to build a custom version of the ubuntu-keyring package. Install the gnupg package if you do not have it already.

To create a signing key, enter gpg --gen-key. Accept the defaults, (for this use, it is probably OK to use "No expiry"). For your Real Name and E-mail address, you might like to use something like "XXX Signing Key" and "packages@xxx.example.org". Enter an appropriate passphrase.

In another directory (I use /opt/build/), we will download the source for the ubuntu-keyring package, unpack it, add our own GPG key, and rebuild the package. These steps import the 2 Ubuntu public signing keys into your main keyring, then exports them, along with your own public signing key, into a replacement keyring. "YOURKEYID" should be replaced with the 8-digit hexadecimal code that gpg tells you when you do the --list-keys command."Signing Key Name" is what you used in the previous step, when running gpg --gen-key.

Here is an example, which you will need to customize to suit your own setup:

apt-get source ubuntu-keyring
cd ubuntu-keyring-2005.01.12.1/keyrings
gpg --import < ubuntu-archive-keyring.gpg
gpg --list-keys "Signing Key Name"
gpg --export FBB75451 437D05B5 YOURKEYID > ubuntu-archive-keyring.gpg
cd .. (you are now on ubuntu-keyring-2005.01.12.1)
dpkg-buildpackage -rfakeroot -m"Your Name <your.email@your.host> -kYOURKEYID
cd .. (you are now on the directory where you started, in the example, /opt/build)
cp ubuntu-keyring*deb /opt/cd-image/pool/main/u/ubuntu-keyring

You will end up with a udeb file for the installer, and a .deb file for the system. Both files were copied into the main component of your CD, because the CD will not check the extras directory.

Building the repository with apt-ftparchive

In order to use apt-ftparchive, we will need to provide it with some configuration and some index files.

We will put the index files in /opt/indices:

mkdir -p /opt/indices
cd /opt/indices/
DIST=dapper; wget http://archive.ubuntu.com/ubuntu/indices/override.$DIST.{extra.main,main,main.debian-installer,restricted,restricted.debian-installer}

Create the files "apt-ftparchive-deb.conf, "apt-ftparchive-udeb.conf", "apt-ftparchive-extras.conf", and "release.conf" in a directory (/opt/apt-ftparchive), substituting /opt/cd-image/ for the path to your CD image directory, and /opt/indices/ for the location of the index files, if they differ.

apt-ftparchive-deb.conf:

• Dir {
    ArchiveDir "/opt/cd-image/";
  };
  
  TreeDefault {
    Directory "pool/";
  };
  
  BinDirectory "pool/main" {
    Packages "dists/dapper/main/binary-i386/Packages";
    BinOverride "/opt/indices/override.dapper.main";
    ExtraOverride "path/to/indices/override.dapper.extra.main";
  };
  
  BinDirectory "pool/restricted" {
   Packages "dists/dapper/restricted/binary-i386/Packages";
   BinOverride "/opt/indices/override.dapper.restricted";
  ;
  
  Default {
    Packages {
      Extensions ".deb";
      Compress ". gzip";
    };
  };
  
  Contents {
    Compress "gzip";
  };

apt-ftparchive-udeb.conf:

• Dir {
    ArchiveDir "/opt/cd-image/";
  };
  
  TreeDefault {
    Directory "pool/";
  };
  
  BinDirectory "pool/main" {
    Packages "dists/dapper/main/debian-installer/binary-i386/Packages";
    BinOverride "/opt/indices/override.dapper.main.debian-installer";
  };
  
  BinDirectory "pool/restricted" {
    Packages "dists/dapper/restricted/debian-installer/binary-i386/Packages";
    BinOverride "/opt/indices/override.dapper.restricted.debian-installer";
  };
  
  Default {
    Packages {
      Extensions ".udeb";
      Compress ". gzip";
    };
  };
  
  Contents {
    Compress "gzip";
  };

apt-ftparchive-extras.conf:

• Dir {
    ArchiveDir "/opt/cd-image/";
  };
  
  TreeDefault {
    Directory "pool/";
  };
  
  BinDirectory "pool/extras" {
    Packages "dists/dapper/extras/binary-i386/Packages";
  };
  
  Default {
    Packages {
      Extensions ".deb";
      Compress ". gzip";
    };
  };
  
  Contents {
    Compress "gzip";
  };

release.conf

This is the configuration file for apt-ftparchive. Change to suit your distribution version:

• APT::FTPArchive::Release::Origin "Ubuntu";
  APT::FTPArchive::Release::Label "Ubuntu";
  APT::FTPArchive::Release::Suite "dapper";
  APT::FTPArchive::Release::Version "6.06";
  APT::FTPArchive::Release::Codename "dapper";
  APT::FTPArchive::Release::Architectures "i386";
  APT::FTPArchive::Release::Components "main restricted extras";
  APT::FTPArchive::Release::Description "Ubuntu 6.06 LTS";

To build the repository, sign it, and update the MD5SUM file, you can use a script like this:

BUILD=/opt/firewall-image-dapper/
APTCONF=/opt/apt-ftparchive/release.conf
DISTNAME=dapper

pushd $BUILD
apt-ftparchive -c $APTCONF generate /opt/apt-ftparchive/apt-ftparchive-deb.conf
apt-ftparchive -c $APTCONF generate /opt/apt-ftparchive/apt-ftparchive-udeb.conf
apt-ftparchive -c $APTCONF generate /opt/apt-ftparchive/apt-ftparchive-extra.conf
apt-ftparchive -c $APTCONF release $BUILD/dists/$DISTNAME

gpg --default-key "YOURKEYID" --output $BUILD/dists/$DISTNAME/Release.gpg -ba $BUILD/dists/$DISTNAME/Release
find . -type f -print0 | xargs -0 md5sum > md5sum.txt
popd

Burning the CD

At this point, you have a directory which is ready to be collected into an .ISO file and then burnt to a CD.

Building the ISO image

x86 (i386) and x86_64 (AMD64)

IMAGE=custom.iso
BUILD=/opt/cd-image/

mkisofs -r -V "Custom Ubuntu Install CD" \
            -cache-inodes \
            -J -l -b isolinux/isolinux.bin \
            -c isolinux/boot.cat -no-emul-boot \
            -boot-load-size 4 -boot-info-table \
            -o $IMAGE $BUILD

Power PC

Download [http://people.ubuntu.com/~cjwatson/hfs.map the HFS map], then use the following command:

IMAGE=custom.iso
BUILD=/opt/cd-image/

mkisofs -r -V "Custom Ubuntu Install CD" \
            --netatalk -hfs -probe -map hfs.map \
            -chrp-boot -iso-level 2 -part -no-desktop \
            -hfs-bless $BUILD/install \
            -hfs-volid Ubuntu/PowerPC_dapper \
            -o $IMAGE $BUILD

ia64

IMAGE=custom.iso
BUILD=/opt/cd-image/

mkisofs -r -V 'Custom Ubuntu 5.10 install ia64' \
        -o $IMAGE -no-emul-boot \
        -J -b boot/boot.img -c boot/boot.catalog $BUILD

• $IMAGE is just the location of your iso image.

Burning the image to CD

To detect the location of your CD drive, try cdrecord --scanbus. For a primary IDE CD drive on /dev/hdc:

sudo nice -18 cdrecord dev=ATA:0,1,0 --speed=24 --blank=fast -v -gracetime=2 -tao $IMAGE

You will burn a lot of coasters in experimenting with this process, so please use rewritable media!

Testing

You can now boot off your CD. Select the new menu item you created. If you've used preseeding to stop the CD asking questions, the installation could be totally automatic.

Troubleshooting

• If your CD fails to read, try re-burning it, possibly at a slower speed.
• If you get a red d-i screen, check the error message (use Alt-F2, Alt-F3 etc to cycle through the terminals to read the log), and fix your CD appropriately.

See also

Check out some [:/Scripts:install CD customization scripts] that can be used to automate this process.