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


8. Customizing package installation

Perhaps the most basic customization of a Debian live system is the selection of packages to be included in the image. This chapter guides you through the various build-time options to customize live-build' s installation of packages. The broadest choices influencing which packages are available to install in the image are the distribution and archive areas. To ensure decent download speeds, you should choose a nearby distribution mirror. You can also add your own repositories for backports, experimental or custom packages, or include packages directly as files. You can define your own lists of packages to include, use live-build' s predefined lists, use tasksel tasks, or a combination of all three. Finally, a number of options give some control over apt, or if you prefer, aptitude, at build time when packages are installed. You may find these handy if you use a proxy, want to disable installation of recommended packages to save space, or need to control which versions of packages are installed via APT pinning, to name a few possibilities.

8.1 Package sources

8.1.1 Distribution, archive areas and mode

The distribution you choose has the broadest impact on which packages are available to include in your live image. Specify the codename, which defaults to squeeze for the Squeeze version of live-build. Any current distribution carried in the Debian archive may be specified by its codename here. (See Terms for more details.) The --distribution option not only influences the source of packages within the archive, but also instructs live-build to behave as needed to build each supported distribution. For example, to build against the unstable release, Sid, specify:

   $ lb config --distribution sid

Within the distribution archive, archive areas are major divisions of the archive. In Debian, these are main, contrib and non-free. Only main contains software that is official a part of the Debian distribution, hence that is the default. One or more values may be specified, e.g.

   $ lb config --archive-areas "main contrib"

Experimental support is available for some Debian derivatives through a --mode option. By default, this option is set to debian, even if you are building on a non-Debian system. If you specify --mode ubuntu or --mode emdebian, the distribution names and archive areas for the specified derivative are supported instead of the ones for Debian. The mode also modifies live-build behaviour to suit the derivatives.

Note: The projects for whom these modes were added are primarily responsible for supporting users of these options. The Debian live project, in turn, provides development support on a best-effort basis only, based on feedback from the derivative projects as we do not develop or support these derivatives ourselves.

8.1.2 Distribution mirrors

The Debian archive is replicated across a large network of mirrors around the world so that people in each region can choose a nearby mirror for best download speed. Each of the --mirror-* options governs which distribution mirror is used at various stages of the build. Recall from Stages of the build that the bootstrap stage is when the chroot is initially populated by debootstrap with a minimal system, and the chroot stage is when the chroot used to construct the live system's filesystem is built. Thus, the corresponding mirror switches are used for those stages, and later, in the binary stage, the --mirror-binary and --mirror-binary-security values are used, superceding any mirrors used in an earlier stage.

8.1.3 Distribution mirrors used at build time

To set the distribution mirrors used at build time to point at a local mirror, it is sufficient to set --mirror-bootstrap and --mirror-chroot-security as follows.

   $ lb config --mirror-bootstrap http://localhost/debian/ \
               --mirror-chroot-security http://localhost/debian-security/

The chroot mirror, specified by --mirror-chroot, defaults to the --mirror-bootstrap value.

8.1.4 Distribution mirrors used at run time

The --mirror-binary* options govern the distribution mirrors placed in the binary image. These may be used to install additional packages while running the live system. The defaults employ, a service that chooses a geographically close mirror based on the user's IP number. This is a suitable choice when you cannot predict which mirror will be best for all of your users. Or you may specify your own values as shown in the example below. An image built from this configuration would only be suitable for users on a network where "mirror" is reachable.

   $ lb config --mirror-binary http://mirror/debian/ \
               --mirror-binary-security http://mirror/debian-security/

8.1.5 Additional repositories

You may add more repositories, broadening your package choices beyond what is available in your target distribution. These may be, for example, for backports, experimental or custom packages. To configure additional repositories, create config/chroot_sources/your-repository.chroot, and/or config/chroot_sources/your-repository.binary files. As with the --mirror-* options, these govern the repositories used in the chroot stage when building the image, and in the binary stage, i.e. for use when running the live system.

For example, config/chroot_sources/live.chroot allows you to install packages from the debian live snapshot repository at live system build time.

   deb sid-snapshots main contrib non-free

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

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

You should also put the GPG key used to sign the repository into config/chroot_sources/your-repository.{binary,chroot}.gpg files.

Note: some preconfigured package repositories are available for easy selection through the --repository option, e.g. for enabling live snapshots, a simple command is enough to enable it:

   $ lb config --repository

8.2 Choosing packages to install

There are a number of ways to choose which packages live-build will install in your image, covering a variety of different needs. You can simply name individual packages to install, either with the --packages option for a few packages, or in a package list of your own for larger numbers. You can also choose larger predefined lists of packages, or use APT tasks. And finally, you may place package files in your config/ tree, which is well suited to testing of new or experimental packages before they are available from a repository.

8.2.1 Choosing a few packages

When the number of packages added is small, simply specify --packages. For example:

   $ lb config --packages "package1 package2 package3"

The behaviour of live-build when specifying a package that does not exist is determined by your choice of APT utility. See Choosing apt or aptitude for more details.

If you need to specify a large number of packages to be installed or you need flexibility regarding which packages to install, use package lists as discussed in the following section, Package lists.

8.2.2 Package lists

Package lists are a powerful way of expressing which packages should be installed. The list syntax supports included files and conditional sections which makes it easy to build lists from other lists and adapt them for use in multiple configurations. You can use predefined package lists, providing in a modular fashion package selections from each of the major desktop environments and some special purpose lists, as well as standard lists the others are based upon. You can also provide your own package lists, or use a combination of both.

8.2.3 Predefined package lists

The simplest way to use lists is to specify one or more predefined lists with the --packages-lists option. For example:

   $ lb config --packages-lists "gnome-core rescue"

In addition to these lists, live-build supports four virtual package lists: gnome-desktop, kde-desktop, lxde-desktop and xfce-desktop, each of which provide a more extensive selection of packages that corresponds with Debian Installer defaults for these desktop environments. See Desktop and language tasks for more details.

Note: The prebuilt GNOME, KDE, LXDE and XFCE images available for download at ‹› are built using the corresponding virtual *-desktop lists.

The default location for the list files on your system is /usr/share/live/build/lists/. To determine the packages in a given list, read the corresponding file, paying attention to included files and conditionals as described in the following sections.

8.2.4 Local package lists

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

Package lists that exist in this directory need to have a .list suffix in order to be processed. Local package lists always override package lists distributed with live-build. This can cause undesired effects, we therefore recommend to use unique names for local package lists.

8.2.5 Local binary package lists

In case you want to include some required .deb packages to live media's pool/ (without installing them onto the live image) you may need to use lists using binary local package lists stored in config/binary_local-packageslists/. Such media can be used as a customized Debian install image for offline installations.

Package lists that exist in this directory need to have a .list suffix in order to be processed.

8.2.6 Extending a provided package list using includes

The package lists that are included with live-build make extensive use of includes. Refer to these in the /usr/share/live/build/lists/ directory, as they serve as good examples of how to write your own lists.

For example, to make a list that includes the predefined gnome list plus iceweasel, create config/chroot_local-packageslists/mygnome.list with the following contents:

   #include <gnome>

8.2.7 Using conditionals inside package lists

Any of the live-build configuration variables stored in config/* (minus the LB_ prefix) may be used in conditional statements in package lists. Generally, this means any lb config option uppercased and with dashes changed to underscores. But in practice, it is only the ones that influence package selection that make sense, such as DISTRIBUTION, ARCHITECTURE or ARCHIVE_AREAS.

For example, to install ia32-libs if the --architecture amd64 is specified:

   #if ARCHITECTURE amd64

You may test for any one of a number of values, e.g. to install memtest86+ if either --architecture i386 or --architecture amd64 is specified:

   #if ARCHITECTURE i386 amd64

You may also test against variables that may contain more than one value, e.g. to install vrms if either contrib or non-free is specified via --archive-areas:

   #if ARCHIVE_AREAS contrib non-free

A conditional may surround an #include directive:

   #if ARCHITECTURE amd64
   #include <gnome-full>

The nesting of conditionals is not supported.

8.2.8 Tasks

The Debian Installer offers the user choices of a number of preselected lists of packages, each one focused on a particular kind of system, or task a system may be used for, such as "Graphical desktop environment", "Mail server" or "Laptop". These lists are called "tasks" and are supported by APT through the "Task:" field. You can specify one or more tasks in live-build via the --tasks option, as in the example below.

   $ lb config --tasks "mail-server file-server"

The primary tasks available in the Debian Installer can be listed with tasksel --list-tasks in the live system. The contents of any task, including ones not included in this list, may be examined with tasksel --task-packages.

8.2.9 Desktop and language tasks

Desktop and language tasks are special cases. In the Debian Installer, if the medium was prepared for a particular desktop environment flavour, the corresponding task will be automatically installed. Thus, there are gnome-desktop, kde-desktop, lxde-desktop and xfce-desktop tasks, none of which are offered in tasksel's menu. Likewise, there are no menu entries for tasks for languages, but the user's language choice during the install influences the selection of corresponding language tasks.

In live-build, therefore, these special cases are also given special consideration, but with three notable differences at the time of writing.

First, there is no provision made yet automatically for language tasks, although a subset of those packages are included if you specify lb config --language. If you need those tasks, which include such things as language-specific fonts and input-method packages, you need to specify them in your configuration. For example:

   $ lb config --tasks "japanese japanese-desktop japanese-gnome-desktop"

Second, live-build supports *-desktop virtual package lists for each of the desktop flavours mentioned above, which select the standard-x11 predefined package list, the corresponding *-desktop task and three additional tasks: desktop, standard and laptop. So, for example, if you specify --packages-lists gnome-desktop, it is equivalent to specifying --packages debian-installer-launcher --packages-lists standard-x11 --tasks "gnome-desktop desktop standard laptop".

Third, if any of the tasks for these desktop flavours are selected, either explicitly through --tasks or implicitly by --packages-lists, live-build will preseed the corresponding desktop value for Debian Installer (if it is included) to ensure it follows its own rules for installing different desktop flavours.

Note: There is also an experimental --language option that has an overlapping purpose with language tasks. For any language for which it is known that there are *-l10n packages, if --language is specified, those packages will be installed. Furthermore, if any syslinux templates matching the language are found, they will be used instead of the default English templates. The package selection done by --language is a poor approximation of language tasks, as it requires that the list of packages to include per language be maintained internally in live-build, and besides, language tasks are more comprehensive and flexible. However, the syslinux aspect is still useful. Thus, if you use --bootloader syslinux and templates for the specified language exist either in /usr/share/live/build/templates/syslinux/ or config/templates/syslinux/, consider using this option, possibly in combination with tasks to ensure all relevant packages are installed. For example:

   $ lb config --language es

Even so, it is limited in that it only supports a single language and a single bootloader. Therefore, for all of these reasons, the future of this option is under review, possibly to be replaced with something entirely different in the next major release of live-build.

8.3 Installing modified or third-party packages

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

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

There are two ways of installing modified custom packages:

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

    8.3.1 Using chroot_local-packages to install custom packages

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

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

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

  • It is not possible to use secure APT.
  • You must install all appropriate packages in the config/chroot_local-packages/ directory.
  • It does not lend itself to storing Debian Live configurations in revision control.
  • 8.3.2 Using an APT repository to install custom packages

    Unlike using chroot_local-packages, when using a custom APT repository you must ensure that you specify the packages elsewhere. See Choosing packages to install for details.

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

    8.3.3 Custom packages and APT

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

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

    8.4 Configuring APT at build time

    You can configure APT through a number of options applied only at build time. (APT configuration used in the running live system may be configured in the normal way for live system contents, that is, by including the appropriate configurations through config/chroot_local_includes/.) For a complete list, look for options starting with apt in the lb_config man page.

    8.4.1 Choosing apt or aptitude

    You can elect to use either apt or aptitude when installing packages at build time. Which utility is used is governed by the --apt argument to lb config. Choose the method implementing the preferred behaviour for package installation, the notable difference being how missing packages are handled.

  • apt: With this method, if a missing package is specified, the package installation will fail. This is the default setting.
  • aptitude: With this method, if a missing package is specified, the package installation will succeed.
  • 8.4.2 Using a proxy with APT

    One commonly required APT configuration is to deal with building an image behind a proxy. You may specify your APT proxy with the --apt-ftp-proxy or --apt-http-proxy options as needed, e.g.

       $ lb config --apt-http-proxy http://proxy/

    8.4.3 Tweaking APT to save space

    You may find yourself needing to save some space on the image media, in which case one or the other or both of the following options may be of interest.

    If you don't want to include APT indices in the image, you can omit those with:

       $ lb config --binary-indices false

    This will not influence the entries in /etc/apt/sources.list, but merely whether /var/lib/apt contains the indices files or not. The tradeoff is that APT needs those indices in order to operate in the live system, so before performing apt-cache search or apt-get install, for instance, the user must apt-get update first to create those indices.

    If you find the installation of recommended packages bloats your image too much, you may disable that default option of APT with:

       $ lb config --apt-recommends false

    The tradeoff here is that if you don't install recommended packages for a given package, that is, "packages that would be found together with this one in all but unusual installations" (Debian Policy Manual, section 7.2), some packages that you actually need may be omitted. Therefore, we suggest you review the difference turning off recommends makes to your packages list (see the binary.packages file generated by lb build) and re-include in your list any missing packages that you still want installed. Alternatively, if you find you only want a small number of recommended packages left out, leave recommends enabled and set a negative APT pin priority on selected packages to prevent them from being installed, as explained in APT pinning.

    8.4.4 Passing options to apt or aptitude

    If there is not an lb config option to alter APT's behaviour in the way you need, use --apt-options or --aptitude-options to pass any options through to your configured APT tool. See the man pages for apt and aptitude for details.

    8.4.5 APT pinning

    For background, please first read the apt_preferences(5) man page. APT pinning can be configured either for build time, or else for run time. For the former, create config/chroot_apt/preferences. For the latter, create config/chroot_local-includes/etc/apt/preferences.

    Let's say you are building a Squeeze live system but need all live-* packages to be installed from Sid at build time. You need to add Sid to your APT sources and pin it so that only the packages you want are installed from it at build time and all others are taken from the target system distribution, Squeeze. The following will accomplish this:

       $ echo "deb http://mirror/debian sid main" > config/chroot_sources/sid.chroot
       $ cat >>config/chroot_apt/preferences <<END
       Package: live-*
       Pin: release n=sid
       Pin-Priority: 600

       Package: *
       Pin: release n=sid
       Pin-Priority: 1

    Negative pin priorities will prevent a package from being installed, as in the case where you do not want a package that is recommended by another package. Suppose you are building a GNOME image but don't want the user prompted to store wifi passwords in the keyring, so you want to omit the recommended gnome-keyring package. This can be done by adding the following stanza to config/chroot_apt/preferences:

       Package: gnome-keyring
       Pin: version *
       Pin-Priority: -1