Debian Live Manual

About

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

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 packages from Debian "main"
2.2.2 No package configuration of the live system
2.3 Contact

User

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'

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

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

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

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 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 Desktop and language tasks
8.2.8 Kernel flavour and version
8.2.9 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

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 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 The persistence.conf file
10.3.2 Using more than one persistence store

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

Project

13. Contributing to the project

13.1 Making changes

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

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. Git repositories

17.1 Handling multiple repositories

Examples

18. Examples

18.1 Using the examples
18.2 Tutorial 1: A default image
18.3 Tutorial 2: A web browser utility
18.4 Tutorial 3: A personalized image
18.4.1 First revision
18.4.2 Second revision
18.5 A VNC Kiosk Client
18.6 A base image for a 128MB USB key
18.7 A localized GNOME desktop and installer

Appendix

18.8 Guidelines for authors
18.8.1 Linguistic features
18.8.2 Procedures
18.9 Guidelines for translators
18.9.1 Translation hints

Debian Live Manual

Project

15. Coding Style

This chapter documents the coding style used in Debian Live.

15.1 Compatibility

  • Don't use syntax or semantics that are unique to the Bash shell. For example, the use of array constructs.
  • Only use the POSIX subset - for example, use $(foo) over `foo`.
  • You can check your scripts with 'sh -n' and 'checkbashisms'.
  • Make sure all shell code runs with 'set -e'.
  • 15.2 Indenting

  • Always use tabs over spaces.
  • 15.3 Wrapping

  • Generally, lines are 80 chars at maximum.
  • Use the "Linux style" of line breaks:
  • Bad:

    if foo; then
             bar
    fi

    Good:

    if foo
    then
             bar
    fi

  • The same holds for functions:
  • Bad:

    Foo () {
             bar
    }

    Good:

    Foo ()
    {
             bar
    }

    15.4 Variables

  • Variables are always in capital letters.
  • Variables used in live-build always start with LB_ prefix.
  • Internal temporary variables in live-build should start with the _LB_ prefix.
  • Local variables start with live-build __LB_ prefix.
  • Variables in connection to a boot parameter in live-config start with LIVE_.
  • All other variables in live-config start with _ prefix.
  • Use braces around variables; e.g. write ${FOO} instead of $FOO.
  • Always protect variables with quotes to respect potential whitespaces: write "${FOO}" not ${FOO}.
  • For consistency reasons, always use quotes when assigning values to variables:
  • Bad:

    FOO=bar

    Good:

    FOO="bar"

  • If multiple variables are used, quote the full expression:
  • Bad:

    if [ -f "${FOO}"/foo/"${BAR}"/bar ]
    then
             foobar
    fi

    Good:

    if [ -f "${FOO}/foo/${BAR}/bar" ]
    then
             foobar
    fi

    15.5 Miscellaneous

  • Use "|" (without the surround quotes) as a separator in calls to sed, e.g. "sed -e 's|foo|bar|'" (without "").
  • Don't use the test command for comparisons or tests, use "[" "]" (without ""); e.g. "if [ -x /bin/foo ]; ..." and not "if test -x /bin/foo; ...".
  • Use case wherever possible over test, as it's easier to read and faster in execution.
  • Use capitalized names for functions to limit messing with the users environment.