Debian Live Manual

The Debian Live Project

April 8, 2010

Debian Live Manualby The Debian Live Project

Published Thu, 08 Apr 2010 06:30:01 +0000Copyright © 2008-2010 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).

ii

Contents

1 About 11.1 About this manual . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

1.1.1 Terms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11.1.2 Authors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21.1.3 Contributing to this document . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

1.1.3.1 Applying patches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2 About the Debian Live Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

1.2.1 Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31.2.1.1 What is wrong with current live systems . . . . . . . . . . . . . . . . . . . 31.2.1.2 Why create our own live system? . . . . . . . . . . . . . . . . . . . . . . . 4

1.2.2 Philosophy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41.2.2.1 Only unchanged, official packages . . . . . . . . . . . . . . . . . . . . . . 41.2.2.2 No package configuration of the live system . . . . . . . . . . . . . . . . . 41.2.2.3 Live system to hard disk installer . . . . . . . . . . . . . . . . . . . . . . . 4

1.2.3 Contact . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

2 Installation 72.1 Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2 Installing live-helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

2.2.1 From the Debian repository . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72.2.2 From source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.2.3 From ’snapshots’ . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 82.2.4 live-initramfs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

2.2.4.1 Using a customised live-initramfs . . . . . . . . . . . . . . . . . . . . 82.2.4.2 Using live-initramfs snapshots . . . . . . . . . . . . . . . . . . . . . 9

3 The basics 113.1 What is a live system? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113.2 First steps: building an ISO image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

3.2.1 Testing an ISO image with Qemu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.2.2 Burning an ISO image to a physical medium . . . . . . . . . . . . . . . . . . . . . . 12

3.3 Building an USB/HDD image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 123.3.1 Copying USB/HDD image to a USB stick . . . . . . . . . . . . . . . . . . . . . . . . 123.3.2 Testing a USB/HDD image with Qemu . . . . . . . . . . . . . . . . . . . . . . . . . 123.3.3 Using the space left on a USB stick . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

3.4 Building a netboot image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 133.5 Netboot testing HowTo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

4 Overview of tools 174.1 live-helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

4.1.1 The lh_config helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.1.2 The lh_build helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184.1.3 The lh_clean helper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

4.2 The live-initramfs package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

5 Customization 215.1 Customising package installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

5.1.1 Package sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215.1.2 Package installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 225.1.3 Installing additional packages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.1.3.1 The LH_PACKAGES variable . . . . . . . . . . . . . . . . . . . . . . . . . 225.1.3.2 Package lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

5.1.3.2.1 Local packages lists . . . . . . . . . . . . . . . . . . . . . . . . . . 235.1.3.2.2 Extending a provided package list using includes . . . . . . . . 23

iii

CONTENTS

5.1.3.2.3 Using conditionals inside packages lists . . . . . . . . . . . . . . 235.1.3.3 Tasks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

5.1.4 Installing modified or third-party packages . . . . . . . . . . . . . . . . . . . . . . . 235.1.4.1 Using chroot_local-packages to install custom packages . . . . . . 245.1.4.2 Using an APT repository to install custom packages . . . . . . . . . . . . 245.1.4.3 Custom packages and APT . . . . . . . . . . . . . . . . . . . . . . . . . . . 245.1.4.4 Altering APT preferences during Live system . . . . . . . . . . . . . . . . 24

5.2 Customising contents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245.2.1 Includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

5.2.1.1 Live/chroot local includes . . . . . . . . . . . . . . . . . . . . . . . . . . . 255.2.1.2 Binary local includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255.2.1.3 Binary includes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

5.2.2 Hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255.2.2.1 Live/chroot local hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255.2.2.2 Binary local hooks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

5.2.3 Preseeding Debconf questions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255.2.4 Symlink conversion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

5.3 Customising the bootup process . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.3.1 Kernel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.3.2 Bootloaders . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

5.3.2.1 Choosing a bootloader . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.3.2.2 Syslinux . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.3.2.3 Bootloader templates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.3.2.4 Booting a Debian Live USB/HDD system from a USB stick with Grub . . 26

5.3.3 Splash screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.3.4 Memtest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265.3.5 Startup scripts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 275.3.6 Cheat codes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

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

5.5 Using a newer kernel with Lenny . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27

6 Common tasks 296.1 The Debian Installer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296.2 WiFi Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337.5.3 Snapshots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337.5.4 Persistent SubText . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337.5.5 Partial remastering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

8 Frequently asked questions (FAQ) 35

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

iv

CONTENTS

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

11 Procedures 4311.1 Udeb Uploads . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4311.2 Major Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4311.3 Point Releases . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

11.3.1 Point release announcement template . . . . . . . . . . . . . . . . . . . . . . . . . . 44

12 Resources and links 4712.1 Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4712.2 Who is using Debian Live? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4712.3 English sources related to debian live . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4712.4 German sources related to debian live . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4812.5 Spanish sources related to debian live . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

A Configuration layout 49

B Configuration files 51B.1 The config/binary file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51B.2 The config/bootstrap file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52B.3 The config/chroot file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52B.4 The config/common file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53B.5 The config/source file . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

v

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 which canbe obtained by becoming the root user via su or by using sudo. To distinguish between commandswhich may be executed by an unprivileged user and those requiring superuser privileges, commandsare 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 donot alter local operating system(s) or file(s) already installed on the computer hard drive unlessinstructed to do so. Live systems are typically booted from media such as CDs or DVDs, somemay also boot with USB sticks or over the network (via netboot images).

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

Debian Live system A live system that uses software from the Debian operating system that may bebooted 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-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-helper.

Debian Installer / (d-i) FIXME

Cheat codes FIXME

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

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

Target distribution FIXME

1

CHAPTER 1. ABOUT 1.1. ABOUT THIS MANUAL

lenny/squeeze/sid stable/testing/unstable The "stable" distribution contains the latest officially releaseddistribution of Debian. The "testing" distribution is the staging area for the next stable release a -the main advantage of using this distribution is that it has more recent versions of software relativeto 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" re-lease. 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 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://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

2

CHAPTER 1. ABOUT 1.2. ABOUT THE DEBIAN LIVE PROJECT

1.1.3.1 Applying patches

Directly commiting to the repository is possible by anyone. However, we ask you to send bigger changesto 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 your openssh-client config:

$ cat >> ~/.ssh/config << EOFHost live.debian.net

Hostname live.debian.netUser gitosisIdentityFile ~/.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, startingwith a capital letter and ending with a full stop. Usually starting with the form ’Fixing/Adding/Re-moving/Correcting/’:

$ git commit -a

• Push the commit to the server:

$ git push

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

3

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 in the "main" section (possibly contrib,although not decided yet). The non-free section is not part of Debian and therefore cannot be used at allfor live systems.

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

As an exception, our own packages such as live-helper or live-initramfs may temporarilybe used from our own repository for development reasons (e.g. to create development snapshots). Theywill 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 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. For more information, please see Chap-ter 5.

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 Live system to hard disk installer

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 compared to aregular Debian installation, the live system does differ in a few essential points (see exceptions, guideline2).

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.

4

CHAPTER 1. ABOUT 1.2. ABOUT THE DEBIAN LIVE PROJECT

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 The Debian Live wiki is a place to gather information, discuss applied technologies, and documentframeworks of Debian Live systems that go beyond the scope of this document.

5

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 onalmost 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 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

7

CHAPTER 2. INSTALLATION 2.2. INSTALLING LIVE-HELPER

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://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 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 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 termsmentioned in Section 1.1.1.

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 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 systemis not sufficient: you should treat the generated .deb like another custom package. Please seeSection 5.1.4 for more information. You should pay particular attention to Section 5.1.4.3.

8

CHAPTER 2. INSTALLATION 2.2. INSTALLING LIVE-HELPER

2.2.4.2 Using 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/ sid-snapshots main contrib non-free" > ←↩config/chroot_sources/debian-live_sid-snapshots.chroot

2. Create a sources.list entry fro 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

9

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 What is a live system?

A live system usually means an OS booted on a computer from a removable support (as CD-ROM, USBstick, or network), ready to use without any installation on the usual drive(s), with an auto-configurationdone at runtime (see Section 1.1.1).

With Debian Live, it’s a Debian GNU/Linux OS, built for one of the supported architectures (cur-rently 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 neededto mount the filesystem’s image and some scripts to do it.

System image The O.S. image. Debian Live uses a SquashFS image, a compressed filesystem, to mini-mize its size. Note that it’s read-only, so during boot, the Debian Live system will uses RAM diskand ’union’ mechanism to be able to write files on the system, but all modifications will be lostwhen shutdown, until using optional persistence partition(s) (see Section 7.5).

Bootloader A small piece of code, crafted to boot up from the chosen media, possibly proposing aprompt or menu to let select options/configuration, then loading the Linux kernel and its initrdto let it run with associated filesystem image. Different solutions can be proposed depending ofthe target media and format of filesystem containing the previous components: Isolinux to bootfrom a CD or DVD in ISO9660 format, syslinux for HDD or USB drive boot from a VFAT partition,GRUB for ext2/3 partition, pxelinux for PXE netboot...

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

3.2 First steps: building an ISO image

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

First, we run the lh_config helper command which will create a "config/" hierarchy in thecurrent 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, which willcreate an image of type binary (see Section 4.1.1).

Now that we have a "config/" hierarchy, we may build the image with lh_build helper com-mand:

11

CHAPTER 3. THE BASICS 3.3. BUILDING AN USB/HDD IMAGE

# lh_build

This process can take a while, depending on the speed of your network connection (see Section 4.1.2).

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 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 theDebian standard system without X.org. It is suitable for booting from USB sticks, USB hard drives, andvarious other portable storage devices.

Note if you created an iso image with the previous example, you will need to clean up your workingdirectory with the lh_clean helper command (see Section 4.1.3):

$ lh_clean --binary

Run the lh_config helper command with the parameters to configure the "config/" hierarchyto create a USD/HDD image type:

$ lh_config -b usb-hdd

Now build the image with 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 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 youro stick!

3.3.2 Testing a USB/HDD image with Qemu

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

12

CHAPTER 3. THE BASICS 3.4. BUILDING A NETBOOT IMAGE

3.3.3 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 apartitioning tool such as gparted or parted to create a new partition on the stick. The first partition willbe 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 beext2 (ext3 isn’t recommended because the journaling causes too much 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 lostbecause the image includes a complete partition table.

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

3.4 Building a netboot image

The following sequence of helper commands will create a basic netboot image containing the Debianstandard 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 directorywith the lh_clean helper command:

$ lh_clean --binary

Run the lh_config helper command with the parameters to configure the "config/" hierarchyto 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 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.

Now build the image with lh_build helper command:

# lh_build

In a network boot, the client runs a small piece of software, usually on the EEPROM of the Ethernetcard, which sends a DHCP request to get an IP address and also information about what to do next;such as getting (through TFTP protocol) a higher level boot software like Grub or PXLINUX, or directlyto an operating 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 :

13

CHAPTER 3. THE BASICS 3.4. 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.You should install the nfs-kernel-server server package -- nfs-user-server does not function cor-rectly with netboot.

14

CHAPTER 3. THE BASICS 3.5. NETBOOT TESTING HOWTO

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.

3.5 Netboot testing HowTo

Netboot images creation is made easy with live-helper magic, but testing the images on physical ma-chines can be really time consuming. To make our life easier, we can use virtualization. There are twosolutions:

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/vmwareconfig.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/shsudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1echo "Executing /etc/qemu-ifup"echo "Bringing up $1 for bridged mode..."sudo /sbin/ifconfig $1 0.0.0.0 promisc upecho "Adding $1 to br0..."sudo /usr/sbin/brctl addif br0 $1sleep 2

15

CHAPTER 3. THE BASICS 3.5. NETBOOT TESTING HOWTO

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

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

16

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 toas "helpers".

The idea behind live-helper is to be a framework that uses a configuration directory to com-pletely automate 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 helper commands, someadditional files can be used to configure the behavior of specific helper commands. These files aretypically named config/foo or config/stage (where "stage", of course, is replaced with the name of thestage that they belong to, and "helper" with the name of the helper).

For example, the lh_bootstrap_debootstrap helper command uses files named config/bootstrapand config/bootstrap_debootstrap to read the options it will use. Generally, these files containvariables with values assigned, one variable per line. Some programs in live-helper use pairs ofvalues or slightly more complicated 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 theyhave 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 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:

17

CHAPTER 4. OVERVIEW OF TOOLS 4.1. LIVE-HELPER

lh_config Responsible for initialising a Live system configuration directory. See Section 4.1.1 formore information.

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

18

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

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.

4.2 The live-initramfs package

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

19

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 debianlive 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 toyour 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

21

CHAPTER 5. CUSTOMIZATION 5.1. CUSTOMISING PACKAGE INSTALLATION

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 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 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 are distributed with live-helper reside in view in the /usr/share/live-helper/listsdirectory.

22

CHAPTER 5. CUSTOMIZATION 5.1. CUSTOMISING PACKAGE INSTALLATION

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

LIVE-HELPER 2.X CHANGE

Any file with .list suffix in config/chroot_local-packageslists is automatically enabled,the variable LH_PACKAES_LISTS should only be used referencing packages lists in-cluded 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 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

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:

23

CHAPTER 5. CUSTOMIZATION 5.2. CUSTOMISING CONTENTS

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

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.

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 Sec-tion 5.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.

24

CHAPTER 5. CUSTOMIZATION 5.2. CUSTOMISING CONTENTS

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) used by the live system to create the live user’s home directory, or adding configurationfiles 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.

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)

25

CHAPTER 5. CUSTOMIZATION 5.3. CUSTOMISING THE BOOTUP PROCESS

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.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 USBstick with ext2/3 partition and Grub bootloader:

First, copy live components in a directory on your key: the Linux kernel (vmlinuz*), its Initial RAMdisk (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 Liveroot (hd0,1) # my Ext2 partition is the second on this stickkernel /boot/live/vmlinuz1 boot=live vga=791 persistent union=aufs live- ←↩

media-path=boot/liveinitrd /boot/live/initrd1.img

EOF

The important kernel command line option to add here is live-media-path, which tells to Live initrd’sscript in which subdirectory to look for the SquashFS image.

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

5.3.3 Splash screens

FIXME

5.3.4 Memtest

FIXME

26

CHAPTER 5. CUSTOMIZATION 5.4. CUSTOMISING THE BINARY IMAGE

5.3.5 Startup scripts

FIXME

5.3.6 Cheat codes

FIXMEChecksums.

5.4 Customising the binary image

This chapter discusses FIXME

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.

5.5 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 laterkernel. 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

27

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.

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

$ lh_config --help...

29

CHAPTER 6. COMMON TASKS 6.2. WIFI CONNECTION

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

You can also use the appropriate variables in the config/binary file:

$ cat config/binary | grep DEBIAN_INTALLERset debian-installerLH_DEBIAN_INSTALLER="disabled"# $LH_DEBIAN_INSTALLER_DISTRIBUTION: set debian-installer suiteLH_DEBIAN_INSTALLER_DISTRIBUTION="lenny"# $LH_DEBIAN_INSTALLER_PRESEEDFILE: set debian-installer preseed filename/urlLH_DEBIAN_INSTALLER_PRESEEDFILE=""

The values "Normal", "Live" and "Ubuntu" are not valid values for LH_BINARY_DEBIAN_INSTALLER.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 DebianLive image you may need to only attach to an available access point. If you encounter difficulty a goodplace to start is at the Debian Wiki entry for WiFi.

30

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 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, 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-liveoption 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.

31

CHAPTER 7. THE LIVE ENVIRONMENT 7.5. PERSISTENCE

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 (ratherlimited to two-letters country codes). To find the value (the two characters) corresponding to a languagetry 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 layoutusing X (XKB) definitions; you can then setup your keyboard layout more precisely with klayou-t, kvariant, koptions and kmodel variables; live-initramfs will use also these parameters for Xconfiguration. For example, to set up a french system with a french-dvorak layout (called Bépo) on aTypeMatrix 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 keybvariable 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, wherewrites 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 addi-tion to CDs; but still, in its default behaviour, it should be considered read-only and all the runtimeevolutions 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 knowthat even if the system is booted and run from read-only media, modification to the files and directoriesare 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 mediaare supported in Debian Live in different ways, and all but the last one require a special boot parameterto 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-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 the boot parameter ’persistent’. This partitioncould 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 thefollowing:

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

32

CHAPTER 7. THE LIVE ENVIRONMENT 7.5. PERSISTENCE

But since live system users cannot always use a hard drive partition, and considering that most USBkeys have poor write speeds, ’full’ persistence could be also used with just image files, so you couldcreate 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, thisfilesystem will be directly mounted as /home, thus permitting persistence of files that belong to e.g. thedefault 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 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 ora 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 ofpersistence, since it does not write continuously to the persistent media, is the most flash-based devicefriendly 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 mainsnapshot 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 conjuntionwith the boot parameter persistent will allow for multiple but unique persistent media. An examplewould be if a user wanted to use a persistent partition labeled live-sn-subText they would use the bootparameters 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 addedto 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.

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 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-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 Known issues

Due to the nature of Debian testing and Debian unstable branches being a moving target, building a livesystem 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-helperdoes 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 notsucceeding to build testing, try if unstable works. If unstable does not work either, revert to testing andpinning 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 wholelive system from scratch to see if the bug is reproducible.

9.3 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.4 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 commonsense and include other relevant information if you think that it might help in solving the problem.

37

CHAPTER 9. REPORTING BUGS 9.5. USE THE CORRECT PACKAGE TO . . .

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

38

CHAPTER 9. REPORTING BUGS 9.6. DO THE RESEARCH

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

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 and (ideally) in live-initramfs.

10.1 Compatibility

• Don’t use syntax or semantics that are unique to the Bash shell. For example, the use of arrayconstructs.

• Only use the POSIX subset - for example, use $(foo) over ‘foo‘.

• You can check your scripts with ’sh -n’ and ’checkbashisms’

10.2 Indenting

• Always use tabs over spaces.

10.3 Wrapping

• Generally, lines are 80 chars at maximum.

• Use the "Linux style" of line breaks: Bad:

if foo; thenbar

fi

Good:

if foothen

barfi

• The same holds for functions: Bad:

foo () {bar

}

Good:

foo (){

bar}

41

CHAPTER 10. CODING STYLE 10.4. VARIABLES

10.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 ]thenfoobar

fi

Good:

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

fi

10.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; ...".

42

Chapter 11

Procedures

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

11.1 Udeb Uploads

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

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

11.2 Major Releases

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

• The local debian mirror of the debian-live buildd needs to be synced against a mirror that containsthe released version.

• The local debian-security mirror of the debian-live buildd needs to be synced against a mirror thatcontains the released version.

• The names of the image need to be known (e.g. debian-live-500-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.

11.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 imagesneed to be checked that they are not too big.

• Images are built and mirrored on cdimage.debian.org.

• Send announcement mail.

43

CHAPTER 11. PROCEDURES 11.3. POINT RELEASES

11.3.1 Point release announcement template

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

$ 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 ofupdated 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 releasealong with a few adjustments for serious problems. A full list of thechanges may be viewed at:

<http://lists.debian.org/debian-announce/%release_mail%>

It also includes the following Live-specific changes:

* [INSERT LIVE-SPECIFIC CHANGE HERE]

* [INSERT LIVE-SPECIFIC CHANGE HERE]

* [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

44

CHAPTER 11. PROCEDURES 11.3. POINT RELEASES

volunteer their time and effort in order to produce the completely freeoperating system Debian GNU/Linux.

About Debian Live-----------------

Debian Live is an official sub-project of Debian which produces Debiansystems that do not require a classical installer. Images are availablefor CD/DVD discs, USB sticks and PXE netbooting as well as a barefilesystem 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>.

45

Chapter 12

Resources and links

12.1 Links

FIXME

1. Debian homepage

12.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 (using live-helper)

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

• GNUSTEP Live CD (using live-package)

• Voyage Linux

• pure:dyne: Providing a live system and a software repository for media artists.

• Privatix Live-System: Debian based german live-system for privacy and encryption.

• lernstick (using live-helper)

12.3 English sources related to debian live

• Debian_Live definition on Wikipedia

• Presentation on Debian-Live

47

CHAPTER 12. RESOURCES AND LINKS 12.4. GERMAN SOURCES RELATED TO . . .

12.4 German sources related to debian live

• German translation (work in progress)

• Article in linux-magazin.de

• Another german documentation

12.5 Spanish sources related to debian live

• Spanish documentation project

48

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)

49

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)

51

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

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 Sec-tion 5.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)

52

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)

53

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

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)

54