Debian Live Manual

The Debian Live Project

December 8, 2008

Debian Live Manualby The Debian Live Project

Published Mon, 08 Dec 2008 12:08:40 +0000Copyright c© 2008 The Debian Live Project

This program is free software: you can redistribute it and/or modify it under the terms of the GNUGeneral 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; with-out even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.See the GNU General Public License for more details.

A copy of the GNU General Public License is available as /usr/share/common-licenses/GPL inthe Debian GNU/Linux distribution or on the World Wide Web at the GNU web site. You can alsoobtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA02111-1307, USA.

If you want to print this reference, this document is also available in Portable Document Format (PDF).

2

Contents

1 About 71.1 About this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

1.1.1 Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71.1.2 Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.1.3 Contributing to this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.2 About the Debian Live Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81.2.1 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

1.2.1.1 What is wrong with current live systems . . . . . . . . . . . . . . . . . . . 81.2.1.2 Why create our own live system? . . . . . . . . . . . . . . . . . . . . . . . 9

1.2.2 Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91.2.2.1 Only unchanged, official packages . . . . . . . . . . . . . . . . . . . . . . 91.2.2.2 No configuration of the live system . . . . . . . . . . . . . . . . . . . . . . 91.2.2.3 No live system to hard disk installer . . . . . . . . . . . . . . . . . . . . . 9

1.2.3 Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9

2 Installation 112.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.2 Installing live-helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

2.2.1 From the Debian repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 112.2.2 From source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.2.3 From ’snapshots’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 122.2.4 From Backports.org . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12

2.2.4.1 Installing debootstrap or cdebootstrap from backports.org . . . . . . . . . 122.2.4.2 Installing live-helper on etch . . . . . . . . . . . . . . . . . . . . . . . 13

2.3 live-initramfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132.3.1 Using a customised live-initramfs . . . . . . . . . . . . . . . . . . . . . . . . . 132.3.2 Using a live-initramfs snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3 The basics 153.1 First steps: building an ISO image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

3.1.1 Testing an ISO image with Qemu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.1.2 Burning an ISO image to physical medium . . . . . . . . . . . . . . . . . . . . . . . 15

3.2 Building an USB/HDD image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 153.2.1 Copying USB/HDD image to a USB stick . . . . . . . . . . . . . . . . . . . . . . . . 163.2.2 Testing a USB/HDD image with Qemu . . . . . . . . . . . . . . . . . . . . . . . . . 16

3.3 Building a netboot image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

4 Overview of tools 194.1 live-helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.1.1 The lh_config helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204.1.2 The lh_build helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204.1.3 The lh_clean helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

4.2 The live-initramfs package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5 Customization 235.1 Customising package installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

5.1.1 Package sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.1.2 Package installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235.1.3 Installing additional packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

5.1.3.1 The LH_PACKAGES variable . . . . . . . . . . . . . . . . . . . . . . . . . 235.1.3.2 Package lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

5.1.3.2.1 Local packages lists . . . . . . . . . . . . . . . . . . . . . . . . . . 245.1.3.2.2 Extending a provided package list using includes . . . . . . . . 245.1.3.2.3 Using conditionals inside packages lists . . . . . . . . . . . . . . 24

3

CONTENTS

5.1.3.3 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245.1.4 Installing modified or third-party packages . . . . . . . . . . . . . . . . . . . . . . . 25

5.1.4.1 Using chroot_local-packages to install custom packages . . . . . . 255.1.4.2 Using an APT repository to install custom packages . . . . . . . . . . . . 255.1.4.3 Custom packages and APT . . . . . . . . . . . . . . . . . . . . . . . . . . . 255.1.4.4 Altering APT preferences during Live system . . . . . . . . . . . . . . . . 25

5.2 Customising contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255.2.1 Includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.2.1.1 Live/chroot local includes . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.2.1.2 Binary local includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.2.1.3 Binary includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.2.2 Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.2.2.1 Live/chroot local hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.2.2.2 Binary local hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.2.3 Preseeding Debconf questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.2.4 Symlink conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

5.3 Customising the bootup process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.3.1 Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.3.2 Bootloaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

5.3.2.1 Choosing a bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.3.2.2 Syslinux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.3.2.3 Bootloader templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

5.3.3 Splash screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.3.4 Memtest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.3.5 Startup scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.3.6 Cheat codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

5.4 Customising the binary image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.4.1 ISO metadata . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

6 Common tasks 296.1 The Debian Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

7 The Live environment 317.1 Swap space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317.2 Hostname . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317.3 The Live user . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317.4 Language . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317.5 Persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

7.5.1 Full persistence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327.5.2 Home automounting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327.5.3 Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 327.5.4 Partial remasterings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

8 Frequently asked questions (FAQ) 35

9 Reporting bugs 379.1 Rebuild from scratch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379.2 Use up-to-date packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379.3 Collect information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379.4 Use the correct package to report the bug against . . . . . . . . . . . . . . . . . . . . . . . . 389.5 Do the research . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389.6 Where to report bugs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

10 Coding Style 4110.1 Compatibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4110.2 Indenting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4110.3 Wrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4110.4 Variables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

4

CONTENTS

11 Resources and links 4311.1 Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4311.2 Who is using Debian Live? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

A Configuration layout 45

B Configuration files 47B.1 The config/binary file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47B.2 The config/bootstrap file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48B.3 The config/chroot file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48B.4 The config/common file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49B.5 The config/source file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50

5

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 theDebian Live project. It does not include end-user documentation for using a Debian Live system.

Some of the commands mentioned in the text must be executed with superuser privileges, either bybecoming the root user or by using sudo. To distinguish between commands which may be executedby 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 doesnot alter operating systems or files already installed on the computer hard drive unless instructedto do so. Live systems are typically booted from CD or DVD media as well as USB sticks and vianetboot.

Debian Live The Debian sub-project which maintains the live-helper and live-initramfs utili-ties.

Debian Live system A Debian Live system is a live system that uses software from the Debian operat-ing system.

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-initramfs A collection of scripts used to boot live systems. live-initramfs is a fork ofcasper by Canonical, Ltd.

live-package The former name of live-initramfs.

Debian Installer / (d-i) FIXME

Cheat codes FIXME

chroot FIXME

binary image FIXME

Target distribution FIXME

etch/lenny/sid stable/testing/unstable FIXME

7

1.2. ABOUT THE DEBIAN LIVE PROJECT CHAPTER 1. ABOUT

1.1.2 Authors

A list of authors (in alphabetical order):

• Ben Armstrong

• Brendan Sleight

• Chris Lamb

• Daniel Baumann

• Franklin Piat

• Kai Hendry

• Marco Amadori

• Mathieu Geli

• Matthias Kirschner

• Trent W. Buck

1.1.3 Contributing to this document

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

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

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

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

1.2 About the Debian Live Project

1.2.1 Motivation

1.2.1.1 What is wrong with current live systems

There are already several Debian-based live systems and they are doing a great job. But, from the Debianperspective, 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 change package’s behavior and/or appearance by stripping them down to save space.

5. They include unofficial packages.

6. They ship custom kernels with additional patches 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

8

CHAPTER 1. ABOUT 1.2. ABOUT THE DEBIAN LIVE PROJECT

1.2.1.2 Why create our own live system?

Debian is the Universal Operating System: Debian should have an official live system for showingaround and to officially represent the true, one and only Debian system with the following main advan-tages:

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-image 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, section main or maybe contrib (the use ofcontrib is not decided yet). The non-free section is not part of Debian and therefore not used at all forthe live system.

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

Exception: temporarily, our own packages like live-helper or live-initramfs may be used from ourown repository for development reasons (e.g. to create development snapshots). They will be syncedinto Debian on a regular basis.

1.2.2.2 No configuration of the live system

In this phase we will not ship or install sample or alternative configurations. All packages are used intheir 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 packagemaintainer in Debian.

A system for configuring packages is provided using debconf in lh_config (use --preseed FILE) al-lowing custom configured packages to be installed in your custom produced Debian Live images, butfor official live images only default configuration will be used.

Exception: There are a few essential changes needed to be make a live system alive (e.g. configuringpam 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.2.3 No live system to hard disk installer

[ this is no longer valid after etch release, we will work on an installer for lenny ]For the moment we will not ship an installer to copy the live system to a partition on the hard

disk. Although we keep the changes in the live system as drastically minimal as possible comparedto a regular Debian installation, the live system does differ in a few essential points (see exceptions,guideline 2).

Therefore, we will ship a copy of the regular DebianInstaller (resp. Debian Installer, Graphical In-staller) instead, to allow users to perform a regular Debian installation (and, of course, cdebootstrap anddebootstrap are on the system too).

1.2.3 Contact

Mailing list The primary contact for the project is the mailing list. You can email the list directly byaddressing your mail to debian-live@lists.debian.org. The list archives are also available.

9

1.2. ABOUT THE DEBIAN LIVE PROJECT CHAPTER 1. ABOUT

IRC A number of users and developers are present in the #debian-live channel on OFTC. When askinga question on IRC, please be patient for an answer. If no answer is forthcoming, please email themailing 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. Formore information, please see Chapter 9.

Wiki FIXME. our entry on the Debian wiki.

10

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 especially that using a Debian installation is not required - live-helper will run on manyoperating systems such as Ubuntu.

2.2 Installing live-helper

You may 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 repos-itory.

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

11

2.2. INSTALLING LIVE-HELPER CHAPTER 2. INSTALLATION

2.2.2 From source

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

$ git clone git://git.debian.net/git/debian-live/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 locatedin 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 builtautomatically from the latest version in Git and are available on http://live.debian.net/debian.

2.2.4 From Backports.org

Whilst live-helper and friends are not a part of Debian etch relase, they will work on etch as well.You will need the following programs:

1. An etch backport of either debootstrap or cdebootstrap from backports.org

2. The lenny or sid version of live-helper

2.2.4.1 Installing debootstrap or cdebootstrap from backports.org

1. Put this in your /etc/apt/sources.list:

deb http://www.backports.org/debian etch-backports main

2. Update the package indices

apt-get update

3. Either install debootstrap:

apt-get install -t etch-backports debootstrap

or install cdebootstrap:

apt-get install -t etch-backports cdebootstrap

12

CHAPTER 2. INSTALLATION 2.3. LIVE-INITRAMFS

2.2.4.2 Installing live-helper on etch

It is not recommended that you use live-helper from backports.org as it is likely to be out of date.The live-helper package from Lenny or Sid can be installed on Etch (without upgrading other packages,such as libc6; it’s just shell scripts).

1. Install debootstrap or cdebootstrap from backports.org (as indicated above).

2. Install live-helper from testing or unstable

# apt-get install -t unstable live-helper

Of course you need the testing or unstable sources in /etc/apt/sources.list for this.

2.3 live-initramfs

N.B. You do not need to install on your host system to create customised Debian Live systems. However, doing sowill do no harm.

2.3.1 Using a customised live-initramfs

To modify the code you can follow the process below. Please ensure you are familiar with the termsmentioned in Section 1.1.1.

1. Checkout the live-initramfs source

$ git clone git://git.debian.net/git/debian-live/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 withoutdashes ’-’, 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 personalbuilder such as pbuilder to automate building packages in chroot. To build directly on the targetplatform, 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 isnot sufficient: you should treat the generated .deb like another custom package. Please see Section5.1.4 for more information. You should pay particular attention to Section 5.1.4.3.

2.3.2 Using a live-initramfs snapshots

You can let live-helper automatically use the latest snapshot of live-initramfs by configuring athird-party repository in your live-system configuration. Assumed you have already created a configu-ration tree with lh_config

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

echo "deb http://live.debian.net/debian/ ./" > config/chroot_sources/live- ←↩snapshots.chroot

2. Create a sources.list entry fro the binary stage:

cp config/chroot_sources/live-snapshots.chroot config/chroot_sources/live- ←↩snapshots.binary

13

2.3. LIVE-INITRAMFS CHAPTER 2. INSTALLATION

3. Fetcht the archive signing key:

wget http://live.debian.net/debian/archive.gpg -O config/chroot_sources/live ←↩-snapshots.chroot.gpg

cp config/chroot_sources/live-snapshots.chroot.gpg config/chroot_sources/ ←↩live-snapshots.binary.gpg

14

Chapter 3

The basics

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

3.1 First steps: building an ISO image

The following sequence of commands will create a basic ISO image containing just the Debian standardsystem without X.org. It is suitable for burning to CD or DVD media.

First, we must configure our Live system:

$ lh_config

Passing no parameters indicated that we wish to use the default binary image type. You will seethat live-helper created a "config/" hierarchy in your current directory - this is used by the restof live-helper to build your live image.

We can then build the image with lh_build as root:

# lh_build

This process can take a while, depending on the speed of your network connection.

3.1.1 Testing an ISO image with Qemu

Testing an ISO is simple:

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

3.1.2 Burning an ISO image to physical medium

Burning an ISO image is easy:

# apt-get install wodim$ wodim binary.iso

3.2 Building an USB/HDD image

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

Note if an iso image had been previously built, you will need to clean live-helper:

$ lh_clean --binary

First, we must configure live-helper to create a USD/HDD image type:

15

3.3. BUILDING A NETBOOT IMAGE CHAPTER 3. THE BASICS

$ lh_config -b usb-hdd

We can then build the image with lh_build as root:

# lh_build

3.2.1 Copying USB/HDD image to a USB stick

The generated binary image contains a VFAT partition and the syslinux bootloader, ready to be directlywritten on an USB stick. Plug in an USB stick with a size larger than binary.img’s one, and type:

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

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

IMPORTANT

This will definitely overwrite any previous contents on your stick!

3.2.2 Testing a USB/HDD image with Qemu

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

3.3 Building a netboot image

First, we configure our Live system:

$ 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 filesystemimage 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 respectfully of the NFS server where the filesytem image will belocated at boot-time.

We can then build the image with lh_build as root:

# lh_build

In a net boot, a client runs a small piece of software, usually on the EEPROM of the Ethernet card,which send a DHCP request to get an IP address and also information about what to do next : usuallygetting (through TFTP protocol) a higher level boot software like Grub or PXLINUX, or directly anoperating system like Linux.

For example, you can extract the generated binary-net.tar.gz archive in the /srv/debian-livedirectory; you’ll get the filesystem image in live/filesystem.squashfs, the kernel, initrd andPXE Linux bootloader in tftpboot/debian-live/i386.

We must now configure three services on the server:

DHCP server We must configure our network’s DHCP server to be sure to give a IP address to thecomputer 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) inthe /etc/dhcp3/dhcpd.conf configuration file :

16

CHAPTER 3. THE BASICS 3.3. BUILDING A NETBOOT IMAGE

# 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 guestsrange 192.168.1.100 192.168.1.149;

# allow booting from the netallow 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 activityoption 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 serves 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 will have downloaded and booted a Linux kernel and its initrd, itwill try to mount the Live filesystem image through a NFS server.

17

3.3. BUILDING A NETBOOT IMAGE CHAPTER 3. THE BASICS

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

Then, declare that the directory of the filesystem image is available through NFS, by writing in/etc/exports :

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

and let the NFS server knowing it typing following command :

# exportfs -rv

Setting all these services is quite error prone, you’ll need some patience to let all of them workingtogether.

18

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 that build Debian Live systems.The idea behind live-helper is a framework that uses a configuration directory to completely auto-

mate and customize all aspects of building a Live image.Many concepts are similar with 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 willlook for file called debian/<packagename>.install to determine which files should exist ina particular binary package. In much the same way, live-helper stores its configuration entirelyunder 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 aboutlh_config, please see Section 4.1.1.

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

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

live-helper respects environment variables which are present in the context of the shell it is run-ning. If variables can be read from config files, then they override environment variables, and if com-mand line options are used, they override values from config files. If no value for a given variable canbe 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 haveto follow the normal shell syntax. You can also put comments in these files; lines beginning with "#" areignored.

In some rare cases, you may want to have different versions of these files for different architecturesor distributions. If files named config/stage.arch or config/stage_helper.arch, and config/stage.dist orconfig/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 theother, more general files.

Please see Chapter 2 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 formore information.

19

4.1. LIVE-HELPER CHAPTER 4. OVERVIEW OF TOOLS

lh_build Responsible for starting a Live system build. See Section 4.1.2 for more information.

lh_clean Responsible for removing parts of a Live system build. Section 4.1.3 for more information.

4.1.1 The lh_config helper

As discussed in Section 4.1, the scripts that make up live-helper source their configuration from asingle directory named config/. As constructing this directory by hand would be time-consuming anderror-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 withsome default settings:

$ lh_config$ ls -ltotal 4.1kdrwxr-xr-x 19 user group 4.1k 2008-05-09 21:37 config$ ls -l config/total 91k-rw-r--r-- 1 user group 4.0k 2008-05-09 21:37 binarydrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_debian-installerdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_grubdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-debsdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-hooksdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-includesdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-packageslistsdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_local-udebsdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_rootfsdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 binary_syslinux-rw-r--r-- 1 user group 1.7k 2008-05-09 21:37 bootstrap-rw-r--r-- 1 user group 1.5k 2008-05-09 21:37 chrootdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_aptdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-hooksdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-includesdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-packagesdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_local-packageslistsdrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 chroot_sources-rw-r--r-- 1 user group 2.9k 2008-05-09 21:37 commondrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 includes-rw-r--r-- 1 user group 212 2008-05-09 21:37 sourcedrwxr-xr-x 2 user group 4.1k 2008-05-09 21:37 templates

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

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

$ lh_config -p gnome

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

$ lh_config --apt aptitude --binary-images net --hostname live-machine --username ←↩live-user ...

A full list of options is available FIXME. Most options have a parallel with an "LH_" prefixed variable.

4.1.2 The lh_build helper

FIXME

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.

20

CHAPTER 4. OVERVIEW OF TOOLS 4.2. THE LIVE-INITRAMFS PACKAGE

4.2 The live-initramfs package

live-initramfs is a collection of scripts.FIXME link to Kernel Handbook

21

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

5.1.2 Package installation

You can elect to use either apt or aptitude when installing packages. Which utility is used is governedby 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 desiredbehaviour.

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 thedesired 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 an initial values on the command line:

23

5.1. CUSTOMISING PACKAGE INSTALLATION CHAPTER 5. CUSTOMIZATION

$ lh_config --packages "package1 package2 package3"

The behaviour of live-helper when specifying a package that does not exist is determined byyour choice of APT utility. See Section 5.1.2 for more details.

If you need to specify a large number of packages to be installed or you need flexibility regardingwhich packages to install, you should probably be using package lists. See Section 5.1.3.2 for moreinformation.

5.1.3.2 Package lists

Package lists are a powerful way of expressing which packages should be installed. live-helperships with a number of predefined package lists which provide sensible default package selections forthe 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"

Packages lists that a distributed with live-helper reside in view in the /usr/share/live-helper/listsdirectory.

5.1.3.2.1 Local packages lists You may supplement the supplied lists using local package lists storedin 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..

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 areavailable to view in the /usr/share/live-helper/lists directory.

5.1.3.2.3 Using conditionals inside packages lists FIXME

#if ARCHITECTURE amd64ia32-libs#endif

or if LH_ARCHITECTURE is set to i386 or amd64:

#if ARCHITECTURE i386 amd64memtest86+#endif

or if LH_SECTIONS contains either contrib or non-free:

#if SECTIONS contrib non-freevrms#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

24

CHAPTER 5. CUSTOMIZATION 5.2. CUSTOMISING CONTENTS

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 sys-tem with modified versions of packages that are in the Debian repository. This may be to modify orsupport additional features, languages and branding, or even to remove elements of existing packagesthat are undesirable. Similarly, "third-party" packages may be used to add bespoke and/or proprietaryfunctionality.

This section does not cover advice regarding building or maintaining modified packages. JoachimBreitner’s ’How to fork privately’ may be of interest, however. The creation of bespoke packages iscovered 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 buthas a number of drawbacks, whilst using a custom APT repository is more time-consuming to setup.

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 thatare inside this directory will be automatically installed into the live system during build - you do notneed to specify them elsewhere.

Packages must be named in the prescribed way. One simple way to is to use dpkg-name. FIXMEUsing chroot_local-packages for installation of custom packages has two 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. Does not lend itself to storing Debian Live configurations in revision control

5.1.4.2 Using an APT repository to install custom packages

FIXMEUnlike You must ensure that you specify the package elsewhere, see (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.1.4.3 Custom packages and APT

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

Because of this. you may wish to increment the version number in your custom packages’ de-bian/changelog files to ensure that your modified version is installed over one in the official Debianrepositories. This may also be achieved by altering the live system’s APT pinning preferences - seeSection 5.1.4.4 for more information.

5.1.4.4 Altering APT preferences during Live system

FIXMEWhilst 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.

25

5.2. CUSTOMISING CONTENTS CHAPTER 5. CUSTOMIZATION

5.2.1 Includes

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

Chroot local includes These allow you to add or replace files to the chroot/Live filesystem. Please seeSection 5.2.1.1 for more information.

Binary local includes These allow you to add or replace files in the binary image. Please see Section5.2.1.2 for more information.

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

Please see Section 1.1.1 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 arevisible when the Live system is booted. Typical uses for them are to populate the skeleton user directory(/etc/skel) or adding configuration files where additional processing is not required.

To include files, simply add them to your config/chroot_local-includes directory. This di-rectory 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 areoverwritten.

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.

26

CHAPTER 5. CUSTOMIZATION 5.3. CUSTOMISING THE BOOTUP PROCESS

5.2.3 Preseeding Debconf questions

Files in the config/chroot_local-preseed directory are considered to be debconf preseed filesand 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 the bootup process

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

FIXME

5.3.1 Kernel

5.3.2 Bootloaders

FIXME

5.3.2.1 Choosing a bootloader

FIXME

5.3.2.2 Syslinux

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

5.3.2.3 Bootloader templates

FIXME

5.3.3 Splash screens

FIXME

5.3.4 Memtest

FIXME

5.3.5 Startup scripts

FIXME

5.3.6 Cheat codes

FIXMEChecksums.

5.4 Customising the binary image

This chapter discusses FIXME

27

5.4. CUSTOMISING THE BINARY IMAGE CHAPTER 5. CUSTOMIZATION

5.4.1 ISO metadata

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

LH_ISO_APPLICATION / --iso-application NAME This should describe the application that will be onthe 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 withsome contact details. The default for this option is the live-helper version you are using, whichmay 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, usuallywith 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 usedas a user-visible label on some platforms such as Windows and Apple Mac OS. The maximumlength for this field is 32 characters.

28

Chapter 6

Common tasks

6.1 The Debian Installer

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

THE "DEBIAN INSTALLER"

Please note the careful use of capital letters when referring to the "Debian Installer" inthis section - when used like this we refer explicitly to the official installer for the Debiansystem, 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 initrdwhich (when selected from the appropriate bootloader) launches into a standard Debian Installerinstance, 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 debootstrapor cdebootstrap, from the local media or some network-base network, resulting in a standardDebian 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 withinglive-helper.

"Live" Debian Installer This is a Debian Live image with a seperate kernel and initrd which (whenselected 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 atthe 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 continuesas 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 livegraphical environment.

This is currently NOT possible with Debian Live.

The values "Normal", "Live" and "Ubuntu" are not valid values for LH_BINARY_DEBIAN_INSTALLER.

29

Chapter 7

The Live environment

7.1 Swap space

FIXME

7.2 Hostname

FIXME

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 toa 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.

7.4 Language

When the live system boots there are three process which concerns language: the locale generation,setting the keyboard layout for the console and setting the keyboard layout for X. To define the localethat should be generated, use the locale parameter to the --bootappend-live option of lh_config, e.g.:

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

Both the console and X keyboard configuration depends on the keyb parameter of the --bootappend-liveoption. Valid options for X keyboard layouts can be found in /etc/X11/xkb/base.xml. To findthe value (the two characters) corresponding to a language try searching for the english name of thenation 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:

31

7.5. PERSISTENCE CHAPTER 7. THE LIVE ENVIRONMENT

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"

7.5 Persistence

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

A Debian Live system is a generalization of this paradigm and thus supports more media, and notonly cds; but stills, in its default behaviour, it should be considered read only and all the runtime evolu-tions of the system are lost with a shutdown.

Persistence is a common name for different kinds of solutions for saving across reboots some or allof this runtime evolution of the system; to undestand how it could work it could be handy to know thateven if the system is booted and runt from a read only media, modification to the files and directoriesare wrote on a writable media , tipically a ram disk (tmpfs) and ram disk’s data do not survive reboots.

The data stored on this ramdisk should be saved in a writable persistent media like on an Hard Disk,a USB key, a network "share" or even a session of a multisession (re)writable CD/DVD. All this citedmedia are supported in Debian Live in different ways, all but latest one requires a special boot parameterto be specified at boot: persistent.

7.5.1 Full persistence

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

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

But since live system users, not always can use an hard drive partition, maybe because they aren’tallowed or they wan’t to repartition a drive, and considering that most USB keys have laughables writespeeds, "full" persistence could be also used with just image files, so you could create a file representinga 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 in a writable partition and reboot with "persistent" boot parameter.

7.5.2 Home automounting

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

7.5.3 Snapshots

Snapshots are collection of files and directories which are not mounted while running but which arecopied from a persistent device to the system (tmpfs) at boot and which are resynced at reboot/shut-down of the system. The content of a snapshot could reside on a partition or an image file (like theabove 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 afile named like that could be found. A power interruption during runtime could lead to data lost hence atool invoked live-snapshot --refresh could be called to sync important changes. This type of persistence

32

CHAPTER 7. THE LIVE ENVIRONMENT 7.5. PERSISTENCE

since it does not write continuosly to the persistent media is the most flash-based device friendly andthe 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 mainsnapshot but it is only applied to /home.

All kind of snapshots cannot currently handle file deleting while full persistence and obviously homeautomounting could.

7.5.4 Partial remasterings

The runtime modification of the tmpfs could be collected usign live-snapshot in a squashfs and addedto the cd by remastering the iso in 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.

33

Chapter 8

Frequently asked questions (FAQ)

35

Chapter 9

Reporting bugs

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

For the impatient:

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

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

9.1 Rebuild from scratch

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

9.2 Use up-to-date packages

This meansUsing 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 theresources of the Debian kernel team are limited and will be unlikely to be able to fix the problem.

9.3 Collect information

Please provide enough information with your report. At a minimum, it should contain the exact versionof live-helper version where the bug is encountered, and steps to reproduce it. Please use common senseand 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

37

9.4. USE THE CORRECT PACKAGE TO REPORT THE BUG AGAINSTCHAPTER 9. REPORTING BUGS

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 up-load it somewhere (do *not* send it as an attachment to the mailinglist), so that we can try to reproducethe errors you encountered.

9.4 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 deboot-strap or cdebootstrap. Depending on the bootstrapping tool used and the Debian distribution itis bootstrapping, it may fail. If a bug appears here, check if the error is related to a specific Debianpackage (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 thisdirectly. 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 Debianarchive and depending on the Debian distribution used and the daily archive state, it can fail. If abug 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 againstthe failing package. Running debootstrap seperately from the Live system build or runninglh_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 prob-lem, 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 infor-mation requested in Section 9.3. 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 alwaysrun it on real hardware before reporting a bug. Providing a screenshot of the failure is also veryhelpful.

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.5 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 alwaysa chance that it has been discussed elsewhere, and a possible solution, patch, or workaround has beenproposed.

You should pay particular attention to the Debian Live mailing list, as well as the homepage, asthese are likely to contain the most up-to-date information. If such information exists, always includethe 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.6 Where to report bugs

The Debian Live project keeps track of all bugs in the Debian Bug Tracking System (BTS). For infor-mation on how to use the system, please see http://bugs.debian.org. You can also submit the bugs byusing 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 errorsagainst live-initramfs. If you are unsure of which package is appropriate or need more help beforesubmitting a bug report, please send a message to the mailing list and we will help you to figure it out.

38

CHAPTER 9. REPORTING BUGS 9.6. WHERE TO REPORT BUGS

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

39

Chapter 10

Coding Style

This chapter documents the coding style used in live-helper.

10.1 Compatibility

• Don’t use bashisms, e.g. no arrays.

• Only use posix subset, e.g. use $(foo) rather than ‘foo‘.

• Do check your scripts with ’sh -n’ and ’checkbasishm’.

10.2 Indenting

• Always use tabs and not spaces.

10.3 Wrapping

• Generally, lines are 80 chars at maximum.

• Use the linux like line breaks: Bad:

if foo; thenbar

fi

Good:

if foothenbar

fi

• Same for functions: Bad:

foo () {bar

}

Good:

foo (){bar

}

41

10.4. VARIABLES CHAPTER 10. CODING STYLE

10.4 Variables

• Variables are always in capital letters.

• Variables that used in config always start with LH_ prefix.

• Internal, live-helper controlling variables start with _LH_ prefix.

• Local variables start with __LH_ prefix.

• Put curly brackets arround them, write ${FOO} not $FOO.

• Always protect variables wrt/ potential whitespaces, write "${FOO}" not ${FOO}.

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

if [ -f "${FOO}"/foo/"${BAR}"/bar ]thenfoobar

fi

Good:

if [ -f "${FOO}/foo/${BAR}/bar" ]thenfoobar

fi

42

Chapter 11

Resources and links

11.1 Links

FIXME

1. Debian homepage

11.2 Who is using Debian Live?

A number of projects are using Debian Live:

• Debian KDE4 livecd

• gNewSense "forked" a very early live-package

• GNUSTEP Live CD using live-package

• PlayStation 3 Live CD using live-package

• Sidux Live CD "forked" an early live-package

• Vamos

• Clonezilla (system image distributer)

• Webconverger

• Xorcom Rapid live cd - Asterisk-based live CD

• PelicanHPC uses live-helper

• IES S’Arenal, Llucmajor (Secondary school located near to Palma de Mallorca), Spain.

43

Appendix A

Configuration layout

LAYOUT OF THE CONFIG/ DIRECTORY

binary_debian-installer/ (see Section 6.1)

binary_grub/ (see Section 5.3.2)

binary_local-debs/ (see Section 6.1)

binary_local-hooks/ (see Section 5.2.2.2)

binary_local-includes/ (see Section 5.2.1.3)

binary_local-packageslists/ (see Appendix A)

binary_local-udebs/ (see Section 6.1)

binary_rootfs/ (see Appendix A)

binary_syslinux/ (see Section 5.3.2)

chroot_apt/ (see Section 5.1.4.3)

chroot_local-hooks/ (see Section 5.2.2.1)

chroot_local-includes/ (see Section 5.2.1.1)

chroot_local-packages/ (see Section 5.1.4.1)

chroot_local-packageslists/ (see Section 5.1.3.2)

chroot_local-presed/ (see Section 5.2.3)

chroot_sources/ (see Section 5.1.4.2)

includes/ (see Section 5.3.2)

templates/ (see Section 5.3.2)

bootstrap (see Section B.2)

binary (see Section B.1)

chroot (see Section B.3)

common (see Section B.4)

source (see Section B.5)

45

Appendix B

Configuration files

B.1 The config/binary file

LH_BINARY_FILESYSTEM Set image filesystem. (See Appendix A)

LH_BINARY_IMAGES Set image type. (See Appendix A)

LH_BINARY_INDICES Set apt/aptitude generic indices. (See Appendix A)

LH_BOOTAPPEND_LIVE Set boot parameters. (See Appendix A)

LH_BOOTAPPEND_INSTALL Set boot parameters. (See Appendix A)

LH_BOOTLOADER Set bootloader. (See Section 5.3.2)

LH_CHECKSUMS Set checksums. (See Section 5.3.6)

LH_CHROOT_BUILD Control if we build binary images chrooted. (See Appendix A)

LH_DEBIAN_INSTALLER Set debian-installer. (See Section 6.1)

LH_DEBIAN_INSTALLER_DAILY Set daily images. (See Section 6.1)

LH_ENCRYPTION Set encrytion. (See Appendix A)

LH_GRUB_SPLASH Set custom grub splash. (See Section 5.3.3)

LH_HOSTNAME Set hostname. (See Section 7.2)

LH_ISO_APPLICATION Set iso author. (See Section 5.4.1)

LH_ISO_PREPARER Set iso preparer. (See Section 5.4.1)

LH_ISO_PUBLISHER Set iso publisher. (See Section 5.4.1)

LH_ISO_VOLUME Set iso volume (max 32 chars). (See Section 5.4.1)

LH_JFFS2_ERASEBLOCK Set jffs2 eraseblock size. (See Appendix A)

LH_MEMTEST Set memtest. (See Section 5.3.4)

LH_NET_ROOT_FILESYSTEM Set netboot filesystem. (See Appendix A)

LH_NET_ROOT_MOUNTOPTIONS Set nfsopts. (See Appendix A)

LH_NET_ROOT_PATH Set netboot server directory. (See Appendix A)

LH_NET_ROOT_SERVER Set netboot server address. (See Appendix A)

LH_NET_COW_FILESYSTEM Set net client cow filesystem. (See Appendix A)

LH_NET_COW_MOUNTOPTIONS Set cow mount options. (See Appendix A)

47

B.2. THE CONFIG/BOOTSTRAP FILE APPENDIX B. CONFIGURATION FILES

LH_NET_COW_PATH Set cow directory. (See Appendix A)

LH_NET_COW_SERVER Set cow server. (See Appendix A)

LH_NET_TARBALL Set net tarball. (See Appendix A)

LH_SYSLINUX_SPLASH Set custom syslinux splash. (See Section 5.3.3)

LH_SYSLINUX_TIMEOUT Set custom syslinux timeout in seconds. (See Section 5.3.2.2)

LH_SYSLINUX_CFG Set custom syslinux configuration file. (See Section 5.3.2.2)

LH_SYSLINUX_MENU Set syslinux menu. (See Section 5.3.2.2)

LH_SYSLINUX_MENU_LIVE_ENTRY Set text to be used on the menu for live entries. (See Section5.3.2.2)

LH_SYSLINUX_MENU_LIVE_FAILSAFE_ENTRY Set text to be used on the menu for live entries(failsafe ones). (See Section 5.3.2.2)

LH_SYSLINUX_MENU_MEMTEST_ENTRY Set text to be used on the menu for memtest entry. (SeeSection 5.3.2.2 and Section 5.3.4)

LH_USERNAME Set username. (See Section 7.3)

B.2 The config/bootstrap file

LH_ARCHITECTURE Select chroot architecture. (See Appendix A)

LH_BOOTSTRAP_CONFIG Set distribution config directory. (See Appendix A)

LH_BOOTSTRAP_INCLUDE Include packages on base. (See Appendix A)

LH_BOOTSTRAP_EXCLUDE Exclude packages on base. (See Appendix A)

LH_BOOTSTRAP_FLAVOUR Select flavour to use. (See Appendix A)

LH_BOOTSTRAP_KEYRING Set distribution keyring. (See Appendix A)

LH_DISTRIBUTION Select distribution to use. (See Appendix A)

LH_MIRROR_BOOTSTRAP Set mirror to bootstrap from. (See Section 5.1.1)

LH_MIRROR_CHROOT Set mirror to fetch packages from. (See Section 5.1.1)

LH_MIRROR_CHROOT_SECURITY Set security mirror to fetch packages from. (See Section 5.1.1)

LH_MIRROR_BINARY Set mirror which ends up in the image. (See Section 5.1.1)

LH_MIRROR_BINARY_SECURITY Set security mirror which ends up in the image. (See Section 5.1.1)

LH_SECTIONS select section(s) to use. (See Section 5.1.1)

B.3 The config/chroot file

LH_CHROOT_FILESYSTEM Set chroot filesystem. (See Appendix A)

LH_UNION_FILESYSTEM Set union filesystem. (See Appendix A)

LH_EXPOSED_ROOT expose root as read only. (See Appendix A)

LH_HOOKS Set hook commands. (See Section 5.2.2)

LH_INTERACTIVE Set interactive build. (See Appendix A)

LH_KEYRING_PACKAGES Set keyring packages. (See Appendix A)

48

APPENDIX B. CONFIGURATION FILES B.4. THE CONFIG/COMMON FILE

LH_LANGUAGE Set language to use. (See Section 7.4)

LH_LINUX_FLAVOURS Set kernel flavour to use. (See Section 5.3.1)

LH_LINUX_PACKAGES Set kernel packages to use. (See Section 5.3.1)

LH_PACKAGES Set packages to install. (See Section 5.1.3.1)

LH_PACKAGES_LISTS Set package list to install. (See Section 5.1.3.2)

LH_TASKS Set tasks to install. (See Section 5.1.3.3)

LH_SECURITY enable security updates. (See Section 5.1.1)

LH_SYMLINKS enable symlink convertion. (See Section 5.2.4)

LH_SYSVINIT enable sysvinit. (See Section 5.3.5)

B.4 The config/common file

LH_APT Set package manager. (See Section 5.1.2)

LH_APT_FTP_PROXY Set apt/aptitude ftp proxy. (See Section 5.1.2)

LH_APT_HTTP_PROXY Set apt/aptitude http proxy. (See Section 5.1.2)

LH_APT_PDIFFS Set apt/aptitude pdiff indices. (See Section 5.1.2)

LH_APT_PIPELINE Set apt/aptitude pipeline depth. (See Section 5.1.2)

LH_APT_RECOMMENDS Set apt/aptitude recommends. (See Section 5.1.2)

LH_APT_SECURE Set apt/aptitude security. (See Section 5.1.2)

LH_BOOTSTRAP Set bootstrap program. (See Appendix A)

LH_CACHE control cache. (See Appendix A)

LH_CACHE_INDICES control if downloaded package indices should be cached. (See Appendix A)

LH_CACHE_PACKAGES control if downloaded packages files should be cached. (See Appendix A)

LH_CACHE_STAGES control if completed stages should be cached. (See Appendix A)

LH_DEBCONF_FRONTEND Set debconf(1) frontend to use. (See Appendix A)

LH_DEBCONF_NOWARNINGS Set debconf(1) warnings. (See Appendix A)

LH_DEBCONF_PRIORITY Set debconf(1) priority to use. (See Appendix A)

LH_INITRAMFS Set initramfs hook. (See Appendix A)

LH_FDISK Set fdisk program. (See Appendix A)

LH_LOSETUP Set losetup program. (See Appendix A)

LH_MODE Set distribution mode. (See Appendix A)

LH_ROOT_COMMAND use sudo or equivalent. (See Appendix A)

LH_USE_FAKEROOT use fakeroot/fakechroot. (See Appendix A)

LH_TASKSEL Set tasksel program. (See Section 5.1.3.3)

LH_INCLUDES Set includes. (See Appendix A)

LH_TEMPLATES Set templates. (See Appendix A)

LH_BREAKPOINTS enable breakpoints. (See Appendix A)

49

B.5. THE CONFIG/SOURCE FILE APPENDIX B. CONFIGURATION FILES

LH_DEBUG enable debug. (See Appendix A)

LH_FORCE enable force. (See Appendix A)

LH_QUIET enable quiet. (See Appendix A)

LH_VERBOSE enable verbose. (See Appendix A)

B.5 The config/source file

LH_SOURCE Set source option. (See Appendix A)

LH_SOURCE_IMAGES Set image type. (See Appendix A)

50