Debian Live Manual


1. Sobre esse manual

1.1 For the impatient
1.2 Terminologia
1.3 Contribuindo com esse documento
1.3.1 Aplicando patches
1.3.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


10. Customizing run time behaviours

All configuration that is done during run time is done by live-config. Here are some most common options of live-config that users are interested in. A full list of all possibilities can be found in the manpage of live-config.

10.1 Customizing the live user

One important consideration is that the live user is created by live-boot at boot time, not by live-build at build time. This not only influences where materials relating to the live user are introduced in your build, as discussed in Live/chroot local includes, but also any groups and permissions associated with the live user.

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 to a file in the config/chroot_local-preseed directory:

   debconf passwd/user-default-groups string audio cdrom dialout floppy video plugdev netdev powerdev fuse

10.2 Customizing locale and 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
  • The default locale when building a Live system is "locales=en_US.UTF-8". To define the locale that should be generated, use the locales parameter in the --bootappend-live option of lb config, e.g.

       $ lb config --bootappend-live "locales=de_CH.UTF-8"

    This parameter can also be used at the kernel command line. You can specify a locale by a full language_country.encoding word.

    Both the console and X keyboard configuration depend on the keyboard-layouts parameter of the --bootappend-live option. Valid options for X keyboard layouts can be found in /usr/share/X11/xkb/rules/base.xml (rather limited to two-letters country codes). To find the value (the two characters) corresponding to a language try searching for the english name of the nation where the language is spoken, e.g:

       $ grep -i sweden -C3 /usr/share/X11/xkb/rules/base.xml | grep name

    To get the locale files for German and Swiss German keyboard layout in X use:

       $ lb config --bootappend-live "locales=de_CH.UTF-8 keyboard-layouts=ch"

    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

    Alternatively, you can use the console-setup package, a tool to let you configure console layout using X (XKB) definitions; you can then set your keyboard layout more precisely with keyboard-layouts, keyboard-variant, keyboard-options and keyboard-model variables; live-boot will use also these parameters for X configuration. For example, to set up a French system with a French-Dvorak layout (called Bepo) on a TypeMatrix keyboard, both in console and X11, use:

       $ lb config --bootappend-live \
           "locales=fr_FR.UTF-8 keyboard-layouts=fr keyboard-variant=bepo keyboard-model=tm2030usb"

    10.3 Persistence

    A live cd paradigm is a pre-installed system which runs from read-only media, like a cdrom, where writes 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 addition to CDs; but still, in its default behaviour, it should be considered read-only and all the run-time evolutions 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 run-time evolution of the system. To understand how it could work it could be handy to know that even if the system is booted and run from read-only media, modification to the files and directories are 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 media are supported in Debian Live in different ways, and all but the last one require a special boot parameter to be specified at boot time: persistent.

    10.3.1 Full persistence

    By 'full persistence' it is meant that instead of using a tmpfs for storing modifications to the read-only media (with the copy-on-write, COW, system) a writable partition is used. In order to use this feature a partition with a clean writable supported filesystem on it labeled "live-rw" must be attached on the system at boot time and the system must be started with the boot parameter 'persistent'. This partition could 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 the following:

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

    But since live system users cannot always use a hard drive partition, and considering that most USB keys have poor write speeds, 'full' persistence could be also used with just image files, so you could create 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'.

    10.3.2 Home automounting

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

    10.3.3 Snapshots

    Snapshots are collections of files and directories which are not mounted while running but which are copied from a persistent device to the system (tmpfs) at boot and which are resynced at reboot/shutdown of the system. The content of a snapshot could reside on a partition or an image file (like the above mentioned types) labeled live-sn, but it defaults to a simple cpio archive named live-sn.cpio.gz. As above, at boot time, the block devices connected to the system are traversed to see if a partition or a file named like that could be found. A power interruption during run time could lead to data loss, hence a tool invoked live-snapshot --refresh could be called to sync important changes. This type of persistence, since it does not write continuously to the persistent media, is the most flash-based device friendly 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 main snapshot but it is only applied to /home.

    Snapshots cannot currently handle file deletion but full persistence and home automounting can.

    10.3.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 conjuntion with the boot parameter persistent will allow for multiple but unique persistent media. An example would be if a user wanted to use a persistent partition labeled live-sn-subText they would use the boot parameters of: persistent persistent-subtext=subText.

    10.3.5 Partial remastering

    The run-time modification of the tmpfs could be collected using live-snapshot in a squashfs and added to the cd by remastering the iso in the case of cd-r or adding a session to multisession cd/dvd(rw); live-boot mounts all /live filesystem in order or with the module boot parameter.