Gentoo Wiki


It has been suggested that this article or section be merged into HOWTO build a LiveCD with Catalyst. (Discuss)

This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc

Gentoo Linux official release metatool
Developer: Gentoo Foundation
Package: dev-util/Catalyst
Category: dev-util
License: GPL-2



This article tries to make a livecd with Catalyst 2 by example. Alternative solutions will be mentioned, along with their respective difficulties and advantages. It's indicated only for people using Catalyst for the first time and for people who know nothing more of livecd's other than they magically boot in a working system.

The advantage of these docs over the official ones is that we explain the procedure and we don't assume you understand much other than what is mentioned below. However they are complementary, and you will need to read the official docs later.

What is Catalyst?

Catalyst is the tool used for building Gentoo releases. This includes stage tarballs, minimal CDs, package CDs, universal CDs, and the relatively new LiveCD with X and Gnome.

Keep in mind that if catalyst does not currently work the way you want it to, do not complain to the developers. Catalyst's primary purpose is Gentoo release building, and that's what it's designed to do.


  1. You know how to modify ebuilds, and you know how portage "thinks".
  2. You've installed a gentoo system in the CLI, and you knew what you were doing.
  3. You will read everything carefully, and be aware that some alternative options may not work properly. However we'll try to say that whenever possible.

General picture

You want a livecd ISO? That's what you get in the last stage of our process, called livecd-stage2. Before that we need to go through these steps: stage3 -> livecd-stage1 -> livecd-stage2 -> iso (more on their meaning soon).

Catalyst actually allows you to start from a stage1 (just like the stages you use when installing gentoo). But what we'll do is use gentoo's stage3 and customize from there.

Once you get to know Catalyst, if you really need to start from stage1/2, you'll be ready to do that on your own.

What's this process about?

You start with a minimal collection of tools (stage3), you will add it packages and some configurations (livecd-stage1) and then you will add a kernel, kernel drivers and a some more personalizations (livecd-stage2).

Getting to work

Putting together all the tools

Let's start by emerging Catalyst 2:

# emerge -av catalyst

I recommend you open the following pages in your browser here, here(down?), here and finally here. Look for warnings on the first site about recent changes that I may not have yet addressed in this guide (at this moment I'm using 2.03).

Now, before we start working in catalyst make sure to configure it:

# nano -w /etc/catalyst/catalyst.conf

In case you have storage issues, at least bother to change the $storedir where the building will take place, which may use a few GB (anything with a '$' is a reference to a catalyst variable in the config).

Warning: Don't do like me and create a dir/file called livecd in the root of a disk. This will lead to your livecd's thinking those disks are CDs.

Getting a portage snapshot and a stage 3

Now, first of all we will need a portage snapshot for catalyst. You can use the one you have in /usr/portage by

# catalyst -s snapshot_example

You can use any name in place of snapshot_example. Catalyst will create a $storedir/snapshots/snapshot_example.tar.bz2 with your snapshot. Alternatively, you can download one from a local mirror like in the handbook. Don't close that site just yet, download a stage 3, and put it in $storedir/builds.

  1. If you're using unstable versions of Catalyst, you should be using unstable versions of genkernel. Change the snapshot to unmask genkernel.
Warning: Many people think that they can use a Gentoo stage3 when doing their own builds. You can not. There is a simple rule of thumb used by Gentoo's Release Engineering team: "If the stage wasn't built with the snapshot you're about to use, rebuild the stages." You can get spec files for stage1 thru stage3 from the releng site. You will need to build all three stages starting with stage1.

Doing a livecd-stage1 from a stage3

This is where Catalyst differs from most available live cd tools. It'll do everything automatically, meaning no chroot's or anything like that, so we need to provide catalyst with all the information. It's stored in a .spec file, let's make one:

# nano livecd-stage1_example.spec

On the gentoo sources site you'll find heavily commented spec's, and more outdated ones in

# ls /usr/share/doc/catalyst-2.0.5/examples/

In this directory you will find examples of specs for the different targets Catalyst supports. Our target obviously is the livecd-stage1. To build this target you need a stage 3 and the portage snaphot. Then we will use the livecd-stage1 as a base to our final stage, the livecd-stage2.

I'm going to assume you read its syntax on the examples, or at the very least the commented example below.

File: livecd-stage1_example.spec
#choose any in
subarch: i686
#choose anything you like
version_stamp: 2007.1 
#this is our target
target: livecd-stage1 
# explained later

#choose a profile in /usr/portage/profiles
profile: default-linux/x86/2006.1 
snapshot: snapshot_example
#This is the stage3 you downloaded. Put it in $storedir/builds.
#This is any directory like /etc/portage
#This can be any portage overlay, or comment it if empty.
#Here catalyst will store binary packages it builds by default, to use again

#Careful when inserting too many use flags. These will overrun packages.use.

#Other flags to consider: -* atm branding socks5 livecd djvu dvi -mythtv pdf msn encode -nls gnome truetype gif mmxext flac oss divx gmedia mad -real nsplugin qt3 -qt4 -xmms asf ffmpeg -quicktime aaliv avahi cairo opengl -kde -arts gtk dvd dvdread dvdr a52 X xine xvid win32codecs v4l2 v4l usb sse mp3 msn nvidia ati -lirc jpeg gtk2 hal ieee1394 -cups -doc -3dfx X -accessibility -apache -apache2 -apm bash-completion -berkdb bluetooth -canna crypt -debug -dvb -eds -examples firefox tetex svg -samba -postgres ogg openal opengl mp3 fbcon

livecd/packages: baselayout xorg-x11 ide-smart logrotate passook livecd-tools dhcpcd acpid apmd fxload gpm mt-st syslog-ng parted links dosfstools nfs-utils jfsutils xfsprogs e2fsprogs reiserfsprogs ntfsprogs pwgen app-admin/sudo rp-pppoe screen mirrorselect penggy iputils hwdata-gentoo hwsetup lvm2 evms vim pptpclient mdadm ethtool wireless-tools prism54-firmware wpa_supplicant gentoolkit xchat netscape-flash slocate skype wine gaim tetex mozilla-firefox totem ufed mplayer gnome abiword mathematica-fonts unrar unzip cpuburn cdrtools gnupg gftp mplayerplug-in module-init-tools pciutils usbutils strace hdparm nano less openssh popt dialog device-mapper gpart tcptraceroute netcat tcpdump nmap libpcap hotplug mkxf86config vlock fbgrab ettercap wireshark bpalogin mingetty minicom bridge-utils rdate vconfig whois pan bittorrent dante tsocks airsnort ipw2100-firmware ipw2200-firmware zd1201-firmware apmd eject ethtool gradm memtester netplug smartmontools partimage grub lilo syslinux distcc hfsutils hfsplusutils synaptics gdm-themes-livecd gdm-themes gentoo-artwork-livecd speedtouch rp-pppoe tor privoxy virtual/jre

Some problems and fixes

Warning: Read this
  1. Catalyst uses /etc/portage or equivalent directory for your build. However, package.use doesn't work how you think it should in catalyst. It's a known bug, but one that won't likely be fixed for some time. Basically, if you use $target/use, then it will ignore package.use settings. You should only use package.use when deviating from the profile defaults for a package, not when setting your own USE.
  2. Don't add packages that need a kernel. You haven't emerged one yet! This will be done on the next stage.
  3. You can't unmerge things that were added as a requisite of this stage, but in the next stage you can.
  4. Use the unstable livecd-tools to fix the shutdown issue (April/2007)

The build

# catalyst -v -f livecd-stage1_example.spec

While it's compiling take a look at the documentation. By default it uses an experimental autoresume. However, after your build fails (it will usually for the first time), you might need to skip the autoresume. Say package1 needs package2 with flag A. If you emerged it without that flag, even if you now write the flag on the spec, when resuming it won't rebuild it. Then remove the auto and start again.

# catalyst -a -v -f livecd-stage1_example.spec

Here you will get more emerge errors, but since you read my requisites and the bug above, you will write new ebuilds and update the snapshot, which by default is $storedir/snapshot_cache/$snapshot_name. But careful, because it might be deleted, so keep an alternative portage dir where you'll save your changes.

Post bugs that might appear, like asking for the kernel without a need for it, etc.

Don't forget that by default, catalyst builds packages that it can use later on new/concurrent builds. If it's complaining of a bad build even though you reemerged it, remove the pkg.

Putting it shortly, right now this isn't going to be better explained. There are multiple ways to go around these errors, and we expect you to solve them. After this step however, if you keep your snapshot, use flags and binary packages unchanged, you can rebuild this stage over and over again easily using the binaries.

The final livecd-stage2

You $storedir/tmp folder should now be populated with the livecd-stage1 you just built, so let's write a new livecd-stage2.spec that will use this built stage to convert in our iso. We set that on our spec as the source_subpath, in this case default/livecd-stage1_example-2007.1. It's in the default folder cause we set rel_type as default, this is mostly useful for concurrent builds, but it has no meaning - it's just an identifier.

A lot of options should be the same as in the previous spec, and we add a few trivial ones as explained in the comments.

# nano livecd-stage2_example.spec
File: A few things to add now

version_stamp: 2007.1

profile: default-linux/x86/2006.1
snapshot: snapshot_example
# see below

#Choose the desired iso location
livecd/iso: /tmp/livecd_example.iso

#You can uncomment the option below, and choose a location of a file you wish to replace the default readme.

On livecd/type we don't recommend anything else, other options are gentoo-release-livecd, gentoo-release-minimal, etc, which as you can guess are used to build the release media. However it should be used only by the release team, as sometimes it alters the behaviour of Catalyst in an undocumented way. The game types are not being maintained while there remain legal issues about redistribution of binary video drivers.

The filesystem [optional]

Now your cd is going to have two "roots" sort of speak. One is the actual root of the cd, the one see when you open it in a file explorer. However, in it you'll usually find a image.squash file. It's the root that you actually see when you boot, compressed in a filesystem of the type squashfs. To see it, mount it with something like:

# mount image.squashfs /mnt/dir -t squashfs -o loop,ro

(assuming you have activated loop and squashfs in the kernel or as modules)

See? If you don't know what loops are, it wouldn't hurt to look. Catalyst lets you use different compression types for these files in the livecd/fstype option, see the examples for all. A couple of options may be given to this file system with livecd/fsops.

Besides, you may want to add files to the cd root and to the loop file. You can with livecd/overlay: and livecd/root_overlay: respectively. This can be very useful, since they are added after the emerging is done, and allow you to overwrite files in /etc for example. You must know that the files will be copied with their original attributes.

The kernels

Choose the kernels you would like and label them. And put the labels on the option below. We call ours "gentoo", so all we need is:

boot/kernel: gentoo

Now for each of those labels you need to specify several things. Which kernel package does it correspond? For "gentoo" we chose

boot/kernel/gentoo/sources: =sys-kernel/gentoo-sources-2.6.19-r5

It could've been just gentoo-sources to install the latest gentoo sources kernel, but we need to provide a corresponding .config in the next option, so it is better control the exact version. Take a sample .config from the official livecd configs for instance and place it below.


All those packages that required a kernel should be placed here:


You know how to use genkernel? Place options to it here:


Set emerge use flags for this kernel:

 boot/kernel/gentoo/use: pcmcia usb oss atm

The boot

We need to choose a bootloader, those available to you are in /usr/lib/catalyst/livecd/cdtar/, but for x86/amd64 the option we chose is preferable.

 livecd/cdtar: /usr/lib/catalyst/livecd/cdtar/isolinux-3.09-memtest86+-cdtar.tar.bz2

You can specify your own linuxrc in livecd/linuxrc.

Also read more about the boot process here. You should know that genkernel is the responsable for building your boot image, so any bugs or questions should be researched there first. The default linuxrc is the one that genkernel uses (genkernel/generic/linuxrc).

More customizing

[Optional] Please consult /usr/share/doc/catalyst-<version>/examples/livecd-stage2_template.spec for the syntax and meaning of other options like: livecd/users, livecd/volid, livecd/rm, livecd/empty, livecd/unmerge, livecd/gk_mainargs, livecd/linuxrc, livecd/xinitrc, livecd/rcadd, livecd/rcdel, livecd/xdm .


File: livecd_stage2_example.spec
version_stamp: 2007.1

profile: default-linux/x86/2006.1
snapshot: snapshot_example
# see below

#Choose the desired iso location
livecd/iso: /tmp/livecd_example.iso

#You can uncomment the option below, and choose a location of a file you wish to replace the default readme.

livecd/motd:"Welcome to our Example LiveCD"

#	xdm|default
#	mkxf86config|default

livecd/fstype: squashfs
livecd/cdtar: /usr/lib/catalyst/livecd/cdtar/isolinux-3.09-memtest86+-cdtar.tar.bz2
livecd/xdm: gdm
livecd/xsession: gnome
livecd/users: guest
livecd/volid: Gentoo Example Live CD

livecd/bootargs: dokeymap

livecd/gk_mainargs: --lvm2 --dmraid --evms2

boot/kernel: gentoo
boot/kernel/gentoo/sources: =sys-kernel/gentoo-sources-2.6.19-r5

boot/kernel/gentoo/config: /mnt/docs/catalyst/kconfig/livecd-2.6.19.config

boot/kernel/gentoo/use: pcmcia usb oss atm

#	media-gfx/splash-themes-livecd
#	net-dialup/fritzcapi
#	net-dialup/fcdsl
#	sys-power/acpid
#	net-wireless/at76c503a
#	net-wireless/rt2500
#	net-wireless/rtl8180
#	net-wireless/adm8211
# These three are removed for licensing reasons.
#	x11-drivers/nvidia-drivers
#	x11-drivers/ati-drivers


livecd/empty: /var/db /usr/lib/portage /usr/portage /var/tmp /var/cache /var/empty /var/lock /var/log /var/run /var/spool /var/state /tmp /usr/share/man /usr/share/info /usr/share/unimaps /usr/share/zoneinfo /usr/share/dict /usr/share/doc /usr/share/ss /usr/share/state /usr/lib/python2.2 /usr/lib/portage /usr/share/gettext /usr/share/i18n /usr/share/rfc /usr/lib/X11/config /usr/lib/X11/etc /usr/lib/X11/doc /usr/src /usr/share/doc /usr/share/man /root/.ccache /etc/cron.daily /etc/cron.hourly /etc/cron.monthly /etc/cron.weekly /etc/logrotate.d /etc/rsync /usr/lib/awk /usr/lib/nfs /usr/local /usr/diet/include /usr/diet/man /usr/share/consolefonts/partialfonts /usr/share/consoletrans /usr/share/emacs /usr/share/genkernel /etc/bootsplash/gentoo /etc/bootsplash/gentoo-highquality /etc/splash/gentoo /etc/splash/emergence /usr/share/lcms /usr/share/locale /etc/skel

livecd/rm: /etc/dispatch-conf.conf /etc/etc-update.conf /etc/issue* /etc/make.conf /etc/man.conf /etc/*.old /root/.viminfo /usr/sbin/bootsplash* /usr/sbin/fsck.cramfs /usr/sbin/fsck.minix /usr/sbin/mkfs.minix /usr/sbin/mkfs.bfs /usr/sbin/mkfs.cramfs /lib/security/ /etc/splash/livecd-2006.1/12* /etc/splash/livecd-2006.1/6* /etc/splash/livecd-2006.1/8* /etc/make.conf.example /etc/make.globals /etc/resolv.conf /var/log/*.log /usr/share/genkernel/pkg/x86/*.bz2 /etc/splash/livecd-2006.1/images/verbose-12* /etc/splash/livecd-2006.1/images/verbose-6*

Last step

 catalyst -v -f livecd_stage2_example.spec

Some problems and fixes

Further Reading

Concerns or Compliments? Please use the Discussion section.

Retrieved from ""

Last modified: Sat, 19 Jul 2008 11:15:00 +0000 Hits: 17,311