Catalyst/Custom Media Image
This is a guide that will teach how to create to a custom Gentoo LiveCD based off the minimal ISO to be able to add custom programs to use as task like a rescuecd or just to the user's preferred applications to help with the install process. The basic principles will be shown here to give a user a clear understanding of how the process works to use in their own projects.
Build Environment Setup
Install dev-util/catalystmaking sure the iso useflag is set
root #emerge --ask dev-util/catalystThis build process will heavily rely on the Releng configs so begin by pulling the git repo
user $git clone -o upstream https://github.com/gentoo/releng.gituser $cd relengroot #mkdir -p /var/tmp/catalyst/builds/defaultStage1
Prepare Seed
A seed stage3 is needed to build the LiveCD, this done by doing the following:
root #cd /var/tmp/catalyst/builds/defaultSelect the best stage3 for the needs of the LiveCD (in this example stage3-amd64-openrc-tar.xz was used.) Stage3 tarballs can be found at https://www.gentoo.org/downloads/mirrors/.
root #wget <URL of file>Portage Snapshot
Return to the base Catalyst build directory
root #cd /var/tmp/catalystPortage snapshots are now handled in git and can be created and updated using:
root #catalyst -s stableThe Gentoo Portage snapshot name will be shown and will look similar to:
Stage1 Spec File
LiveCD spec files can be found on the Releng Github Mirror
Now edit the settings of the spec file to match the locations of the downloaded files earlier.
Parts of the spec file needing to be edited are:
version_stamp to build date
snapshot to portage squashfs name taken earlier
portage_confdir to location that the releng github repo was downloaded to
/var/tmp/catalyst/installcd-stage1.specinstallcd-stage1.specsubarch: amd64
version_stamp: 2023-05-07
target: livecd-stage1
rel_type: default
profile: default/linux/amd64/17.1/no-multilib
snapshot: stable
source_subpath: default/stage3-amd64-openrc-20230423T164653Z
compression_mode: pixz
portage_confdir: <location of releng>/releases/portage/isos
Next, change the program list to match the require custom applications needed, in this example app-misc/neofetch will be added to the ISO to show how it works, but here is also how you can apply global USEFLAG changes if required or via <location of releng>/releases/portage/iso/package.use for a per package flag.
/var/tmp/catalyst/installcd-stage1.specinstallcd-stage1.speclivecd/use:
alsa
compile-locales
fbcon
livecd
portaudio
socks5
unicode
xml
livecd/packages:
app-accessibility/brltty
app-accessibility/espeakup
app-admin/hddtemp
app-admin/pwgen
app-admin/syslog-ng
app-arch/unzip
app-crypt/gnupg
app-editors/mg
app-editors/nano
app-misc/livecd-tools
app-misc/screen
app-misc/tmux
app-portage/cpuid2cpuflags
app-portage/mirrorselect
app-text/wgetpaste
media-gfx/fbgrab
media-sound/alsa-utils
net-analyzer/traceroute
net-dialup/mingetty
net-dialup/pptpclient
net-dialup/rp-pppoe
net-fs/cifs-utils
net-fs/nfs-utils
net-irc/irssi
net-misc/dhcpcd
net-misc/iputils
net-misc/ndisc6
net-misc/ntp
net-misc/openssh
net-misc/rdate
net-misc/rsync
net-misc/vconfig
net-proxy/dante
net-proxy/tsocks
net-wireless/b43-fwcutter
net-wireless/iw
net-wireless/wireless-tools
net-wireless/wpa_supplicant
sys-apps/arch-chroot
sys-apps/busybox
sys-apps/dmidecode
sys-apps/ethtool
sys-apps/fxload
sys-apps/gptfdisk
sys-apps/hdparm
sys-apps/iproute2
sys-apps/memtester
sys-apps/memtest86+
sys-apps/netplug
sys-apps/nvme-cli
sys-apps/pciutils
sys-apps/pcmciautils
sys-apps/sdparm
sys-apps/usbutils
sys-auth/ssh-import-id
sys-block/parted
sys-block/partimage
sys-firmware/ipw2100-firmware
sys-firmware/ipw2200-firmware
sys-fs/bcache-tools
sys-fs/btrfs-progs
sys-fs/cryptsetup
sys-fs/dmraid
sys-fs/dosfstools
sys-fs/e2fsprogs
sys-fs/f2fs-tools
sys-fs/genfstab
sys-fs/jfsutils
sys-fs/lsscsi
sys-fs/lvm2
sys-fs/mac-fdisk
sys-fs/mdadm
sys-fs/multipath-tools
sys-fs/ntfs3g
sys-fs/reiserfsprogs
sys-fs/xfsprogs
sys-kernel/linux-firmware
#force rebuild for USE="(-multilib*)"
sys-libs/glibc
sys-libs/gpm
sys-power/acpid
www-client/links
#Custom programs
app-misc/neofetch
Build Stage1
Start the build process with:
root #catalyst -f installcd-stage1.specStage2
Stage2 Spec File
Next, use the stage2 spec to edit for custom needs.
Parts of the spec file needing to be edited are:
version_stamp to build date
snapsho to portage squashfs name taken earlier
portage_confdir and boot/kernel/gentoo/configto location that the releng github repo was downloaded to
installcd-stage2-minimal.specinstallcd-stage2-minimal.spec Examplesubarch: amd64
version_stamp: 2023-05-07
target: livecd-stage2
rel_type: default
profile: default/linux/amd64/17.1/no-multilib
snapshot: stable
source_subpath: default/livecd-stage1-amd64-2023-05-07
portage_confdir: <location of releng sources>/releases/portage/isos
livecd/bootargs: dokeymap
livecd/fstype: squashfs
livecd/iso: install-amd64-minimal-2023-05-07.iso
livecd/type: gentoo-release-minimal
livecd/volid: Gentoo amd64 2023-05-07
boot/kernel: gentoo
boot/kernel/gentoo/sources: gentoo-sources
boot/kernel/gentoo/config: <location of releng sources>/releases/kconfig/amd64/amd64-5.15.80.config
This will create a livecd using squashfs just like the official minimal ISO does but with the custom programs or useflags set by the user.
The remaining options in the spec file will remove unneeded packages and files for the ISO to work and can also be edited to the user's preference.
Build Stage2
Start the build process with:
root #catalyst -f installcd-stage2-minimal.specISO File
The ISO will be located in /var/tmp/catalyst/builds/default which can be written to a CD, USB or just tested directly in a VM.