Debian Live Manual The Debian Live Project Unreleased Snapshot Copyright ? 2008-2010 The Debian Live Project This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. A copy of the GNU General Public License is available as /usr/ share/common-licenses/GPL in the Debian GNU/Linux distribution or on the World Wide Web at the GNU web site. You can also obtain it by writing to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. If you want to print this reference, this document is also available in Portable Document Format (PDF). Sat, 01 May 2010 02:56:21 +0000 ---------------------------------------------------------------- Table of Contents 1. About 1.1. About this manual 1.1.1. Terms 1.1.2. Authors 1.1.3. Contributing to this document 1.2. About the Debian Live Project 1.2.1. Motivation 1.2.2. Philosophy 1.2.3. Contact 2. Installation 2.1. Requirements 2.2. Installing live-helper 2.2.1. From the Debian repository 2.2.2. From source 2.2.3. From 'snapshots' 2.2.4. live-initramfs 3. The basics 3.1. What is a live system? 3.2. First steps: building an ISO image 3.2.1. Testing an ISO image with Qemu 3.2.2. Burning an ISO image to a physical medium 3.3. Building an USB/HDD image 3.3.1. Copying USB/HDD image to a USB stick 3.3.2. Testing a USB/HDD image with Qemu 3.3.3. Using the space left on a USB stick 3.4. Building a netboot image 3.5. Netboot testing HowTo 4. Overview of tools 4.1. live-helper 4.1.1. The lh config helper 4.1.2. The lh build helper 4.1.3. The lh clean helper 4.2. The live-initramfs package 5. Customization 5.1. Customising package installation 5.1.1. Package sources 5.1.2. Package installation 5.1.3. Installing additional packages 5.1.4. Installing modified or third-party packages 5.2. Customising contents 5.2.1. Includes 5.2.2. Hooks 5.2.3. Preseeding Debconf questions 5.2.4. Symlink conversion 5.3. Customising the bootup process 5.3.1. Kernel 5.3.2. Bootloaders 5.3.3. Splash screens 5.3.4. Memtest 5.3.5. Startup scripts 5.3.6. Cheat codes 5.4. Customising the binary image 5.4.1. ISO metadata 5.5. Using a newer kernel with Lenny 6. Common tasks 6.1. The Debian Installer 6.2. WiFi Connection 7. The Live environment 7.1. Swap space 7.2. Hostname 7.3. The Live user 7.4. Language 7.5. Persistence 7.5.1. Full persistence 7.5.2. Home automounting 7.5.3. Snapshots 7.5.4. Persistent SubText 7.5.5. Partial remastering 8. Frequently asked questions (FAQ) 9. Reporting bugs 9.1. Known issues 9.2. Rebuild from scratch 9.3. Use up-to-date packages 9.4. Collect information 9.5. Use the correct package to report the bug against 9.6. Do the research 9.7. Where to report bugs 10. Coding Style 10.1. Compatibility 10.2. Indenting 10.3. Wrapping 10.4. Variables 10.5. Miscellaneous 11. Procedures 11.1. Udeb Uploads 11.2. Major Releases 11.3. Point Releases 11.3.1. Point release announcement template 12. Resources and links 12.1. Links 12.2. Who is using Debian Live? 12.3. English sources related to debian live 12.4. German sources related to debian live 12.5. Spanish sources related to debian live A. Configuration layout B. Configuration files B.1. The config/binary file B.2. The config/bootstrap file B.3. The config/chroot file B.4. The config/common file B.5. The config/source file Chapter 1. About 1.1. About this manual The main goal of this manual is to serve as a single access point to all documentation related to the Debian Live project. It does not include end-user documentation for using a Debian Live system. Some of the commands mentioned in the text must be executed with superuser privileges which can be obtained by becoming the root user via su or by using sudo. To distinguish between commands which may be executed by an unprivileged user and those requiring superuser privileges, commands are prepended by $ or # respectively. This symbol is not a part of the command. 1.1.1. Terms Live system An operating system that can boot without installation to a hard drive. Live systems do not alter local operating system (s) or file(s) already installed on the computer hard drive unless instructed to do so. Live systems are typically booted from media such as CDs or DVDs, some may also boot with USB sticks or over the network (via netboot images). Debian Live The Debian sub-project which maintains the live-helper and live-initramfs utilities. Debian Live system A live system that uses software from the Debian operating system that may be booted from CDs, DVDs, USB sticks, over the network (via netboot images), and over the internet (via boot parameter fetch=URL) Build system / host system The environment used to create the live system. live-helper A collection of scripts used to build customised Debian Live systems. live-initramfs A collection of scripts used to boot live systems. live-initramfs is a fork of casper by Canonical, Ltd. live-package The former name of live-helper. Debian Installer / (d-i) The official installation system for the Debian distribution. Cheat codes FIXME chroot The chroot program, chroot(8), enables us to run different instances of the GNU/Linux environment on a single system simultaneously without rebooting. binary image On a live system, binary image refers to the binary filesystem and the respective extension, such as binary.iso or binary.img. Target distribution The distribution upon which your live system will be based. This can differ from the distribution of your Build System. lenny/squeeze/sid stable/testing/unstable The "stable" distribution contains the latest officially released distribution of Debian. The "testing" distribution is the staging area for the next stable release. A major advantage of using this distribution is that it has more recent versions of software relative to the "stable" release. The "unstable" distribution is where active development of Debian occurs. Generally, this distribution is run by developers and those who like to live on the edge. At the time of writing, lenny is the current "stable" release and squeeze is the current "testing" release. sid will always be a synonym for the "unstable" release. 1.1.2. Authors A list of authors (in alphabetical order): * Ben Armstrong * Brendan Sleight * Chris Lamb * Daniel Baumann * Franklin Piat * Jonas Stein * Kai Hendry * Marco Amadori * Mathieu Geli * Matthias Kirschner * Richard Nelson * Trent W. Buck 1.1.3. Contributing to this document This manual is intended as a community project and all proposals for improvements and contributions are extremely welcome. The preferred way to submit a contribution is to send it to the mailing list. Please see Section 1.2.3, ?Contact? for more information. When submitting a contribution please clearly identify its copyright holder and include the licensing statement. Note that to be accepted the contribution must be licensed under the same license as the rest of the document, namely GPL version 3 or later. The sources for this manual are maintained using the Git version control system. You can checkout the latest copy by executing: $ git clone git://live.debian.net/git/live-manual.git Prior to submission of your contribution, please preview your work. To preview the live-manual, ensure the packages needed for building are installed by executing: # apt-get install dblatex docbook-xml docbook-xsl make po4a w3m You may build the live-manual from the top level directory of your git checkout by executing: $ make build 1.1.3.1. Applying patches Directly commiting to the repository is possible by anyone. However, we ask you to send bigger changes to the mailinglist to discuss them first. In order to push to the repository, the following steps are required. * Fetch the public commit key: $ mkdir -p ~/.ssh/identity.d $ wget http://live.debian.net/other/openssh/repository-public-commit-key-current/live-manual@debian-live -O ~/.ssh/identity.d/live-manual@debian-live $ wget http://live.debian.net/other/openssh/repository-public-commit-key-current/live-manual@debian-live.pub -O ~/.ssh/identity.d/live-manual@debian-live.pub $ chmod 0600 ~/.ssh/identity.d/live-manual@debian-live* * Add the following section to your openssh-client config: $ cat >> ~/.ssh/config << EOF Host live.debian.net Hostname live.debian.net User gitosis IdentityFile ~/.ssh/identity.d/live-manual@debian-live EOF * Checkout a clone of the manual through ssh: $ git clone gitosis@live.debian.net:/live-manual.git * Commit the file after editing. Write commit messages, that consist of full useful sentences, starting with a capital letter and ending with a full stop. Usually starting with the form 'Fixing/Adding/Removing/Correcting/': $ git commit -a * Push the commit to the server: $ git push 1.2. About the Debian Live Project 1.2.1. Motivation 1.2.1.1. What is wrong with current live systems There are already several Debian-based live systems and they are doing a great job. But, from the Debian perspective most of them have one or more of the following disadvantages: 1. They are unofficial projects, developed outside of Debian. 2. They mix different distributions, e.g. testing and unstable. 3. They support i386 only. 4. They modify the behaviour and/or appearance of packages by stripping them down to save space. 5. They include unofficial packages. 6. They ship custom kernels with additional patches that are not part of Debian. 7. They are large and slow due to their sheer size and thus not suitable for rescue issues. 8. They are not available in different flavours, e.g. CDs, DVDs, USB-stick and netboot images 1.2.1.2. Why create our own live system? Debian is the Universal Operating System: Debian should have an official live system for showing around and to officially represent the true, one and only Debian system with the following main advantages: 1. It would be an official Debian subproject. 2. It reflects the (current) state of one distribution. 3. It runs on as many architectures as possible. 4. It consists of unchanged Debian packages only. 5. It does not contain any unofficial packages. 6. It uses an unaltered Debian kernel-image with no additional patches. 1.2.2. Philosophy 1.2.2.1. Only unchanged, official packages We will only use official packages from the Debian repository in the "main" section (possibly contrib, although not decided yet). The non-free section is not part of Debian and therefore cannot be used at all for live systems. We will not change any packages. Whenever we need to change something, we will do that in coordination with its package maintainer in Debian. As an exception, our own packages such as live-helper or live-initramfs may temporarily be used from our own repository for development reasons (e.g. to create development snapshots). They will be uploaded to Debian on a regular basis. 1.2.2.2. No package configuration of the live system In this phase we will not ship or install sample or alternative configurations. All packages are used in their default configuration as they are after a regular installation of Debian. Whenever we need a different default configuration, we will do that in coordination with its package maintainer in Debian. A system for configuring packages is provided using debconf in lh config (use --preseed FILE) allowing custom configured packages to be installed in your custom produced Debian Live images, but for official live images only default configuration will be used. For more information, please see Chapter 5, Customization. Exception: There are a few essential changes needed to bring a live system to life (e.g. configuring pam to allow empty passwords). These essential changes have to be kept as minimal as possible and should be merged within the Debian repository if possible. 1.2.2.3. Live system to hard disk installer For the moment we will not ship an installer to copy the live system to a partition on the hard disk. Although we keep the changes in the live system as drastically minimal as possible compared to a regular Debian installation, the live system does differ in a few essential points (see exceptions, guideline 2). Therefore, we will ship a copy of the regular DebianInstaller (resp. Debian Installer, Graphical Installer) instead, to allow users to perform a regular Debian installation (and, of course, cdebootstrap and debootstrap are on the system too). 1.2.3. Contact Mailing list The primary contact for the project is the mailing list. You can email the list directly by addressing your mail to < debian-live@lists.debian.org>. The list archives are also available. IRC A number of users and developers are present in the # debian-live channel on OFTC. When asking a question on IRC, please be patient for an answer. If no answer is forthcoming, please email the mailing list. BTS The Debian Bug Tracking System (BTS) contains details of bugs reported by users and developers. Each bug is given a number, and is kept on file until it is marked as having been dealt with. For more information, please see Chapter 9, Reporting bugs. Wiki The Debian Live wiki is a place to gather information, discuss applied technologies, and document frameworks of Debian Live systems that go beyond the scope of this document. Chapter 2. Installation 2.1. Requirements Building Debian Live images has very few system requirements: 1. Super user (root) access 2. An up-to-date version of live-helper 3. A POSIX-compliant shell, such as bash or dash. 4. debootstrap or cdebootstrap 5. Linux 2.6.x Note that using Debian or a Debian-derived distribution is not required - live-helper will run on almost any operating system with the above requirements. 2.2. Installing live-helper You can install live-helper in a number of different ways: 1. From the Debian repository 2. From source 3. From snapshots 4. From backports.org If you are using lenny or sid the recommended way is to install live-helper via the Debian repository. 2.2.1. From the Debian repository Simply install live-helper like any other package: # apt-get install live-helper or # aptitude install live-helper 2.2.2. From source live-helper is developed using the Git version control system. On Debian systems, this is provided by the git-core package. To check out the latest code, execute: $ git clone git://live.debian.net/git/live-helper.git You can build and install your own Debian package by executing: $ cd live-helper $ dpkg-buildpackage -rfakeroot -b -uc -us $ cd .. # dpkg -i live-helper*.deb You can also use a local version of live-helper without installation: # live-helper/helpers/lh_local Subsequent calls to lh_-prefixed helpers in that shell environment will then use the version located in the directory you executed lh_local from. You can also install live-helper directly to your system by executing: # make install 2.2.3. From 'snapshots' If you do not wish to build or install live-helper from source, you can use snapshots. These are built automatically from the latest version in Git and are available on http:// live.debian.net/debian. 2.2.4. live-initramfs N.B. You do not need to install live-initramfs on your system to create customised Debian Live systems. However, doing so will do no harm. 2.2.4.1. Using a customised live-initramfs To modify the code you can follow the process below. Please ensure you are familiar with the terms mentioned in Section 1.1.1, ?Terms?. 1. Checkout the live-initramfs source $ git clone git://live.debian.net/git/live-initramfs.git 2. Make changes to your local copy And beware that if you want to add your pre-init script in live-bottom, you should name it without dashes '-', e.g: call it "81new_feature" and not "81new-feature". 3. Build a live-initramfs .deb You must build either on your target distribution or in a chroot containing your target platform: this means if your target is lenny then you should build against lenny. You can use a personal builder such as pbuilder to automate building packages in chroot. To build directly on the target platform, use dpkg-buildpackage (provided by the dpkg-dev package): $ cd live-initramfs $ dpkg-buildpackage -rfakeroot -b -uc -us 4. Use the generated live-initramfs .deb As live-initramfs is installed by the build system, installing the package in the host system is not sufficient: you should treat the generated .deb like another custom package. Please see Section 5.1.4, ?Installing modified or third-party packages? for more information. You should pay particular attention to Section 5.1.4.3, ?Custom packages and APT?. 2.2.4.2. Using live-initramfs snapshots You can let live-helper automatically use the latest snapshot of live-initramfs by configuring a third-party repository in your live-system configuration. Assuming you have already created a configuration tree with lh config: 1. Create a sources.list entry for the chroot stage: echo "deb http://live.debian.net/ sid-snapshots main contrib non-free" > config/chroot_sources/debian-live_sid-snapshots.chroot 2. Create a sources.list entry for the binary stage: cp config/chroot_sources/debian-live_sid-snapshots.chroot config/chroot_sources/debian-live_sid-snapshots.binary 3. Fetch the archive signing key: wget http://live.debian.net/debian/project/openpgp/archive-key.asc -O config/chroot_sources/debian-live_sid-snapshots.chroot.gpg cp config/chroot_sources/debian-live_sid-snapshots.chroot.gpg config/chroot_sources/debian-live_sid-snapshots.binary.gpg Chapter 3. The basics This chapter contains a brief overview of the build process as well as containing instructions on how to boot the various binary image types. 3.1. What is a live system? A live system usually means an OS booted on a computer from a removable medium (such as CD-ROM, USB stick, or network), ready to use without any installation on the usual drive(s), with an auto-configuration done at runtime (see Section 1.1.1, ?Terms?). With Debian Live, it's a Debian GNU/Linux OS, built for one of the supported architectures (currently amd64, i386, powerpc and sparc). It is made from following parts: Linux kernel The Linux image, usually named vmlinuz*. Initial RAM disk image (initrd) RAM disk setup for the Linux boot, containing modules possibly needed to mount the filesystem's image and some scripts to do it. System image The OS filesystem image. Debian Live uses SquashFS, a compressed filesystem, to minimize its image size. Note that it's 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 partition (s) are used. (See Section 7.5, ?Persistence?.) Bootloader A small piece of code, crafted to boot up from the chosen media, possibly presenting a prompt or menu to allow selection of options/configuration. It then loads the Linux kernel and its initrd to run with an associated filesystem image. Different solutions can be used depending on the target media and format of the filesystem containing the previous components: Isolinux to boot from a CD or DVD in ISO9660 format, syslinux for HDD or USB drive booting from a VFAT partition, GRUB for ext2/3 partition, pxelinux for PXE netboot, etc. The Debian Live tools will build the system image from your specifications, setup a Linux kernel and its initrd, a bootloader to run them, all in one media-dependant format (ISO9660 image, disk image, etc.) 3.2. First steps: building an ISO image The following sequence of helper commands, provided by live-helper, will create a basic ISO image containing just the Debian standard system without X.org. It is suitable for burning to CD or DVD media. First, we run the lh config helper command which will create a "config/" hierarchy in the current directory for use by other helper commands: $ lh config By passing no parameters to lh config we indicated that we wish to use the defaults. This will create an image of type binary (see Section 4.1.1, ?The lh config helper?). Now that we have a "config/" hierarchy, we may build the image with the lh build helper command: # lh build This process can take a while, depending on the speed of your network connection (see Section 4.1.2, ?The lh build helper?). 3.2.1. Testing an ISO image with Qemu Testing an ISO is simple: # apt-get install qemu $ qemu -cdrom binary.iso 3.2.2. Burning an ISO image to a physical medium Burning an ISO image is easy: # apt-get install wodim $ wodim binary.iso 3.3. Building an USB/HDD image The following sequence of helper commands will create a basic USB/HDD image containing just the Debian standard system without X.org. It is suitable for booting from USB sticks, USB hard drives, and various other portable storage devices. Note if you created an iso image with the previous example, you will need to clean up your working directory with the lh clean helper command (see Section 4.1.3, ?The lh clean helper?): $ lh clean --binary Run the lh config helper command with the parameters to configure the "config/" hierarchy to create a USB/HDD image type: $ lh config -b usb-hdd Now build the image with the lh build helper command: # lh build 3.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 an USB stick. Plug in an 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. Important This will definitely overwrite any previous contents on your stick! 3.3.2. Testing a USB/HDD image with Qemu # apt-get install qemu $ qemu -hda binary.img 3.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 filsystem on it. One possible choice would be ext2 (ext3 isn't recommended because the journaling causes too many writes to the stick). # mkfs.ext2 ${USBSTICK} If you want to use this data partition with Windows, use FAT32. # mkfs.vfat -F 32 Important Remember: Every time you install a new binary.img on the stick, all your data will be lost because the image includes a complete partition table. FIXME: Describe installing Debian Live to a partition (e.g. /dev /sdc1) AND using a bootloader to boot this. 3.4. Building a netboot image The following sequence of helper commands will create a basic netboot image containing the Debian standard system without X.org. 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 lh clean helper command: $ lh clean --binary Run the lh config helper command with the parameters to configure the "config/" hierarchy to create our netboot image: $ lh config -b net --net-root-path "/srv/debian-live" --net-root-server "192.168.0.1" In contrast with the ISO and USB hdd images, netbooting does not support serving a filesystem image with 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. Now build the image with the lh build helper command: # lh build In a network boot the client runs a small piece of software, which usually resides on the EEPROM 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 boot loader via the TFTP protocol. That could be Grub, PXELINUX, 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 PXE Linux bootloader in tftpboot/debian-live/i386. We must now configure three services on the server to enable netboot: DHCP server We must configure our network's DHCP server to be sure to give an IP address to the computer netbooting, and to advertise the location of the PXE bootloader. Here is an example for inspiration, written for the ISC DHCP server (package dhcp3-server) in the /etc/dhcp3/dhcpd.conf configuration file: # Options DHCP sp?cifiques ? Pxelinux: option space pxelinux; option pxelinux.magic code 208 = string; option pxelinux.configfile code 209 = text; option pxelinux.pathprefix code 210 = text; option pxelinux.reboottime code 211 = unsigned integer 32; subnet 192.168.1.0 netmask 255.255.255.0 { # 192.168.1.0/24 # IP addresses available for guests range 192.168.1.100 192.168.1.149; # allow booting from the net allow bootp; # for net booting, server where the first file to be loaded (by TFTP # protocol) ("filename" following definition) lies : so the TFTP # server's name. next-server myserver; # net boot configuration for guests with a PXE client : if substring (option vendor-class-identifier, 0, 9) = "PXEClient" { # Note : all files for PXE are relatives to the TFTP server's root # path, as usually defined in /etc/inetd.conf. # PXE boot loader (first program to be loaded, by TFTP) filename "pxelinux.0"; # describe some specific pxelinux's options through DHCP options : site-option-space "pxelinux"; option pxelinux.magic f1:00:74:7e; if exists dhcp-parameter-request-list { # Always send the PXELINUX options (specified in hexadecimal) option dhcp-parameter-request-list = concat(option dhcp-parameter-request-list,d0,d1,d2,d3); } # For a PXE boot menu, different versions are available : simple # text, text with curses, graphic (VESA) #option pxelinux.configfile "pxelinux/config_simple"; #option pxelinux.configfile "pxelinux/config_curses"; option pxelinux.configfile "pxelinux/config_vesa"; # automatically reboot after 10 minutes of no activity option pxelinux.reboottime 600; } } TFTPd 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 /var/lib/ tftpboot/, as defined with its -s option. To let it serve files inside /srv/debian-live/tftpboot, modify its start definition in /etc/inetd.conf with: tftp dgram udp wait root /usr/sbin/in.tftpd /usr/sbin/in.tftpd -s /srv/debian-live/tftpboot -r blksize -v -v and reload the super server with /etc/init.d/openbsd-inetd reload. 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 should install the nfs-kernel-server package -- nfs-user-server does not function correctly with netboot. Then, make the filesystem image available through NFS by adding a line like the following to /etc/exports: /srv/debian-live *(ro,async,subtree_check,no_root_squash) 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. The Debian Installer Manual's TFTP Net Booting section might help as that process is very similar. 3.5. Netboot testing HowTo Netboot image creation is made easy with live-helper 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: 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 (i.e. change memory limit to 256) Double click on this file (or run VMWare player and selecet this file). When running just press space if that strange question comes up... Qemu Install qemu, bridge-utils, sudo. Edit /etc/qemu-ifup: #!/bin/sh sudo -p "Password for $0:" /sbin/ifconfig $1 172.20.0.1 echo "Executing /etc/qemu-ifup" echo "Bringing up $1 for bridged mode..." sudo /sbin/ifconfig $1 0.0.0.0 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" Chapter 4. Overview of tools This chapter contains an overview of the two main tools used in building Debian Live systems. 4.1. live-helper live-helper is a collection of scripts to build Debian Live systems. These scripts are also referred to as "helpers". The idea behind live-helper is to be a framework that uses a configuration directory to completely automate and customize all aspects of building a Live image. Many concepts are similar to those in the debhelper Debian package tools written by Joey Hess: 1. The scripts have a central location for configuring their operation. In debhelper, this is the debian subdirectory of a package tree. For example, dh_install will look for a file called debian/.install to determine which files should exist in a particular binary package. In much the same way, live-helper stores its configuration entirely under a config / subdirectory. 2. The scripts are independent - that is to say, it is always safe to run each command. Unlike debhelper, live-helper contains a tool to generate a skeleton configuration directory, lh config. This could be considered to be similar to tools such as dh-make. For more information about lh config, please see Section 4.1.1, ?The lh config helper?. Besides the common config/common, which is used by all live-helper helper commands, some additional files can be used to configure the behavior of specific helper commands. These files are typically named config/helper or config/stage (where "stage", of course, is replaced with the name of the stage that they belong to, and "helper" with the name of the helper). For example, the lh bootstrap debootstrap helper command uses files named config/bootstrap and config/bootstrap_debootstrap to read the options it will use. Generally, these files contain variables with values assigned, one variable per line. Some programs in live-helper use pairs of values or slightly more complicated variable assignments. live-helper respects environment variables which are present in the context of the shell it is running. If variables can be read from config files, then they override environment variables, and if command line options are used, they override values from config files. If no value for a given variable can be found (and is thus unset), live-helper will automatically set it to a default value. All config files are shell scripts which are sourced by a live-helper program. That means they have to follow the normal shell syntax. You can also put comments in these files; lines beginning with "#" are ignored. In some rare cases you may want to have different versions of these files for different architectures or distributions. If files named config/stage.arch or config/stage_helper.arch, and config/stage.dist or config/stage_helper.dist exist (where "arch" is the same as the output of dpkg --print-architecture and "dist" is the same as the codename of the target distribution), then they will be used in preference to the other, more general files. Please see Chapter 2, Installation for information on how to install live-helper. The remainder of this section discusses the three most important helpers: lh config Responsible for initialising a Live system configuration directory. See Section 4.1.1, ?The lh config helper? for more information. lh build Responsible for starting a Live system build. See Section 4.1.2, ?The lh build helper? for more information. lh clean Responsible for removing parts of a Live system build. See Section 4.1.3, ?The lh clean helper? for more information. 4.1.1. The lh config helper As discussed in Section 4.1, ?live-helper?, the scripts that make up live-helper source their configuration from a single directory named config/. As constructing this directory by hand would be time-consuming and error-prone, the lh config helper can be used to create skeleton configuration folders. Issuing lh config without any arguments creates a config subdirectory which it populates with some default settings: $ lh config $ ls -l total 4.1k drwxr-xr-x 19 user group 4.1k 2008-05-09 21:37 config $ ls -l config/ total 104 -rw-r--r-- 1 user group 4175 2010-04-11 12:16 binary drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_debian-installer drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_debian-installer-includes drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_grub drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-debs drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-hooks drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-includes drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-packageslists drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_local-udebs drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_rootfs drwxr-xr-x 2 user group 4096 2010-04-11 12:16 binary_syslinux -rw-r--r-- 1 user group 2205 2010-04-11 12:16 bootstrap -rw-r--r-- 1 user group 1599 2010-04-11 12:16 chroot drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_apt drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-hooks drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-includes drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-packages drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-packageslists drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-patches drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_local-preseed drwxr-xr-x 2 user group 4096 2010-04-11 12:16 chroot_sources -rw-r--r-- 1 user group 2938 2010-04-11 12:16 common drwxr-xr-x 2 user group 4096 2010-04-11 12:16 includes -rw-r--r-- 1 user group 206 2010-04-11 12:16 source drwxr-xr-x 2 user group 4096 2010-04-11 12:16 templates Using lh config without any arguments would be suitable for users who are either happy editing the generated files, or are simply happy with the defaults it creates. You can ask lh config to generate a config/ directory "preseeded" with various options. This might be suitable if you do not require the default settings but do not need to change a large number of options. For example: $ lh config -p gnome will build a config/ directory configured to include the 'gnome' package list. It is possible to specify many options: $ lh config --apt aptitude --binary-images net --hostname live-machine --username live-user ... A full list of options is available in the lh_config man page. Most options have a parallel with an "LH_" prefixed variable. 4.1.2. The lh build helper The lh build helper reads in your configuration from the config/ directory. It then runs the lower lower level commands needed to build your Live system. 4.1.3. The lh clean helper It is the job of the lh clean helper to remove various parts of a Live helper build so subsequent builds can start from a clean state. 4.2. The live-initramfs package live-initramfs is a collection of scripts providing hooks for the initramfs-tools, used to generate an initramfs capable of booting live systems, such as those created by live-helper. This includes the Debian Live isos, netboot tarballs, and usb stick images. At boot time it will look for read-only media containing a "/ live" directory where a root filesystem (often a compressed filesystem image like squashfs) is stored. If found, it will create a writable environment, using aufs or unionfs, for Debian like systems to boot from. live-initramfs is a fork of casper. More information on initial ramfs in Debian can be found in the Debian Linux Kernel Handbook's chapter on initramfs. Chapter 5. Customization 5.1. Customising package installation This chapter discusses the customisation of package installation. This involves: 1. Selecting additional packages to be installed 2. Installing modified packages 5.1.1. Package sources FIXME Debian repositories To set a local mirror (used to ''build'' the live-cd) $ lh config --mirror-bootstrap "http://local.intra.net/debian/" --mirror-chroot "http://local.intra.net/debian/" The generic mirror is added to the live-system's /etc/apt/ sources.list. $ lh config --mirror-binary "http://ftp.debian.org/debian/" Note: It is ''not'' used for building the live-cd but to install new software while using the live-cd. It can be disabled by setting binary indices parameter to disabled $ lh config --binary-indices disabled Note: the same applies for mirror chroot security and mirror binary security $ lh config --mirror-chroot-security {URL} $ lh config --mirror-binary-security {URL} Own repository To add more repositories (e.g. backports, experimental packages, etc.), create config/chroot_sources/your-cdd-repo. {chroot,binary} file. e.g. config/chroot_sources/live.chroot allows you to install packages from the debian live snapshot repository at live-cd build time (you have to add the packages in your package list): deb http://live.debian.net/ sid-snapshots main contrib non-free If you add the line to config/chroot_sources/live.binary the repository will be added to your live-system's /etc/apt/ sources.list. If such files exist, they will be picked up automatically. You can also put the gpg-key used to sign the repository into config/chroot_sources/foo.{binary,chroot}.gpg 5.1.2. Package installation You can elect to use either apt or aptitude when installing packages. Which utility is used is governed by the LH_APT variable in config/chroot or by the --apt argument to lh config: apt Specifying a missing package causes package installation to fail, which may not be the desired behaviour. This is the default setting for building images for Lenny or later. aptitude Specifying a missing package causes package installation to succeed, which may not be the desired behaviour. This is the default setting for building images for Etch. 5.1.3. Installing additional packages live-helper has a number of mechanisms for indicating that additional packages should be installed, including: 1. The LH_PACKAGES variable 2. Package lists 3. Local packages (chroot_local-packages/) 4. Tasks 5.1.3.1. The LH_PACKAGES variable To install additional packages, simply add them to the LH_PACKAGES variable in config/chroot. For example: LH_PACKAGES="package1 package2 package3 ... " You can also specify initial values on the command line: $ lh config --packages "package1 package2 package3" The behaviour of live-helper when specifying a package that does not exist is determined by your choice of APT utility. See Section 5.1.2, ?Package installation? 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, you should probably be using package lists. See Section 5.1.3.2, ?Package lists? for more information. 5.1.3.2. Package lists Package lists are a powerful way of expressing which packages should be installed. live-helper ships with a number of predefined package lists which provide sensible default package selections for the GNOME and KDE desktop environments, as well as standard systems. To specify a package list, add the name of the list to the LH_PACKAGES_LISTS variable in config/chroot. For example: LH_PACKAGES_LISTS="gnome" Package lists that are distributed with live-helper reside in the /usr/share/live-helper/lists directory. 5.1.3.2.1. Local packages lists You may supplement the supplied lists using local package lists stored in config/chroot_local-packageslists. Package lists that exist in this directory always override package lists distributed with live-helper. This can cause undesired effects when. live-helper 2.x change Any file with .list suffix in config/chroot_local-packageslists is automatically enabled, the variable LH_PACKAGES_LISTS should only be used referencing packages lists included in live-helper (at /usr/share/live-helper/lists/. 5.1.3.2.2. Extending a provided package list using includes FIXME #include iceweasel The package lists that are included with live-helper make extensive use of includes. They are available to view in the / usr/share/live-helper/lists directory. 5.1.3.2.3. Using conditionals inside packages lists FIXME #if ARCHITECTURE amd64 ia32-libs #endif or if LH_ARCHITECTURE is set to i386 or amd64: #if ARCHITECTURE i386 amd64 memtest86+ #endif or if LH_SECTIONS contains either contrib or non-free: #if SECTIONS contrib non-free vrms #endif A conditional may surround an #include directive: #if ARCHITECTURE amd64 #include #endif Any live-helper configuration variable that begins with LH_ can be tested in this way. The nesting of conditionals is not supported. 5.1.3.3. Tasks FIXME 5.1.4. 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' may be of interest, however. The creation of bespoke packages is covered in the Debian New Maintainers' Guide and elsewhere. There are two ways of installing modified custom packages: 1. chroot_local-packages 2. Using a custom APT repository The chroot_local-packages is simpler to achieve and useful for "one-off" customisations but has a number of drawbacks, whilst using a custom APT repository is more time-consuming to set up. 5.1.4.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. FIXME Using chroot_local-packages for installation of custom packages has disadvantages: 1. It is not possible to use secure APT 2. You must install all appropriate packages in the config/ chroot_local-packages directory 3. It does not lend itself to storing Debian Live configurations in revision control 5.1.4.2. Using an APT repository to install custom packages FIXME Unlike using chroot_local-packages, when using a custom APT repository you must ensure that you specify the packages elsewhere. See Section 5.1.3.1, ?The LH_PACKAGES variable? 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. 5.1.4.3. Custom packages and APT live-helper 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 Section 5.1.4.4, ?Altering APT preferences during Live system? for more information. 5.1.4.4. Altering APT preferences during Live system FIXME 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 package. 5.2. Customising contents This chapter discusses further customisation of the live system. 5.2.1. Includes Using includes, it is possible to add (or replace) arbitrary files in your Debian Live image. live-helper provides three mechanisms for using them: Chroot local includes These allow you to add or replace files to the chroot/Live filesystem. Please see Section 5.2.1.1, ?Live/chroot local includes? for more information. Binary local includes These allow you to add or replace files in the binary image. Please see Section 5.2.1.2, ?Binary local includes? for more information. Binary includes These allow you to add or replace Debian specific files in the binary image, such as the templates and tools directories. Please see Section 5.2.1.3, ?Binary includes? for more information. Please see Section 1.1.1, ?Terms? for more information about the distinction between the "Live" and "binary" images. 5.2.1.1. Live/chroot local includes Chroot local includes can be used to add or replace files in the chroot/Live filesystem so that they are visible when the Live system is booted. Typical uses for them are to populate the skeleton user directory (/etc/skel) used by the live system to create the live user's home directory, or adding configuration files where additional processing is not required. To include files, simply add them to your config/ chroot_local-includes directory. This directory corresponds to the root directory (/) of the live system. For example, to add a file /var/www/index.html in the live system, use: $ mkdir -p config/chroot_local-includes/var/www $ cp /path/to/my/index.html config/chroot_local-includes/var/www Your configuration will then have the following layout: -- config [...] |-- chroot_local-includes | `-- var | `-- www | `-- index.html [...] `-- templates Chroot local includes are installed after package installation so that files installed by packages are overwritten. 5.2.1.2. Binary local includes FIXME. 5.2.1.3. Binary includes FIXME. 5.2.2. Hooks FIXME. Enabling hooks 5.2.2.1. Live/chroot local hooks FIXME. 5.2.2.2. Binary local hooks FIXME. 5.2.3. Preseeding Debconf questions Files in the config/chroot_local-preseed directory are considered to be debconf preseed files and are installed by live-helper using debconf-set-selections. For more information about debconf, please see debconf(7) in the debconf package. 5.2.4. Symlink conversion FIXME. (This is probably in the wrong section) 5.3. Customising the bootup process This chapter discusses customisation of bootup process of a live system, including kernel options, modifications to the bootloader, "splash" screens and startup scripts. FIXME 5.3.1. Kernel 5.3.2. Bootloaders FIXME 5.3.2.1. Choosing a bootloader FIXME 5.3.2.2. Syslinux In the default configuration, Syslinux will pause indefinitely at its splash screen. To adjust this, modify the LH_SYSLINUX_TIMEOUT value or pass --syslinux-timeout TIMEOUT to lh_config. The value is specified in units of 1/10s and the maximum possible timeout is 35996. A timeout of 0 (zero) disables the timeout completely. For more information please see syslinux(1). 5.3.2.3. Bootloader templates FIXME 5.3.2.4. Booting a Debian Live USB/HDD system from a USB stick with Grub Suppose you've built your Debian Live USB/HDD image, but want to install it on an already used USB stick with ext2/3 partition and Grub bootloader: First, copy live components in a directory on your key: the Linux kernel (vmlinuz*), its Initial RAM disk (initrd*) and the system (filesystem.squashfs): # mkdir /media/myUsb/boot/live/ # cp binary/vmlinuz1 binary/initrd1.img binary/live/filesystem.squashfs /media/myUsb/boot/live/ Then, add a stanza in Grub's menu definition to boot up this system: echo >>/media/myUsb/boot/grub/menu.lst <live-media-path, which tells to Live initrd's script in which subdirectory to look for the SquashFS image. Next, umount your USB stick and reboot on it. That's all! 5.3.3. Splash screens FIXME 5.3.4. Memtest FIXME 5.3.5. Startup scripts FIXME 5.3.6. Cheat codes FIXME Checksums. 5.4. Customising the binary image This chapter discusses FIXME 5.4.1. ISO metadata When creating an ISO9660 binary image, you can use the following options to add various textual metadata for your image. This can help you easily identify the version or configuration of an image without booting it. LH_ISO_APPLICATION / --iso-application NAME This should describe the application that will be on the image. The maximum length for this field is 128 characters. LH_ISO_PREPARER / --iso-preparer NAME This should describe the preparer of the image, usually with some contact details. The default for this option is the live-helper version you are using, which may help with debugging later. The maximum length for this field is 128 characters. LH_ISO_PUBLISHER / --iso-publisher NAME This should describe the publisher of the image, usually with some contact details. The maximum length for this field is 128 characters. LH_ISO_VOLUME / --iso-volume NAME This should specify the volume ID of the image. This is used as a user-visible label on some platforms such as Windows and Apple Mac OS. The maximum length for this field is 32 characters. 5.5. Using a newer kernel with Lenny The backports repository, backports.org, lacks the necessary module packages (linux-modules-extra-2.6, aufs, etc.) so an alternative repository has been set up, in order to build Lenny live images with a later kernel. Shown here is one way of doing it. $ lh_config --linux-packages 'linux-image-2.6 aufs-modules-2.6' $ echo 'deb http://unsupported.debian-maintainers.org/backports-kernel/ ./' > config/chroot_sources/backports-kernel.chroot $ echo 'deb http://unsupported.debian-maintainers.org/backports-kernel/ ./' > config/chroot_sources/backports-kernel.binary $ wget http://unsupported.debian-maintainers.org/backports-kernel/archive-key.asc -O config/chroot_sources/backports-kernel.chroot.gpg $ wget http://unsupported.debian-maintainers.org/backports-kernel/archive-key.asc -O config/chroot_sources/backports-kernel.binary.gpg # lh_build Chapter 6. Common tasks 6.1. The Debian Installer Although Debian Live is mostly concerned with avoiding permanent installation, integrating some form of installer to your image is possible. There are number of different "types" of installation, varying in what and how to install the image. The "Debian Installer" Please note the careful use of capital letters when referring to the "Debian Installer" in this section - when used like this we refer explicitly to the official installer for the Debian system, not anything else. It is often seen abbreviated to "d-i". The three main types of installer are: "Normal" Debian Installer This is a normal Debian Live image with a seperate kernel and initrd which (when selected from the appropriate bootloader) launches into a standard Debian Installer instance, just as if you had downloaded a CD image of Debian and booted it. This means that Debian is installed by fetching and installing .deb packages using debootstrap or cdebootstrap, from the local media or some network-base network, resulting in a standard Debian system being installed to the hard disk. This whole process can be preseeded and customised in a number of ways; see the relevant "DebianInstaller" wiki page and installation guide for more. This is operational now withing live-helper. "Live" Debian Installer This is a Debian Live image with a seperate kernel and initrd which (when selected from the appropriate bootloader) launches into an instance of the Debian Installer. Installation will proceed in an identical fashion to the "Normal" installation described above, but at the actual package installation stage, instead of using debootstrap to fetch and install packages, the "live" filesystem image is copied to the target. After this stage, the Debian Installer continues as normal, installing and configuring items such as bootloaders and local users, etc. This is working now. "Ubuntu"-style installer This is where you boot into a graphical Debian Live system and run a wizard-based program which installs and configures the live system, all the time remaining inside the live graphical environment. This is currently NOT possible with Debian Live. By default, no installar will be included in the Debian Live image. You can enable it by using lh_config : $ lh_config --help ... [--debian-installer enabled|cdrom|netinst|netboot|businesscard|live|disabled] [--debian-installer-distribution CODENAME|daily] [--debian-installer-preseedfile FILE|URL] ... You can also use the appropriate variables in the config/binary file: $ cat config/binary | grep DEBIAN_INTALLER set debian-installer LH_DEBIAN_INSTALLER="disabled" # $LH_DEBIAN_INSTALLER_DISTRIBUTION: set debian-installer suite LH_DEBIAN_INSTALLER_DISTRIBUTION="lenny" # $LH_DEBIAN_INSTALLER_PRESEEDFILE: set debian-installer preseed filename/url LH_DEBIAN_INSTALLER_PRESEEDFILE="" The values "Normal", "Live" and "Ubuntu" are not valid values for LH_BINARY_DEBIAN_INSTALLER. Refer to the output of lh_config cited above to choose the appropriate values. 6.2. WiFi Connection Depending on the Debian Live image you are using and the given tools configured with your Debian Live image you may need to only attach to an available access point. If you encounter difficulty a good place to start is at the Debian Wiki entry for WiFi. Chapter 7. The Live environment 7.1. Swap space FIXME 7.2. Hostname The name of host running live system can be set with the hostname parameter into the --bootappend-live option of lh_config, e.g.: lh_config --bootappend-live "hostname=myhost" This parameter can also be used in kernel command line. 7.3. The Live user Username FIXME. One important consideration is that the live user is created by live-initramfs during bootup, it is not created by live-helper when building the image. 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 For more information about debconf preseeding, please see Section 5.2.3, ?Preseeding Debconf questions?. 7.4. 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 To define the locale that should be generated, use the locale parameter into the --bootappend-live option of lh_config, e.g.: lh_config --bootappend-live "locale=sv_SE.utf8" This parameter can also be used in kernel command line. You can specify a locale by a two-letters code, or for better control, by a full language_country.encoding word. Both the console and X keyboard configuration depends on the keyb parameter of the --bootappend-live option. Valid options for X keyboard layouts can be found in /etc/X11/xkb/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 /etc/X11/xkb/base.xml | grep name se To get the locale files for swedish generated and a swedish keyboard layout in X use: lh_config --bootappend-live "locale=sv_SE.utf8 keyb=se" 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 To make the console keyboard use a swedish layout use lh_config --bootappend-live "locale=sv_SE.utf8 keyb=se-latin1" Alternatively, you can use the console-setup package, a tool to let you configure console layout using X (XKB) definitions; you can then setup your keyboard layout more precisely with klayout, kvariant, koptions and kmodel variables; live-initramfs will use also these parameters for X configuration. For example, to set up a french system with a french-dvorak layout (called B?po) on a TypeMatrix keyboard, both in console and X11, use: lh_config --bootappend-live \ "locale=fr_FR.UTF-8 klayout=fr kvariant=bepo kmodel=tm2030usb" Note that on old versions of console-setup (i.e. Lenny's one), you'll need to setup also the keyb variable to the klayout's value. 7.5. Persistence A live cd paradigm is a preinstalled 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 runtime 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 runtime 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. 7.5.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 bootime 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'. 7.5.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. 7.5.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 runtime 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. 7.5.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. 7.5.5. Partial remastering The runtime 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-initramfs mounts all /live filesystem in order or with the module bootparameter. Chapter 8. Frequently asked questions (FAQ) Chapter 9. Reporting bugs Debian Live is far from being perfect, but we want to make it as close as possible to perfect - with your help. Do not hesitate to report a bug: it is better to fill a report twice than never. However, this chapter includes recommendations how to file good bug reports. For the impatient: * Always check first the image status updates on our homepage for known issues. * Always try to reproduce the bug with the most recent version of live-helper and live-initramfs before submitting a bug report. * Try to give as specific information as possible about the bug. This includes (at least) the version of live-helper and live-initramfs used and the distribution of the live system you are building. 9.1. Known issues Due to the nature of Debian testing and Debian unstable branches being a moving target, building a live system may not always be possible. If this is a problem, do not build a system based on testing or unstable, but go with stable. live-helper does always default to the current stable release. Currently known issues are listed under the section 'status' on our homepage. It is out of the scope of this manual to train you in correctly identifying and fixing problems in packages of the development branches, however, there are two things you can always try: When not succeeding to build testing, try if unstable works. If unstable does not work either, revert to testing and pinning the newer version of the failing package from unstable. 9.2. Rebuild from scratch To ensure that a particular bug is not caused by an unclean built system, please always rebuild the whole live system from scratch to see if the bug is reproducible. 9.3. Use up-to-date packages This means Using outdated packages can cause significant problems when trying to reproduce (and ultimately fix) your problem. If a relevant package is not available in Debian anymore, please recognize that the resources of the Debian kernel team are limited and will be unlikely to be able to fix the problem. 9.4. Collect information Please provide enough information with your report. At a minimum, it should contain the exact version of live-helper version where the bug is encountered, and steps to reproduce it. Please use common sense and include other relevant information if you think that it might help in solving the problem. To make the most out of your bug report, we require at least the following information: * Architecture of the host system * Version of live-helper on the host system * Version of live-initramfs on the live system * Version of debootstrap and/or cdebootstrap on the host system * Architecture of the live system * Distribution of the live system * Version of the kernel on the live system You can generate a log of the build process by using the tee command: # lh_build 2>&1 | tee buildlog.txt Additionally, to rule out other errors, it is always a good idea to tar up your config directory and upload it somewhere (do *not* send it as an attachment to the mailinglist), so that we can try to reproduce the errors you encountered. Remember to send in any logs that were produced with English locale settings, e.g. run your live-helper commands with a leading LC_ALL=C or LC_ALL=en_US. 9.5. Use the correct package to report the bug against Where does the bug appear? At build time whilst bootstrapping live-helper first bootstraps a basic Debian system with debootstrap or cdebootstrap. Depending on the bootstrapping tool used and the Debian distribution it is bootstrapping, it may fail. If a bug appears here, check if the error is related to a specific Debian package (most likely), or if it is related to cdebootstrap itself. In both cases, this is not a bug in Debian Live, but rather in Debian itself which we can not fix this directly. Please report such a bug against debootstrap, cdebootstrap or the failing package. At build time whilst installing packages live-helper installs additional packages from the Debian archive and depending on the Debian distribution used and the daily archive state, it can fail. If a bug appears here, check if the error is also reproducible on a normal system. If this is the case, this is not a bug in Debian Live, but rather in Debian - please report it against the failing package. Running debootstrap seperately from the Live system build or running lh_bootstrap with --debug will give you more information. Also, if you are using a local mirror and/or any of sort of proxy and you are experiencing a problem, please always reproduce it first by bootstrapping from an official mirror. At boot-time If your image does not boot, please report it to the mailing list together with the information requested in Section 9.4, ?Collect information?. Do not forget to mention, how/when the image failed, in Qemu, VMWare or real hardware. If you are using a virtualization technology of any kind, please always run it on real hardware before reporting a bug. Providing a screenshot of the failure is also very helpful. At run-time If a package was successfully installed, but fails while actually running the Live system, this is probably a bug in Debian Live. However, 9.6. Do the research Before filing the bug, please search the web for the particular error message or symptom you are getting. As it is highly unlikely that you are the only person experiencing a particular problem, there is always a chance that it has been discussed elsewhere, and a possible solution, patch, or workaround has been proposed. You should pay particular attention to the Debian Live mailing list, as well as the homepage, as these are likely to contain the most up-to-date information. If such information exists, always include the references to it in your bug report. In addition, you should check the current bug list for live-helper and the current bug list for live-initramfs to see whether something similar has been reported already. 9.7. Where to report bugs The Debian Live project keeps track of all bugs in the Debian Bug Tracking System (BTS). For information on how to use the system, please see http://bugs.debian.org. You can also submit the bugs by using the reportbug command from the package with the same name. In general, you should report build time errors against the live-helper package and run time errors against live-initramfs. If you are unsure of which package is appropriate or need more help before submitting a bug report, please send a message to the mailing list and we will help you to figure it out. Please note that bugs found in distributions derived from Debian (such as Ubuntu, Knoppix, Xandros, etc.) should not be reported to the Debian BTS unless they can be also reproduced on a Debian system using official Debian packages. Chapter 10. Coding Style This chapter documents the coding style used in live-helper and (ideally) in live-initramfs. 10.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' 10.2. Indenting * Always use tabs over spaces. 10.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 } 10.4. Variables * Variables are always in capital letters. * Variables that used in config always start with LH_ prefix. * Internal temporary variables should start with the _LH_ prefix. * Local variables start with __LH_ prefix. * Use braces around variables; eg. write ${FOO} instead of $FOO. * Always protect variables with respect to 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 10.5. Miscellaneous * Use "|" (without the surround quotes) as a seperator 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; ...". Chapter 11. Procedures This chapter documents the procedures within the Debian Live project for various tasks that need cooperation with other teams in Debian. 11.1. Udeb Uploads Before commiting releases of a udeb in d-i svn, one has to call: ../../scripts/l10n/output-l10n-changes . -d 11.2. Major Releases Releasing a new stable major version of Debian includes a lot of different teams working together to make it happen. At some point, the Live team comes in and builds live system images. The requirements to do this are: * The local debian mirror of the debian-live buildd needs to be synced against a mirror that contains the released version. * The local debian-security mirror of the debian-live buildd needs to be synced against a mirror that contains the released version. * The names of the image need to be known (e.g. debian-live-500-ARCH-FLAVOUR.iso). * The data from debian-cd needs to be synced (udeb exclude lists). * The includes from debian-cd needs to be synced (README.*, doc/*, etc.). * Images are built and mirrored on cdimage.debian.org. 11.3. Point Releases * Again, we need updated mirror of both debian and debian-security. * Before actual images can be built, the sizes of the gnome-desktop and kde-desktop CD images need to be checked that they are not too big. * Images are built and mirrored on cdimage.debian.org. * Send announcement mail. 11.3.1. Point release announcement template An annoucement mail for point releases can be generated using the template below and the following command: $ sed \ -e 's|%major%|5.0|g' \ -e 's|%minor%|5.0.2|g' \ -e 's|%codename%|lenny|g' \ -e 's|%release_mail%|2009/msg00007.html|g' Please check the mail carefully before sending and pass it to others for proof-reading. Debian Live images for Debian GNU/Linux %major% updated The Debian Live project is pleased to announce the availability of updated Live images for its stable distribution Debian GNU/Linux %major% (codename "%codename%"). The images are available for download at: This update incorporates the changes made in the %minor% point release, which adds corrections for security problems to the stable release along with a few adjustments for serious problems. A full list of the changes may be viewed at: It also includes the following Live-specific changes: * [INSERT LIVE-SPECIFIC CHANGE HERE] * [INSERT LIVE-SPECIFIC CHANGE HERE] * [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] URLs ---- Download location of updated images: Debian Live project homepage: The current stable distribution: stable distribution information (release notes, errata etc.): Security announcements and information: About Debian ------------- The Debian Project is an association of Free Software developers who volunteer their time and effort in order to produce the completely free operating system Debian GNU/Linux. About Debian Live ----------------- Debian Live is an official sub-project of Debian which produces Debian systems that do not require a classical installer. Images are available for CD/DVD discs, USB sticks and PXE netbooting as well as a bare filesystem images for booting directly from the internet. Contact Information ------------------- For further information, please visit the Debian Live web pages at or alternatively send mail to . Chapter 12. Resources and links 12.1. Links FIXME 1. Debian homepage 12.2. Who is using Debian Live? A number of projects are using Debian Live: * Debian KDE4 livecd * gNewSense "forked" a very early live-package * GNUSTEP Live CD using live-package * PlayStation 3 Live CD using live-package * Sidux Live CD "forked" an early live-package * Vamos * Clonezilla (system image distributer) * Webconverger (using live-helper) * Xorcom Rapid live cd - Asterisk-based live CD * PelicanHPC uses live-helper * IES S'Arenal, Llucmajor (Secondary school located near to Palma de Mallorca), Spain. * GNUSTEP Live CD (using live-package) * Voyage Linux * pure:dyne: Providing a live system and a software repository for media artists. * Privatix Live-System: Debian based german live-system for privacy and encryption. * lernstick (using live-helper) 12.3. English sources related to debian live * Debian_Live definition on Wikipedia * Presentation on Debian-Live 12.4. German sources related to debian live * German translation (work in progress) * Article in linux-magazin.de * Another german documentation 12.5. Spanish sources related to debian live * Spanish documentation project Appendix A. Configuration layout Layout of the config/ directory binary_debian-installer/ (see Section 6.1, ?The Debian Installer?) binary_grub/ (see Section 5.3.2, ?Bootloaders?) binary_local-debs/ (see Section 6.1, ?The Debian Installer?) binary_local-hooks/ (see Section 5.2.2.2, ?Binary local hooks?) binary_local-includes/ (see Section 5.2.1.3, ?Binary includes?) binary_local-packageslists/ (see Appendix A, Configuration layout) binary_local-udebs/ (see Section 6.1, ?The Debian Installer?) binary_rootfs/ (see Appendix A, Configuration layout) binary_syslinux/ (see Section 5.3.2, ?Bootloaders?) chroot_apt/ (see Section 5.1.4.3, ?Custom packages and APT?) chroot_local-hooks/ (see Section 5.2.2.1, ?Live/chroot local hooks?) chroot_local-includes/ (see Section 5.2.1.1, ?Live/chroot local includes?) chroot_local-packages/ (see Section 5.1.4.1, ? Using chroot_local-packages to install custom packages ?) chroot_local-packageslists/ (see Section 5.1.3.2, ?Package lists?) chroot_local-presed/ (see Section 5.2.3, ?Preseeding Debconf questions?) chroot_sources/ (see Section 5.1.4.2, ?Using an APT repository to install custom packages?) includes/ (see Section 5.3.2, ?Bootloaders?) templates/ (see Section 5.3.2, ?Bootloaders?) bootstrap (see Section B.2, ?The config/bootstrap file?) binary (see Section B.1, ?The config/binary file?) chroot (see Section B.3, ?The config/chroot file?) common (see Section B.4, ?The config/common file?) source (see Section B.5, ?The config/source file?) Appendix B. Configuration files B.1. The config/binary file LH_BINARY_FILESYSTEM Set image filesystem. (See Appendix A, Configuration layout) LH_BINARY_IMAGES Set image type. (See Appendix A, Configuration layout) LH_BINARY_INDICES Set apt/aptitude generic indices. (See Appendix A, Configuration layout) LH_BOOTAPPEND_LIVE Set boot parameters. (See Appendix A, Configuration layout) LH_BOOTAPPEND_INSTALL Set boot parameters. (See Appendix A, Configuration layout) LH_BOOTLOADER Set bootloader. (See Section 5.3.2, ?Bootloaders?) LH_CHECKSUMS Set checksums. (See Section 5.3.6, ?Cheat codes?) LH_CHROOT_BUILD Control if we build binary images chrooted. (See Appendix A, Configuration layout) LH_DEBIAN_INSTALLER Set debian-installer. (See Section 6.1, ?The Debian Installer?) LH_DEBIAN_INSTALLER_DAILY Set daily images. (See Section 6.1, ?The Debian Installer?) LH_ENCRYPTION Set encrytion. (See Appendix A, Configuration layout) LH_GRUB_SPLASH Set custom grub splash. (See Section 5.3.3, ?Splash screens? ) LH_HOSTNAME Set hostname. (See Section 7.2, ?Hostname?) LH_ISO_APPLICATION Set iso author. (See Section 5.4.1, ?ISO metadata?) LH_ISO_PREPARER Set iso preparer. (See Section 5.4.1, ?ISO metadata?) LH_ISO_PUBLISHER Set iso publisher. (See Section 5.4.1, ?ISO metadata?) LH_ISO_VOLUME Set iso volume (max 32 chars). (See Section 5.4.1, ?ISO metadata?) LH_JFFS2_ERASEBLOCK Set jffs2 eraseblock size. (See Appendix A, Configuration layout) LH_MEMTEST Set memtest. (See Section 5.3.4, ?Memtest?) LH_NET_ROOT_FILESYSTEM Set netboot filesystem. (See Appendix A, Configuration layout) LH_NET_ROOT_MOUNTOPTIONS Set nfsopts. (See Appendix A, Configuration layout) LH_NET_ROOT_PATH Set netboot server directory. (See Appendix A, Configuration layout) LH_NET_ROOT_SERVER Set netboot server address. (See Appendix A, Configuration layout) LH_NET_COW_FILESYSTEM Set net client cow filesystem. (See Appendix A, Configuration layout) LH_NET_COW_MOUNTOPTIONS Set cow mount options. (See Appendix A, Configuration layout ) LH_NET_COW_PATH Set cow directory. (See Appendix A, Configuration layout) LH_NET_COW_SERVER Set cow server. (See Appendix A, Configuration layout) LH_NET_TARBALL Set net tarball. (See Appendix A, Configuration layout) LH_SYSLINUX_SPLASH Set custom syslinux splash. (See Section 5.3.3, ?Splash screens?) LH_SYSLINUX_TIMEOUT Set custom syslinux timeout in seconds. (See Section 5.3.2.2, ?Syslinux?) LH_SYSLINUX_CFG Set custom syslinux configuration file. (See Section 5.3.2.2, ?Syslinux?) LH_SYSLINUX_MENU Set syslinux menu. (See Section 5.3.2.2, ?Syslinux?) LH_SYSLINUX_MENU_LIVE_ENTRY Set text to be used on the menu for live entries. (See Section 5.3.2.2, ?Syslinux?) LH_SYSLINUX_MENU_LIVE_FAILSAFE_ENTRY Set text to be used on the menu for live entries (failsafe ones). (See Section 5.3.2.2, ?Syslinux?) LH_SYSLINUX_MENU_MEMTEST_ENTRY Set text to be used on the menu for memtest entry. (See Section 5.3.2.2, ?Syslinux? and Section 5.3.4, ?Memtest?) LH_USERNAME Set username. (See Section 7.3, ?The Live user?) B.2. The config/bootstrap file LH_ARCHITECTURE Select chroot architecture. (See Appendix A, Configuration layout) LH_BOOTSTRAP_CONFIG Set distribution config directory. (See Appendix A, Configuration layout) LH_BOOTSTRAP_INCLUDE Include packages on base. (See Appendix A, Configuration layout) LH_BOOTSTRAP_EXCLUDE Exclude packages on base. (See Appendix A, Configuration layout) LH_BOOTSTRAP_FLAVOUR Select flavour to use. (See Appendix A, Configuration layout ) LH_BOOTSTRAP_KEYRING Set distribution keyring. (See Appendix A, Configuration layout) LH_DISTRIBUTION Select distribution to use. (See Appendix A, Configuration layout) LH_MIRROR_BOOTSTRAP Set mirror to bootstrap from. (See Section 5.1.1, ?Package sources?) LH_MIRROR_CHROOT Set mirror to fetch packages from. (See Section 5.1.1, ?Package sources?) LH_MIRROR_CHROOT_SECURITY Set security mirror to fetch packages from. (See Section 5.1.1, ?Package sources?) LH_MIRROR_BINARY Set mirror which ends up in the image. (See Section 5.1.1, ?Package sources?) LH_MIRROR_BINARY_SECURITY Set security mirror which ends up in the image. (See Section 5.1.1, ?Package sources?) LH_SECTIONS select section(s) to use. (See Section 5.1.1, ?Package sources?) B.3. The config/chroot file LH_CHROOT_FILESYSTEM Set chroot filesystem. (See Appendix A, Configuration layout ) LH_UNION_FILESYSTEM Set union filesystem. (See Appendix A, Configuration layout) LH_EXPOSED_ROOT expose root as read only. (See Appendix A, Configuration layout) LH_HOOKS Set hook commands. (See Section 5.2.2, ?Hooks?) LH_INTERACTIVE Set interactive build. (See Appendix A, Configuration layout ) LH_KEYRING_PACKAGES Set keyring packages. (See Appendix A, Configuration layout) LH_LANGUAGE Set language to use. (See Section 7.4, ?Language?) LH_LINUX_FLAVOURS Set kernel flavour to use. (See Section 5.3.1, ?Kernel?) LH_LINUX_PACKAGES Set kernel packages to use. (See Section 5.3.1, ?Kernel?) LH_PACKAGES Set packages to install. (See Section 5.1.3.1, ?The LH_PACKAGES variable?) LH_PACKAGES_LISTS Set package list to install. (See Section 5.1.3.2, ?Package lists?) LH_TASKS Set tasks to install. (See Section 5.1.3.3, ?Tasks?) LH_SECURITY enable security updates. (See Section 5.1.1, ?Package sources?) LH_SYMLINKS enable symlink convertion. (See Section 5.2.4, ?Symlink conversion?) LH_SYSVINIT enable sysvinit. (See Section 5.3.5, ?Startup scripts?) B.4. The config/common file LH_APT Set package manager. (See Section 5.1.2, ?Package installation?) LH_APT_FTP_PROXY Set apt/aptitude ftp proxy. (See Section 5.1.2, ?Package installation?) LH_APT_HTTP_PROXY Set apt/aptitude http proxy. (See Section 5.1.2, ?Package installation?) LH_APT_PDIFFS Set apt/aptitude pdiff indices. (See Section 5.1.2, ?Package installation?) LH_APT_PIPELINE Set apt/aptitude pipeline depth. (See Section 5.1.2, ?Package installation?) LH_APT_RECOMMENDS Set apt/aptitude recommends. (See Section 5.1.2, ?Package installation?) LH_APT_SECURE Set apt/aptitude security. (See Section 5.1.2, ?Package installation?) LH_BOOTSTRAP Set bootstrap program. (See Appendix A, Configuration layout ) LH_CACHE control cache. (See Appendix A, Configuration layout) LH_CACHE_INDICES control if downloaded package indices should be cached. (See Appendix A, Configuration layout) LH_CACHE_PACKAGES control if downloaded packages files should be cached. (See Appendix A, Configuration layout) LH_CACHE_STAGES control if completed stages should be cached. (See Appendix A, Configuration layout) LH_DEBCONF_FRONTEND Set debconf(1) frontend to use. (See Appendix A, Configuration layout) LH_DEBCONF_NOWARNINGS Set debconf(1) warnings. (See Appendix A, Configuration layout) LH_DEBCONF_PRIORITY Set debconf(1) priority to use. (See Appendix A, Configuration layout) LH_INITRAMFS Set initramfs hook. (See Appendix A, Configuration layout) LH_FDISK Set fdisk program. (See Appendix A, Configuration layout) LH_LOSETUP Set losetup program. (See Appendix A, Configuration layout) LH_MODE Set distribution mode. (See Appendix A, Configuration layout ) LH_ROOT_COMMAND use sudo or equivalent. (See Appendix A, Configuration layout) LH_USE_FAKEROOT use fakeroot/fakechroot. (See Appendix A, Configuration layout) LH_TASKSEL Set tasksel program. (See Section 5.1.3.3, ?Tasks?) LH_INCLUDES Set includes. (See Appendix A, Configuration layout) LH_TEMPLATES Set templates. (See Appendix A, Configuration layout) LH_BREAKPOINTS enable breakpoints. (See Appendix A, Configuration layout) LH_DEBUG enable debug. (See Appendix A, Configuration layout) LH_FORCE enable force. (See Appendix A, Configuration layout) LH_QUIET enable quiet. (See Appendix A, Configuration layout) LH_VERBOSE enable verbose. (See Appendix A, Configuration layout) B.5. The config/source file LH_SOURCE Set source option. (See Appendix A, Configuration layout) LH_SOURCE_IMAGES Set image type. (See Appendix A, Configuration layout)