From Gentoo Linux Wiki

[edit] Introduction

I've written this how-to after trying to find a boot medium for my home Gateway machine which could be used for system rescues and even installing Gentoo. Why not use the standard Gentoo Live CD you ask? Well my Gateway machine is one of those small, silent and cool running mini-itx machines (www.mini-itx.com) and has no CDROM or floppy drive. I needed some way of getting Gentoo on there and some way of easily rescuing it when the need arises. The good news is that these VIA mini-itx machines are USB bootable and I much preferred the idea of having a little USB drive/stick that I could push into any USB bootable machine and boot into Linux rather than having to set up a PXE networked boot environment (which is also supported).

So I purchased a 64Meg PQI USB stick from www.ebuyer.com for about 15 quid and had a go at generating the equivalent of Gentoo LiveCD to work from a USB drive. During my research I found that there was not really any documentation on re-building the Gentoo LiveCD in general (eg. to add uncommon hard-drive and network driver support, etc), so this is also a how-to on re-building the normal Live CD too. The output of this procedure yields an installation which can be used for both Gentoo Live CDs and USB sticks.

[edit] Purpose

This Howto describes how to put the LiveCD onto a USB stick.

[edit] Scope

[edit] Acronyms

USB = Universal Serial Bus

[edit] References

[edit] Creating LiveCD

Use an existing Gentoo Linux machine and insert your USB stick into it (the USB drive must be at least 28Meg in size and needs to support USB booting). If you intend to also put the Gentoo stage1 bz2 archive on there too, for installations, you will need an additional 12 Meg. The alternative is to just use 'wget' to retrieve the stage1 archive from a Gentoo mirror once you've booted the Gentoo Live USB stick.

[edit] Catalyst method

HOWTO build a LiveCD with Catalyst

[edit] livecd-ng method (obsolete)

The livecd-ng is no longer supported. Catalyst is the preferred method now.

[edit] Emerge livecd-ng

• First emerge the livecd-ng ebuild package, which, I believe, is used to create the normal LiveCD. You can unmask it with:

$ echo "app-admin/livecd-ng" >> /etc/portage/package.keywords
$ echo "app-admin/livecd-ng" >> /etc/portage/package.unmask

This installs a LiveCD ISO creation script at /usr/sbin/livecd-ng. In addition, a new directory called livecd-ng is created in /etc which will be used to create and store the profile of the type of livecd you wish to create. This contains a profile called gentoo-basic by default which will be used and customised..

[edit] Settings

Change some of the settings specified in this profile to:

1. Use the correct Gentoo mirror
2. Ensure the LiveCD loads the relevant USB modules on boot-up
3. Specify the custom Kernel config file to be used.

## change the CD_STAGETARBALL line to:
## or anothner stage ARCH CD_STAGETARBALL line to:
CD_STAGETARBALL=http://distro.ibiblio.org/pub/linux/distributions/gentoo/releases/2005.0/x86/x86/stages/stage3-pentium3-2005.0.tar.bz2

## This tarball seem to be obsolete.
##CD_STAGETARBALL=http://distro.ibiblio.org/pub/linux/distributions/gentoo/releases/1.4_rc4/x86/x86/stages/stage3-x86-1.4_rc4.tar.bz2
CD_STAGETARBALL=http://distro.ibiblio.org/pub/linux/distributions/gentoo/releases/x86/2005.1-r1/stages/x86/stage3-x86-2005.1-r1.tar.bz2

## add the following usb modules to the START of the STORAGE_MODULES variable
usbcore usb-uhci uhci usb-ohci usb-storage

## change the KERNCONFIG config file name to the following:
KERNCONFIG=kernel-config-2.4-latest

## Edit CD_PORTAGE_PROFILE to
CD_PORTAGE_PROFILE="default-linux"

[edit] MOTD

• Change the boot message to Welcome to the Gentoo Live USB stick in addition to the Live CD.

Welcome to the Gentoo Linux LiveUSBstick!

[edit] Customize Kernel Config

• Copy an existing Kernel config file and customise it to include all the relevant USB modules and to also include support for VFAT filesystems (used as the filesystem on most USB drives).

$ cp kernel-config-2.4.20_pre4-pcmcia kernel-config-2.4-latest
$ nano -w kernel-config-2.4-latest

(set the following parameters in the 'File Systems' section)
   CONFIG_FAT_FS=y
   CONFIG_MSDOS_FS=y
   CONFIG_VFAT_FS=y

(set the following parameters in the 'USB Support' section)
   CONFIG_USB=m
   CONFIG_USB_DEVICEFS=y
   # CONFIG_USB_EHCI_HCD is not set
   CONFIG_USB_UHCI=m
   CONFIG_USB_UHCI_ALT=m
   CONFIG_USB_OHCI=m
   CONFIG_USB_STORAGE=m

## And add support PPP in the 'Ethernet (1000 Mbit)' section)
CONFIG_PPP=y
CONFIG_PPP_MULTILINK=y
CONFIG_PPP_FILTER=y
CONFIG_PPP_ASYNC=y
CONFIG_PPP_SYNC_TTY=y
CONFIG_PPP_DEFLATE=y
CONFIG_PPP_BSDCOMP=y

[edit] stage1-experimental

• Modify the file stating which masked ebuilds should be included in the LiveCD. Note: We are going to use the latest gentoo-sources kernel instead and partimage is no longer a masked package.

$ nano -w stage1-experimental

(REMOVE the following TWO entries:)
     =sys-kernel/xfs-sources-2.4.20_pre4
     sys-apps/partimage

[edit] stage1-packages

• Modify the file stating the standard ebuilds to include the latest 2.4 Gentoo kernel and the partimage utility.

$ nano -w stage1-packages

sys-kernel/gentoo-sources
sys-block/partimage

[edit] stage2-packages

• Edit stage2-packages for 2.6 kernels
• comment these lines:

1. net-misc/nforce-net
2. linux-wlan-ng

[edit] Make the packages available

• Make sure all the necessary packages are on your box.

$ < stage1-packages xargs -tn1 emerge -Df
$ < stage2-packages xargs -tn1 emerge -Df

[edit] linuxrc

• The init script used by the LiveCD image on bootup is called linuxrc. This needs to be modified to add support for booting from the USB drive as well as CDROMs.

$  nano -w /etc/livecd-ng/profiles/global/linuxrc

findusbmount() { 
  if mount -t vfat -r /dev/sda1 /newroot/mnt/cdrom; then 
    if [ ! -e /newroot/mnt/cdrom/livecd.cloop -a ! -e /newroot/mnt/cdrom/livecd.loop ]; then 
      echo -e "${HILITE}---- /dev/sda1 is not a LiveUSBStick; skipping...${NORMAL}" 
      umount /newroot/mnt/cdrom 
    else 
      mounted=/dev/sda1 
      echo -e "${HILITE}---- USB medium found on /dev/sda1${NORMAL}" 
    fi 
  fi 
} 

initmsg "---- Mounting the CD" 
findmount /newroot/dev/cdroms/* 

initmsg "---- Mounting the USB/CD" 
findusbmount 
if [ ! "$mounted" ]; then 
  findmount /newroot/dev/cdroms/* 
fi

[edit] Emerge CCache

• Emerge CCache. The livecd-ng script assumes you have ccache installed. For some reason the the ebuild script for livecd-ng is broken and does not include this.

$ emerge ccache
$ ccache -M 2G

[edit] Environment

Before running the livecd-ng script to generate the ISO image, users have to specify some environment information in a special file in the user's home directory (ie. root).

This includes information on the location of the existing system's portage tree plus a temporary location to build the image and download the stage1 bootstrap archive.

This probably requires up to 1 Gig of temporary space. I had the most space left in my /opt partition so in my case this is the location I used.

$  nano -w ~/.livecd-ng

CD_DISTDIR=/usr/portage/distfiles
CD_PORTDIR=/usr/portage
CD_TEMPROOT=/opt/tmp
CD_STAGELOC=/opt/download

[edit] Emerge missing packages

• For some reason the livecd-ng ebuild seems to be broken and misses out some required packages for generating the LiveCD image. Syslinux, Busybox and cloop are accessible as ebuilds.

$ mkdir /etc/livecd-ng/archives
$ emerge syslinux
$ cp /usr/lib/syslinux/isolinux.bin /etc/livecd-ng/archives/
$ emerge -f busybox
$ cp /usr/portage/distfiles/busybox-1.01.tar.bz2 /etc/livecd-ng/archives/
$ emerge -f cloop
$ cp /usr/portage/distfiles/cloop_2.02-1.tar.gz /etc/livecd-ng/archives/

[edit] livecd-ng

• In addition to not including the above utilities, the versions/archive-formats of these are not what is expected by the livecd-ng script, therefore some settings in this script need to be changed.

$ nano -w /usr/sbin/livecd-ng

BUSYBOX_TARBALL=busybox-1.01.tar.bz2
BUSYBOX_DIR=busybox-1.01

CLOOP_TARBALL=cloop_2.02-1.tar.gz
CLOOP_DIR=cloop-2.02.1

cp ${CD_BUILDTEMP}/${CLOOP_DIR}/cloop.o ${CD_BUILDCHROOT}-initrd/modules/cloop.o || chroot_die "can't find ucl cloop module"

< ${LOOP_FILE} ${CD_BUILDTEMP}/${CLOOP_DIR}/create_compressed_fs - 131072 > ${CLOOP_FILE} || chroot_die

• In function mount_all) add next string in first line:

$ mkdir $CD_BUILDCHROOT/usr/portage

• And chroot_generate() :

ln -s /usr/portage/profiles/${CD_PORTAGE_PROFILE} ${CD_BUILDCHROOT}/etc/make.profile

• Then, edit your /usr/portage/profiles/default-linux/make.defaults:

ARCH="x86"
ACCEPT_KEYWORDS="x86"

[edit] Create the temporary directories

• Create the temporary directories for building the ISO image.

$ mkdir -p /opt/tmp/gentoo-basic
$ mkdir /opt/download

[edit] Prep for generation

• Move to the root of the livecd profile ready to run the ISO generation scripts.

$ cd /etc/livecd-ng

Note: More help on the usage of the livecd-ng script can be found by entering the command livecd-ng -h and the command zcat /usr/share/doc/livecd-ng-1.0/README.gz | less

• Run the script with the gentoo-basic profile to download all the required packages to be used in the ISO image.

$ livecd-ng gentoo-basic fetch

• Build all the packages (including the kernel)

$ livecd-ng gentoo-basic build

Note: You will be prompted whether to include each kernel module which does not exist in the kernel config file created earlier. Once the build has finished it is worthwhile copying the modified kernel config file from /opt/tmp/gentoo-basic/cdroot/usr/src/linux/.config and overwriting /etc/livecd-ng/profiles/gentoo-basic/kernel-config-2.4-latest. If you want to modify the kernel again and rebuild it, you can then just alter 'kernel-config-2.4-latest' and then run 'livecd-ng kernbuild'.

• Create the complete initrd root environment for the ISO image.

$ livecd-ng gentoo-basic initrd

• Clean out any extraneous files which should not be included in the ISO image.

$ livecd-ng gentoo-basic clean

• Create the compressed loop image.

$ livecd-ng gentoo-basic cloop

• Create the ISO image for the livecd

$ livecd-ng gentoo-basic isogen

• Undo any temporary chroot environments used by the script.

$ livecd-ng gentoo-basic umount

• You now have a CD bootable Gentoo LiveCD ISO image ready to be burnt onto a CD using your favourite CD burning software. This image will be located at:

/opt/tmp/gentoo-basic/livecd.iso

[edit] Copy LiveCd method

:)

[edit] Open issues

[edit] Add support for USB to the kernel (NEW)

until this is done I add doscsi to the boot options. (for 2005.1) i.e. boot: gentoo doscsi

[edit] Create the the LiveUSB stick (NEW)

Process from Create the bootable USB-stick.

Download your livecd image. Recommended choices are the 2008 versions of minimal gentoo livecd and the (full) gentoo installer livecd.

• zero your USB stick

dd if=/dev/zero of=/dev/sda bs=512 count=1

• Create a partition

 fdisk /dev/sda

n # create new partition
p # primary
1 # first
# press enter to accept the default value for the beginning of the partition
# press enter to accept the default value for the end of the partition
w # Write the new partition table and exit.

• Format and mount the stick

 mke2fs /dev/sda1
 mount /dev/sda1 /mnt/gentoo

• Mount your livecd iso image and copy its files to the stick

 mkdir /mnt/loop0
 mount your_livecd_image.iso /mnt/loop0 -o loop
 rsync -avH /mnt/loop0/ /mnt/gentoo/

• A Gentoo livecd only contains the stage2_eltorito file, which is the one needed to boot from a cd. Copy other grub stage files to the stick. Make sure your system's boot partition (if you have one) is mounted on /boot.

 cp -av /boot/grub/*stage* /mnt/gentoo/boot/grub/
 umount /mnt/gentoo

• Put grub on the stick

 grub

(Make sure that hd1 is in fact your USB stick, hd0 is your primary disk).

 root (hd1,0)
 setup (hd1)
 quit

Done!

[edit] Creating LiveUSBstick

The official guide to create LiveUSB is at http://www.gentoo.org/doc/en/liveusb.xml

These are the last few steps to produce a bootable USB drive in addition to the CD:

• Check that the usb drive is inserted into the machine but is NOT mounted

• Install the Gentoo package for creating VFAT filesystems

$ emerge dosfstools

• Install the packages for syslinux

emerge  syslinux

[edit] Prepare the USB stick

• Erasing the usb stick. This may take a few minutes (ignore the warning at end).

There are two possible ways to do this:

[edit] Simply format the drive

mkdosfs -F 16 /dev/sda1 (if the USB disk is < 4 GB)
mkdosfs -F 32 /dev/sda1 (if the USB disk is > 4 GB)

[edit] Layman method

$ dd if=/dev/zero of=/dev/sda1

• Write a MBR-record to the USB stick.

(Use the whole disk as target for dd NOT the partition!) (Make sure you have sys-boot/syslinux-3.00 or later installed)

$ dd if=/usr/lib/syslinux/mbr.bin of=/dev/sda

• Format the usb drive with a VFAT filesystem. The mkfs.vfat-program is in the dosfstools -package.

$ mkfs.vfat /dev/sda1

• Mount the USB stick

$ mkdir /mnt/usbstick
$ mount -t vfat /dev/sda1 /mnt/usbstick

[edit] Copy data to USB stick

[edit] livecd-ng method

• Copy the generated LiveCD boot files which were used in the ISO to the root of the USB drive.

$ cp /opt/tmp/gentoo-basic/isoroot/livecd.cloop /mnt/usbstick/
$ cp /opt/tmp/gentoo-basic/isoroot/isolinux/* /mnt/usbstick

• Make a copy of the ISO Syslinux bootloader configuration file to the name required by Syslinux for floppy/usb booting.

$ cp /opt/tmp/gentoo-basic/isoroot/isolinux/isolinux.cfg /mnt/usbstick/syslinux.cfg

Note: You may also want to include an extra directory called 'gentoo' at the root of the USB drive and copy the Gentoo stage 1 bz2 archive from a Gentoo mirror, into there.

[edit] LiveCD copy method

• Copy the release to the USB stick

cd /opt/usb_live
find . | cpio -pdm /mnt/usbstick

[edit] Finalize the USB stick

• Unmount usb stick and then run the Syslinux utility to make the USB stick bootable. (there is a bug in the older versions syslinux that does not seems to work, try the latest version, syslinux-3.71 works OK for me. )

$ umount /mnt/usbstick
$ syslinux /dev/sda1

You now have a bootable Gentoo LiveUSB stick!!!

• Remove the usbstick, and push it into the usb port of the target machine to be booted into Gentoo. Configure the BIOS of the target machine to boot from USB before the hard drive and then boot the machine.

[edit] Backup the USB stick (Partition-method)

• To make a back-up copy of the USB stick image you can use a command like the following (Partition only):

$ dd if=/dev/sda1 of=~/gentoousb.img

Then whenever you need to restore your USB stick to the Gentoo Live image you built, you can run a command like the following:

$ dd if=~/gentoousb.img of=/dev/sda1

[edit] Backup the USB stick (Full-Stick-method)

• To make a back-up copy of the USB stick image you can use a command like the following (whole stick with MBR etc.):

$ dd if=/dev/sda of=~/gentoousb_disk.img

Then whenever you need to restore your USB stick to the Gentoo Live image you built, you can run a command like the following:

$ dd if=~/gentoousb_disk.img of=/dev/sda

[edit] Issues etc.

[edit] Notes

As an alternative, Instead of using the livecd-ng package to create a USB bootable Linux device, you could start off with the pre-built LiveCD image provided by Gentoo, mount the iso, modify the linuxrc scripts, add the extra USB modules, copy the contents to the formatted USB stick and then run syslinux to make the device bootable. HowTo Hack My Gentoo Linux Boot CD should provide some good pointers for getting started with this alternative method.

UNetbootin is a GUI-based utility that can create a LiveUSB from a Gentoo 2007.0 or 2008.0 Beta2 ISO file, and can be run from either Windows or Linux.

The command "livecd-ng gentoo-basic enter" can be used to enter the install before making an image. This can be used to add/remove packages (normal emerge available), or to alter settings you want on your livecd (enviroment variables, services started...)

I don't know how feasible it is, but the Gentoo store could sell small USB sticks with the Gentoo Logo on the side and the Gentoo Live install already included. This would make a great way of providing Gentoo with more funds in addition to normal donations and would probably appeal to a lot more people? The USB drive I bought is tiny and fits on a key ring. This means that I've got Gentoo at my fingertips wherever I may be.

The following bugs and enhancement reqests have been added/modified in relation to this howto to make building livecds and usbs easier:

BUG 22155: Sort out the livecd-ng script to use correct versions of BusyBox and Cloop and include Busybox, Cloop and Syslinux in the gentoo-basic example profile. Resolution: Use catalyst.

BUG 21411: Include cloop as a standard ebuild for Gentoo

BUG 22157: Modify the linuxrc script and example basic-gentoo profile to provide support for LiveUSBsticks in addition to the LiveCD. Still Open It will be done for catalyst.

Note: The initial linuxrc script changes I've used in the how-to will need some improvement to cycle through all possible USB devices and may also need to ensure that there is no conflict with existing SCSI devices.

If you have trouble with a message like "Could not find CD to boot, something else needed!" when booting from this pendrive you will have to insert a delay on the /init script inside syslinux/gentoo.igz; to do that:

-> Mount the pendrive:

   mount /dev/sda1 /mnt2

[Edit: 20080330] use :s/TRAILER!!!/notTRAILER/gc with bvi

-> Expand the initrd:

    cd /tmp; mkdir gentoo.initrd; cd gentoo.initrd
    gunzip </mnt2/isolinux/gentoo.igz >../gentoo.i
    bvi ../gentoo.i
         -> Replace all ocurrences of 'TRAILER!!!' for 'notTRAILER',
            *EXCEPT* the LAST one. Use common sense to verify if there isn't any ocurrences
                  that aren't cpio headers (DON'T change these if there are any).
               -> This is needed because the .cpio file that was compressed to produce
                  the original isolinux/gentoo.igz file is actually a concatenation of
                  *many* (I counted 10) different CPIO files; the kernel (and presumably
                  some other version of cpio) can handle this correctly, but mine (debian
                  v. 2.6-5) can't, and silently stops expanding the file on the first
                  'TRAILER!!!' header.
     cpio -idv < ../gentoo.i
         -> Expands the whole initrd tree

[Edit: 20080330] perhaps due to the above cpio irregularity, could not find the init script mentioned below. An actual pathname would be nice. Decided to use http://pages.cs.wisc.edu/~vladimir/install-x86-minimal-2006.0.USB.1G.iso.tar.bz2 instead. It's very easy.

-> Modify the init script:

   -> Just before these lines:

        # Mount sysfs
        mount_sysfs

        # Start udev/devfs
        start_dev_mgr

   -> Add these lines:

       #2005/09/25 Durval Menezes
       #good delay after loading modules, so the system can stabilize
       #(if we don't delay, the start_dev_mgr a few lines below won't
       #find our pendrive's device and the boot will fail
       echo -n "Waiting for loaded drivers to stabilize"
       COUNTER=0
       while [ $COUNTER -lt 5 ]; do
              sleep 1
              echo -n '.'
              let COUNTER=$COUNTER+1
       done
       echo

   -> Recreating the initrd file with the modification above:
       find . | cpio --quiet --dereference -o -H newc | gzip -9 >/mnt2/isolinux/gentoo.igz

   -> Unmount the pendrive:
       umount /mnt2

The above modification should eliminate the "could not find CD to boot" message so the boot will proceed smoothly to the end.

Good Luck!

[edit] See Also

• Original Forum Post
• HOWTO Small Footprint Gentoo on USB
• Catalyst
• Catalyst HowTo
• Pre-made 2006.0 LiveUSB dd image. Unpack and run dd to make a LiveUSB drive

[edit] Version History

[edit] Feedback

Concerns or Compliments? Please use the Discussion section.