%META:TOPICINFO{author="WoRohrmoser" date="1148271331" format="1.0" version="1.3"}%
%META:TOPICPARENT{name="TWikiGuestLeftBar"}%

---+ LiveBackup Documentation

%TOC%

---++ Introduction

This document is under development.


---++ Installation

---+++ Prequisites

---++ Basic Configuration

---+++ Boot Screen Menu

---++ Creating a LiveBackup

---++ Create the system image

---++ Configure the initial ramdisk

---+++ Binaries inside initrd

*busybox*

modify Rules.mak

CROSS=i386-uclibc-linux-

make menuconfig
make


*unionctrl*

in Makefile set:

CC      = i386-uclibc-linux-gcc

make unionctl
 

---++ Create and burn the ISO image

---+++ Selecting the proper Boot-Loader
     
In a perfect world all software would run without any
limitations. Unfortunately this is not true especially for the grub
boot-loader. I would recommend to give grub the first try. If it works
for you, then you are lucky to use a state-of-the-art and feature rich
software. 

If it fails, or you want to support as many different hardware as
possible then you should use isolinux. Known issues are 

   * grub fails on some CDROM drives
   * grub fails to boot on amd64 architecture (at least in my case) 
  
Selection of the bootloader will be done by the environment variable
BOOTLOADER which can have the values "grub" or "isolinux". Just define
it as any other Setting inside the config/<system>.cfg file.

If you use isolinux there are some restrictions:

   * your kernel/initrd name length is limited and the kernel-file 
     must be located in the isolinux subdirectory. Use something like
     linux32 instead of vmlinuz-2.6.17.14-lb-i386. Example

<verbatim>
    # ls -l master/boot/
    vmlinuz-2.6.17.14-lb-i386 -> isolinux/linux32
    initrd-2.6.17.14-lb-i386 -> initrd32
</verbatim>

---++ How to add linux kernels to boot the !LiveSystem

Before you start there are a few things to consider:

   * if you use an overlay filesystem (i.e. unionfs or aufs) the kernel needs
     support for it. If you cannot get this to work - maybe you have
     an older kernel version - there still is the option to use
     the copy-to-ramfs technique.
   * the recommended way to compress your system backup is to use the
     squashfs project. Your kernel needs support for it. LiveBackup
     also offers you options like:
      * cloop block device compression
      * mounting the filesystem over nfs
      * use a simple file-copy of the root-filesystem
      * or any other trick to access a root-filesystem, this can be
        implemented by defining a proper lb_xcmd boot option.
  
Now after you decided which way to go, inclusion of a kernel is
straigth forward.

   * copy the kernel image (and system-map file) to $MASTER_DIR/boot
   * if the kernel modules are NOT inside your backup-image copy them
     to $MASTER_DIR/lib/modules/<kernel-version>
   * adjust the boot-loader configuration,
     i.e. $MASTER_DIR/boot/grub/menu.lst if you use GRUB
   
To create the initial ramdisk you need a configuration entry like:

<verbatim>
        INITRDKCONF=( '|' '<root-directory>' \
            '<kernel-version>' \
            '<kernel-module1>' '<kernel-module2>' ...  )
</verbatim>

The Skript =make_initrd= assumes to find kernel modules at the common
place which is according to FHS: 

<verbatim>
    <root-directory>/lib/modules/<kernel-version>
</verbatim>

Make sure to include all kernel-modules which are neccessary to mount
the root-filesystem during system-start. You need not to worry about
dependencies. Module dependencies are handled by the script
=make_initrd= which used depmod for this task. The example

<verbatim>
        INITRDKCONF=( '|' '/' \
            '2.6.20.16-custom' \
            'loop' 'squashfs' 'unionfs' )
</verbatim>

will use the kernel with version =2.6.20.16-custom= which is installed
on the current running system. 
  



---++ Testing and Debugging

---+++ Qemu

---++++ USB devices
to use usb devices run qemu with sudo


*  -usb -usbdevice host:xxxx:xxxx
*  qemu-monitor:  usb_add host:xxxx:xxxx

xxxx.xxxx is the usb address, see dmesg or lsusb 

---++++ Create a hard disk image to boot with qemu

  # fdisk -l /dev/loop0  => C,H,S
  # grub --device-map=/dev/null

  grub> device (hd0,0) /dev/loop0
  grub> device (hd0) /dev/loop0
  grub> geometry (hd0) <C>  <H>  <S>
  grub> root (hd0,0)
  grub> setup (hd0)
  grub> quit


---++++ Start a LiveBackup with qemu without graphics 


Prequisites:

  When the system has booted it must permit you to login on a serial console.
  You may check the /etc/inittab file and add a line:

    2:2345:respawn:/sbin/getty 38400 ttyS0

  It is recommended to use the LiveBackup configuration features, i.e.
  copy the inittab file into <master>/config/<your-system-name>/etc and
  make the changes there.  


---++++ Create an ext2 harddisk image from master directory

qemu requires a harddisk image to run with the nographics option.
LiveBackup keeps all files already in the master directory. Therefore to
create a file containing the image is staight forward.

   # name of the hardisk image file
   hda_img=/tmp/lb.ext2

   # this example creates an image of 700M 
   qemu-img create $hda_image  700M

   loopdev=$(losetup -f)
   losetup $loopdev $hda_image
   # ext2 filesystem is a good choice
   mke2fs $loopdev
   mount $loopdev /mnt
   # copy everything from master directory
   rsync -a master/* /mnt/
   # cleanup
   umount /mnt
   losetup -d $loopdev

*Starting qemu* 

qemu redirects the serial port to stdio. 

Options:

       console=ttyS0          redirect all kernel messages
       lb_console=/dev/ttyS0  write output of LiveBackup initrd scripts to 
                              serial console


<verbatim>
# if you want to avoid to many disk access, use the filesystem tmpfs
# and make vl use it for its temporary memory file:
# export QEMU_TMPDIR=/tmpfsdir
#
# if you don't want to modify the image, you can use the option
# '-snapshot'.

qemu -nographic -hda $hda_image \
     -kernel master/boot/<kernel-image> \
     -initrd master/boot/<initrd> \
     -append "console=ttyS0 lb_console=/dev/ttyS0 acpi=off lb_system=<system>"
</verbatim>




---+++ Boot options (cheatcodes)

---++ Configuring your live system

---++ Advanced Configuration Options

---+++ Supporting for different system images on one LiveCD

---+++ Beautifying Appearence

 boot logo, kernel boot splash screen, graphical login manager
 
---++++ grub bootsplash

convert -resize 640x480 skole.png splash.jpg
convert -colors 8 -depth 4  splash.jpg splash.xpm
gzip -9 splash.xpm

# => use splash.xpm.gz with grub (menu.lst)


---++++ isolinux bootsplash

  isolinux will display a boot screen according to master/boot/isolinux/isolinux.cfg
   The file boot.msg displays a splash picture. It
   is encoded in a special format. For replacing it, grab a new image
   and convert it.

     > convert -colors 16 -depth 4 -geometry 640x480! splash.xpm splash.ppm
     > ppmtolss16 < splash.ppm > splash.rle

   to verify the conversion:

     > lss16toppm < splash.rle > testme.ppm; display testme.ppm


---++ Using other boot devices

---+++ USB Memory Stick

example:
<verbatim>
# fdisk -l /dev/sda

Disk /dev/sda: 262 MB, 262144000 bytes
255 heads, 63 sectors/track, 31 cylinders
Units = cylinders of 16065 * 512 = 8225280 bytes

   Device Boot      Start         End      Blocks   Id  System
/dev/sda1               1           5       33008    6  FAT16
/dev/sda2   *           6          31      208845   83  Linux
</verbatim>

you can use parted to modify and create partitions.

<verbatim>
mount /dev/sda2 /mnt

# copy all neccassary files from master to usb memory stick
rsync -a --progress  --delete master/ /mnt

# install grub into MBR
grub-install --root-directory=/mnt /dev/sda
</verbatim>

You have to edit the grub boot menu configuration file
/mnt/boot/grub/menu.lst.


<verbatim>
title           memory test
root            (hd0,1)
kernel          /boot/memtest.img
boot
</verbatim>


---+++ Booting over Network

You can use LiveBackup for diskless client configuration by providing
the LiveBackup root directory (master directory) over network. If the
system-size is less than 50 percent of available RAM it is recommended
to use the wget feature to copy the LiveBackup into client memory and run
it there. If you have less memory available you can use NFS to mount
the LiveBackup root directory over network.


Basic procedure:

1. Client boot-loader configures NIC hardware. You are free to use any 
   technologie you are used to. It was testet with grub. More NIC hardware
   is currently supported by http://www.etherboot.org project. With proper 
   DHCP/PXE configuration 
   
2. Include NIC hardware support for your kernel in the LiveBackup initrd.
   Use cramfs as filesystem for initrd. 

3. Create initrd by make_initrd.sh. Copy initrd and kernel to be accessable
   by a tftp-Server.
   
4. Make your LiveBackup master directory accessable via wget. You can
   choose any ftp or http Server.

5. Use proper kernel boot options to configure your network and get
   access to the LiveBackup master directory.

---++++ Configure a DHCP SERVER for PXE-boot

=apt-get install dhcp3-server= configured by =/etc/dhcp3/dhcpd.conf=

<verbatim>
#
# configuration file for ISC dhcpd for PXE boot
#
#

ddns-update-style none;

option domain-name "mydomain.de ";
option domain-name-servers 208.67.222.222, 208.67.220.220;

default-lease-time 600;
max-lease-time 7200;

allow booting;
allow bootp;

log-facility local7;

subnet 192.168.2.0 netmask 255.255.255.0 {
  range 192.168.2.60 192.168.2.70;
  next-server 192.168.2.80;
  filename "pxelinux.0";
}

</verbatim>

---++++ Using Grub Bootloader

compile grub with diskless support and enable hardware driver for your NIC,
example suitable for qemu

<verbatim>
configure --enable-diskless --enable-ns8390
</verbatim>

make necessary grub-stage2 modules available on your client. You probably need:

<verbatim>
-- boot
   `-- grub
       |-- about.msg
       |-- help.msg
       |-- menu.lst
       |-- nbgrub
       |-- pxegrub
       |-- splash.xpm.gz
       |-- stage2_eltorito
</verbatim>

Example for a =menu.lst=  grub configuration:

<verbatim>
title           LiveBackup Network Boot
ifconfig        --address=10.123.56.113  --server=10.123.64.75 --mask=255.255.0.0 --gateway=10.123.8.1
root            (nd)
kernel          /vmlinuz-2.6.20.4-lb-i386 lb_address=10.123.56.113 lb_netmask=255.255.0.0 lb_gateway=10.123.8.1 lb_system=BaCkUp lb_wget=-r%-l%20%ftp://10.123.64.75/pub/LiveBackup lb_mastersize=700M lb_system=BaCkUp
initrd          /initrd-2.6.20.4-lb-i386
boot
</verbatim>

---++ Maintaining a collection of LiveBackup's from several machines

---++ Hardware Detection

master/config/IBMT60/etc/rcS.d/S00LiveBackup:

#
# this example shows how you could use additional
# boot options
#
if [ "$(grep x11config /proc/cmdline)" ]; then
    if [ "$(which dpkg-reconfigure)" ]; then
        if [ "$(dpkg -l xserver-xorg | grep ^ii)" ]; then
            dpkg-reconfigure -pcritical xserver-xorg
        fi
    fi
fi


---++ How the provided generic Linux Kernel was build

On a Debian/GNU Linux system:

1. build a generic linux kernel. Start always with vanilla kernel and apply the patches  

      get kernel sources and latest patch from http://kernel.org

      cd <LiveBackup>/source/kernel
      tar xjf linux-2.6.20.tar.bz2

      patch -p1 <  patch-2.6.20.18

      recommended: get a version of squashfs matching to your kernel
        patch -p1 < squashfs3.2-r2/linux-2.6.20/squashfs3.0-patch

      get a version of unionfs matching to your kernel
        (http://www.am-utils.org/project-unionfs.html)

      zcat unionfs-2.1.2_for_2.6.20.16.diff.gz | patch -p1

      get bootsplash from:  http://www.bootsplash.org/Downloads
      patch -p1 < bootsplash-3.1.6-2.6.20.diff 

      select default config (generic or minimal kernel)
      cp master/config-2.6.16.14-lb-i386 .config
            oder
      cp master/config-2.6.16.14-lbm-i386 .config

     
      make oldconfig
      make xconfig

      make-kpkg --revision "070830" --append-to-version "-lb-i386" kernel_image

      export KVERSION=2.6.20.18-lb-i386

2. install kernel package in a (non system) directory tree 

      dpkg -x kernel-image-$KVERSION_<revision>_i386.deb <master-example>

   add additional modules if necessary, e.i. aufs

    make -f local.mk clean
    make KDIR=<LiveBackup>/linux-$KVERSION/ -f local.mk
    cp aufs.ko <master-example>/lib/modules/$KVERSION/kernel/fs/unionfs/

3.  build kernel package with make_distrib.sh


---++ Advanced Topics

---+++ Splitting LiveBackups into several images

   System + User data

   encrypt User Data image with aespipe:

       works with loop-AES compatible filesystems, ext2, ext3
       not possible with squashfs

       


---++ Searching other places for backup images

---++ Using LiveBackup for Remastering

mount the iso:

> mount -o loop <image.iso> /mnt

search the cloop image

---+++ Build a minimal Debian based LiveCD

debootstrap etch ./DebianEtch.chroot  http://ftp.debian.org/debian/

cp /etc/apt/sources.list ./DebianEtch.chroot/etc/apt/

chroot ./DebianEtch.chroot

apt-get update
apt-get dist-upgrade

---++ Converting a Redhat OLPC image into a !LiveCD

this example is a proof of concept

decide which kernel to use:

does the supplied olpc-kernel support any compressed filesystem (squashfs, cloop,..) ?
if not you may try ext3img + copy2ram   

---+++ Configuration file

---+++ Prepare the master directory

<verbatim>
mkdir $MASTER_DIR/lib/modules
cp -a $BACKUP_FS_ROOT/lib/modules/*   $MASTER_DIR/lib/modules/
</verbatim>

---++ Success Stories

   * Debian on Medion desktop
   * Debian on Samsung X10plus notebook
   * Skolelinux ( http://www.skolelinux.de )
   * Fedora2
   * Ubuntu 6.06
   * Debian/GNU linux on amd64 architecture


---++ Links

   * you find a long list of LiveCD's on http://www.frozentech.com/
   * good concepts are also used in http://www.morphix.org/
   * LinuxLive (http://www.linux-live.org) is a distribution which
     also provides scripts to create your own live system from a running
     distribution

