Debian Live Manual


1. À propos de ce manuel

1.1 For the impatient
1.2 Terminologie
1.3 Auteurs
1.4 Contribuer à ce document
1.4.1 Appliquer des 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


4. The basics

This chapter contains a brief overview of the build process and instructions for using the three most commonly used image types. The most versatile image type, iso-hybrid, may be used on a virtual machine, optical media or USB portable storage device. In certain special cases, usb-hdd may be more suitable for USB devices. The chapter finishes with instructions for building and using a net type image, which is a bit more involved due to the setup required on the server. This is a slightly advanced topic for anyone who is not familiar already with netbooting, but is included here because once the setup is done, it is a very convenient way to test and deploy images for booting on the local network without the hassle of dealing with image media.

4.1 What is a live system?

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

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

  • Linux kernel image, usually named vmlinuz*
  • Initial RAM disk image (initrd): a RAM disk set up for the Linux boot, containing modules possibly needed to mount the System image and some scripts to do it.
  • System image: The operating system's filesystem image. Usually, a SquashFS compressed filesystem is used to minimize the Debian Live image size. Note that it is read-only. So, during boot the Debian Live system will use a RAM disk and 'union' mechanism to enable writing files within the running system. However, all modifications will be lost upon shutdown unless optional persistence is used (see Persistence).
  • Bootloader: A small piece of code crafted to boot from the chosen media, possibly presenting a prompt or menu to allow selection of options/configuration. It loads the Linux kernel and its initrd to run with an associated system filesystem. Different solutions can be used, depending on the target media and format of the filesystem containing the previously mentioned components: isolinux to boot from a CD or DVD in ISO9660 format, syslinux for HDD or USB drive booting from a VFAT partition, extlinux for ext2/3/4 and btrfs partitions, pxelinux for PXE netboot, GRUB for ext2/3/4 partitions, etc.
  • You can use live-build to build the system image from your specifications, set up a Linux kernel, its initrd, and a bootloader to run them, all in one media-dependant format (ISO9660 image, disk image, etc.).

    4.2 First steps: building an ISO image

    The following sequence of live-build commands will create a basic ISO hybrid image containing just the Debian standard system without It is suitable for burning to CD or DVD media, and also to copy onto a USB stick (as per Copying USB/HDD image to a USB stick, specifying ".iso" extension where ".img" is indicated).

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

       $ lb config

    By passing no parameters to lb config, we indicated that we wish to use the defaults (see The lb config command).

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

       # lb build

    This process can take a while, depending on the speed of your network connection (see The lb build command).

    4.2.1 Testing an ISO image with Qemu

    Testing an ISO is simple:

       # apt-get install qemu

       $ qemu -cdrom binary.iso

    4.2.2 Testing an ISO image with virtualbox-ose

    In order to test the ISO with virtualbox-ose:

       # apt-get install virtualbox-ose virtualbox-ose-dkms

       $ virtualbox

    Create a new virtual machine, change the storage settings to use binary.iso as the CD/DVD device, and start the machine.

    Note: For live systems containing that you want to test with virtualbox-ose, you may wish to include the VirtualBox driver package, virtualbox-ose-guest-x11, in your live-build configuration. Otherwise, the resolution is limited to 800x600.

       $ lb config --packages virtualbox-ose-guest-x11

    4.2.3 Burning an ISO image to a physical medium

    Burning an ISO image is easy:

       # apt-get install wodim

       $ wodim binary.iso

    4.3 Building a USB/HDD image

    The following sequence of commands will create a basic USB/HDD image containing just the Debian standard system without It is suitable for booting from USB sticks, USB hard drives, and various other portable storage devices. Normally, an ISO hybrid image can be used for this purpose instead, but if you have a BIOS which does not handle hybrid images properly, or want to use the remaining space on the media for a persistence partition, you need a USB/HDD image.

    Note: if you created an ISO image with the previous example, you will need to clean up your working directory with the lb clean command (see The lb clean command):

       # lb clean --binary

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

       $ lb config -b usb-hdd

    Now build the image with the lb build command:

       # lb build

    4.3.1 Copying USB/HDD image to a USB stick

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

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

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

    This will definitely overwrite any previous contents on your stick!

    Note: As discussed earlier, this same process can be used for iso-hybrid type images (suffixed -hybrid.iso), but not iso type images.

    4.3.2 Testing a USB/HDD image with Qemu

       # apt-get install qemu

       $ qemu -hda binary.img

    4.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 a partitioning tool such as gparted or parted to create a new partition on the stick. The first partition will be used by the Debian Live system.

       # gparted ${USBSTICK}

    After the creation of the partition, you have to create a filesystem on it. One possible choice would be ext4.

       # mkfs.ext4 ${USBSTICK}

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

       # mkfs.vfat -F 32

    Remember: Every time you install a new binary.img on the stick, all data on the stick will be lost because the partition table is overwritten by the contents of the image.

    4.4 Building a netboot image

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

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

       # lb clean --binary

    Run the lb config command as follows to configure your image for netbooting:

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

    In contrast with the ISO and USB/HDD images, netbooting does not, itself, serve the filesystem image to the client, so the files must be served via NFS. The --net-root-path and --net-root-server options specify the location and server, respectively, of the NFS server where the filesytem image will be located at boot time. Make sure these are set to suitable values for your network and server.

    Now build the image with the lb build command:

       # lb build

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

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

    We must now configure three services on the server to enable netboot: the DHCP server, the TFTP server and the NFS server.

    4.4.1 DHCP server

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

    Here is an example for inspiration, written for the ISC DHCP server isc-dhcp-server in the /etc/dhcp/dhcpd.conf configuration file:

       # /etc/dhcp/dhcpd.conf - configuration file for isc-dhcp-server

       ddns-update-style none;

       option domain-name "";
       option domain-name-servers,;

       default-lease-time 600;
       max-lease-time 7200;

       log-facility local7;

       subnet netmask {
         next-server servername;
         filename "pxelinux.0";

    4.4.2 TFTP 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 /srv/tftp. To let it serve files inside /srv/debian-live/tftpboot, run as root the following command:

       # dpkg-reconfigure -plow tftpd-hpa

    and fill in the new tftp server directory when being asked about it.

    4.4.3 NFS server

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

    You need to install the nfs-kernel-server package.

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

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

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

       # exportfs -rv

    Setting up these three services can be a little tricky. You might need some patience to get all of them working together. For more information, see the syslinux wiki at ‹› or the Debian Installer Manual's TFTP Net Booting section at ‹›. They might help, as their processes are very similar.

    4.4.4 Netboot testing HowTo

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

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

    4.4.5 Qemu

  • Install qemu, bridge-utils, sudo.
  • Edit /etc/qemu-ifup:

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

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

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

    4.4.6 VMWare Player

  • Install VMWare Player ("free as in beer" edition)
  • Create a PXETester directory, and create a text file called pxe.vwx inside
  • Paste this text inside:
  •    #!/usr/bin/vmware
       config.version = "8"
       virtualHW.version = "4"
       memsize = "512"
       MemAllowAutoScaleDown = "FALSE"

       ide0:0.present = "FALSE"
       ide1:0.present = "FALSE"
       floppy0.present = "FALSE"
       sound.present = "FALSE"
       tools.remindInstall = "FALSE"

       ethernet0.present = "TRUE"
       ethernet0.addressType = "generated"

       displayName = "Test Boot PXE"
       guestOS = "other"

       ethernet0.generatedAddress = "00:0c:29:8d:71:3b"
       uuid.location = "56 4d 83 72 5c c4 de 3f-ae 9e 07 91 1d 8d 71 3b"
       uuid.bios = "56 4d 83 72 5c c4 de 3f-ae 9e 07 91 1d 8d 71 3b"
       ethernet0.generatedAddressOffset = "0"

  • You can play with this configuration file (e.g. change memory limit to 256)
  • Double click on this file (or run VMWare player and select this file).
  • When running just press space if that strange question comes up...