2.0~a2
Copyright © 2006-2010 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.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
On Debian systems, the complete text of the GNU General Public License can be found in /usr/share/common-licenses/GPL-3 file.
2010-06-18
Table of Contents
Table of Contents
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 as far as things are live specific.
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.
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/DVDs or USB sticks, some may also boot over the network.
The Debian sub-project which maintains the live-helper, live-boot and live-config packages.
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)
The environment used to create the live system.
live-helper
A collection of scripts used to build customised Debian Live systems. live-helper was formerly know as live-package.
live-boot
A collection of scripts used to boot live systems. live-boot was formerly a part of live-initramfs.
live-config
A collection of scripts used to configure a live systems during the boot process. live-config was formerly a part of live-initramfs.
The official installation system for the Debian distribution.
FIXME
The chroot program, chroot(8), enables us to run different instances of the GNU/Linux environment on a single system simultaneously without rebooting.
On a live system, binary image refers to the binary filesystem and the respective extension, such as binary.iso or binary.img.
The distribution upon which your live system will be based. This can differ from the distribution of your Build System.
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.
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
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
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
When Debian Live was initiated, there were already several Debian based live systems available and they are doing a great job. From the Debian perspective most of them have one or more of the following disadvantages:
They are unofficial projects, developed outside of Debian.
They mix different distributions, e.g. testing and unstable.
They support i386 only.
They modify the behaviour and/or appearance of packages by stripping them down to save space.
They include unofficial packages.
They ship custom kernels with additional patches that are not part of Debian.
They are large and slow due to their sheer size and thus not suitable for rescue issues.
They are not available in different flavours, e.g. CDs, DVDs, USB-stick and netboot images.
Debian is the Universal Operating System: Debian has an official live system for showing around and to officially represent the true, one and only Debian system with the following main advantages:
It would be an official Debian subproject.
It reflects the (current) state of one distribution.
It runs on as many architectures as possible.
It consists of unchanged Debian packages only.
It does not contain any unofficial packages.
It uses an unaltered Debian kernel with no additional patches.
We will only use official packages from the Debian repository in the "main" section. The non-free section is not part of Debian and therefore cannot be used at all for official live system images.
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, live-boot or live-config 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.
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.
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.
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.
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.
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.
Table of Contents
Table of Contents
Building Debian Live images has very few system requirements:
Super user (root) access
An up-to-date version of live-helper
A POSIX-compliant shell, such as bash or dash.
debootstrap or cdebootstrap
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.
You can install live-helper in a number of different ways:
From the Debian repository
From source
From snapshots
From backports.org
If you are using lenny or sid the recommended way is to install live-helper via the Debian repository.
Simply install live-helper like any other package:
# apt-get install live-helper
or
# aptitude install live-helper
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
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.
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.
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”.
Checkout the live-initramfs source
$ git clone git://live.debian.net/git/live-initramfs.git
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".
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
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”.
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:
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
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
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
Table of Contents
This chapter contains a brief overview of the build process as well as containing instructions on how to boot the various binary image types.
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:
The Linux image, usually named vmlinuz*.
RAM disk setup for the Linux boot, containing modules possibly needed to mount the filesystem's image and some scripts to do it.
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”.)
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.)
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”).
Testing an ISO is simple:
# apt-get install qemu $ qemu -cdrom binary.iso
In order to test the ISO with virtualbox-ose:
# apt-get install virtualbox-oseand either install
the modules package for a stock kernel eg virtualbox-ose-modules-2.6.26-1-486 or
the modules package compiled for your kernel using module-assistant from the package virtualbox-ose-source
Run Virtualbox:
For example, in Gnome{{{Applications -> System Tools -> VirtualBox OSE }}}
Create a virtual machine from your Live ISO
To create a virtual machine "mylive" from A CDROM ISO "binary.iso" in VirtualBox:
{{{Machine -> New }}}
In the Wizard: FIXME
In order to test the ISO with VMware Workstation:
Run VMware Workstation:
Click on Edit virtual machine settings in the VM summary page.
Then, click on the CD-ROM device and select Use ISO image. Remeber to connect the CD-ROM device at power on and remeber to adjust the boot order in the bios.
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
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.
In order to test the USB/HDD image with VMware Workstation:
Run VMware Workstation:
Write the image to an usb stick. In VMware, click on Edit virtual machine settings in VM summary page. Then, add a new physical harddisk device and enter the device node of your 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
FIXME: Describe installing Debian Live to a partition (e.g. /dev/sdc1) AND using a bootloader to boot this.
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:
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; } }
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.
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.
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:
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...
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"
Table of Contents
This chapter contains an overview of the two main tools used in building Debian Live systems.
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:
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/<packagename>.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.
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.
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.
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.
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.
Table of Contents
This chapter discusses the customisation of package installation. This involves:
Selecting additional packages to be installed
Installing modified packages
FIXME
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}
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
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:
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.
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.
live-helper has a number of mechanisms for indicating that additional packages should be installed, including:
The LH_PACKAGES variable
Package lists
Local packages (chroot_local-packages/)
Tasks
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.
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.
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 changeAny 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/.
FIXME
#include <gnome> 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.
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 <gnome-full> #endif
Any live-helper configuration variable that begins with LH_ can be tested in this way.
The nesting of conditionals is not supported.
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:
chroot_local-packages
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.
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:
It is not possible to use secure APT
You must install all appropriate packages in the config/chroot_local-packages directory
It does not lend itself to storing Debian Live configurations in revision control
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.
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.
This chapter discusses further customisation of the live system.
Using includes, it is possible to add (or replace) arbitrary files in your Debian Live image. live-helper provides three mechanisms for using them:
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.
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.
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.
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.
FIXME.
Enabling hooks
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.
This chapter discusses customisation for language specific parameters.
The default locale when building a live cd is "locale=en_US.UTF-8". To set the locale for the UK (locale=en_GB.UTF-8)
$ lh_config --bootappend-live "locale=en_GB.UTF-8"
The entry for a British keyboard would be
$ lh_config --bootappend-live "keyb=uk"
To configure both the locale and the keyboard for the UK the entry would be
$ lh_config --bootappend-live "locale=en_GB.UTF-8 keyb=uk"
or
$ lh_config --bootappend-live "locale=uk"
lh build can automatically check for each package, for which it's know that there are -l10n packages available and install them. To add Swedish packages the entry would be
$ lh_config --language "se"
This will also change the default syslinux language if
config/templates/syslinux/se
is available. Check syslinux configuration FIXME
This chapter discusses customisation of bootup process of a live system, including kernel options, modifications to the bootloader, "splash" screens and startup scripts.
FIXME
FIXME
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).
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 <<EOF title my Debian Live root (hd0,1) # my Ext2 partition is the second on this stick kernel /boot/live/vmlinuz1 boot=live vga=791 persistent union=aufs live-media-path=boot/live initrd /boot/live/initrd1.img EOF
The important kernel command line option to add here is <variablename>live-media-path</variablename>, 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!
This chapter discusses FIXME
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.
NAME
This should describe the application that will be on the image. The maximum length for this field is 128 characters.
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.
NAME
This should describe the publisher of the image, usually with some contact details. The maximum length for this field is 128 characters.
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.
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
Table of Contents
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.
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:
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.
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.
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 installer 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] ...
The values "Normal", "Live" and "Ubuntu" are not valid values for <term>LH_BINARY_DEBIAN_INSTALLER</term>. Refer to the output of lh_config cited above to choose the appropriate values.
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.
Table of Contents
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.
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”.
When the live system boots, language is involved in three steps:
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
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 <name>se</name>
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.
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.
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'.
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.
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.
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.
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.
Q: I downloaded a prebuilt live image. How do I put it on a USB stick?
A: See Section 3.3.1, “Copying USB/HDD image to a USB stick” "Copying USB/HDD image to a USB stick"
Q: How do I log my build?
A: You could use script, screen or tee:
$ lh_build 2>&1 | tee build.log
Q: How can I convert an already installed standard Debian partition into a Debian Live system?
A: Save the list of installed packages and load it into your new Debian Live System. Copy your /etc to config/chroot_local-includes
Q: What does 'losetup: could not find any free loop device' mean and how do I fix it?
A: Loop devices are used during the build; there probably aren't any free if you've aborted several builds. Something like: for l in /dev/loop0 /dev/loop1 /dev/loop2 /dev/loop3 /dev/loop4 /dev/loop5 /dev/loop6 /dev/loop7 ; do losetup -d $l ; done should rectify the situation (assuming all loop devices in use were created by lh_build; if in doubt, check the contents of each loop device before deleting them with losetup -d).
Q: How do I launch an interactive shell during the chroot stage?
A: To enable interactive shell:
$ lh_config --interactive shell
To continue the build process:
# logout
or
# exit
To disable interactive shell, set LH_INTERACTIVE to "disabled" in config/chroot.
Q: What is the root /user password?
A: The user password for the live user is 'live'. By default, there is not any root password. You can switch to root with
sudo -i
or set a password for root with
sudo passwd
Q: How do I change root or any user password?
A: Add a chroot local hook script to change root or any user password each time you build an image.
e.g. config/chroot_local-hooks/01-update_password.sh to set root password to "nopasswd"
#!/bin/sh echo "I: update password" echo "root:nopasswd" | chpasswd
$ chmod +x config/chroot_local-hooks/01-update_password.sh
mkdir -p config/chroot_local-includes/usr/share/initramfs-tools/scripts/live-bottom/ cp /usr/share/initramfs-tools/scripts/live-bottom/10adduser config/chroot_local-includes/usr/share/initramfs-tools/scripts/live-bottom/
Then edit the config/chroot_local-includes/usr/share/initramfs-tools/scripts/live-bottom/10adduser and paste in the new user_crypted password that you make with:
echo "newlivepass" | mkpasswd -s.
Or add an hook file in config/chroot_local-hooks/ with something like the below:
#!/bin/sh # Change the autogenerated user password to "debianlive" plain_password="debianlive" password=$(echo "${plain_password}" | mkpasswd -s) sed -i -e 's/\(user_crypted=\)\(.*\)\( #.*\)/\1\"'${password}'\"\3/' /usr/share/initramfs-tools/scripts/live-bottom/10adduser update-initramfs -tu -kall
The latter (hook model) could be more future proof than the former solution since it modifies just one string selectively but it requires the package "whois" to be installed on the target system (for mkpasswd) or that you generate the $password string not at build time and include it crypted in the above script.
Q: How to disable autologin?
A1: use the commandline parameter
lh config --bootappend-live "noautologin"
A2: You need to set boot=noautologin noxautologin as described in man live-initramfs If you boot via TFTP you want to insert the option to pxelinux.cfg/default
Q: How do I change default hostname or username?
A: To change default hostname or username:
$ lh_config --hostname myhostname $ lh_config --username myusername
Q: How do I make the final image smaller?
A: Clean orphaned apps/libs: Install package "deborphan" and then run 'sudo deborphan -n' . Delete unwanted packages. Remove the apt cache. Purge unwanted locales (see "localepurge" package).
Q: How do I customize bash-config permanently (aliases, bash-completion etc.)?
A: Add your own .bashrc config/chroot_local-includes/etc/skel/.bashrc
Q: How do I disable services permanently? (Be careful!)
A: Add a chroot local hook script to disable a service each time you build an image:
e.g. config/chroot_local-hooks/01-disable_service.sh
#!/bin/sh echo "I: disable service" update-rc.d -f 〈service name 〉 remove
$ chmod +x config/chroot_local-hooks/01-disable_service.sh
Q: How do I enable | disable the md5checksum at the ISO building?
lh_config --checksums enabled|disabled
Or change the LH_CHECKSUMS value.
Q: How to disable the generation of the .tar.gz file?
lh_config --net-tarball none|gzip
Or change the LH_NET_TARBALL value. (only available in snapsshot version at the moment 2008/Feb/28)
Q: How do I "build a new image" ?
A: Run commands:
$ sudo lh_clean --binary $ sudo lh_build
Hint: If the configuration had changed you should leave "--binary" out. This will clean your chroot directory too.
Q: How do I use Fluxbox ?
A: Add a new lists file with the fluxbox packages you want.
Create /home/$USERNAME/.dmrc file (default username is "user").
$ cat .dmrc [Desktop] Session=fluxbox
See also http://wiki.debian.org/Fluxbox
A short HOWTO can be found here: http://wiki.debian.org/MichaelAblassmeier/CustomLiveCD
Q: How do I use custom repositories?
Q: How do I customize the artwork for the live CD (grub or syslinux boot splash, usplash, etc.)?
A: See DebianLive/Howto/Custom_Artwork. FIXME: NEED TO UPDATE
Q: How do I customize desktop environment (KDE, GNOME, XFCE, etc...) look?
A: Start the live system in qemu:
$ qemu -m 256 -cdrom binary.iso -boot d -redir tcp:4222:10.0.2.15:22
Q: How do I execute a custom shell script inside the chroot system after the chroot stage?
A: Add your script in config/chroot_local-hooks.
Q: How do I add a script running immediately after all other scripts when the live system boots?
A: Add your script in config/chroot_local-includes/usr/share/initramfs-tools/scripts/live-bottom/99script
$ chmod +x config/chroot_local-includes/usr/share/initramfs-tools/scripts/live-bottom/99script
You must also use the example script /usr/share/live-helper/examples/hooks/update-initramfs.sh to ensure your script gets built into the initramfs (read the comment header for instructions).
Q: How do I add software not in Debian ?
A: See Section 5.1, “Customising package installation” Customising package installation
Q: What is the manifest with Ubuntu used for?
A: Manifest is just the package list, which ubuntu does $something with. Don't worry about it.
Q: What is this {p} syntax with mtools{p} and parted{p} ?
A: That's aptitude.
Q: Do I need to write the image on USB stick to test it?
Q: What is /cow ?
A: Copy-on-write, the 'diff' from unionfs.
Q: Is /usr/share/live-helper/lists/standard-x11 like preseed or is preseed something else entirely?
A: It is not. It is a package list, not a debconf preseeding.
Q: What is the difference between standard and minimal?
standard: packages of priority standard and higher;
minimal: packages of priority essential and higher;
Q: What can the sections be used for? Aren't they BIG?
A: Someone maybe wants to include packages from contrib or non-free.
Q: memtest86+ ... is that used?
A: Yes
Q: How do I build using predefined packages lists?
A: e.g. to build using standard-x11 packages list:
$ sudo lh_config -p standard-x11 $ sudo lh_build
Q: How do I rebuild without downloading all the packages again?
A: All packages are cached in cache subdirectory. They remain until a clean purge:
$ sudo lh_clean --purge
You do not have to do anything to prevent packages from being re-downloaded. You need to remember to clean whichever stages you want to rebuild first.
e.g. to rebuild from the cached bootstrap, chroot packages and build a new image.
$ sudo lh_clean $ sudo lh_build
Q: How do I boot USB debian-live on systems not supporting USB boot?
A: Make a boot CD with grub, configured to boot from a debian-live kernel copied on the cd structure.
$ mkdir -p iso/boot/grub $ cp /usr/lib/grub/i386-pc/stage2_eltorito iso/boot/grub $ cp chroot/boot/* iso/boot/
Create iso/boot/grub/menu.lst
default 0 timeout 5 color cyan/blue white/blue title Debian Live root (cd) kernel /boot/vmlinuz boot=live initrd /boot/initrd.img
Create the iso image
$ mkisofs -R -b boot/grub/stage2_eltorito -no-emul-boot \ -boot-load-size 4 -boot-info-table -o grub.iso iso
Burn the image.
Q: How do I boot debian-live on systems not supporting CDROM or USB boot?
A: If you have a floppy drive, you may be able to use it, otherwise you will need to use loadlin/grub4dos/win32-loader. If you have a second system to serve up the image over the network, See DebianLive/Howto/Creating_a_Netboot_Image. FIXME LINK
Q: The X configuration does not seems to work, the resolution is too low. What can I do?
A: Use xdebconfigurator
$ lh_config --bootappend xdebconf $ lh_config --packages xdebconfigurator
Q: Apache has problems with static files
A: Sendfile does not work well on the unionfs used by Debian Live. Add the following to apache's configuration:
EnableSendfile off
Q: How do I make hard disk partitions auto-mountable?
A: Short answer: Right now the best is to use a script that will populate the fstab when the CD is booting. Such a script can be found FIXME BROKEN LINK . A proper solution based on HAL will be described here in a hopefully near future.
A: Long Answer: Since 55_nonpolkit-mount-policy.patch in HAL, debian-storage-policy-fixed-drives.fdi is not available anymore and the previous trick that consisted to remove this file to enable automounting of fixed drives as a consequence is obsolete.
Eventually, it will be possible to combine HAL and PolicyKit to enable different permissions and actions to achieve advanced (auto)mounting for non-root users. Until then, because the live scripts are only touching to the fstab to add a swap partition if discovered at boot time, the only way to have fixed drives mounted automatically is to use a script that will populate the fstab file at the end of the multiuser runlevel.
To achieve this, you can do, for example, the following:
download the diskmounter.sh script FIXME BROKEN LINK
Create the chroot_local-includes/sbin directory, and move the script inside
Make sure the script is executable (chmod +x diskmounter.sh)
create the chroot_local-includes/etc/rc.local file and call the diskmounter from there (see this rc.local FIXME BROKEN LINK
When called correctly, the script detects ext2, ext3, reiserfs, xfs, FAT32, HFS+ and NTFS partitions and mount them read-write, except for NTFS. This will change soon and an option will be available to use ntfs-3g to mount NTFS as read-write.
comments, patches and other things about this script and issue: http://code.goto10.org/projects/puredyne/ticket/463
Q: Boot fails with panic: can't open /scripts/live
A: Add latest live-initramfs deb package into config/chroot_local-packages directory and rebuild.
Q: How do I configure the locale and the keyboard?
Q: How do I get past boot prompt without a working keyboard?
A: See Section 5.4, “Customising the bootup process” Customising the bootup process
Q: Can I serve the root image from a web or ftp server?
A: Since live-initramfs 1.99, it should be possible to use the fetch= argument on the kernel command line. You can build a netboot image as usual, and when you are done edit the tftpboot/pxelinux.cfg/default file. Remove the references to network boot (netboot, nfsroot, nfsopts), and replace with fetch= 〈url where you placed the root image>.
$ lh_config --packages wget
Q: Why doesn't quickreboot (or some other boot parameter) work?
A: If you are building an etch image (which was the default up to 2007/09/14) you have a very old version of casper which does not support quickreboot and possibly other boot parameters as well. You could configure your sources to use live-backports (see /usr/share/live-helper/examples/sources/live-backports) and switch to live-initramfs, or better yet, build a lenny image instead, which is the new default.
$ lh_config --distribution lenny $ lh_config --initramfs live-initramfs
Q: How do I fix "Could not find kernel image" issue with syslinux bootloader?
A: Add a binary local hook script to fix kernel and initrd path each time you build an image.
e.g. config/binary_local-hooks/01-fix_syslinux.sh
#!/bin/sh SYSLINUXCFG=`find binary -type f -name syslinux.cfg` sed -i "s|kernel /vmlinuz|kernel vmlinuz|g" ${SYSLINUXCFG} sed -i "s|initrd=/initrd|initrd=initrd|g" ${SYSLINUXCFG}
$ chmod +x config/binary_local-hooks/01-fix_syslinux.sh
Q: How do I use a newer kernel with lenny?
A: A build with backports.org kernels will fail as that repository lacks the necessary module packages (linux-modules-extra-2.6, aufs, etc.). Use the kernel backports http://unsupported.debian-maintainers.org/backports-kernel/.
The quick way to success:
$ lh_config --linux-packages 'linux-image-2.6 aufs-modules-2.6 squashfs-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
Q: How do I use a custom kernel?
〉 Is there a nice way of booting debian-live with a custom kernel (not in an apt repo)?
A: Copy it into config/chroot_local-packages and set LH_LINUX_PACKAGES="none" or use lh config --linux-packages " "
Don't forget to compile your kernel with an union filesystem (unionfs or aufs), squashfs modules, and initrd support.
〉 I can cause the kernel to be installed but it seems this happens later than grub/syslinux is configured so it's not listed and casper/ and the menu require munging.
You need to follow the debian scheme, e.g. placing the files in /boot as vmlinuz-$version and initrd.img-$version etc.
I personally wouldn't go that way which is too much of a hassle, and just use make-kpkg to produce custom kernel deb packages. They should integrate nicely if you just put them into config/chroot_local-packages and set LH_LINUX_PACKAGES="".
Hint: to work around an error, which lh_binary_syslinux will throw on custom kernels if there is not an 468/686 in the kernel-name, you need to set CONFIG_LOCALVERSION="-486" or "-686" within the kernel configuration (-> General setup -> Local version set to -486 or -686) corresponding to LH_LINUX_FLAVOURS="" or "686". this at least up till live-helper version 1.0~a40-1
see
http://lists.alioth.debian.org/pipermail/debian-live-devel/2007-July/001947.html
and
http://lists.alioth.debian.org/pipermail/debian-live-devel/2007-November/002581.html
Q: How do I create a cross arch live CD image?
A: In short: You can't. Read on:
The procedure to create a live CD is based on creating a chroot that contains the files that will be finally available on the live CD. The live CD building procedure includes chrooting into the chroot dir and so some operations. chrooting means that the terminal you chroot on will behave as a different system so your real system and the chroot environment is decoupled somehow.
Once the live CD scripts chroots into the chroot dir they have some operations to do inside that environment and your real system won't be able to run them unless you are using the same architecture.
So you only are able to make live CD for the arch you run on. But this doesn't prevent you run qemu or some other machine emulator that make this possible.
Q: When is a lh_clean necessary?
lh_clean is a script in /usr/bin/
A: That depends what you've changed between builds
If, for example, you've built an iso image and you want a usb image, you only need to run lh_clean --binary before you run lh_build again.
If you've changed anything in the chroot , you'll need to cleanup both chroot and binary with lh_clean before continuing
Q: How can i set boot= parameters?
A: Set LH_BOOTAPPEND_LIVE in config/binary
Q: How do I include different modules to load when the live system boots?
A: Configure config/chroot_local-includes/etc/initramfs-tools/
The lh_chroot_hacks helper rebuilds the live/initrd1.img using the default initramfs.conf "MODULES = most". You may override that by supplying your own initramfs.conf, or else just add your own modules, e.g.
mkdir -p config/chroot_local-includes/etc/initramfs-tools/ echo "atl2" >> config/chroot_local-includes/etc/initramfs-tools/modules
Q: Can I have a splash screen?
A: Yes you can
You will not know what is going on when the splash screen is active, it may fail to activate on some hardware or break X on other (both usplash and splashy use libdirectfb which does some evil voodoo and may break you graphics or input until you reboot). However, you can install and activate it just as you would on any other Debian system.
To use splashy:
1) install splashy and read the README, the manpages are useless for setting it up. Add some parameters to your kernel command line, such as in your pxelinux configuration or in LH_BOOTAPPEND_LIVE in config/binary in debian-live configuration:
vga=792 splash quiet
vga to select video mode, splash to activate splashy, quiet to suppress most kernel messages that you cannot see anyway but would scroll past before splashy manages to paint the graphics on your screen.
You might want to add splashy to the list of packages installed in your image:
echo splashy > config/chroot_local-packageslists/splashy echo splashy-themes >> config/chroot_local-packageslists/splashy
and select a theme:
echo '#!/bin/sh' > config/chroot_local-hooks/splashy echo splashy_config -s debian-moreblue '||' true >> config/chroot_local-hooks/splashy # update the ramdisk to include the splash screen echo update-initramfs -u -k all >> config/chroot_local-hooks/splashy chmod 755 config/chroot_local-hooks/splashy
After you rebuild your live system you should observe a bluish splash screen while booting. Nothing happens while initramfs is running because there is no splashy support in initramfs-tools. Once the init starts the progress bar should start to fill.
If vga=something sets a mode that your screen cannot show or your card cannot do vesa 2.0 (and thus you get plain text mode and no splashy) read the splashy faq.
Q: Howto use my Broadcom eXtrem 2 network card (module bnx2) ?
A: Add the firmwares to the initrd image.
You need to install the non-free package "firmware-bnx2". Uncompress your initrd image, then copy files :
cp /lib/firmware/bnx2x-e1-4.8.53.0.fw /lib/firmware/bnx2x-e1-5.0.21.0.fw /lib/firmware/bnx2x-e1h-4.8.53.0.fw /lib/firmware/bnx2x-e1h-5.0.21.0.fw ${INITRD}/lib/firmware/ cp /lib/udev/firmware.agent ${INITRD}/lib/udev/
Recompress your initrd image and boot: it works !
Q: X is broken (the system boots, messages scroll by, and then the screen goes blank). What do I do?
On my system starting X completely disables graphics so that I do not see anything even after X bails out and I am back to the console. To prevent this you can change the driver Xorg uses.
If you have a working splash screen or at least graphical console you can use
live xdriver=fbdev
when booting the live system (instead of just enter).
Another driver you might want to try is vesa.
If all fails you might try to set xdriver to some wrong value so that Xorg fails to start and you can examine the system while you still see something on the console.
live xdriver=none
Q: How can I get Debian first stable versions?
I'm developing software and testing it on Live-CD. Thanks for the LiveCD project. To be sure my development is fully compatible with the "etch" version, I need the same scenario when Debian GNU/Linux 4.0 was published as stable (I believe 2007.04.08). If there was some bug on 2007.04.08 that was corrected one week later, I need to test software foreseeing that scenario without the bug solved.
Q: I get "fopen: Permission denied"-warnings from apt on building/at the live-system
That's a harmless bug in apt. However, if you want to get off this warnings in the live-system, add a file in chroot_local-hooks with follow row:
chown -R man.man /var/cache/man
Q: Why I always fail during "Retrieving Packages" stage when running lh_build? I have already set apt-http-proxy and so on.
A: lh_build retrieves packages via wget, as a result you need to enable the proxy settings in /etc/wgetrc before running lh_build.
Q: How do I edit Xorg.conf?
A: Xorg.conf is generated every time system boots, so it's useless to put modifed Xorg.conf in config/choort_local-includes/etc/X11, because it will be overwritten during boot. However, you can edit /usr/bin/dexconf, which generate xorg.conf during boot, so the result will be modified Xorg.conf. The modified dexconf has to be put in config/choort_local-includes/usr/bin. e.g.: you can configure Xorg.conf for two or more keyboards layouts with alt+shift toggle by editing dexconf and replacing the line:
Option "XkbLayout" "$XKB_LAYOUT"
with the lines:
Option "XkbLayout" "us,il" Option "XkbOptions" "grp:alt_shift_toggle,grp_led:scroll"
when "us,il" are the wanted keyboard layouts.
You can force default screen resulotion (e.g. 1024*768) by adding the lines: .
SubSection "Display" Modes "1024x768" EndSubSection
between the lines:
Section "Screen" Identifier "Default Screen" Monitor "Configured Monitor" . . . . . . . SECTION printf "EndSection\n" 〉 &4
Q: Where are the build parameters for the prebuilt images
Table of Contents
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.
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.
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.
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.
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.
Where does the bug appear?
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.
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.
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.
If a package was successfully installed, but fails while actually running the Live system, this is probably a bug in Debian Live. However,
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.
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.
Table of Contents
Generating a Debian Live CD is very simple. You need to have live-helper (package available in Debian sid and lenny), and Debootstrap (or cdebootstrap) from etch or newer.
apt-get install live-helper
lh_config -b iso -a $ARCH
where $ARCH is the intended architecture (i.e. - i386 or amd64).
-b flag is used to be sure to obtain image in ISO format.
lh_build
The command above will create the basic image, containing just the Debian standard system (with no X at all).
If you want to have any of the Desktop_environments on your livecd, ls /usr/share/live-helper/lists will show a number of available package Lists to choose from, e.g. lh_config -p gnome-desktop
More examples are listed at DebianLive/Examples. FIXME LINK
See Section 5.1, “Customising package installation” for help configuring a local Debian Mirror and other aspects of the live system.
qemu -cdrom binary.iso
If you have also kqemu installed, you can add -kernel-kqemu
Multiple machine boot CDs can be created with the following manual procedure. This procedure has been successfully used to create a single CD which is bootable on alpha, i386, pmax, and sparc. It should be possible to also make the CD bootable on macppc, vax and on sun2, sun3 and sun3x.
To create a CD which is bootable by multiple architectures, use the following steps in this order. Please note that the order is critical.
Make sure you have all the required files including the various kernels and boot programs listed in the individual machine sections.
Include a directory somewhere in the cdsources directory called mdec.pmax and include the pmax bootxx_cd9660 file there. For example, /cdsources/usr/mdec.pmax/bootxx_cd9660.
Include a directory somewhere in the cdsources directory called mdec.vax and include the vax xxboot file there. For example, /cdsources/usr/mdec.vax/xxboot.
Include the macppc ofwboot.xcf bootloader in /cdsources.
Create an i386 bootable image.
sh mkisofs -v -v -o output.iso -b i386/installation/floppy/boot-big.fs \ -c boot.catalog -l -J -r -L /cdsources 2 &1 | tee /tmp/mkisofs.log exit
Run mksunbootcd on a NetBSD/sparc machine to install sparc and sun2/sun3 bootblocks. Alternatively, install the sysutils/mksunbootcd package on your favorite NetBSD machine.
mksunbootcd output.iso boot-sun4.fs boot-sun4c.fs boot-sun4m.fs boot-sun3.fs
Run the installboot(8) program targeted for NetBSD/pmax to install the pmax bootblocks. Note that in order to coexist with other NetBSD boot blocks, the pmax boot block is appended to the end of the ISO file system.
installboot -m pmax -v -o append,sunsum output.iso /tmp/mdec.pmax/bootxx_cd9660
The -o append,sunsum option appends the first stage boot block to the end of the ISO file system, and restores the checksum used when booting on a sun.
Run the installboot(8) program targeted for NetBSD/vax to install the vax bootblocks. Note that in order to coexist with other NetBSD boot blocks, the vax boot block is appended to the end of the ISO file system.
installboot -m vax -v -o append,sunsum output.iso /tmp/mdec.vax/xxboot
(See the pmax entry above for an explanation of the flags).
Run the installboot(8) program targeted for NetBSD/alpha to install the alpha bootblocks.
installboot -m alpha -v -o append,sunsum output.iso /tmp/mdec.alpha/bootxx_cd9660
Table of Contents
This chapter documents the coding style used in live-helper and (ideally) in live-initramfs.
Bad:
if foo; then bar fi
Good:
if foo then bar fi
Bad:
foo () { bar }
Good:
foo () { bar }
Bad:
FOO=bar
Good:
FOO="bar"
Bad:
if [ -f "${FOO}"/foo/"${BAR}"/bar ] then foobar fi
Good:
if [ -f "${FOO}/foo/${BAR}/bar" ] then foobar fi
Table of Contents
This chapter documents the procedures within the Debian Live project for various tasks that need cooperation with other teams in Debian.
Before commiting releases of a udeb in d-i svn, one has to call:
../../scripts/l10n/output-l10n-changes . -d
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:
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: <http://cdimage.debian.org/cdimage/release/current-live/> 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: <http://lists.debian.org/debian-announce/%release_mail%> It also includes the following Live-specific changes: COPYING debian html Makefile manual VERSION xml xsl [INSERT LIVE-SPECIFIC CHANGE HERE] COPYING debian html Makefile manual VERSION xml xsl [INSERT LIVE-SPECIFIC CHANGE HERE] COPYING debian html Makefile manual VERSION xml xsl [LARGER ISSUES MAY DESERVE THEIR OWN SECTION] URLs ---- Download location of updated images: <http://cdimage.debian.org/cdimage/release/current-live/> Debian Live project homepage: <http://live.debian.net/> The current stable distribution: <http://ftp.debian.org/debian/dists/stable> stable distribution information (release notes, errata etc.): <http://www.debian.org/releases/stable/> Security announcements and information: <http://www.debian.org/security/> 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 <http://live.debian.net/> or alternatively send mail to <debian-live@lists.debian.org>.
Table of Contents
Table of Contents
This chapter is for users to document their use cases with Debian Live.
Create an image with live-helper to boot directly to a VNC server.
Make a build directory:
$ mkdir vncBuild
Move to the build directory:
$ cd vncBuild
Example to config the build directory to include gdm metacity xtightvncviewer:
$ lh config --packages "gdm metacity xtightvncviewer"
Create a folder /etc/skel folder for a custom .xsession for the default user:
$ mkdir -p config/chroot_local-includes/etc/skel
Create the .xsession for the default user:
$ touch config/chroot_local-includes/etc/skel/.xsession
Edit the .xsession file to launch metacity and start xvncviewer with something similar to the below:
#!/bin/sh /usr/bin/metacity & /usr/bin/vncviewer xxx.xxx.xxx.xxx:PORT exit
Build the image:
# lh build
To check on the client
look at /live.log and /netboot.conf
could the image be mounted
To check on the pc that creates the image
was chroot unmounted after build? (it should)
Layout of the config/ directory
binary_debian-installer/
binary_grub/
binary_local-debs/
binary_local-hooks/
binary_local-includes/
binary_local-packageslists/
binary_local-udebs/
binary_rootfs/
binary_syslinux/
chroot_apt/
chroot_local-hooks/
chroot_local-includes/
chroot_local-packages/
(see Section 5.1.4.1, “ Using chroot_local-packages to install custom packages ”)
chroot_local-packageslists/
chroot_local-presed/
chroot_sources/
(see Section 5.1.4.2, “Using an APT repository to install custom packages”)
includes/
templates/
bootstrap
binary
chroot
common
source
Table of Contents
Set image filesystem. (See Appendix A, Configuration layout)
Set image type. (See Appendix A, Configuration layout)
Set apt/aptitude generic indices. (See Appendix A, Configuration layout)
Set boot parameters. (See Appendix A, Configuration layout)
Set boot parameters. (See Appendix A, Configuration layout)
Set bootloader. (See Section 5.4.2, “Bootloaders”)
Set checksums. (See Section 5.4.6, “Cheat codes”)
Control if we build binary images chrooted. (See Appendix A, Configuration layout)
Set debian-installer. (See Section 6.1, “The Debian Installer”)
Set daily images. (See Section 6.1, “The Debian Installer”)
Set encrytion. (See Appendix A, Configuration layout)
Set custom grub splash. (See Section 5.4.3, “Splash screens”)
Set hostname. (See Section 7.2, “Hostname”)
Set iso author. (See Section 5.5.1, “ISO metadata”)
Set iso preparer. (See Section 5.5.1, “ISO metadata”)
Set iso publisher. (See Section 5.5.1, “ISO metadata”)
Set iso volume (max 32 chars). (See Section 5.5.1, “ISO metadata”)
Set jffs2 eraseblock size. (See Appendix A, Configuration layout)
Set memtest. (See Section 5.4.4, “Memtest”)
Set netboot filesystem. (See Appendix A, Configuration layout)
Set nfsopts. (See Appendix A, Configuration layout)
Set netboot server directory. (See Appendix A, Configuration layout)
Set netboot server address. (See Appendix A, Configuration layout)
Set net client cow filesystem. (See Appendix A, Configuration layout)
Set cow mount options. (See Appendix A, Configuration layout)
Set cow directory. (See Appendix A, Configuration layout)
Set cow server. (See Appendix A, Configuration layout)
Set net tarball. (See Appendix A, Configuration layout)
Set custom syslinux splash. (See Section 5.4.3, “Splash screens”)
Set custom syslinux timeout in seconds. (See Section 5.4.2.2, “Syslinux”)
Set custom syslinux configuration file. (See Section 5.4.2.2, “Syslinux”)
Set syslinux menu. (See Section 5.4.2.2, “Syslinux”)
Set text to be used on the menu for live entries. (See Section 5.4.2.2, “Syslinux”)
Set text to be used on the menu for live entries (failsafe ones). (See Section 5.4.2.2, “Syslinux”)
Set text to be used on the menu for memtest entry. (See Section 5.4.2.2, “Syslinux” and Section 5.4.4, “Memtest”)
Set username. (See Section 7.3, “The Live user”)
Select chroot architecture. (See Appendix A, Configuration layout)
Set distribution config directory. (See Appendix A, Configuration layout)
Include packages on base. (See Appendix A, Configuration layout)
Exclude packages on base. (See Appendix A, Configuration layout)
Select flavour to use. (See Appendix A, Configuration layout)
Set distribution keyring. (See Appendix A, Configuration layout)
Select distribution to use. (See Appendix A, Configuration layout)
Set mirror to bootstrap from. (See Section 5.1.1, “Package sources”)
Set mirror to fetch packages from. (See Section 5.1.1, “Package sources”)
Set security mirror to fetch packages from. (See Section 5.1.1, “Package sources”)
Set mirror which ends up in the image. (See Section 5.1.1, “Package sources”)
Set security mirror which ends up in the image. (See Section 5.1.1, “Package sources”)
select section(s) to use. (See Section 5.1.1, “Package sources”)
Set chroot filesystem. (See Appendix A, Configuration layout)
Set union filesystem. (See Appendix A, Configuration layout)
expose root as read only. (See Appendix A, Configuration layout)
Set hook commands. (See Section 5.2.2, “Hooks”)
Set interactive build. (See Appendix A, Configuration layout)
Set keyring packages. (See Appendix A, Configuration layout)
Set language to use. (See Section 7.4, “Language”)
Set kernel flavour to use. (See Section 5.4.1, “Kernel”)
Set kernel packages to use. (See Section 5.4.1, “Kernel”)
Set packages to install. (See Section 5.1.3.1, “The LH_PACKAGES variable”)
Set package list to install. (See Section 5.1.3.2, “Package lists”)
Set tasks to install. (See Section 5.1.3.3, “Tasks”)
enable security updates. (See Section 5.1.1, “Package sources”)
enable symlink convertion. (See Section 5.2.4, “Symlink conversion”)
enable sysvinit. (See Section 5.4.5, “Startup scripts”)
Set package manager. (See Section 5.1.2, “Package installation”)
Set apt/aptitude ftp proxy. (See Section 5.1.2, “Package installation”)
Set apt/aptitude http proxy. (See Section 5.1.2, “Package installation”)
Set apt/aptitude pdiff indices. (See Section 5.1.2, “Package installation”)
Set apt/aptitude pipeline depth. (See Section 5.1.2, “Package installation”)
Set apt/aptitude recommends. (See Section 5.1.2, “Package installation”)
Set apt/aptitude security. (See Section 5.1.2, “Package installation”)
Set bootstrap program. (See Appendix A, Configuration layout)
control cache. (See Appendix A, Configuration layout)
control if downloaded package indices should be cached. (See Appendix A, Configuration layout)
control if downloaded packages files should be cached. (See Appendix A, Configuration layout)
control if completed stages should be cached. (See Appendix A, Configuration layout)
Set debconf(1) frontend to use. (See Appendix A, Configuration layout)
Set debconf(1) warnings. (See Appendix A, Configuration layout)
Set debconf(1) priority to use. (See Appendix A, Configuration layout)
Set initramfs hook. (See Appendix A, Configuration layout)
Set fdisk program. (See Appendix A, Configuration layout)
Set losetup program. (See Appendix A, Configuration layout)
Set distribution mode. (See Appendix A, Configuration layout)
use sudo or equivalent. (See Appendix A, Configuration layout)
use fakeroot/fakechroot. (See Appendix A, Configuration layout)
Set tasksel program. (See Section 5.1.3.3, “Tasks”)
Set includes. (See Appendix A, Configuration layout)
Set templates. (See Appendix A, Configuration layout)
enable breakpoints. (See Appendix A, Configuration layout)
enable debug. (See Appendix A, Configuration layout)
enable force. (See Appendix A, Configuration layout)
enable quiet. (See Appendix A, Configuration layout)
enable verbose. (See Appendix A, Configuration layout)
Set source option. (See Appendix A, Configuration layout)
Set image type. (See Appendix A, Configuration layout)