Debian Live Manual


1. About this manual

1.1 For the impatient
1.2 Terms
1.3 Authors
1.4 Contributing to this document
1.4.1 Applying patches
1.4.2 Translation

2. About the Debian Live Project

2.1 Motivation
2.1.1 What is wrong with current live systems
2.1.2 Why create our own live system?
2.2 Philosophy
2.2.1 Only unchanged, official packages
2.2.2 No package configuration of the live system
2.3 Contact


3. Installation

3.1 Requirements
3.2 Installing live-build
3.2.1 From the Debian repository
3.2.2 From source
3.2.3 From 'snapshots'
3.3 live-boot and live-config
3.3.1 From the Debian repository
3.3.2 From source
3.3.3 From 'snapshots'

4. The basics

4.1 What is a live system?
4.2 First steps: building an ISO image
4.2.1 Testing an ISO image with Qemu
4.2.2 Testing an ISO image with virtualbox-ose
4.2.3 Burning an ISO image to a physical medium
4.3 Building a USB/HDD image
4.3.1 Copying USB/HDD image to a USB stick
4.3.2 Testing a USB/HDD image with Qemu
4.3.3 Using the space left on a USB stick
4.4 Building a netboot image
4.4.1 DHCP server
4.4.2 TFTP server
4.4.3 NFS server
4.4.4 Netboot testing HowTo
4.4.5 Qemu
4.4.6 VMWare Player

5. Overview of tools

5.1 live-build
5.1.1 The lb config command
5.1.2 The lb build command
5.1.3 The lb clean command
5.2 The live-boot package
5.3 The live-config package

6. Managing a configuration

6.1 Use auto to manage configuration changes
6.2 Example auto scripts

7. Customization overview

7.1 Build time vs. boot time configuration
7.2 Stages of the build
7.3 Supplement lb config with files
7.4 Customization tasks

8. Customizing package installation

8.1 Package sources
8.1.1 Distribution, archive areas and mode
8.1.2 Distribution mirrors
8.1.3 Distribution mirrors used at build time
8.1.4 Distribution mirrors used at run time
8.1.5 Additional repositories
8.2 Choosing packages to install
8.2.1 Choosing a few packages
8.2.2 Package lists
8.2.3 Predefined package lists
8.2.4 Local package lists
8.2.5 Local binary package lists
8.2.6 Extending a provided package list using includes
8.2.7 Using conditionals inside package lists
8.2.8 Tasks
8.2.9 Desktop and language tasks
8.3 Installing modified or third-party packages
8.3.1 Using chroot_local-packages to install custom packages
8.3.2 Using an APT repository to install custom packages
8.3.3 Custom packages and APT
8.4 Configuring APT at build time
8.4.1 Choosing apt or aptitude
8.4.2 Using a proxy with APT
8.4.3 Tweaking APT to save space
8.4.4 Passing options to apt or aptitude
8.4.5 APT pinning

9. Customizing contents

9.1 Includes
9.1.1 Live/chroot local includes
9.1.2 Binary local includes
9.1.3 Binary includes
9.2 Hooks
9.2.1 Live/chroot local hooks
9.2.2 Boot-time hooks
9.2.3 Binary local hooks
9.3 Preseeding Debconf questions

10. Customizing run time behaviours

10.1 Customizing the live user
10.2 Customizing locale and language
10.3 Persistence
10.3.1 Full persistence
10.3.2 Home automounting
10.3.3 Snapshots
10.3.4 Persistent SubText
10.3.5 Partial remastering

11. Customizing the binary image

11.1 Bootloader
11.2 ISO metadata

12. Customizing Debian Installer

12.1 Types of Debian Installer
12.2 Customizing Debian Installer by preseeding
12.3 Customizing Debian Installer content


13. Reporting bugs

13.1 Known issues
13.2 Rebuild from scratch
13.3 Use up-to-date packages
13.4 Collect information
13.5 Isolate the failing case if possible
13.6 Use the correct package to report the bug against
13.6.1 At build time whilst bootstrapping
13.6.2 At build time whilst installing packages
13.6.3 At boot time
13.6.4 At run time
13.7 Do the research
13.8 Where to report bugs

14. Coding Style

14.1 Compatibility
14.2 Indenting
14.3 Wrapping
14.4 Variables
14.5 Miscellaneous

15. Procedures

15.1 Udeb Uploads
15.2 Major Releases
15.3 Point Releases
15.3.1 Point release announcement template


16. Examples

16.1 Using the examples
16.2 Tutorial 1: A standard image
16.3 Tutorial 2: A web browser utility
16.4 Tutorial 3: A personalized image
16.4.1 First revision
16.4.2 Second revision
16.5 A VNC Kiosk Client
16.6 A base image for a 128M USB key
16.7 A localized KDE desktop and installer

Debian Live Manual


5. Overview of tools

This chapter contains an overview of the three main tools used in building Debian Live systems: live-build, live-boot and live-config.

5.1 live-build

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

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

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

  • The scripts have a central location for configuring their operation. In debhelper, this is the debian/ subdirectory of a package tree. For example, dh_install will look, amongst others, for a file called debian/install to determine which files should exist in a particular binary package. In much the same way, live-build stores its configuration entirely under a config/ subdirectory.
  • The scripts are independent - that is to say, it is always safe to run each command.
  • Unlike debhelper, live-build contains a tool to generate a skeleton configuration directory, lb config. This could be considered to be similar to tools such as dh-make. For more information about lb config, please see The lb config command.

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

  • lb config: Responsible for initializing a Live system configuration directory. See The lb config command for more information.
  • lb build: Responsible for starting a Live system build. See The lb build command for more information.
  • lb clean: Responsible for removing parts of a Live system build. See The lb clean command for more information.
  • 5.1.1 The lb config command

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

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

       $ lb config
       P: Creating config tree

       $ ls -l
       total 8
       drwxr-xr-x  3 user user 4096 Sep  7 13:02 auto
       drwxr-xr-x 22 user user 4096 Sep  7 13:02 config

       $ ls -l config/
       total 104
       -rw-r--r-- 1 user user 4197 Sep  7 13:02 binary
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 binary_debian-installer
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 binary_debian-installer-includes
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 binary_grub
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 binary_local-debs
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 binary_local-hooks
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 binary_local-includes
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 binary_local-packageslists
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 binary_local-udebs
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 binary_rootfs
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 binary_syslinux
       -rw-r--r-- 1 user user 2051 Sep  7 13:02 bootstrap
       -rw-r--r-- 1 user user 1647 Sep  7 13:02 chroot
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 chroot_apt
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 chroot_local-hooks
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 chroot_local-includes
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 chroot_local-packages
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 chroot_local-packageslists
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 chroot_local-patches
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 chroot_local-preseed
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 chroot_sources
       -rw-r--r-- 1 user user 2954 Sep  7 13:02 common
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 includes
       -rw-r--r-- 1 user user  205 Sep  7 13:02 source
       drwxr-xr-x 2 user user 4096 Sep  7 13:02 templates

    Using lb config without any arguments would be suitable for users who need a very basic image, or who intend to later provide a more complete configuration via auto/config (see Managing a configuration for details).

    Normally, you will want to specify some options. For example, to include the 'gnome' package list in your configuration:

       $ lb config -p gnome

    It is possible to specify many options, such as:

       $ lb config --binary-images net --hostname live-machine --username live-user ...

    A full list of options is available in the lb_config man page.

    5.1.2 The lb build command

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

    5.1.3 The lb clean command

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

    5.2 The live-boot package

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

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

    More information on initial ramfs in Debian can be found in the Debian Linux Kernel Handbook at ‹› in the chapter on initramfs.

    5.3 The live-config package

    live-config consists of the scripts that run at boot time after live-boot to configure the live system automatically. It handles such tasks as setting the hostname, locales and timezone, creating the live user, inhibiting cron jobs and performing autologin of the live user.