Gentoo Wiki


This page is a candidate for deletion 
Reason given: Outdated.
If you disagree with its deletion, please explain why on its discussion page.
If you intend to fix it, please remove this notice, but do not remove this notice from articles that you have created yourself.
Make sure no other pages link here and check the page's history before deleting.
Note: This page is outdated! Catalyst is supposed to be the newer way to make LiveCDs. See also for more up-to-date information.



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 ( 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 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.

Note: This page is outdated! Catalyst is supposed to be the newer way to make LiveCDs


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



USB = Universal Serial Bus


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.

Catalyst method

HOWTO build a LiveCD with Catalyst

livecd-ng method (obsolete)

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

Emerge livecd-ng

$ 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..


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.
File: /etc/livecd-ng/profiles/gentoo-basic/settings
## change the CD_STAGETARBALL line to:
## or anothner stage ARCH CD_STAGETARBALL line to:

## This tarball seem to be obsolete.

## 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:



File: /etc/livecd-ng/profiles/gentoo-basic/motd
Welcome to the Gentoo Linux LiveUSBstick!

Customize Kernel Config

$ cp kernel-config-2.4.20_pre4-pcmcia kernel-config-2.4-latest
$ nano -w kernel-config-2.4-latest
Code: kernel-config-2.4-latest
(set the following parameters in the 'File Systems' section)

(set the following parameters in the 'USB Support' section)
   # CONFIG_USB_EHCI_HCD is not set

## And add support PPP in the 'Ethernet (1000 Mbit)' section)


$ nano -w stage1-experimental
File: stage1-experimental
(REMOVE the following TWO entries:)


$ nano -w stage1-packages
File: stage1-packages

(at the end of the file, add the following two entries)


(Change sys-apps/star to sys-apps/stat )


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

Make the packages available

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


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

(add the following new function directly preceding the existing findmount() function)

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 
      echo -e "${HILITE}---- USB medium found on /dev/sda1${NORMAL}" 

(remove the following lines......)

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

(....and replace with the following)

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

Emerge CCache

$ emerge ccache
$ ccache -M 2G


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
File: ~/.livecd-ng

Emerge missing packages

$ 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/


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

(change the version and location of the source busybox archive)


(change the version and location of the source cloop archive)


(change the move of cloop_ucl.o line to be a move of cloop.o instead)

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

(change use of create_compressed_ucl_fs executable line to use create_compressed_fs instead)

< ${LOOP_FILE} ${CD_BUILDTEMP}/${CLOOP_DIR}/create_compressed_fs - 131072 > ${CLOOP_FILE} || chroot_die
$ mkdir $CD_BUILDCHROOT/usr/portage
ln -s /usr/portage/profiles/${CD_PORTAGE_PROFILE} ${CD_BUILDCHROOT}/etc/make.profile

Create the temporary directories

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

Prep for generation

$ 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

$ livecd-ng gentoo-basic fetch
$ 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'.

$ livecd-ng gentoo-basic initrd
$ livecd-ng gentoo-basic clean
Note: Ignore this warning if it appears: 'No gentoo-basic clean script found; skipping'
$ livecd-ng gentoo-basic cloop
$ livecd-ng gentoo-basic isogen
$ livecd-ng gentoo-basic umount
Note: When burning a CD you may also want to include an extra directory called 'gentoo' at the root of the CD and copy the 3 Gentoo stage bz2 archives from a Gentoo mirror, into there.

Copy LiveCd method


Open issues

ANewDrPepper20050905Describe how to add support for USB to the liveCD
BNewDrPepper20050905Attempt to put the Full install cd onto a 1GB stick

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

Create the the LiveUSB stick (NEW)

Process from Create the bootable USB-stick.

Warning: If you have other SCSI devices in your computer (like SATA drive), make absolutely sure that /dev/sda is actually the USB stick device (or change the shown commands accordingly). If you don't do so, you'll instantly lose all of your hd's content! If you're unsure of what your usb device is called, use dmesg to investigate.

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

dd if=/dev/zero of=/dev/sda bs=512 count=1
 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.
 mke2fs /dev/sda1
 mount /dev/sda1 /mnt/gentoo
 mkdir /mnt/loop0
 mount your_livecd_image.iso /mnt/loop0 -o loop
 rsync -avH /mnt/loop0/ /mnt/gentoo/
 cp -av /boot/grub/*stage* /mnt/gentoo/boot/grub/
 umount /mnt/gentoo

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

 root (hd1,0)
 setup (hd1)


Creating LiveUSBstick

The official guide to create LiveUSB is at

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

Warning: These instructions assume that the usb drive has been allocated to device sda1. If you have a SATA or SCSI hard drive (or other SATA/SCSI device) this usually is not the case so ALTER the device number used below otherwise you will end up blowing away some partitions and/or your hard drive!!
$ emerge dosfstools
emerge  syslinux

Prepare the USB stick

There are two possible ways to do this:

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)

Layman method

Warning: Warning: this command screwed up my USB stick completely. It shouldn't be really necessary to do this anyway. Skip it if you wish
$ dd if=/dev/zero of=/dev/sda1

(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
$ mkfs.vfat /dev/sda1
$ mkdir /mnt/usbstick
$ mount -t vfat /dev/sda1 /mnt/usbstick

Copy data to USB stick

livecd-ng method

$ cp /opt/tmp/gentoo-basic/isoroot/livecd.cloop /mnt/usbstick/
$ cp /opt/tmp/gentoo-basic/isoroot/isolinux/* /mnt/usbstick
$ 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.

LiveCD copy method

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

Finalize the USB stick

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

You now have a bootable Gentoo LiveUSB stick!!!

Backup the USB stick (Partition-method)

$ 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

Backup the USB stick (Full-Stick-method)

$ 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

Issues etc.


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 instead. It's very easy.

-> Modify the init script:

   -> Just before these lines:
        # Mount sysfs

        # Start udev/devfs
   -> 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"
       while [ $COUNTER -lt 5 ]; do
              sleep 1
              echo -n '.'
              let COUNTER=$COUNTER+1
   -> 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!

See Also

Version History

VersionDateEditorVerified byDescription
x.x2005-09-04 DrPepper Changed to support 2005.1


Concerns or Compliments? Please use the Discussion section.

Retrieved from ""

Last modified: Thu, 02 Oct 2008 11:02:00 +0000 Hits: 121,942