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/catalyst
This 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.git
user $
cd releng
root #
mkdir -p /var/tmp/catalyst/builds/default
Stage1
Prepare Seed
A seed stage3 is needed to build the LiveCD, this done by doing the following:
root #
cd /var/tmp/catalyst/builds/default
Select 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/catalyst
Portage snapshots are now handled in git and can be created and updated using:
root #
catalyst -s stable
The 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.spec
installcd-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.spec
installcd-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.spec
Stage2
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/config
to location that the releng github repo was downloaded to
installcd-stage2-minimal.spec
installcd-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.spec
ISO 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.