Debian Live Handbuch

Debian Live Project

2.0~a2

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-3 file.

2010-06-18


Table of Contents

1. About
1.1. About this manual
1.1.1. Terms
1.1.2. Authors
1.1.3. Contributing to this document
1.2. Über das Debian Live Projekt
1.2.1. Motivation
1.2.2. Philosophy
1.2.3. Contact
I. User
II. Development
III. Project
IV. Other
2. Installation
2.1. Requirements
2.2. Installing live-helper
2.2.1. From the Debian repository
2.2.2. From source
2.2.3. From 'snapshots'
2.2.4. live-initramfs
3. The basics
3.1. What is a live system?
3.2. First steps: building an ISO image
3.2.1. Testing an ISO image with Qemu
3.2.2. Testing an ISO image with virtualbox-ose
3.2.3. Testing an ISO image with VMware Workstation
3.2.4. Burning an ISO image to a physical medium
3.3. Building an USB/HDD image
3.3.1. Copying USB/HDD image to a USB stick
3.3.2. Testing a USB/HDD image with Qemu
3.3.3. Testing an USB/HDD image with VMware Workstation
3.3.4. Using the space left on a USB stick
3.4. Building a netboot image
3.5. Netboot testing HowTo
4. Overview of tools
4.1. live-helper
4.1.1. The lh config helper
4.1.2. The lh build helper
4.1.3. The lh clean helper
4.2. The live-initramfs package
5. Customization
5.1. Customising package installation
5.1.1. Package sources
5.1.2. Package installation
5.1.3. Installing additional packages
5.1.4. Installing modified or third-party packages
5.2. Customising contents
5.2.1. Includes
5.2.2. Hooks
5.2.3. Preseeding Debconf questions
5.2.4. Symlink conversion
5.3. Customising Locale And Language
5.3.1. Default locale and keyboard
5.3.2. l10n Packages
5.4. Customising the bootup process
5.4.1. Kernel
5.4.2. Bootloaders
5.4.3. Splash screens
5.4.4. Memtest
5.4.5. Startup scripts
5.4.6. Cheat codes
5.5. Customising the binary image
5.5.1. ISO metadata
5.6. Using a newer kernel with Lenny
6. Common tasks
6.1. The Debian Installer
6.2. WiFi Connection
7. The Live environment
7.1. Swap space
7.2. Hostname
7.3. The Live user
7.4. Language
7.5. Persistence
7.5.1. Full persistence
7.5.2. Home automounting
7.5.3. Snapshots
7.5.4. Persistent SubText
7.5.5. Partial remastering
8. Frequently asked questions (FAQ)
9. Reporting bugs
9.1. Known issues
9.2. Rebuild from scratch
9.3. Use up-to-date packages
9.4. Collect information
9.5. Use the correct package to report the bug against
9.6. Do the research
9.7. Where to report bugs
10. Howtos
10.1. ISO
10.2. ISO_(multiarch)
11. Coding Style
11.1. Compatibility
11.2. Indenting
11.3. Wrapping
11.4. Variables
11.5. Miscellaneous
12. Procedures
12.1. Udeb Uploads
12.2. Major Releases
12.3. Point Releases
12.3.1. Point release announcement template
13. Resources and links
13.1. Links
13.2. English sources related to debian live
13.3. German sources related to debian live
13.4. Spanish sources related to debian live
14. Use Cases
14.1. VNC Kiosk Client
15. Success Stories
16. Hints for troubleshooting
A. Configuration layout
B. Configuration files
B.1. The config/binary file
B.2. The config/bootstrap file
B.3. The config/chroot file
B.4. The config/common file
B.5. The config/source file

Chapter 1. About

1.1. About this manual

The main goal of this manual is to serve as a single access point to all documentation related to the Debian Live project. It does not include end-user documentation for using a Debian Live system as far as things are live specific.

Some of the commands mentioned in the text must be executed with superuser privileges which can be obtained by becoming the root user via su or by using sudo. To distinguish between commands which may be executed by an unprivileged user and those requiring superuser privileges, commands are prepended by $ or # respectively. This symbol is not a part of the command.

1.1.1. Terms

Live system

An operating system that can boot without installation to a hard drive. Live systems do not alter local operating system(s) or file(s) already installed on the computer hard drive unless instructed to do so. Live systems are typically booted from media such as CDs/DVDs or USB sticks, some may also boot over the network.

Debian Live

The Debian sub-project which maintains the live-helper, live-boot and live-config packages.

Debian Live Projekt

A live system that uses software from the Debian operating system that may be booted from CDs, DVDs, USB sticks, over the network (via netboot images), and over the internet (via boot parameter fetch=URL)

Build system/host system

The environment used to create the live system.

live-helper

A collection of scripts used to build customised Debian Live systems. live-helper was formerly know as live-package.

live-boot

A collection of scripts used to boot live systems. live-boot was formerly a part of live-initramfs.

live-config

A collection of scripts used to configure a live systems during the boot process. live-config was formerly a part of live-initramfs.

Debian Installer/(d-i)

The official installation system for the Debian distribution.

Cheat codes

FIXME

chroot

The chroot program, chroot(8), enables us to run different instances of the GNU/Linux environment on a single system simultaneously without rebooting.

binary image

On a live system, binary image refers to the binary filesystem and the respective extension, such as binary.iso or binary.img.

Target distribution

The distribution upon which your live system will be based. This can differ from the distribution of your Build System.

lenny/squeeze/sid stable/testing/unstable

The "stable" distribution contains the latest officially released distribution of Debian. The "testing" distribution is the staging area for the next stable release. A major advantage of using this distribution is that it has more recent versions of software relative to the "stable" release. The "unstable" distribution is where active development of Debian occurs. Generally, this distribution is run by developers and those who like to live on the edge.

At the time of writing, lenny is the current "stable" release and squeeze is the current "testing" release. sid will always be a synonym for the "unstable" release.

1.1.2. Authors

A list of authors (in alphabetical order):

  • Ben Armstrong

  • Brendan Sleight

  • Chris Lamb

  • Daniel Baumann

  • Franklin Piat

  • Jonas Stein

  • Kai Hendry

  • Marco Amadori

  • Mathieu Geli

  • Matthias Kirschner

  • Richard Nelson

  • Trent W. Buck

1.1.3. Contributing to this document

This manual is intended as a community project and all proposals for improvements and contributions are extremely welcome. The preferred way to submit a contribution is to send it to the mailing list. Please see Section 1.2.3, “Contact” for more information.

When submitting a contribution please clearly identify its copyright holder and include the licensing statement. Note that to be accepted the contribution must be licensed under the same license as the rest of the document, namely GPL version 3 or later.

The sources for this manual are maintained using the Git version control system. You can checkout the latest copy by executing:

$ git clone git://live.debian.net/git/live-manual.git

Prior to submission of your contribution, please preview your work. To preview the live-manual, ensure the packages needed for building are installed by executing:

# apt-get install dblatex docbook-xml docbook-xsl make po4a w3m

You may build the live-manual from the top level directory of your git checkout by executing:

$ make build

1.1.3.1. Applying patches

Directly commiting to the repository is possible by anyone. However, we ask you to send bigger changes to the mailinglist to discuss them first. In order to push to the repository, the following steps are required.

  • Fetch the public commit key:

    $ mkdir -p ~/.ssh/identity.d $ wget http://live.debian.net/other/openssh/repository-public-commit-key-current/live-manual@debian-live -O ~/.ssh/identity.d/live-manual@debian-live $ wget http://live.debian.net/other/openssh/repository-public-commit-key-current/live-manual@debian-live.pub -O ~/.ssh/identity.d/live-manual@debian-live.pub $ chmod 0600 ~/.ssh/identity.d/live-manual@debian-live*

  • Add the following section to your openssh-client config:

     $ cat >> ~/.ssh/config << EOF Host live.debian.net Hostname live.debian.net User gitosis IdentityFile ~/.ssh/identity.d/live-manual@debian-live EOF

  • Checkout a clone of the manual through ssh:

    $ git clone gitosis@live.debian.net:/live-manual.git

  • Commit the file after editing. Write commit messages, that consist of full useful sentences, starting with a capital letter and ending with a full stop. Usually starting with the form 'Fixing/Adding/Removing/Correcting/':

    $ git commit -a

  • Push the commit to the server:

    $ git push

1.2. Über das Debian Live Projekt

1.2.1. Motivation

1.2.1.1. What is wrong with current live systems

When Debian Live was initiated, there were already several Debian based live systems available and they are doing a great job. From the Debian perspective most of them have one or more of the following disadvantages:

  1. They are unofficial projects, developed outside of Debian.

  2. They mix different distributions, e.g. testing and unstable.

  3. They support i386 only.

  4. They modify the behaviour and/or appearance of packages by stripping them down to save space.

  5. They include unofficial packages.

  6. They ship custom kernels with additional patches that are not part of Debian.

  7. They are large and slow due to their sheer size and thus not suitable for rescue issues.

  8. They are not available in different flavours, e.g. CDs, DVDs, USB-stick and netboot images.

1.2.1.2. Why create our own live system?

Debian is the Universal Operating System: Debian has an official live system for showing around and to officially represent the true, one and only Debian system with the following main advantages:

  1. It would be an official Debian subproject.

  2. It reflects the (current) state of one distribution.

  3. It runs on as many architectures as possible.

  4. It consists of unchanged Debian packages only.

  5. It does not contain any unofficial packages.

  6. It uses an unaltered Debian kernel with no additional patches.

1.2.2. Philosophy

1.2.2.1. Only unchanged, official packages

We will only use official packages from the Debian repository in the "main" section. The non-free section is not part of Debian and therefore cannot be used at all for official live system images.

We will not change any packages. Whenever we need to change something, we will do that in coordination with its package maintainer in Debian.

As an exception, our own packages such as live-helper, live-boot or live-config may temporarily be used from our own repository for development reasons (e.g. to create development snapshots). They will be uploaded to Debian on a regular basis.

1.2.2.2. No package configuration of the live system

In this phase we will not ship or install sample or alternative configurations. All packages are used in their default configuration as they are after a regular installation of Debian.

Whenever we need a different default configuration, we will do that in coordination with its package maintainer in Debian.

A system for configuring packages is provided using debconf in lh config (use --preseed FILE) allowing custom configured packages to be installed in your custom produced Debian Live images, but for official live images only default configuration will be used. For more information, please see Chapter 5, Customization.

Exception: There are a few essential changes needed to bring a live system to life (e.g. configuring pam to allow empty passwords). These essential changes have to be kept as minimal as possible and should be merged within the Debian repository if possible.

1.2.3. Contact

Mailing list

The primary contact for the project is the mailing list. You can email the list directly by addressing your mail to . The list archives are also available.

IRC

A number of users and developers are present in the #debian-live channel on OFTC. When asking a question on IRC, please be patient for an answer. If no answer is forthcoming, please email the mailing list.

BTS

The Debian Bug Tracking System (BTS) contains details of bugs reported by users and developers. Each bug is given a number, and is kept on file until it is marked as having been dealt with. For more information, please see Chapter 9, Reporting bugs.

Wiki

The Debian Live wiki is a place to gather information, discuss applied technologies, and document frameworks of Debian Live systems that go beyond the scope of this document.

Part I. User

Part II. Development

Part III. Project

Part IV. Other

Table of Contents

2. Installation
2.1. Requirements
2.2. Installing live-helper
2.2.1. From the Debian repository
2.2.2. From source
2.2.3. From 'snapshots'
2.2.4. live-initramfs
3. The basics
3.1. What is a live system?
3.2. First steps: building an ISO image
3.2.1. Testing an ISO image with Qemu
3.2.2. Testing an ISO image with virtualbox-ose
3.2.3. Testing an ISO image with VMware Workstation
3.2.4. Burning an ISO image to a physical medium
3.3. Building an USB/HDD image
3.3.1. Copying USB/HDD image to a USB stick
3.3.2. Testing a USB/HDD image with Qemu
3.3.3. Testing an USB/HDD image with VMware Workstation
3.3.4. Using the space left on a USB stick
3.4. Building a netboot image
3.5. Netboot testing HowTo
4. Overview of tools
4.1. live-helper
4.1.1. The lh config helper
4.1.2. The lh build helper
4.1.3. The lh clean helper
4.2. The live-initramfs package
5. Customization
5.1. Customising package installation
5.1.1. Package sources
5.1.2. Package installation
5.1.3. Installing additional packages
5.1.4. Installing modified or third-party packages
5.2. Customising contents
5.2.1. Includes
5.2.2. Hooks
5.2.3. Preseeding Debconf questions
5.2.4. Symlink conversion
5.3. Customising Locale And Language
5.3.1. Default locale and keyboard
5.3.2. l10n Packages
5.4. Customising the bootup process
5.4.1. Kernel
5.4.2. Bootloaders
5.4.3. Splash screens
5.4.4. Memtest
5.4.5. Startup scripts
5.4.6. Cheat codes
5.5. Customising the binary image
5.5.1. ISO metadata
5.6. Using a newer kernel with Lenny
6. Common tasks
6.1. The Debian Installer
6.2. WiFi Connection
7. The Live environment
7.1. Swap space
7.2. Hostname
7.3. The Live user
7.4. Language
7.5. Persistence
7.5.1. Full persistence
7.5.2. Home automounting
7.5.3. Snapshots
7.5.4. Persistent SubText
7.5.5. Partial remastering
8. Frequently asked questions (FAQ)
9. Reporting bugs
9.1. Known issues
9.2. Rebuild from scratch
9.3. Use up-to-date packages
9.4. Collect information
9.5. Use the correct package to report the bug against
9.6. Do the research
9.7. Where to report bugs
10. Howtos
10.1. ISO
10.2. ISO_(multiarch)
11. Coding Style
11.1. Compatibility
11.2. Indenting
11.3. Wrapping
11.4. Variables
11.5. Miscellaneous
12. Procedures
12.1. Udeb Uploads
12.2. Major Releases
12.3. Point Releases
12.3.1. Point release announcement template
13. Resources and links
13.1. Links
13.2. English sources related to debian live
13.3. German sources related to debian live
13.4. Spanish sources related to debian live
14. Use Cases
14.1. VNC Kiosk Client
15. Success Stories
16. Hints for troubleshooting
A. Configuration layout
B. Configuration files
B.1. The config/binary file
B.2. The config/bootstrap file
B.3. The config/chroot file
B.4. The config/common file
B.5. The config/source file

Chapter 2. Installation

2.1. Requirements

Building Debian Live images has very few system requirements:

  1. Super user (root) access

  2. An up-to-date version of live-helper

  3. A POSIX-compliant shell, such as bash or dash.

  4. debootstrap or cdebootstrap

  5. Linux 2.6.x

Note that using Debian or a Debian-derived distribution is not required - live-helper will run on almost any operating system with the above requirements.

2.2. Installing live-helper

You can install live-helper in a number of different ways:

  1. From the Debian repository

  2. From source

  3. From snapshots

  4. From backports.org

If you are using lenny or sid the recommended way is to install live-helper via the Debian repository.

2.2.1. From the Debian repository

Simply install live-helper like any other package:

# apt-get install live-helper

or

# aptitude install live-helper

2.2.2. From source

live-helper is developed using the Git version control system. On Debian systems, this is provided by the git-core package. To check out the latest code, execute:

$ git clone git://live.debian.net/git/live-helper.git

You can build and install your own Debian package by executing:

 $ cd live-helper $ dpkg-buildpackage -rfakeroot -b -uc -us $ cd .. # dpkg -i live-helper*.deb 

You can also use a local version of live-helper without installation:

# live-helper/helpers/lh_local

Subsequent calls to lh_-prefixed helpers in that shell environment will then use the version located in the directory you executed lh_local from.

You can also install live-helper directly to your system by executing:

# make install

2.2.3. From 'snapshots'

If you do not wish to build or install live-helper from source, you can use snapshots. These are built automatically from the latest version in Git and are available on http://live.debian.net/debian.

2.2.4.  live-initramfs

N.B. You do not need to install live-initramfs on your system to create customised Debian Live systems. However, doing so will do no harm.

2.2.4.1. Using a customised live-initramfs

To modify the code you can follow the process below. Please ensure you are familiar with the terms mentioned in Section 1.1.1, “Terms”.

  1. Checkout the live-initramfs source

    $ git clone git://live.debian.net/git/live-initramfs.git
  2. Make changes to your local copy

    And beware that if you want to add your pre-init script in live-bottom, you should name it without dashes '-', e.g: call it "81new_feature" and not "81new-feature".

  3. Build a live-initramfs .deb

    You must build either on your target distribution or in a chroot containing your target platform: this means if your target is lenny then you should build against lenny. You can use a personal builder such as pbuilder to automate building packages in chroot. To build directly on the target platform, use dpkg-buildpackage (provided by the dpkg-dev package):

     $ cd live-initramfs $ dpkg-buildpackage -rfakeroot -b -uc -us 
  4. Use the generated live-initramfs .deb

    As live-initramfs is installed by the build system, installing the package in the host system is not sufficient: you should treat the generated .deb like another custom package. Please see Section 5.1.4, “Installing modified or third-party packages” for more information. You should pay particular attention to Section 5.1.4.3, “Custom packages and APT”.

2.2.4.2. Using live-initramfs snapshots

You can let live-helper automatically use the latest snapshot of live-initramfs by configuring a third-party repository in your live-system configuration. Assuming you have already created a configuration tree with lh config:

  1. Create a sources.list entry for the chroot stage:

    echo "deb http://live.debian.net/ sid-snapshots main contrib non-free" > config/chroot_sources/debian-live_sid-snapshots.chroot
  2. Create a sources.list entry for the binary stage:

    cp config/chroot_sources/debian-live_sid-snapshots.chroot config/chroot_sources/debian-live_sid-snapshots.binary
  3. Fetch the archive signing key:

     wget http://live.debian.net/debian/project/openpgp/archive-key.asc -O config/chroot_sources/debian-live_sid-snapshots.chroot.gpg cp config/chroot_sources/debian-live_sid-snapshots.chroot.gpg config/chroot_sources/debian-live_sid-snapshots.binary.gpg 

Chapter 3. The basics

This chapter contains a brief overview of the build process as well as containing instructions on how to boot the various binary image types.

3.1. What is a live system?

A live system usually means an OS booted on a computer from a removable medium (such as CD-ROM, USB stick, or network), ready to use without any installation on the usual drive(s), with an auto-configuration done at runtime (see Section 1.1.1, “Terms”).

With Debian Live, it's a Debian GNU/Linux OS, built for one of the supported architectures (currently amd64, i386, powerpc and sparc). It is made from following parts:

Linux kernel

The Linux image, usually named vmlinuz*.

Initial RAM disk image (initrd)

RAM disk setup for the Linux boot, containing modules possibly needed to mount the filesystem's image and some scripts to do it.

System image

The OS filesystem image. Debian Live uses SquashFS, a compressed filesystem, to minimize its image size. Note that it's read-only. So, during boot the Debian Live system will use a RAM disk and 'union' mechanism to enable writing files within the running system. However, all modifications will be lost upon shutdown unless optional persistence partition(s) are used. (See Section 7.5, “Persistence”.)

Bootloader

A small piece of code, crafted to boot up from the chosen media, possibly presenting a prompt or menu to allow selection of options/configuration. It then loads the Linux kernel and its initrd to run with an associated filesystem image. Different solutions can be used depending on the target media and format of the filesystem containing the previous components: Isolinux to boot from a CD or DVD in ISO9660 format, syslinux for HDD or USB drive booting from a VFAT partition, GRUB for ext2/3 partition, pxelinux for PXE netboot, etc.

The Debian Live tools will build the system image from your specifications, setup a Linux kernel and its initrd, a bootloader to run them, all in one media-dependant format(ISO9660 image, disk image, etc.)

3.2. First steps: building an ISO image

The following sequence of helper commands, provided by live-helper, will create a basic ISO image containing just the Debian standard system without X.org. It is suitable for burning to CD or DVD media.

First, we run the lh config helper command which will create a "config/" hierarchy in the current directory for use by other helper commands:

$ lh config

By passing no parameters to lh config we indicated that we wish to use the defaults. This will create an image of type binary (see Section 4.1.1, “The lh config helper”).

Now that we have a "config/" hierarchy, we may build the image with the lh build helper command:

# lh build

This process can take a while, depending on the speed of your network connection (see Section 4.1.2, “The lh build helper”).

3.2.1. Testing an ISO image with Qemu

Testing an ISO is simple:

# apt-get install qemu $ qemu -cdrom binary.iso

3.2.2. Testing an ISO image with virtualbox-ose

In order to test the ISO with virtualbox-ose:

# apt-get install virtualbox-ose
and either install
  • the modules package for a stock kernel eg virtualbox-ose-modules-2.6.26-1-486 or

  • the modules package compiled for your kernel using module-assistant from the package virtualbox-ose-source

Run Virtualbox:

For example, in Gnome

{{{Applications -> System Tools -> VirtualBox OSE }}}

Create a virtual machine from your Live ISO

To create a virtual machine "mylive" from A CDROM ISO "binary.iso" in VirtualBox:

{{{Machine -> New }}}

In the Wizard: FIXME

3.2.3. Testing an ISO image with VMware Workstation

In order to test the ISO with VMware Workstation:

Run VMware Workstation:

Click on Edit virtual machine settings in the VM summary page.

Then, click on the CD-ROM device and select Use ISO image. Remeber to connect the CD-ROM device at power on and remeber to adjust the boot order in the bios.

3.2.4. Burning an ISO image to a physical medium

Burning an ISO image is easy:

# apt-get install wodim $ wodim binary.iso

3.3. Building an USB/HDD image

The following sequence of helper commands will create a basic USB/HDD image containing just the Debian standard system without X.org. It is suitable for booting from USB sticks, USB hard drives, and various other portable storage devices.

Note if you created an iso image with the previous example, you will need to clean up your working directory with the lh clean helper command (see Section 4.1.3, “The lh clean helper”):

$ lh clean --binary

Run the lh config helper command with the parameters to configure the "config/" hierarchy to create a USB/HDD image type:

$ lh config -b usb-hdd

Now build the image with the lh build helper command:

# lh build

3.3.1. Copying USB/HDD image to a USB stick

The generated binary image contains a VFAT partition and the syslinux bootloader, ready to be directly written on an USB stick. Plug in an USB stick with a size larger than that of binary.img and type:

$ dd if=binary.img of=${USBSTICK}

where ${USBSTICK} is the device file of your key, like /dev/sdb (not a partition like /dev/sdb1!); you can find the right device name by looking in dmesg's output after plugging in the stick, for example.

Important

This will definitely overwrite any previous contents on your stick!

3.3.2. Testing a USB/HDD image with Qemu

# apt-get install qemu $ qemu -hda binary.img

3.3.3. Testing an USB/HDD image with VMware Workstation

In order to test the USB/HDD image with VMware Workstation:

Run VMware Workstation:

Write the image to an usb stick. In VMware, click on Edit virtual machine settings in VM summary page. Then, add a new physical harddisk device and enter the device node of your usb stick.

3.3.4. Using the space left on a USB stick

If you want to use the remaining free space after you have installed the binary.img, you can use a partitioning tool such as gparted or parted to create a new partition on the stick. The first partition will be used by the Debian Live system.

# gparted ${USBSTICK}

After the creation of the partition you have to create a filsystem on it. One possible choice would be ext2 (ext3 isn't recommended because the journaling causes too many writes to the stick).

# mkfs.ext2 ${USBSTICK}

If you want to use this data partition with Windows, use FAT32.

# mkfs.vfat -F 32

Important

Remember: Every time you install a new binary.img on the stick, all your data will be lost because the image includes a complete partition table.

FIXME: Describe installing Debian Live to a partition (e.g. /dev/sdc1) AND using a bootloader to boot this.

3.4. Building a netboot image

The following sequence of helper commands will create a basic netboot image containing the Debian standard system without X.org. It is suitable for booting over the network.

Note if you performed any previous examples, you will need to clean up your working directory with the lh clean helper command:

$ lh clean --binary

Run the lh config helper command with the parameters to configure the "config/" hierarchy to create our netboot image:

$ lh config -b net --net-root-path "/srv/debian-live" --net-root-server "192.168.0.1"

In contrast with the ISO and USB hdd images, netbooting does not support serving a filesystem image with the client so the files must be served via NFS. The net-root-path and net-root-server options specify the location and server, respectively, of the NFS server where the filesytem image will be located at boot-time.

Now build the image with the lh build helper command:

# lh build

In a network boot the client runs a small piece of software, which usually resides on the EEPROM of the Ethernet card. This program sends a DHCP request to get an IP address and information about what to do next. Typically the next step is getting a higher level boot loader via the TFTP protocol. That could be Grub, PXELINUX, or even boot directly to an operating system like Linux.

For example, if you unpack the generated binary-net.tar.gz archive in the /srv/debian-live directory, you'll find the filesystem image in live/filesystem.squashfs and the kernel, initrd and PXE Linux bootloader in tftpboot/debian-live/i386.

We must now configure three services on the server to enable netboot:

DHCP server

We must configure our network's DHCP server to be sure to give an IP address to the computer netbooting, and to advertise the location of the PXE bootloader.

Here is an example for inspiration, written for the ISC DHCP server (package dhcp3-server) in the /etc/dhcp3/dhcpd.conf configuration file:

# Options DHCP spécifiques à Pxelinux: option space pxelinux; option pxelinux.magic code 208 = string; option pxelinux.configfile code 209 = text; option pxelinux.pathprefix code 210 = text; option pxelinux.reboottime code 211 = unsigned integer 32; subnet 192.168.1.0 netmask 255.255.255.0 { # 192.168.1.0/24 # IP addresses available for guests range 192.168.1.100 192.168.1.149; # allow booting from the net allow bootp; # for net booting, server where the first file to be loaded (by TFTP # protocol) ("filename" following definition) lies : so the TFTP # server's name. next-server myserver; # net boot configuration for guests with a PXE client : if substring (option vendor-class-identifier, 0, 9) = "PXEClient" { # Note : all files for PXE are relatives to the TFTP server's root # path, as usually defined in /etc/inetd.conf. # PXE boot loader (first program to be loaded, by TFTP) filename "pxelinux.0"; # describe some specific pxelinux's options through DHCP options : site-option-space "pxelinux"; option pxelinux.magic f1:00:74:7e; if exists dhcp-parameter-request-list { # Always send the PXELINUX options (specified in hexadecimal) option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3); } # For a PXE boot menu, different versions are available : simple # text, text with curses, graphic (VESA) #option pxelinux.configfile "pxelinux/config_simple"; #option pxelinux.configfile "pxelinux/config_curses"; option pxelinux.configfile "pxelinux/config_vesa"; # automatically reboot after 10 minutes of no activity option pxelinux.reboottime 600; } }

TFTPd server

This serves the kernel and initial ramdisk to the system at run-time.

You should install the tftpd-hpa package. It can serve all files contained inside a root directory, usually /var/lib/tftpboot/, as defined with its -s option. To let it serve files inside /srv/debian-live/tftpboot, modify its start definition in /etc/inetd.conf with:

tftp dgram udp wait root /usr/sbin/in.tftpd /usr/sbin/in.tftpd -s /srv/debian-live/tftpboot -r blksize -v -v

and reload the super server with /etc/init.d/openbsd-inetd reload.

NFS server

Once the guest computer has downloaded and booted a Linux kernel and loaded its initrd, it will try to mount the Live filesystem image through a NFS server.

You should install the nfs-kernel-server package -- nfs-user-server does not function correctly with netboot.

Then, make the filesystem image available through NFS by adding a line like the following to /etc/exports:

/srv/debian-live *(ro,async,subtree_check,no_root_squash)

and tell the NFS server about this new export with the following command:

# exportfs -rv

Setting up these three services can be a little tricky. You might need some patience to get all of them working together. The Debian Installer Manual's TFTP Net Booting section might help as that process is very similar.

3.5.  Netboot testing HowTo

Netboot image creation is made easy with live-helper magic, but testing the images on physical machines can be really time consuming.

To make our life easier, we can use virtualization. There are two solutions:

VMWare Player

Install VMWare Player ("free as in beer" edition)

Create a PXETester directory, and create a text file called pxe.vwx inside

Paste this text inside:

#!/usr/bin/vmware config.version = "8" virtualHW.version = "4" memsize = "512" MemAllowAutoScaleDown = "FALSE" ide0:0.present = "FALSE" ide1:0.present = "FALSE" floppy0.present = "FALSE" sound.present = "FALSE" tools.remindInstall = "FALSE" ethernet0.present = "TRUE" ethernet0.addressType = "generated" displayName = "Test Boot PXE" guestOS = "other" ethernet0.generatedAddress = "00:0c:29:8d:71:3b" uuid.location = "56 4d 83 72 5c c4 de 3f-ae 9e 07 91 1d 8d 71 3b" uuid.bios = "56 4d 83 72 5c c4 de 3f-ae 9e 07 91 1d 8d 71 3b" ethernet0.generatedAddressOffset = "0"

You can play with this configuration file (i.e. change memory limit to 256)

Double click on this file (or run VMWare player and selecet this file).

When running just press space if that strange question comes up...

Qemu

Install qemu, bridge-utils, sudo.

Edit /etc/qemu-ifup:

#!/bin/sh sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 echo "Executing /etc/qemu-ifup" echo "Bringing up $1 for bridged mode..." sudo /sbin/ifconfig $1 0.0.0.0 promisc up echo "Adding $1 to br0..." sudo /usr/sbin/brctl addif br0 $1 sleep 2

Get, or build a grub-floppy-netboot (in the svn).

Launch qemu with "-net nic,vlan=0 -net tap,vlan=0,ifname=tun0"

Chapter 4. Overview of tools

This chapter contains an overview of the two main tools used in building Debian Live systems.

4.1.  live-helper

live-helper is a collection of scripts to build Debian Live systems. These scripts are also referred to as "helpers".

The idea behind live-helper is to be a framework that uses a configuration directory to completely automate and customize all aspects of building a Live image.

Many concepts are similar to those in the debhelper Debian package tools written by Joey Hess:

  1. The scripts have a central location for configuring their operation.

    In debhelper, this is the debian subdirectory of a package tree. For example, dh_install will look for a file called debian/<packagename>.install to determine which files should exist in a particular binary package. In much the same way, live-helper stores its configuration entirely under a config/ subdirectory.

  2. The scripts are independent - that is to say, it is always safe to run each command.

Unlike debhelper, live-helper contains a tool to generate a skeleton configuration directory, lh config. This could be considered to be similar to tools such as dh-make. For more information about lh config, please see Section 4.1.1, “The lh config helper”.

Besides the common config/common, which is used by all live-helper helper commands, some additional files can be used to configure the behavior of specific helper commands. These files are typically named config/helper or config/stage (where "stage", of course, is replaced with the name of the stage that they belong to, and "helper" with the name of the helper).

For example, the lh bootstrap debootstrap helper command uses files named config/bootstrap and config/bootstrap_debootstrap to read the options it will use. Generally, these files contain variables with values assigned, one variable per line. Some programs in live-helper use pairs of values or slightly more complicated variable assignments.

live-helper respects environment variables which are present in the context of the shell it is running. If variables can be read from config files, then they override environment variables, and if command line options are used, they override values from config files. If no value for a given variable can be found (and is thus unset), live-helper will automatically set it to a default value.

All config files are shell scripts which are sourced by a live-helper program. That means they have to follow the normal shell syntax. You can also put comments in these files; lines beginning with "#" are ignored.

In some rare cases you may want to have different versions of these files for different architectures or distributions. If files named config/stage.arch or config/stage_helper.arch, and config/stage.dist or config/stage_helper.dist exist (where "arch" is the same as the output of dpkg --print-architecture and "dist" is the same as the codename of the target distribution), then they will be used in preference to the other, more general files.

Please see Chapter 2, Installation for information on how to install live-helper.

The remainder of this section discusses the three most important helpers:

lh config

Responsible for initialising a Live system configuration directory. See Section 4.1.1, “The lh config helper” for more information.

lh build

Responsible for starting a Live system build. See Section 4.1.2, “The lh build helper” for more information.

lh clean

Responsible for removing parts of a Live system build. See Section 4.1.3, “The lh clean helper” for more information.

4.1.1. The lh config helper

As discussed in Section 4.1, “ live-helper, the scripts that make up live-helper source their configuration from a single directory named config/. As constructing this directory by hand would be time-consuming and error-prone, the lh config helper can be used to create skeleton configuration folders.

Issuing lh config without any arguments creates a config subdirectory which it populates with some default settings:

$ lh config $ ls -l total 4.1k drwxr-xr-x 19 user group 4.1k 2008-05-09 21:37 config $ ls -l config/ total 104 -rw-r--r-- 1 user group 4175 2010-04-11 12:16 binary drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_debian-installer drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_debian-installer-includes drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_grub drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-debs drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-hooks drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-includes drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-packageslists drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-udebs drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_rootfs drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_syslinux -rw-r--r-- 1 user group 2205 2010-04-11 12:16 bootstrap -rw-r--r-- 1 user group 1599 2010-04-11 12:16 chroot drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_apt drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-hooks drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-includes drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-packages drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-packageslists drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-patches drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-preseed drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_sources -rw-r--r-- 1 user group 2938 2010-04-11 12:16 common drwxr-xr-x 2 user group 4096 2010-04-11 12:16 includes -rw-r--r-- 1 user group 206 2010-04-11 12:16 source drwxr-xr-x 2 user group 4096 2010-04-11 12:16 templates 

Using lh config without any arguments would be suitable for users who are either happy editing the generated files, or are simply happy with the defaults it creates.

You can ask lh config to generate a config/ directory "preseeded" with various options. This might be suitable if you do not require the default settings but do not need to change a large number of options. For example:

$ lh config -p gnome

will build a config/ directory configured to include the 'gnome' package list. It is possible to specify many options:

$ lh config --apt aptitude --binary-images net --hostname live-machine --username live-user ...

A full list of options is available in the lh_config man page. Most options have a parallel with an "LH_" prefixed variable.

4.1.2. The lh build helper

The lh build helper reads in your configuration from the config/ directory. It then runs the lower lower level commands needed to build your Live system.

4.1.3. The lh clean helper

It is the job of the lh clean helper to remove various parts of a Live helper build so subsequent builds can start from a clean state.

4.2. The live-initramfs package

live-initramfs is a collection of scripts providing hooks for the initramfs-tools, used to generate an initramfs capable of booting live systems, such as those created by live-helper. This includes the Debian Live isos, netboot tarballs, and usb stick images.

At boot time it will look for read-only media containing a "/live" directory where a root filesystem (often a compressed filesystem image like squashfs) is stored. If found, it will create a writable environment, using aufs or unionfs, for Debian like systems to boot from.

live-initramfs is a fork of casper.

More information on initial ramfs in Debian can be found in the Debian Linux Kernel Handbook's chapter on initramfs.

Chapter 5. Customization

5.1. Customising package installation

This chapter discusses the customisation of package installation. This involves:

  1. Selecting additional packages to be installed

  2. Installing modified packages

5.1.1. Package sources

FIXME

Debian repositories

To set a local mirror (used to ''build'' the live-cd)

$ lh config --mirror-bootstrap "http://local.intra.net/debian/" --mirror-chroot "http://local.intra.net/debian/"

The generic mirror is added to the live-system's /etc/apt/sources.list.

$ lh config --mirror-binary "http://ftp.debian.org/debian/"

Note: It is ''not'' used for building the live-cd but to install new software while using the live-cd.

It can be disabled by setting binary indices parameter to disabled

$ lh config --binary-indices disabled

Note: the same applies for mirror chroot security and mirror binary security

$ lh config --mirror-chroot-security {URL} $ lh config --mirror-binary-security {URL}

Own repository

To add more repositories (e.g. backports, experimental packages, etc.), create config/chroot_sources/your-cdd-repo.{chroot,binary} file.

e.g. config/chroot_sources/live.chroot allows you to install packages from the debian live snapshot repository at live-cd build time (you have to add the packages in your package list):

deb http://live.debian.net/ sid-snapshots main contrib non-free

If you add the line to config/chroot_sources/live.binary the repository will be added to your live-system's /etc/apt/sources.list.

If such files exist, they will be picked up automatically.

You can also put the gpg-key used to sign the repository into config/chroot_sources/foo.{binary,chroot}.gpg

5.1.2. Package installation

You can elect to use either apt or aptitude when installing packages. Which utility is used is governed by the LH_APT variable in config/chroot or by the --apt argument to lh config:

apt

Specifying a missing package causes package installation to fail, which may not be the desired behaviour.

This is the default setting for building images for Lenny or later.

aptitude

Specifying a missing package causes package installation to succeed, which may not be the desired behaviour.

This is the default setting for building images for Etch.

5.1.3. Installing additional packages

live-helper has a number of mechanisms for indicating that additional packages should be installed, including:

  1. The LH_PACKAGES variable

  2. Package lists

  3. Local packages (chroot_local-packages/)

  4. Tasks

5.1.3.1. The LH_PACKAGES variable

To install additional packages, simply add them to the LH_PACKAGES variable in config/chroot. For example:

LH_PACKAGES="package1 package2 package3 ... "

You can also specify initial values on the command line:

$ lh config --packages "package1 package2 package3"

The behaviour of live-helper when specifying a package that does not exist is determined by your choice of APT utility. See Section 5.1.2, “Package installation” for more details.

If you need to specify a large number of packages to be installed or you need flexibility regarding which packages to install, you should probably be using package lists. See Section 5.1.3.2, “Package lists” for more information.

5.1.3.2. Package lists

Package lists are a powerful way of expressing which packages should be installed. live-helper ships with a number of predefined package lists which provide sensible default package selections for the GNOME and KDE desktop environments, as well as standard systems.

To specify a package list, add the name of the list to the LH_PACKAGES_LISTS variable in config/chroot. For example:

LH_PACKAGES_LISTS="gnome"

Package lists that are distributed with live-helper reside in the /usr/share/live-helper/lists directory.

5.1.3.2.1. Local packages lists

You may supplement the supplied lists using local package lists stored in config/chroot_local-packageslists.

Package lists that exist in this directory always override package lists distributed with live-helper. This can cause undesired effects when.

live-helper 2.x change

Any file with .list suffix in config/chroot_local-packageslists is automatically enabled, the variable LH_PACKAGES_LISTS should only be used referencing packages lists included in live-helper (at /usr/share/live-helper/lists/.

5.1.3.2.2. Extending a provided package list using includes

FIXME

#include <gnome> iceweasel

The package lists that are included with live-helper make extensive use of includes. They are available to view in the /usr/share/live-helper/lists directory.

5.1.3.2.3. Using conditionals inside packages lists

FIXME

#if ARCHITECTURE amd64 ia32-libs #endif

or if LH_ARCHITECTURE is set to i386 or amd64:

#if ARCHITECTURE i386 amd64 memtest86+ #endif

or if LH_SECTIONS contains either contrib or non-free:

#if SECTIONS contrib non-free vrms #endif

A conditional may surround an #include directive:

#if ARCHITECTURE amd64 #include <gnome-full> #endif

Any live-helper configuration variable that begins with LH_ can be tested in this way.

The nesting of conditionals is not supported.

5.1.3.3. Tasks

FIXME

5.1.4. Installing modified or third-party packages

Whilst it is against the philosophy of Debian Live, it may sometimes be necessary to build a Live system with modified versions of packages that are in the Debian repository. This may be to modify or support additional features, languages and branding, or even to remove elements of existing packages that are undesirable. Similarly, "third-party" packages may be used to add bespoke and/or proprietary functionality.

This section does not cover advice regarding building or maintaining modified packages. Joachim Breitner's 'How to fork privately' may be of interest, however. The creation of bespoke packages is covered in the Debian New Maintainers' Guide and elsewhere.

There are two ways of installing modified custom packages:

  1. chroot_local-packages

  2. Using a custom APT repository

The chroot_local-packages is simpler to achieve and useful for "one-off" customisations but has a number of drawbacks, whilst using a custom APT repository is more time-consuming to set up.

5.1.4.1.  Using chroot_local-packages to install custom packages

To install a custom package, simply copy it to the config/chroot_local-packages directory. Packages that are inside this directory will be automatically installed into the live system during build - you do not need to specify them elsewhere.

Packages must be named in the prescribed way. One simple way to do this is to use dpkg-name. FIXME

Using chroot_local-packages for installation of custom packages has disadvantages:

  1. It is not possible to use secure APT

  2. You must install all appropriate packages in the config/chroot_local-packages directory

  3. It does not lend itself to storing Debian Live configurations in revision control

5.1.4.2. Using an APT repository to install custom packages

FIXME

Unlike using chroot_local-packages, when using a custom APT repository you must ensure that you specify the packages elsewhere. See Section 5.1.3.1, “The LH_PACKAGES variable” for details.

Whilst it may seem unnecessary effort to create an APT repository to install custom packages, the infrastructure can be easily re-used at a later date to offer updates of the modified packages.

5.1.4.3. Custom packages and APT

live-helper uses APT to install all packages into the live system so will therefore inherit behaviours from this program. One relevant example is that (assuming a default configuration) given a package available in two different repositories with different version numbers, APT will elect to install the package with the higher version number.

Because of this, you may wish to increment the version number in your custom packages' debian/changelog files to ensure that your modified version is installed over one in the official Debian repositories. This may also be achieved by altering the live system's APT pinning preferences - see Section 5.1.4.4, “Altering APT preferences during Live system” for more information.

5.1.4.4. Altering APT preferences during Live system

FIXME

Whilst it may seem unnecessary effort to create an APT repository to install custom packages, the infrastructure can be easily re-used at a later date to offer updates of the modified package.

5.2. Customising contents

This chapter discusses further customisation of the live system.

5.2.1. Includes

Using includes, it is possible to add (or replace) arbitrary files in your Debian Live image. live-helper provides three mechanisms for using them:

Chroot local includes

These allow you to add or replace files to the chroot/Live filesystem. Please see Section 5.2.1.1, “Live/chroot local includes” for more information.

Binary local includes

These allow you to add or replace files in the binary image. Please see Section 5.2.1.2, “Binary local includes” for more information.

Binary includes

These allow you to add or replace Debian specific files in the binary image, such as the templates and tools directories. Please see Section 5.2.1.3, “Binary includes” for more information.

Please see Section 1.1.1, “Terms” for more information about the distinction between the "Live" and "binary" images.

5.2.1.1. Live/chroot local includes

Chroot local includes can be used to add or replace files in the chroot/Live filesystem so that they are visible when the Live system is booted. Typical uses for them are to populate the skeleton user directory (/etc/skel) used by the live system to create the live user's home directory, or adding configuration files where additional processing is not required.

To include files, simply add them to your config/chroot_local-includes directory. This directory corresponds to the root directory (/) of the live system. For example, to add a file /var/www/index.html in the live system, use:

 $ mkdir -p config/chroot_local-includes/var/www $ cp /path/to/my/index.html config/chroot_local-includes/var/www 

Your configuration will then have the following layout:

 -- config [...] |-- chroot_local-includes | `-- var | `-- www | `-- index.html [...] `-- templates 

Chroot local includes are installed after package installation so that files installed by packages are overwritten.

5.2.1.2. Binary local includes

FIXME.

5.2.1.3. Binary includes

FIXME.

5.2.2. Hooks

FIXME.

Enabling hooks

5.2.2.1. Live/chroot local hooks

FIXME.

5.2.2.2. Binary local hooks

FIXME.

5.2.3. Preseeding Debconf questions

Files in the config/chroot_local-preseed directory are considered to be debconf preseed files and are installed by live-helper using debconf-set-selections.

For more information about debconf, please see debconf(7) in the debconf package.

5.2.4. Symlink conversion

FIXME. (This is probably in the wrong section)

5.3. Customising Locale And Language

This chapter discusses customisation for language specific parameters.

5.3.1. Default locale and keyboard

The default locale when building a live cd is "locale=en_US.UTF-8". To set the locale for the UK (locale=en_GB.UTF-8)

 $ lh_config --bootappend-live "locale=en_GB.UTF-8" 

The entry for a British keyboard would be

 $ lh_config --bootappend-live "keyb=uk" 

To configure both the locale and the keyboard for the UK the entry would be

 $ lh_config --bootappend-live "locale=en_GB.UTF-8 keyb=uk" 

or

 $ lh_config --bootappend-live "locale=uk" 

Note

You can find a list of options in the manpage for live-initramfs. Only UTF8 locales are supported by live-initramfs.

5.3.2. l10n Packages

lh build can automatically check for each package, for which it's know that there are -l10n packages available and install them. To add Swedish packages the entry would be

 $ lh_config --language "se" 

This will also change the default syslinux language if

 config/templates/syslinux/se 

is available. Check syslinux configuration FIXME

5.4. Customising the bootup process

This chapter discusses customisation of bootup process of a live system, including kernel options, modifications to the bootloader, "splash" screens and startup scripts.

FIXME

5.4.1. Kernel

5.4.2. Bootloaders

FIXME

5.4.2.1. Choosing a bootloader

FIXME

5.4.2.2. Syslinux

In the default configuration, Syslinux will pause indefinitely at its splash screen. To adjust this, modify the LH_SYSLINUX_TIMEOUT value or pass --syslinux-timeout TIMEOUT to lh_config. The value is specified in units of 1/10s and the maximum possible timeout is 35996. A timeout of 0 (zero) disables the timeout completely. For more information please see syslinux(1).

5.4.2.3. Bootloader templates

FIXME

5.4.2.4. Booting a Debian Live USB/HDD system from a USB stick with Grub

Suppose you've built your Debian Live USB/HDD image, but want to install it on an already used USB stick with ext2/3 partition and Grub bootloader:

First, copy live components in a directory on your key: the Linux kernel (vmlinuz*), its Initial RAM disk (initrd*) and the system (filesystem.squashfs):

 # mkdir /media/myUsb/boot/live/ # cp binary/vmlinuz1 binary/initrd1.img binary/live/filesystem.squashfs /media/myUsb/boot/live/ 

Then, add a stanza in Grub's menu definition to boot up this system:

 echo >>/media/myUsb/boot/grub/menu.lst <<EOF title my Debian Live root (hd0,1) # my Ext2 partition is the second on this stick kernel /boot/live/vmlinuz1 boot=live vga=791 persistent union=aufs live-media-path=boot/live initrd /boot/live/initrd1.img EOF 

The important kernel command line option to add here is <variablename>live-media-path</variablename>, which tells to Live initrd's script in which subdirectory to look for the SquashFS image.

Next, umount your USB stick and reboot on it. That's all!

5.4.3. Splash screens

FIXME

5.4.4. Memtest

FIXME

5.4.5. Startup scripts

FIXME

5.4.6. Cheat codes

FIXME

Checksums.

5.5. Customising the binary image

This chapter discusses FIXME

5.5.1. ISO metadata

When creating an ISO9660 binary image, you can use the following options to add various textual metadata for your image. This can help you easily identify the version or configuration of an image without booting it.

LH_ISO_APPLICATION / --iso-application NAME

This should describe the application that will be on the image. The maximum length for this field is 128 characters.

LH_ISO_PREPARER / --iso-preparer NAME

This should describe the preparer of the image, usually with some contact details. The default for this option is the live-helper version you are using, which may help with debugging later. The maximum length for this field is 128 characters.

LH_ISO_PUBLISHER / --iso-publisher NAME

This should describe the publisher of the image, usually with some contact details. The maximum length for this field is 128 characters.

LH_ISO_VOLUME / --iso-volume NAME

This should specify the volume ID of the image. This is used as a user-visible label on some platforms such as Windows and Apple Mac OS. The maximum length for this field is 32 characters.

5.6. Using a newer kernel with Lenny

The backports repository, backports.org, lacks the necessary module packages (linux-modules-extra-2.6, aufs, etc.) so an alternative repository has been set up, in order to build Lenny live images with a later kernel. Shown here is one way of doing it.

 $ lh_config --linux-packages 'linux-image-2.6 aufs-modules-2.6' $ echo 'deb http://unsupported.debian-maintainers.org/backports-kernel/ ./' > config/chroot_sources/backports-kernel.chroot $ echo 'deb http://unsupported.debian-maintainers.org/backports-kernel/ ./' > config/chroot_sources/backports-kernel.binary $ wget http://unsupported.debian-maintainers.org/backports-kernel/archive-key.asc -O config/chroot_sources/backports-kernel.chroot.gpg $ wget http://unsupported.debian-maintainers.org/backports-kernel/archive-key.asc -O config/chroot_sources/backports-kernel.binary.gpg # lh_build 

Chapter 6. Common tasks

6.1. The Debian Installer

Although Debian Live is mostly concerned with avoiding permanent installation, integrating some form of installer to your image is possible. There are number of different "types" of installation, varying in what and how to install the image.

The "Debian Installer"

Please note the careful use of capital letters when referring to the "Debian Installer" in this section - when used like this we refer explicitly to the official installer for the Debian system, not anything else. It is often seen abbreviated to "d-i".

The three main types of installer are:

"Normal" Debian Installer

This is a normal Debian Live image with a seperate kernel and initrd which (when selected from the appropriate bootloader) launches into a standard Debian Installer instance, just as if you had downloaded a CD image of Debian and booted it.

This means that Debian is installed by fetching and installing .deb packages using debootstrap or cdebootstrap, from the local media or some network-base network, resulting in a standard Debian system being installed to the hard disk.

This whole process can be preseeded and customised in a number of ways; see the relevant "DebianInstaller" wiki page and installation guide for more. This is operational now withing live-helper.

"Live" Debian Installer

This is a Debian Live image with a seperate kernel and initrd which (when selected from the appropriate bootloader) launches into an instance of the Debian Installer.

Installation will proceed in an identical fashion to the "Normal" installation described above, but at the actual package installation stage, instead of using debootstrap to fetch and install packages, the "live" filesystem image is copied to the target. After this stage, the Debian Installer continues as normal, installing and configuring items such as bootloaders and local users, etc.

This is working now.

"Ubuntu"-style installer

This is where you boot into a graphical Debian Live system and run a wizard-based program which installs and configures the live system, all the time remaining inside the live graphical environment.

This is currently NOT possible with Debian Live.

By default, no installer will be included in the Debian Live image. You can enable it by using lh_config :

 $ lh_config --help ... [--debian-installer enabled|cdrom|netinst|netboot|businesscard|live|disabled] [--debian-installer-distribution CODENAME|daily] [--debian-installer-preseedfile FILE|URL] ... 

The values "Normal", "Live" and "Ubuntu" are not valid values for <term>LH_BINARY_DEBIAN_INSTALLER</term>. Refer to the output of lh_config cited above to choose the appropriate values.

6.2. WiFi Connection

Depending on the Debian Live image you are using and the given tools configured with your Debian Live image you may need to only attach to an available access point. If you encounter difficulty a good place to start is at the Debian Wiki entry for WiFi.

Chapter 7. The Live environment

7.1. Swap space

FIXME

7.2. Hostname

The name of host running live system can be set with the hostname parameter into the --bootappend-live option of lh_config, e.g.:

lh_config --bootappend-live "hostname=myhost"

This parameter can also be used in kernel command line.

7.3. The Live user

Username FIXME.

One important consideration is that the live user is created by live-initramfs during bootup, it is not created by live-helper when building the image.

You can specify additional groups that the live user will belong to by preseeding the passwd/user-default-groups debconf value. For example, to add the live user to the fuse group, add the following to a file in the config/chroot_local-preseed directory:

 debconf passwd/user-default-groups string audio cdrom dialout floppy video plugdev netdev powerdev fuse 

For more information about debconf preseeding, please see Section 5.2.3, “Preseeding Debconf questions”.

7.4. Language

When the live system boots, language is involved in three steps:

  • the locale generation
  • setting the keyboard layout for the console
  • setting the keyboard layout for X

To define the locale that should be generated, use the locale parameter into the --bootappend-live option of lh_config, e.g.:

lh_config --bootappend-live "locale=sv_SE.utf8"

This parameter can also be used in kernel command line. You can specify a locale by a two-letters code, or for better control, by a full language_country.encoding word.

Both the console and X keyboard configuration depends on the keyb parameter of the --bootappend-live option. Valid options for X keyboard layouts can be found in /etc/X11/xkb/base.xml (rather limited to two-letters country codes). To find the value (the two characters) corresponding to a language try searching for the english name of the nation where the language is spoken, e.g:

$ grep -i sweden -C3 /etc/X11/xkb/base.xml | grep name <name>se</name> 

To get the locale files for swedish generated and a swedish keyboard layout in X use:

lh_config --bootappend-live "locale=sv_SE.utf8 keyb=se"

A list of the valid values of the keyboards for the console can be figured with the following command:

for i in `find /usr/share/keymaps/ -iname "*kmap.gz"`; do basename $i | head -c -9; echo; done | sort | less 

To make the console keyboard use a swedish layout use

lh_config --bootappend-live "locale=sv_SE.utf8 keyb=se-latin1"

Alternatively, you can use the console-setup package, a tool to let you configure console layout using X (XKB) definitions; you can then setup your keyboard layout more precisely with klayout, kvariant, koptions and kmodel variables; live-initramfs will use also these parameters for X configuration. For example, to set up a french system with a french-dvorak layout (called Bépo) on a TypeMatrix keyboard, both in console and X11, use:

lh_config --bootappend-live \ "locale=fr_FR.UTF-8 klayout=fr kvariant=bepo kmodel=tm2030usb"

Note that on old versions of console-setup (i.e. Lenny's one), you'll need to setup also the keyb variable to the klayout's value.

7.5. Persistence

A live cd paradigm is a preinstalled system which runs from read-only media, like a cdrom, where writes and modifications do not survive reboots of the host hardware which runs it.

A Debian Live system is a generalization of this paradigm and thus supports other media in addition to CDs; but still, in its default behaviour, it should be considered read-only and all the runtime evolutions of the system are lost at shutdown.

Persistence is a common name for different kinds of solutions for saving across reboots some, or all, of this runtime evolution of the system. To understand how it could work it could be handy to know that even if the system is booted and run from read-only media, modification to the files and directories are written on writable media, typically a ram disk (tmpfs) and ram disks' data do not survive reboots.

The data stored on this ramdisk should be saved on a writable persistent medium like a Hard Disk, a USB key, a network share or even a session of a multisession (re)writable CD/DVD. All these media are supported in Debian Live in different ways, and all but the last one require a special boot parameter to be specified at boot time: persistent.

7.5.1. Full persistence

By 'full persistence' it is meant that instead of using a tmpfs for storing modifications to the read-only media (with the copy-on-write, COW, system) a writable partition is used. In order to use this feature a partition with a clean writable supported filesystem on it labeled "live-rw" must be attached on the system at bootime and the system must be started with the boot parameter 'persistent'. This partition could be an ext2 partition on the hard disk or on a usb key created with, e.g.:

 # mkfs.ext2 -L live-rw /dev/sdb1 

If you already have a partition on your device, you could just change the label with one of the following:

 # tune2fs -L live-rw /dev/sdb1 # for ext2,3,4 filesystems # dosfslabel /dev/sdb1 live-rw # for a fat filesystem 

But since live system users cannot always use a hard drive partition, and considering that most USB keys have poor write speeds, 'full' persistence could be also used with just image files, so you could create a file representing a partition and put this image file even on a NTFS partition of a foreign OS, with something like:

 $ dd if=/dev/null of=live-rw bs=1G seek=1 # for a 1GB sized image file $ /sbin/mkfs.ext2 -F live-rw 

Then copy the live-rw file to a writable partition and reboot with the boot parameter 'persistent'.

7.5.2. Home automounting

If during the boot a partition (filesystem) image file or a partition labeled home-rw is discovered, this filesystem will be directly mounted as /home, thus permitting persistence of files that belong to e.g. the default user. It can be combined with full persistence.

7.5.3. Snapshots

Snapshots are collections of files and directories which are not mounted while running but which are copied from a persistent device to the system (tmpfs) at boot and which are resynced at reboot/shutdown of the system. The content of a snapshot could reside on a partition or an image file (like the above mentioned types) labeled live-sn, but it defaults to a simple cpio archive named live-sn.cpio.gz. As above, at boot time, the block devices connected to the system are traversed to see if a partition or a file named like that could be found. A power interruption during runtime could lead to data loss, hence a tool invoked live-snapshot --refresh could be called to sync important changes. This type of persistence, since it does not write continuously to the persistent media, is the most flash-based device friendly and the fastest of all the persistence systems.

A /home version of snapshot exists too and its label is home-sn.*; it works the same as the main snapshot but it is only applied to /home.

Snapshots cannot currently handle file deletion but full persistence and home automounting can.

7.5.4. Persistent SubText

If a user would need multiple persistent storage of the same type for different locations or testing, such as live-rw-nonwork and live-rw-work, the boot parameter persistent-subtext used in conjuntion with the boot parameter persistent will allow for multiple but unique persistent media. An example would be if a user wanted to use a persistent partition labeled live-sn-subText they would use the boot parameters of: persistent persistent-subtext=subText.

7.5.5. Partial remastering

The runtime modification of the tmpfs could be collected using live-snapshot in a squashfs and added to the cd by remastering the iso in the case of cd-r or adding a session to multisession cd/dvd(rw); live-initramfs mounts all /live filesystem in order or with the module bootparameter.

Chapter 8. Frequently asked questions (FAQ)

  • Q: I downloaded a prebuilt live image. How do I put it on a USB stick?

    A: See Section 3.3.1, “Copying USB/HDD image to a USB stick” "Copying USB/HDD image to a USB stick"

  • Q: How do I log my build?

    A: You could use script, screen or tee:

    $ lh_build 2>&1 | tee build.log

  • Q: How can I convert an already installed standard Debian partition into a Debian Live system?

    A: Save the list of installed packages and load it into your new Debian Live System. Copy your /etc to config/chroot_local-includes

  • Q: What does 'losetup: could not find any free loop device' mean and how do I fix it?

    A: Loop devices are used during the build; there probably aren't any free if you've aborted several builds. Something like: for l in /dev/loop0 /dev/loop1 /dev/loop2 /dev/loop3 /dev/loop4 /dev/loop5 /dev/loop6 /dev/loop7 ; do losetup -d $l ; done should rectify the situation (assuming all loop devices in use were created by lh_build; if in doubt, check the contents of each loop device before deleting them with losetup -d).

  • Q: How do I launch an interactive shell during the chroot stage?

    A: To enable interactive shell:

    $ lh_config --interactive shell

    To continue the build process:

    # logout

    or

    # exit

    To disable interactive shell, set LH_INTERACTIVE to "disabled" in config/chroot.

  • Q: What is the root /user password?

    A: The user password for the live user is 'live'. By default, there is not any root password. You can switch to root with

     sudo -i 

    or set a password for root with

    sudo passwd
  • Q: How do I change root or any user password?

    A: Add a chroot local hook script to change root or any user password each time you build an image.

    e.g. config/chroot_local-hooks/01-update_password.sh to set root password to "nopasswd"

    #!/bin/sh echo "I: update password" echo "root:nopasswd" | chpasswd
    $ chmod +x config/chroot_local-hooks/01-update_password.sh

    Note

    For live user; you need to copy the /usr/share/initramfs-tools/scripts/live-bottom/10adduser your build folder:
    mkdir -p config/chroot_local-includes/usr/share/initramfs-tools/scripts/live-bottom/ cp /usr/share/initramfs-tools/scripts/live-bottom/10adduser config/chroot_local-includes/usr/share/initramfs-tools/scripts/live-bottom/

    Then edit the config/chroot_local-includes/usr/share/initramfs-tools/scripts/live-bottom/10adduser and paste in the new user_crypted password that you make with:

     echo "newlivepass" | mkpasswd -s.

    Or add an hook file in config/chroot_local-hooks/ with something like the below:

     #!/bin/sh # Change the autogenerated user password to "debianlive" plain_password="debianlive" password=$(echo "${plain_password}" | mkpasswd -s) sed -i -e 's/\(user_crypted=\)\(.*\)\( #.*\)/\1\"'${password}'\"\3/' /usr/share/initramfs-tools/scripts/live-bottom/10adduser update-initramfs -tu -kall

    The latter (hook model) could be more future proof than the former solution since it modifies just one string selectively but it requires the package "whois" to be installed on the target system (for mkpasswd) or that you generate the $password string not at build time and include it crypted in the above script.

  • Q: How to disable autologin?

    A1: use the commandline parameter

    lh config --bootappend-live "noautologin"

    A2: You need to set boot=noautologin noxautologin as described in man live-initramfs If you boot via TFTP you want to insert the option to pxelinux.cfg/default

  • Q: How do I change default hostname or username?

    A: To change default hostname or username:

    $ lh_config --hostname myhostname $ lh_config --username myusername

  • Q: How do I make the final image smaller?

    A: Clean orphaned apps/libs: Install package "deborphan" and then run 'sudo deborphan -n' . Delete unwanted packages. Remove the apt cache. Purge unwanted locales (see "localepurge" package).

  • Q: How do I customize bash-config permanently (aliases, bash-completion etc.)?

    A: Add your own .bashrc config/chroot_local-includes/etc/skel/.bashrc

  • Q: How do I disable services permanently? (Be careful!)

    A: Add a chroot local hook script to disable a service each time you build an image:

    e.g. config/chroot_local-hooks/01-disable_service.sh

    #!/bin/sh echo "I: disable service" update-rc.d -f 〈service name 〉 remove 

     $ chmod +x config/chroot_local-hooks/01-disable_service.sh 

  • Q: How do I enable | disable the md5checksum at the ISO building?

    lh_config --checksums enabled|disabled 

    Or change the LH_CHECKSUMS value.

  • Q: How to disable the generation of the .tar.gz file?

    lh_config --net-tarball none|gzip 

    Or change the LH_NET_TARBALL value. (only available in snapsshot version at the moment 2008/Feb/28)

  • Q: How do I "build a new image" ?

    A: Run commands:

    $ sudo lh_clean --binary $ sudo lh_build 

    Hint: If the configuration had changed you should leave "--binary" out. This will clean your chroot directory too.

  • Q: How do I use Fluxbox ?

    A: Add a new lists file with the fluxbox packages you want.

    Create /home/$USERNAME/.dmrc file (default username is "user").

    $ cat .dmrc [Desktop] Session=fluxbox

    Note

    .dmrc is owned by $USERNAME:$USERNAME.

    See also http://wiki.debian.org/Fluxbox

    A short HOWTO can be found here: http://wiki.debian.org/MichaelAblassmeier/CustomLiveCD

  • Q: How do I use custom repositories?

    A: See DebianLive/Configuration.

  • Q: How do I customize the artwork for the live CD (grub or syslinux boot splash, usplash, etc.)?

    A: See DebianLive/Howto/Custom_Artwork. FIXME: NEED TO UPDATE

  • Q: How do I customize desktop environment (KDE, GNOME, XFCE, etc...) look?

    A: Start the live system in qemu:

    $ qemu -m 256 -cdrom binary.iso -boot d -redir tcp:4222:10.0.2.15:22

    Note

    the -redir argument must be changed to meet your needs

  • Q: How do I execute a custom shell script inside the chroot system after the chroot stage?

    A: Add your script in config/chroot_local-hooks.

  • Q: How do I add a script running immediately after all other scripts when the live system boots?

    A: Add your script in config/chroot_local-includes/usr/share/initramfs-tools/scripts/live-bottom/99script

    $ chmod +x config/chroot_local-includes/usr/share/initramfs-tools/scripts/live-bottom/99script

    Note

    The hook script must be executable. Do not forget to lh_clean --chroot after making this change before you build again.

    You must also use the example script /usr/share/live-helper/examples/hooks/update-initramfs.sh to ensure your script gets built into the initramfs (read the comment header for instructions).

  • Q: How do I add software not in Debian ?

    A: See Section 5.1, “Customising package installation” Customising package installation

  • Q: What is the manifest with Ubuntu used for?

    A: Manifest is just the package list, which ubuntu does $something with. Don't worry about it.

  • Q: What is this {p} syntax with mtools{p} and parted{p} ?

    A: That's aptitude.

  • Q: Do I need to write the image on USB stick to test it?

    Note

    you must use qemu >= 0.8.

  • Q: What is /cow ?

    A: Copy-on-write, the 'diff' from unionfs.

  • Q: Is /usr/share/live-helper/lists/standard-x11 like preseed or is preseed something else entirely?

    A: It is not. It is a package list, not a debconf preseeding.

  • Q: What is the difference between standard and minimal?

    standard: packages of priority standard and higher;

    minimal: packages of priority essential and higher;

  • Q: What can the sections be used for? Aren't they BIG?

    A: Someone maybe wants to include packages from contrib or non-free.

  • Q: memtest86+ ... is that used?

    A: Yes

  • Q: How do I build using predefined packages lists?

    A: e.g. to build using standard-x11 packages list:

    $ sudo lh_config -p standard-x11 $ sudo lh_build

    Note

    The packages lists can be found in /usr/share/live-helper/lists/ directory.

  • Q: How do I rebuild without downloading all the packages again?

    A: All packages are cached in cache subdirectory. They remain until a clean purge:

    $ sudo lh_clean --purge

    You do not have to do anything to prevent packages from being re-downloaded. You need to remember to clean whichever stages you want to rebuild first.

    e.g. to rebuild from the cached bootstrap, chroot packages and build a new image.

    $ sudo lh_clean $ sudo lh_build

  • Q: How do I boot USB debian-live on systems not supporting USB boot?

    A: Make a boot CD with grub, configured to boot from a debian-live kernel copied on the cd structure.

    $ mkdir -p iso/boot/grub $ cp /usr/lib/grub/i386-pc/stage2_eltorito iso/boot/grub $ cp chroot/boot/* iso/boot/

    Create iso/boot/grub/menu.lst

    default 0 timeout 5 color cyan/blue white/blue title Debian Live root (cd) kernel /boot/vmlinuz boot=live initrd /boot/initrd.img

    Create the iso image

    $ mkisofs -R -b boot/grub/stage2_eltorito -no-emul-boot \ -boot-load-size 4 -boot-info-table -o grub.iso iso

    Burn the image.

  • Q: How do I boot debian-live on systems not supporting CDROM or USB boot?

    A: If you have a floppy drive, you may be able to use it, otherwise you will need to use loadlin/grub4dos/win32-loader. If you have a second system to serve up the image over the network, See DebianLive/Howto/Creating_a_Netboot_Image. FIXME LINK

  • Q: The X configuration does not seems to work, the resolution is too low. What can I do?

    A: Use xdebconfigurator

    $ lh_config --bootappend xdebconf $ lh_config --packages xdebconfigurator

  • Q: Apache has problems with static files

    A: Sendfile does not work well on the unionfs used by Debian Live. Add the following to apache's configuration:

    EnableSendfile off

  • Q: How do I make hard disk partitions auto-mountable?

    A: Short answer: Right now the best is to use a script that will populate the fstab when the CD is booting. Such a script can be found FIXME BROKEN LINK . A proper solution based on HAL will be described here in a hopefully near future.

    A: Long Answer: Since 55_nonpolkit-mount-policy.patch in HAL, debian-storage-policy-fixed-drives.fdi is not available anymore and the previous trick that consisted to remove this file to enable automounting of fixed drives as a consequence is obsolete.

    Eventually, it will be possible to combine HAL and PolicyKit to enable different permissions and actions to achieve advanced (auto)mounting for non-root users. Until then, because the live scripts are only touching to the fstab to add a swap partition if discovered at boot time, the only way to have fixed drives mounted automatically is to use a script that will populate the fstab file at the end of the multiuser runlevel.

    To achieve this, you can do, for example, the following:

    download the diskmounter.sh script FIXME BROKEN LINK

    Create the chroot_local-includes/sbin directory, and move the script inside

    Make sure the script is executable (chmod +x diskmounter.sh)

    create the chroot_local-includes/etc/rc.local file and call the diskmounter from there (see this rc.local FIXME BROKEN LINK

    When called correctly, the script detects ext2, ext3, reiserfs, xfs, FAT32, HFS+ and NTFS partitions and mount them read-write, except for NTFS. This will change soon and an option will be available to use ntfs-3g to mount NTFS as read-write.

    comments, patches and other things about this script and issue: http://code.goto10.org/projects/puredyne/ticket/463

  • Q: Boot fails with panic: can't open /scripts/live

    A: Add latest live-initramfs deb package into config/chroot_local-packages directory and rebuild.

  • Q: How do I configure the locale and the keyboard?

    A: See Section 5.3, “Customising Locale And Language” 10n

  • Q: How do I get past boot prompt without a working keyboard?

    A: See Section 5.4, “Customising the bootup process” Customising the bootup process

    Note

    Boot from an USB-HDD on an iMac with GRUB did not work.
  • Q: Can I serve the root image from a web or ftp server?

    A: Since live-initramfs 1.99, it should be possible to use the fetch= argument on the kernel command line. You can build a netboot image as usual, and when you are done edit the tftpboot/pxelinux.cfg/default file. Remove the references to network boot (netboot, nfsroot, nfsopts), and replace with fetch= 〈url where you placed the root image>.

    Note

    You have to include wget in the chroot. It could work for other boot methods as well. However, I am not sure the live scripts configure the network when booting from a CD or USB disk.

    $ lh_config --packages wget

  • Q: Why doesn't quickreboot (or some other boot parameter) work?

    A: If you are building an etch image (which was the default up to 2007/09/14) you have a very old version of casper which does not support quickreboot and possibly other boot parameters as well. You could configure your sources to use live-backports (see /usr/share/live-helper/examples/sources/live-backports) and switch to live-initramfs, or better yet, build a lenny image instead, which is the new default.

    $ lh_config --distribution lenny $ lh_config --initramfs live-initramfs

  • Q: How do I fix "Could not find kernel image" issue with syslinux bootloader?

    A: Add a binary local hook script to fix kernel and initrd path each time you build an image.

    e.g. config/binary_local-hooks/01-fix_syslinux.sh

    #!/bin/sh SYSLINUXCFG=`find binary -type f -name syslinux.cfg` sed -i "s|kernel /vmlinuz|kernel vmlinuz|g" ${SYSLINUXCFG} sed -i "s|initrd=/initrd|initrd=initrd|g" ${SYSLINUXCFG}

    $ chmod +x config/binary_local-hooks/01-fix_syslinux.sh

  • Q: How do I use a newer kernel with lenny?

    A: A build with backports.org kernels will fail as that repository lacks the necessary module packages (linux-modules-extra-2.6, aufs, etc.). Use the kernel backports http://unsupported.debian-maintainers.org/backports-kernel/.

    The quick way to success:

    $ lh_config --linux-packages 'linux-image-2.6 aufs-modules-2.6 squashfs-modules-2.6' $ echo 'deb http://unsupported.debian-maintainers.org/backports-kernel/ ./' > config/chroot_sources/backports-kernel.chroot $ echo 'deb http://unsupported.debian-maintainers.org/backports-kernel/ ./' > config/chroot_sources/backports-kernel.binary $ wget http://unsupported.debian-maintainers.org/backports-kernel/archive-key.asc -O config/chroot_sources/backports-kernel.chroot.gpg $ wget http://unsupported.debian-maintainers.org/backports-kernel/archive-key.asc -O config/chroot_sources/backports-kernel.binary.gpg $ lh_build

  • Q: How do I use a custom kernel?

    〉 Is there a nice way of booting debian-live with a custom kernel (not in an apt repo)?

    A: Copy it into config/chroot_local-packages and set LH_LINUX_PACKAGES="none" or use lh config --linux-packages " "

    Don't forget to compile your kernel with an union filesystem (unionfs or aufs), squashfs modules, and initrd support.

    〉 I can cause the kernel to be installed but it seems this happens later than grub/syslinux is configured so it's not listed and casper/ and the menu require munging.

    You need to follow the debian scheme, e.g. placing the files in /boot as vmlinuz-$version and initrd.img-$version etc.

    I personally wouldn't go that way which is too much of a hassle, and just use make-kpkg to produce custom kernel deb packages. They should integrate nicely if you just put them into config/chroot_local-packages and set LH_LINUX_PACKAGES="".

    Hint: to work around an error, which lh_binary_syslinux will throw on custom kernels if there is not an 468/686 in the kernel-name, you need to set CONFIG_LOCALVERSION="-486" or "-686" within the kernel configuration (-> General setup -> Local version set to -486 or -686) corresponding to LH_LINUX_FLAVOURS="" or "686". this at least up till live-helper version 1.0~a40-1

    see

    http://lists.alioth.debian.org/pipermail/debian-live-devel/2007-July/001947.html

    and

    http://lists.alioth.debian.org/pipermail/debian-live-devel/2007-November/002581.html

  • Q: How do I create a cross arch live CD image?

    A: In short: You can't. Read on:

    The procedure to create a live CD is based on creating a chroot that contains the files that will be finally available on the live CD. The live CD building procedure includes chrooting into the chroot dir and so some operations. chrooting means that the terminal you chroot on will behave as a different system so your real system and the chroot environment is decoupled somehow.

    Once the live CD scripts chroots into the chroot dir they have some operations to do inside that environment and your real system won't be able to run them unless you are using the same architecture.

    So you only are able to make live CD for the arch you run on. But this doesn't prevent you run qemu or some other machine emulator that make this possible.

  • Q: When is a lh_clean necessary?

    lh_clean is a script in /usr/bin/

    A: That depends what you've changed between builds

    If, for example, you've built an iso image and you want a usb image, you only need to run lh_clean --binary before you run lh_build again.

    If you've changed anything in the chroot , you'll need to cleanup both chroot and binary with lh_clean before continuing

  • Q: How can i set boot= parameters?

    A: Set LH_BOOTAPPEND_LIVE in config/binary

  • Q: How do I include different modules to load when the live system boots?

    A: Configure config/chroot_local-includes/etc/initramfs-tools/

    The lh_chroot_hacks helper rebuilds the live/initrd1.img using the default initramfs.conf "MODULES = most". You may override that by supplying your own initramfs.conf, or else just add your own modules, e.g.

    mkdir -p config/chroot_local-includes/etc/initramfs-tools/ echo "atl2" >> config/chroot_local-includes/etc/initramfs-tools/modules

    Note

    Even though initramfs.conf(5) says "most adds all the framebuffer, acpi, file system, ide, sata, scsi and usb drivers", it actually includes network drivers as well. See auto_add_modules() in /usr/share/initramfs-tools/hook-functions for the complete list.

  • Q: Can I have a splash screen?

    A: Yes you can

    You will not know what is going on when the splash screen is active, it may fail to activate on some hardware or break X on other (both usplash and splashy use libdirectfb which does some evil voodoo and may break you graphics or input until you reboot). However, you can install and activate it just as you would on any other Debian system.

    To use splashy:

    1) install splashy and read the README, the manpages are useless for setting it up. Add some parameters to your kernel command line, such as in your pxelinux configuration or in LH_BOOTAPPEND_LIVE in config/binary in debian-live configuration:

    vga=792 splash quiet

    vga to select video mode, splash to activate splashy, quiet to suppress most kernel messages that you cannot see anyway but would scroll past before splashy manages to paint the graphics on your screen.

    You might want to add splashy to the list of packages installed in your image:

    echo splashy > config/chroot_local-packageslists/splashy echo splashy-themes >> config/chroot_local-packageslists/splashy

    and select a theme:

    echo '#!/bin/sh' > config/chroot_local-hooks/splashy echo splashy_config -s debian-moreblue '||' true >> config/chroot_local-hooks/splashy # update the ramdisk to include the splash screen echo update-initramfs -u -k all >> config/chroot_local-hooks/splashy chmod 755 config/chroot_local-hooks/splashy 

    After you rebuild your live system you should observe a bluish splash screen while booting. Nothing happens while initramfs is running because there is no splashy support in initramfs-tools. Once the init starts the progress bar should start to fill.

    If vga=something sets a mode that your screen cannot show or your card cannot do vesa 2.0 (and thus you get plain text mode and no splashy) read the splashy faq.

  • Q: Howto use my Broadcom eXtrem 2 network card (module bnx2) ?

    A: Add the firmwares to the initrd image.

    You need to install the non-free package "firmware-bnx2". Uncompress your initrd image, then copy files :

    cp /lib/firmware/bnx2x-e1-4.8.53.0.fw /lib/firmware/bnx2x-e1-5.0.21.0.fw /lib/firmware/bnx2x-e1h-4.8.53.0.fw /lib/firmware/bnx2x-e1h-5.0.21.0.fw ${INITRD}/lib/firmware/ cp /lib/udev/firmware.agent ${INITRD}/lib/udev/

    Recompress your initrd image and boot: it works !

  • Q: X is broken (the system boots, messages scroll by, and then the screen goes blank). What do I do?

    On my system starting X completely disables graphics so that I do not see anything even after X bails out and I am back to the console. To prevent this you can change the driver Xorg uses.

    If you have a working splash screen or at least graphical console you can use

    live xdriver=fbdev

    when booting the live system (instead of just enter).

    Another driver you might want to try is vesa.

    If all fails you might try to set xdriver to some wrong value so that Xorg fails to start and you can examine the system while you still see something on the console.

    live xdriver=none

  • Q: How can I get Debian first stable versions?

    I'm developing software and testing it on Live-CD. Thanks for the LiveCD project. To be sure my development is fully compatible with the "etch" version, I need the same scenario when Debian GNU/Linux 4.0 was published as stable (I believe 2007.04.08). If there was some bug on 2007.04.08 that was corrected one week later, I need to test software foreseeing that scenario without the bug solved.

  • Q: I get "fopen: Permission denied"-warnings from apt on building/at the live-system

    That's a harmless bug in apt. However, if you want to get off this warnings in the live-system, add a file in chroot_local-hooks with follow row:

     chown -R man.man /var/cache/man 
  • Q: Why I always fail during "Retrieving Packages" stage when running lh_build? I have already set apt-http-proxy and so on.

    A: lh_build retrieves packages via wget, as a result you need to enable the proxy settings in /etc/wgetrc before running lh_build.

  • Q: How do I edit Xorg.conf?

    A: Xorg.conf is generated every time system boots, so it's useless to put modifed Xorg.conf in config/choort_local-includes/etc/X11, because it will be overwritten during boot. However, you can edit /usr/bin/dexconf, which generate xorg.conf during boot, so the result will be modified Xorg.conf. The modified dexconf has to be put in config/choort_local-includes/usr/bin. e.g.: you can configure Xorg.conf for two or more keyboards layouts with alt+shift toggle by editing dexconf and replacing the line:

    Option "XkbLayout" "$XKB_LAYOUT"

    with the lines:

    Option "XkbLayout" "us,il" Option "XkbOptions" "grp:alt_shift_toggle,grp_led:scroll"

    when "us,il" are the wanted keyboard layouts.

    You can force default screen resulotion (e.g. 1024*768) by adding the lines: .

     SubSection "Display" Modes "1024x768" EndSubSection

    between the lines:

     Section "Screen" Identifier "Default Screen" Monitor "Configured Monitor" . . . . . . . SECTION printf "EndSection\n" 〉 &4

  • Q: Where are the build parameters for the prebuilt images

    A: See http://live.debian.net/README.images.

Chapter 9. Reporting bugs

Debian Live is far from being perfect, but we want to make it as close as possible to perfect - with your help. Do not hesitate to report a bug: it is better to fill a report twice than never. However, this chapter includes recommendations how to file good bug reports.

For the impatient:

  • Always check first the image status updates on our homepage for known issues.

  • Always try to reproduce the bug with the most recent version of live-helper and live-initramfs before submitting a bug report.

  • Try to give as specific information as possible about the bug. This includes (at least) the version of live-helper and live-initramfs used and the distribution of the live system you are building.

9.1. Known issues

Due to the nature of Debian testing and Debian unstable branches being a moving target, building a live system may not always be possible.

If this is a problem, do not build a system based on testing or unstable, but go with stable. live-helper does always default to the current stable release.

Currently known issues are listed under the section 'status' on our homepage.

It is out of the scope of this manual to train you in correctly identifying and fixing problems in packages of the development branches, however, there are two things you can always try: When not succeeding to build testing, try if unstable works. If unstable does not work either, revert to testing and pinning the newer version of the failing package from unstable.

9.2. Rebuild from scratch

To ensure that a particular bug is not caused by an unclean built system, please always rebuild the whole live system from scratch to see if the bug is reproducible.

9.3. Use up-to-date packages

This means

Using outdated packages can cause significant problems when trying to reproduce (and ultimately fix) your problem. If a relevant package is not available in Debian anymore, please recognize that the resources of the Debian kernel team are limited and will be unlikely to be able to fix the problem.

9.4. Collect information

Please provide enough information with your report. At a minimum, it should contain the exact version of live-helper version where the bug is encountered, and steps to reproduce it. Please use common sense and include other relevant information if you think that it might help in solving the problem.

To make the most out of your bug report, we require at least the following information:

  • Architecture of the host system

  • Version of live-helper on the host system

  • Version of live-initramfs on the live system

  • Version of debootstrap and/or cdebootstrap on the host system

  • Architecture of the live system

  • Distribution of the live system

  • Version of the kernel on the live system

You can generate a log of the build process by using the tee command:

 # lh_build 2>&1 | tee buildlog.txt 

Additionally, to rule out other errors, it is always a good idea to tar up your config directory and upload it somewhere (do *not* send it as an attachment to the mailinglist), so that we can try to reproduce the errors you encountered.

Remember to send in any logs that were produced with English locale settings, e.g. run your live-helper commands with a leading LC_ALL=C or LC_ALL=en_US.

9.5. Use the correct package to report the bug against

Where does the bug appear?

At build time whilst bootstrapping

live-helper first bootstraps a basic Debian system with debootstrap or cdebootstrap. Depending on the bootstrapping tool used and the Debian distribution it is bootstrapping, it may fail. If a bug appears here, check if the error is related to a specific Debian package (most likely), or if it is related to cdebootstrap itself.

In both cases, this is not a bug in Debian Live, but rather in Debian itself which we can not fix this directly. Please report such a bug against debootstrap, cdebootstrap or the failing package.

At build time whilst installing packages

live-helper installs additional packages from the Debian archive and depending on the Debian distribution used and the daily archive state, it can fail. If a bug appears here, check if the error is also reproducible on a normal system.

If this is the case, this is not a bug in Debian Live, but rather in Debian - please report it against the failing package. Running debootstrap seperately from the Live system build or running lh_bootstrap with --debug will give you more information.

Also, if you are using a local mirror and/or any of sort of proxy and you are experiencing a problem, please always reproduce it first by bootstrapping from an official mirror.

At boot-time

If your image does not boot, please report it to the mailing list together with the information requested in Section 9.4, “Collect information”. Do not forget to mention, how/when the image failed, in Qemu, VMWare or real hardware. If you are using a virtualization technology of any kind, please always run it on real hardware before reporting a bug. Providing a screenshot of the failure is also very helpful.

At run-time

If a package was successfully installed, but fails while actually running the Live system, this is probably a bug in Debian Live. However,

9.6. Do the research

Before filing the bug, please search the web for the particular error message or symptom you are getting. As it is highly unlikely that you are the only person experiencing a particular problem, there is always a chance that it has been discussed elsewhere, and a possible solution, patch, or workaround has been proposed.

You should pay particular attention to the Debian Live mailing list, as well as the homepage, as these are likely to contain the most up-to-date information. If such information exists, always include the references to it in your bug report.

In addition, you should check the current bug list for live-helper and the current bug list for live-initramfs to see whether something similar has been reported already.

9.7. Where to report bugs

The Debian Live project keeps track of all bugs in the Debian Bug Tracking System (BTS). For information on how to use the system, please see http://bugs.debian.org. You can also submit the bugs by using the reportbug command from the package with the same name.

In general, you should report build time errors against the live-helper package and run time errors against live-initramfs. If you are unsure of which package is appropriate or need more help before submitting a bug report, please send a message to the mailing list and we will help you to figure it out.

Please note that bugs found in distributions derived from Debian (such as Ubuntu, Knoppix, Xandros, etc.) should not be reported to the Debian BTS unless they can be also reproduced on a Debian system using official Debian packages.

Chapter 10. Howtos

Table of Contents

10.1. ISO
10.2. ISO_(multiarch)

10.1. ISO

Generating a Debian Live CD is very simple. You need to have live-helper (package available in Debian sid and lenny), and Debootstrap (or cdebootstrap) from etch or newer.

Install live-helper
.
apt-get install live-helper
Configure the current working directory with lh_config
.
lh_config -b iso -a $ARCH

where $ARCH is the intended architecture (i.e. - i386 or amd64).

-b flag is used to be sure to obtain image in ISO format.

Build the image with lh_build
Execute lh_build as root:
lh_build

The command above will create the basic image, containing just the Debian standard system (with no X at all).

If you want to have any of the Desktop_environments on your livecd, ls /usr/share/live-helper/lists will show a number of available package Lists to choose from, e.g. lh_config -p gnome-desktop

More examples are listed at DebianLive/Examples. FIXME LINK

See Section 5.1, “Customising package installation” for help configuring a local Debian Mirror and other aspects of the live system.

Test the image
If you have qemu installed, you can boot the image with:
qemu -cdrom binary.iso

If you have also kqemu installed, you can add -kernel-kqemu

10.2. ISO_(multiarch)

Multiple machine boot CDs can be created with the following manual procedure. This procedure has been successfully used to create a single CD which is bootable on alpha, i386, pmax, and sparc. It should be possible to also make the CD bootable on macppc, vax and on sun2, sun3 and sun3x.

To create a CD which is bootable by multiple architectures, use the following steps in this order. Please note that the order is critical.

Make sure you have all the required files including the various kernels and boot programs listed in the individual machine sections.

Include a directory somewhere in the cdsources directory called mdec.pmax and include the pmax bootxx_cd9660 file there. For example, /cdsources/usr/mdec.pmax/bootxx_cd9660.

Include a directory somewhere in the cdsources directory called mdec.vax and include the vax xxboot file there. For example, /cdsources/usr/mdec.vax/xxboot.

Include the macppc ofwboot.xcf bootloader in /cdsources.

Create an i386 bootable image.

sh mkisofs -v -v -o output.iso -b i386/installation/floppy/boot-big.fs \ -c boot.catalog -l -J -r -L /cdsources 2 &1 | tee /tmp/mkisofs.log exit

Note

The appearance of the -v flag twice is required. If you are making a bootable CD for an Open Firmware 3 macppc model, make sure to include -hfs -part in the parameters for mkisofs.

Run mksunbootcd on a NetBSD/sparc machine to install sparc and sun2/sun3 bootblocks. Alternatively, install the sysutils/mksunbootcd package on your favorite NetBSD machine.

mksunbootcd output.iso boot-sun4.fs boot-sun4c.fs boot-sun4m.fs boot-sun3.fs

Run the installboot(8) program targeted for NetBSD/pmax to install the pmax bootblocks. Note that in order to coexist with other NetBSD boot blocks, the pmax boot block is appended to the end of the ISO file system.

installboot -m pmax -v -o append,sunsum output.iso /tmp/mdec.pmax/bootxx_cd9660

The -o append,sunsum option appends the first stage boot block to the end of the ISO file system, and restores the checksum used when booting on a sun.

Run the installboot(8) program targeted for NetBSD/vax to install the vax bootblocks. Note that in order to coexist with other NetBSD boot blocks, the vax boot block is appended to the end of the ISO file system.

installboot -m vax -v -o append,sunsum output.iso /tmp/mdec.vax/xxboot

(See the pmax entry above for an explanation of the flags).

Run the installboot(8) program targeted for NetBSD/alpha to install the alpha bootblocks.

installboot -m alpha -v -o append,sunsum output.iso /tmp/mdec.alpha/bootxx_cd9660

Note

The alpha installboot must occur after the others, because currently it's the only machine dependent back-end for installboot(8) that can calculate the alpha checksum. (See the pmax entry above for an explanation of the flags).

Chapter 11. Coding Style

This chapter documents the coding style used in live-helper and (ideally) in live-initramfs.

11.1. Compatibility

  • Don't use syntax or semantics that are unique to the Bash shell. For example, the use of array constructs.
  • Only use the POSIX subset - for example, use $(foo) over `foo`.
  • You can check your scripts with 'sh -n' and 'checkbashisms'

11.2. Indenting

  • Always use tabs over spaces.

11.3. Wrapping

  • Generally, lines are 80 chars at maximum.
  • Use the "Linux style" of line breaks:

    Bad:

     if foo; then bar fi 

    Good:

     if foo then bar fi 

  • The same holds for functions:

    Bad:

     foo () { bar } 

    Good:

     foo () { bar } 

11.4. Variables

  • Variables are always in capital letters.
  • Variables that used in config always start with LH_ prefix.
  • Internal temporary variables should start with the _LH_ prefix.
  • Local variables start with __LH_ prefix.
  • Use braces around variables; eg. write ${FOO} instead of $FOO.
  • Always protect variables with respect to potential whitespaces, write "${FOO}" not ${FOO}.
  • For consistency reasons, always use quotes when assigning values to variables:

    Bad:

     FOO=bar 

    Good:

     FOO="bar" 

  • If multiple variables are used, quote the full expression:

    Bad:

     if [ -f "${FOO}"/foo/"${BAR}"/bar ] then foobar fi 

    Good:

     if [ -f "${FOO}/foo/${BAR}/bar" ] then foobar fi 

11.5. Miscellaneous

  • Use "|" (without the surround quotes) as a seperator in calls to sed, e.g. "sed -e 's|foo|bar|'" (without "").
  • Don't use the test command for comparisons or tests, use "[" "]" (without ""), e.g. "if [ -x /bin/foo ]; ..." and not "if test -x /bin/foo; ...".

Chapter 12. Procedures

This chapter documents the procedures within the Debian Live project for various tasks that need cooperation with other teams in Debian.

12.1. Udeb Uploads

Before commiting releases of a udeb in d-i svn, one has to call:

      ../../scripts/l10n/output-l10n-changes . -d
    

12.2. Major Releases

Releasing a new stable major version of Debian includes a lot of different teams working together to make it happen. At some point, the Live team comes in and builds live system images. The requirements to do this are:

  • The local debian mirror (debian, debian-security, debian-volatile) of the debian-live buildd needs to be synced against a mirror that contains the released version.
  • The names of the image need to be known (e.g. debian-live-VERSION-ARCH-FLAVOUR.iso).
  • The data from debian-cd needs to be synced (udeb exclude lists).
  • The includes from debian-cd needs to be synced (README.*, doc/*, etc.).
  • Images are built and mirrored on cdimage.debian.org.

12.3. Point Releases

  • Again, we need updated mirror of both debian and debian-security.
  • Before actual images can be built, the sizes of the gnome-desktop and kde-desktop CD images need to be checked that they are not too big.
  • Images are built and mirrored on cdimage.debian.org.
  • Send announcement mail.

12.3.1. Point release announcement template

An annoucement mail for point releases can be generated using the template below and the following command:

 $ sed \ -e 's|%major%|5.0|g' \ -e 's|%minor%|5.0.2|g' \ -e 's|%codename%|lenny|g' \ -e 's|%release_mail%|2009/msg00007.html|g' 

Please check the mail carefully before sending and pass it to others for proof-reading.

 Debian Live images for Debian GNU/Linux %major% updated The Debian Live project is pleased to announce the availability of updated Live images for its stable distribution Debian GNU/Linux %major% (codename "%codename%"). The images are available for download at: <http://cdimage.debian.org/cdimage/release/current-live/> This update incorporates the changes made in the %minor% point release, which adds corrections for security problems to the stable release along with a few adjustments for serious problems. A full list of the changes may be viewed at: <http://lists.debian.org/debian-announce/%release_mail%> It also includes the following Live-specific changes: COPYING debian html Makefile manual VERSION xml xsl [INSERT LIVE-SPECIFIC CHANGE HERE] COPYING debian html Makefile manual VERSION xml xsl [INSERT LIVE-SPECIFIC CHANGE HERE] COPYING debian html Makefile manual VERSION xml xsl [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] URLs ---- Download location of updated images: <http://cdimage.debian.org/cdimage/release/current-live/> Debian Live project homepage: <http://live.debian.net/> The current stable distribution: <http://ftp.debian.org/debian/dists/stable> stable distribution information (release notes, errata etc.): <http://www.debian.org/releases/stable/> Security announcements and information: <http://www.debian.org/security/> About Debian ------------- The Debian Project is an association of Free Software developers who volunteer their time and effort in order to produce the completely free operating system Debian GNU/Linux. About Debian Live ----------------- Debian Live is an official sub-project of Debian which produces Debian systems that do not require a classical installer. Images are available for CD/DVD discs, USB sticks and PXE netbooting as well as a bare filesystem images for booting directly from the internet. Contact Information ------------------- For further information, please visit the Debian Live web pages at <http://live.debian.net/> or alternatively send mail to <debian-live@lists.debian.org>. 

Chapter 14. Use Cases

Table of Contents

14.1. VNC Kiosk Client

This chapter is for users to document their use cases with Debian Live.

14.1. VNC Kiosk Client

Create an image with live-helper to boot directly to a VNC server.

  • Make a build directory:

    $ mkdir vncBuild

  • Move to the build directory:

    $ cd vncBuild

  • Example to config the build directory to include gdm metacity xtightvncviewer:

    $ lh config --packages "gdm metacity xtightvncviewer"

  • Create a folder /etc/skel folder for a custom .xsession for the default user:

    $ mkdir -p config/chroot_local-includes/etc/skel

  • Create the .xsession for the default user:

    $ touch config/chroot_local-includes/etc/skel/.xsession

  • Edit the .xsession file to launch metacity and start xvncviewer with something similar to the below:

     #!/bin/sh /usr/bin/metacity & /usr/bin/vncviewer xxx.xxx.xxx.xxx:PORT exit 

  • Build the image:

    # lh build

Chapter 15. Success Stories

This chapter documents success stories with Debian Live applied.

FIXME

Chapter 16. Hints for troubleshooting

To check on the client

  • look at /live.log and /netboot.conf

  • could the image be mounted

To check on the pc that creates the image

  • was chroot unmounted after build? (it should)

Appendix A. Configuration layout

Layout of the config/ directory

binary_debian-installer/

(see Section 6.1, “The Debian Installer”)

binary_grub/

(see Section 5.4.2, “Bootloaders”)

binary_local-debs/

(see Section 6.1, “The Debian Installer”)

binary_local-hooks/

(see Section 5.2.2.2, “Binary local hooks”)

binary_local-includes/

(see Section 5.2.1.3, “Binary includes”)

binary_local-packageslists/

(see Appendix A, Configuration layout)

binary_local-udebs/

(see Section 6.1, “The Debian Installer”)

binary_rootfs/

(see Appendix A, Configuration layout)

binary_syslinux/

(see Section 5.4.2, “Bootloaders”)

chroot_apt/

(see Section 5.1.4.3, “Custom packages and APT”)

chroot_local-hooks/

(see Section 5.2.2.1, “Live/chroot local hooks”)

chroot_local-includes/

(see Section 5.2.1.1, “Live/chroot local includes”)

chroot_local-packages/

(see Section 5.1.4.1, “ Using chroot_local-packages to install custom packages ”)

chroot_local-packageslists/

(see Section 5.1.3.2, “Package lists”)

chroot_local-presed/

(see Section 5.2.3, “Preseeding Debconf questions”)

chroot_sources/

(see Section 5.1.4.2, “Using an APT repository to install custom packages”)

includes/

(see Section 5.4.2, “Bootloaders”)

templates/

(see Section 5.4.2, “Bootloaders”)

bootstrap

(see Section B.2, “The config/bootstrap file”)

binary

(see Section B.1, “The config/binary file”)

chroot

(see Section B.3, “The config/chroot file”)

common

(see Section B.4, “The config/common file”)

source

(see Section B.5, “The config/source file”)

Appendix B. Configuration files

B.1. The config/binary file

LH_BINARY_FILESYSTEM

Set image filesystem. (See Appendix A, Configuration layout)

LH_BINARY_IMAGES

Set image type. (See Appendix A, Configuration layout)

LH_BINARY_INDICES

Set apt/aptitude generic indices. (See Appendix A, Configuration layout)

LH_BOOTAPPEND_LIVE

Set boot parameters. (See Appendix A, Configuration layout)

LH_BOOTAPPEND_INSTALL

Set boot parameters. (See Appendix A, Configuration layout)

LH_BOOTLOADER

Set bootloader. (See Section 5.4.2, “Bootloaders”)

LH_CHECKSUMS

Set checksums. (See Section 5.4.6, “Cheat codes”)

LH_CHROOT_BUILD

Control if we build binary images chrooted. (See Appendix A, Configuration layout)

LH_DEBIAN_INSTALLER

Set debian-installer. (See Section 6.1, “The Debian Installer”)

LH_DEBIAN_INSTALLER_DAILY

Set daily images. (See Section 6.1, “The Debian Installer”)

LH_ENCRYPTION

Set encrytion. (See Appendix A, Configuration layout)

LH_GRUB_SPLASH

Set custom grub splash. (See Section 5.4.3, “Splash screens”)

LH_HOSTNAME

Set hostname. (See Section 7.2, “Hostname”)

LH_ISO_APPLICATION

Set iso author. (See Section 5.5.1, “ISO metadata”)

LH_ISO_PREPARER

Set iso preparer. (See Section 5.5.1, “ISO metadata”)

LH_ISO_PUBLISHER

Set iso publisher. (See Section 5.5.1, “ISO metadata”)

LH_ISO_VOLUME

Set iso volume (max 32 chars). (See Section 5.5.1, “ISO metadata”)

LH_JFFS2_ERASEBLOCK

Set jffs2 eraseblock size. (See Appendix A, Configuration layout)

LH_MEMTEST

Set memtest. (See Section 5.4.4, “Memtest”)

LH_NET_ROOT_FILESYSTEM

Set netboot filesystem. (See Appendix A, Configuration layout)

LH_NET_ROOT_MOUNTOPTIONS

Set nfsopts. (See Appendix A, Configuration layout)

LH_NET_ROOT_PATH

Set netboot server directory. (See Appendix A, Configuration layout)

LH_NET_ROOT_SERVER

Set netboot server address. (See Appendix A, Configuration layout)

LH_NET_COW_FILESYSTEM

Set net client cow filesystem. (See Appendix A, Configuration layout)

LH_NET_COW_MOUNTOPTIONS

Set cow mount options. (See Appendix A, Configuration layout)

LH_NET_COW_PATH

Set cow directory. (See Appendix A, Configuration layout)

LH_NET_COW_SERVER

Set cow server. (See Appendix A, Configuration layout)

LH_NET_TARBALL

Set net tarball. (See Appendix A, Configuration layout)

LH_SYSLINUX_SPLASH

Set custom syslinux splash. (See Section 5.4.3, “Splash screens”)

LH_SYSLINUX_TIMEOUT

Set custom syslinux timeout in seconds. (See Section 5.4.2.2, “Syslinux”)

LH_SYSLINUX_CFG

Set custom syslinux configuration file. (See Section 5.4.2.2, “Syslinux”)

LH_SYSLINUX_MENU

Set syslinux menu. (See Section 5.4.2.2, “Syslinux”)

LH_SYSLINUX_MENU_LIVE_ENTRY

Set text to be used on the menu for live entries. (See Section 5.4.2.2, “Syslinux”)

LH_SYSLINUX_MENU_LIVE_FAILSAFE_ENTRY

Set text to be used on the menu for live entries (failsafe ones). (See Section 5.4.2.2, “Syslinux”)

LH_SYSLINUX_MENU_MEMTEST_ENTRY

Set text to be used on the menu for memtest entry. (See Section 5.4.2.2, “Syslinux” and Section 5.4.4, “Memtest”)

LH_USERNAME

Set username. (See Section 7.3, “The Live user”)

B.2. The config/bootstrap file

LH_ARCHITECTURE

Select chroot architecture. (See Appendix A, Configuration layout)

LH_BOOTSTRAP_CONFIG

Set distribution config directory. (See Appendix A, Configuration layout)

LH_BOOTSTRAP_INCLUDE

Include packages on base. (See Appendix A, Configuration layout)

LH_BOOTSTRAP_EXCLUDE

Exclude packages on base. (See Appendix A, Configuration layout)

LH_BOOTSTRAP_FLAVOUR

Select flavour to use. (See Appendix A, Configuration layout)

LH_BOOTSTRAP_KEYRING

Set distribution keyring. (See Appendix A, Configuration layout)

LH_DISTRIBUTION

Select distribution to use. (See Appendix A, Configuration layout)

LH_MIRROR_BOOTSTRAP

Set mirror to bootstrap from. (See Section 5.1.1, “Package sources”)

LH_MIRROR_CHROOT

Set mirror to fetch packages from. (See Section 5.1.1, “Package sources”)

LH_MIRROR_CHROOT_SECURITY

Set security mirror to fetch packages from. (See Section 5.1.1, “Package sources”)

LH_MIRROR_BINARY

Set mirror which ends up in the image. (See Section 5.1.1, “Package sources”)

LH_MIRROR_BINARY_SECURITY

Set security mirror which ends up in the image. (See Section 5.1.1, “Package sources”)

LH_SECTIONS

select section(s) to use. (See Section 5.1.1, “Package sources”)

B.3. The config/chroot file

LH_CHROOT_FILESYSTEM

Set chroot filesystem. (See Appendix A, Configuration layout)

LH_UNION_FILESYSTEM

Set union filesystem. (See Appendix A, Configuration layout)

LH_EXPOSED_ROOT

expose root as read only. (See Appendix A, Configuration layout)

LH_HOOKS

Set hook commands. (See Section 5.2.2, “Hooks”)

LH_INTERACTIVE

Set interactive build. (See Appendix A, Configuration layout)

LH_KEYRING_PACKAGES

Set keyring packages. (See Appendix A, Configuration layout)

LH_LANGUAGE

Set language to use. (See Section 7.4, “Language”)

LH_LINUX_FLAVOURS

Set kernel flavour to use. (See Section 5.4.1, “Kernel”)

LH_LINUX_PACKAGES

Set kernel packages to use. (See Section 5.4.1, “Kernel”)

LH_PACKAGES

Set packages to install. (See Section 5.1.3.1, “The LH_PACKAGES variable”)

LH_PACKAGES_LISTS

Set package list to install. (See Section 5.1.3.2, “Package lists”)

LH_TASKS

Set tasks to install. (See Section 5.1.3.3, “Tasks”)

LH_SECURITY

enable security updates. (See Section 5.1.1, “Package sources”)

LH_SYMLINKS

enable symlink convertion. (See Section 5.2.4, “Symlink conversion”)

LH_SYSVINIT

enable sysvinit. (See Section 5.4.5, “Startup scripts”)

B.4. The config/common file

LH_APT

Set package manager. (See Section 5.1.2, “Package installation”)

LH_APT_FTP_PROXY

Set apt/aptitude ftp proxy. (See Section 5.1.2, “Package installation”)

LH_APT_HTTP_PROXY

Set apt/aptitude http proxy. (See Section 5.1.2, “Package installation”)

LH_APT_PDIFFS

Set apt/aptitude pdiff indices. (See Section 5.1.2, “Package installation”)

LH_APT_PIPELINE

Set apt/aptitude pipeline depth. (See Section 5.1.2, “Package installation”)

LH_APT_RECOMMENDS

Set apt/aptitude recommends. (See Section 5.1.2, “Package installation”)

LH_APT_SECURE

Set apt/aptitude security. (See Section 5.1.2, “Package installation”)

LH_BOOTSTRAP

Set bootstrap program. (See Appendix A, Configuration layout)

LH_CACHE

control cache. (See Appendix A, Configuration layout)

LH_CACHE_INDICES

control if downloaded package indices should be cached. (See Appendix A, Configuration layout)

LH_CACHE_PACKAGES

control if downloaded packages files should be cached. (See Appendix A, Configuration layout)

LH_CACHE_STAGES

control if completed stages should be cached. (See Appendix A, Configuration layout)

LH_DEBCONF_FRONTEND

Set debconf(1) frontend to use. (See Appendix A, Configuration layout)

LH_DEBCONF_NOWARNINGS

Set debconf(1) warnings. (See Appendix A, Configuration layout)

LH_DEBCONF_PRIORITY

Set debconf(1) priority to use. (See Appendix A, Configuration layout)

LH_INITRAMFS

Set initramfs hook. (See Appendix A, Configuration layout)

LH_FDISK

Set fdisk program. (See Appendix A, Configuration layout)

LH_LOSETUP

Set losetup program. (See Appendix A, Configuration layout)

LH_MODE

Set distribution mode. (See Appendix A, Configuration layout)

LH_ROOT_COMMAND

use sudo or equivalent. (See Appendix A, Configuration layout)

LH_USE_FAKEROOT

use fakeroot/fakechroot. (See Appendix A, Configuration layout)

LH_TASKSEL

Set tasksel program. (See Section 5.1.3.3, “Tasks”)

LH_INCLUDES

Set includes. (See Appendix A, Configuration layout)

LH_TEMPLATES

Set templates. (See Appendix A, Configuration layout)

LH_BREAKPOINTS

enable breakpoints. (See Appendix A, Configuration layout)

LH_DEBUG

enable debug. (See Appendix A, Configuration layout)

LH_FORCE

enable force. (See Appendix A, Configuration layout)

LH_QUIET

enable quiet. (See Appendix A, Configuration layout)

LH_VERBOSE

enable verbose. (See Appendix A, Configuration layout)

B.5. The config/source file

LH_SOURCE

Set source option. (See Appendix A, Configuration layout)

LH_SOURCE_IMAGES

Set image type. (See Appendix A, Configuration layout)