Live manual

Live Systems

<< previous toc next >>

Live Systems Manual


About this 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 changes
1.4.2 Translation

About the Live Systems Project

2. About the Live Systems 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 packages from Debian "main"
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 Installing live-boot and live-config
3.3.1 From the Debian repository
3.3.2 From source
3.3.3 From 'snapshots'

The basics

4. The basics

4.1 What is a live system?
4.2 Downloading prebuilt images
4.3 Using the web live image builder
4.3.1 Web builder usage and caveats
4.4 First steps: building an ISO hybrid image
4.5 Using an ISO hybrid live image
4.5.1 Burning an ISO image to a physical medium
4.5.2 Copying an ISO hybrid image to a USB stick
4.5.3 Using the space left on a USB stick
4.5.4 Booting the live medium
4.6 Using a virtual machine for testing
4.6.1 Testing an ISO image with QEMU
4.6.2 Testing an ISO image with VirtualBox
4.7 Building and using an HDD image
4.8 Building a netboot image
4.8.1 DHCP server
4.8.2 TFTP server
4.8.3 NFS server
4.8.4 Netboot testing HowTo
4.8.5 Qemu
4.9 Webbooting
4.9.1 Getting the webboot files
4.9.2 Booting webboot images

Overview of tools

5. Overview of tools

5.1 The live-build package
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

Managing a configuration

6. Managing a configuration

6.1 Dealing with configuration changes
6.1.1 Why use auto scripts? What do they do?
6.1.2 Use example auto scripts
6.2 Clone a configuration published via Git

Customizing contents

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

Customizing package installation

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 Package lists
8.2.2 Using metapackages
8.2.3 Local package lists
8.2.4 Local binary package lists
8.2.5 Generated package lists
8.2.6 Using conditionals inside package lists
8.2.7 Removing packages at install time
8.2.8 Desktop and language tasks
8.2.9 Kernel flavour and version
8.2.10 Custom kernels
8.3 Installing modified or third-party packages
8.3.1 Using packages.chroot 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

Customizing contents

9. Customizing contents

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

Customizing run time behaviours

10. Customizing run time behaviours

10.1 Customizing the live user
10.2 Customizing locale and language
10.3 Persistence
10.3.1 The persistence.conf file
10.3.2 Using more than one persistence store
10.3.3 Using persistence with encryption

Customizing the binary image

11. Customizing the binary image

11.1 Bootloaders
11.2 ISO metadata

Customizing Debian Installer

12. Customizing Debian Installer

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


Contributing to the project

13. Contributing to the project

13.1 Translation of man pages

Reporting bugs

14. Reporting bugs

14.1 Known issues
14.2 Rebuild from scratch
14.3 Use up-to-date packages
14.4 Collect information
14.5 Isolate the failing case if possible
14.6 Use the correct package to report the bug against
14.6.1 At build time while bootstrapping
14.6.2 At build time while installing packages
14.6.3 At boot time
14.6.4 At run time
14.7 Do the research
14.8 Where to report bugs

Coding Style

15. Coding Style

15.1 Compatibility
15.2 Indenting
15.3 Wrapping
15.4 Variables
15.5 Miscellaneous


16. Procedures

16.1 Major Releases
16.2 Point Releases
16.2.1 Last Point Release of a Debian Release
16.2.2 Point release announcement template



17. Examples

17.1 Using the examples
17.2 Tutorial 1: A default image
17.3 Tutorial 2: A web browser utility
17.4 Tutorial 3: A personalized image
17.4.1 First revision
17.4.2 Second revision
17.5 A VNC Kiosk Client
17.6 A base image for a 128MB USB key
17.7 A localized GNOME desktop and installer


Style guide

18. Style guide

18.1 Guidelines for authors
18.1.1 Linguistic features
18.1.2 Procedures
18.2 Guidelines for translators
18.2.1 Translation hints


SiSU Metadata, document information

Live Systems Manual

Managing a configuration

6. Managing a configuration

This chapter explains how to manage a live configuration from initial creation, through successive revisions and successive releases of both the live-build software and the live image itself.

6.1 Dealing with configuration changes

Live configurations rarely are perfect on the first try. It may be fine to pass lb config options from the command-line to perform a single build, but it is more typical to revise those options and build again until you are satisfied. To support these changes, you will need auto scripts which ensure your configuration is kept in a consistent state.

6.1.1 Why use auto scripts? What do they do?

The lb config command stores the options you pass to it in config/* files along with many other options set to default values. If you run lb config again, it will not reset any option that was defaulted based on your initial options. So, for example, if you run lb config again with a new value for --binary-images, any dependent options that were defaulted for the old image type may no longer work with the new ones. Nor are these files intended to be read or edited. They store values for over a hundred options, so nobody, let alone yourself, will be able to see in these which options you actually specified. And finally, if you run lb config, then upgrade live-build and it happens to rename an option, config/* would still contain variables named after the old option that are no longer valid.

For all these reasons, auto/* scripts will make your life easier. They are simple wrappers to the lb config, lb build and lb clean commands that are designed to help you manage your configuration. The auto/config script stores your lb config command with all desired options, the auto/clean script removes the files containing configuration variable values, and the auto/build script keeps a build.log of each build. Each of these scripts is run automatically every time you run the corresponding lb command. By using these scripts, your configuration is easier to read and is kept internally consistent from one revision to the next. Also, it will be much easier for you identify and fix options which need to change when you upgrade live-build after reading the updated documentation.

6.1.2 Use example auto scripts

For your convenience, live-build comes with example auto shell scripts to copy and edit. Start a new, default configuration, then copy the examples into it:

$ mkdir mylive && cd mylive && lb config
$ mkdir auto
$ cp /usr/share/doc/live-build/examples/auto/* auto/

Edit auto/config, adding any options as you see fit. For instance:

lb config noauto \
     --architectures i386 \
     --linux-flavours 686-pae \
     --binary-images hdd \
     --mirror-bootstrap \
     --mirror-binary \

Now, each time you use lb config, auto/config will reset the configuration based on these options. When you want to make changes to them, edit the options in this file instead of passing them to lb config. When you use lb clean, auto/clean will clean up the config/* files along with any other build products. And finally, when you use lb build, a log of the build will be written by auto/build in build.log.

Note: A special noauto parameter is used here to suppress another call to auto/config, thereby preventing infinite recursion. Make sure you don't accidentally remove it when making edits. Also, take care to ensure when you split the lb config command across multiple lines for readability, as shown in the example above, that you don't forget the backslash (\) at the end of each line that continues to the next.

6.2 Clone a configuration published via Git

Use the lb config --config option to clone a Git repository that contains a live system configuration. If you would like to base your configuration on one maintained by the Live Systems Project, look at ‹› for the repository named live-images in the category Packages. This repository contains the configurations for the live systems prebuilt images.

For example, to build a standard image, use the live-images repository as follows:

$ mkdir live-images && cd live-images
$ lb config --config
$ cd images/standard

Edit auto/config and any other things you need in the config tree to suit your needs. For example, the unofficial non-free prebuilt images are made by simply adding --archive-areas "main contrib non-free".

You may optionally define a shortcut in your Git configuration by adding the following to your ${HOME}/.gitconfig:

[url ""]
         insteadOf = lso:

This enables you to use lso: anywhere you need to specify the address of a git repository. If you also drop the optional .git suffix, starting a new image using this configuration is as easy as:

$ lb config --config lso:live-images

Cloning the entire live-images repository pulls the configurations used for several images. If you feel like building a different image after you have finished with the first one, change to another directory and again and optionally, make any changes to suit your needs.

In any case, remember that every time you will have to build the image as superuser: lb build

<< previous toc next >>