Gentoo-iPXE

Example on Minimal Gentoo PXE boot with focus on using iPXE

iPXE booting Gentoo sample screen

Background

This is to show and use how Gentoo can be booted over PXE since Gentoo bug #396467 was resolved in 24ad50 . Unfortunatly there was later a move to Dracut, and some things changed, See #11

Quick start

Quick QEMU test: qemu-system-x86_64 -enable-kvm -M q35 -m 1024 -cpu host -nic user,model=virtio,tftp=.,bootfile=http://gentoo.ipxe.se/boot.ipxe -boot menu=on -usb This uses iPXE, manual steps: * Get into the iPXE shell (from PXE boot or even from one of the disk images) * Get ip dhcp * Start Gentoo chain http://gentoo.ipxe.se/boot.ipxe

Explanation of ipxe script

If a file is referred to in a iPXE script, and not given as absolute path it tries to load from the "last path" * kernel gentoo dokeymap looptype=squashfs loop=/image.squashfs cdroot - download gentoo kernel image, and append standard cmdline as seen in isolinux/grub, (initrd= was required in older iPXE/kernels for EFI) * initrd gentoo.igz - base initrd into memory - you can give the full path over http or tftp if you want to. * initrd image.squashfs /image.squashfs - append squashfs into initrd * boot - boot

Testing

Script to simplify testing: test_w_qemu.sh useonline See Issue #4 for more work on EFI

Having Gentoo mirrors host the needed files

Working on this, See Gentoo bug #494300 and issue #2. There is also forum post

Create your own mirror

Grab or create boot.ipxe script with the minimal configuration. Use gentoocd_unpack.sh to download latest iso and unpack needed files. If you want to extract them yourself then it ise these files you need * /boot/gentoo * /boot/gentoo.igz * /image.squashfs And finaly create the combined initrd using (cat boot/gentoo.igz; (echo image.squashfs | cpio -H newc -o)) > combined.igz

Setting up your own server

Needed services are BOOTP/DHCP and TFTP. Refer to these services individually. You might also want to have a HTTP server for better performance. "PXE server" might refer to the one machine that serves both of these services.

TFTP service

Install a simple to use tftp server

# install atftp
emerge -uv1 net-ftp/atftp
# ensure we have tftp root directory
mkdir -p /tftproot
# add it to startup
rc-update add atftp default
# make sure it is running
/etc/init.d/atftp restart

# move to tftp root directory
pushd /tftproot
# Prepare iPXE files
for i in ipxe.efi snponly.efi undionly.kpxe ipxe.pxe; do wget -nc http://boot.ipxe.org/$i; done

# Optional Prepare Grub
grub-mknetdir --net-directory .

# Optional Prepare pxelinux
emerge -uv1 syslinux
cp /usr/share/syslinux/pxelinux.0 .
cp /usr/share/syslinux/ldlinux.c32 .

# TODO copy over configs for grub/pxelinux

popd

BOOTP/DHCP service

Use one of these, not both

isc-dhcpd

This configuration as a great start for iPXE, official documentation can also be helpful. If you are in control of your DHCP server, then this is the best option.

dnsmasq Proxy DHCP mode

If you can not replace your DHCP server then you can instead run Proxy DHCP. Full configuration for dnsmasq in proxydhcp mode

# Disable DNS server
port=0

# Configure proxy mode and interface
dhcp-range=${interface_subnet},proxy
interface=${interface_name}

# Enable PXE menu for non iPXE clients
dhcp-match=set:ipxe-ok,175,19
pxe-service=tag:!ipxe-ok,X86PC,PXE,undionly.kpxe,${tftp_server_ip}
pxe-service=tag:!ipxe-ok,BC_EFI,PXE,snponly.efi,${tftp_server_ip}
pxe-service=tag:!ipxe-ok,X86-64_EFI,PXE,snponly.efi,${tftp_server_ip}

# Send script to valid iPXE clients
dhcp-boot=tag:ipxe-ok,http://gentoo.ipxe.se/boot.ipxe,,0.0.0.1

Client side CPIO combine

Older iPXE, especially in EFI mode, could not do this, but that is old now, so this is the default. * initrd gentoo.igz * kernel gentoo {insert options} - (older version of iPXE and/or kernel required initrd=initrd.magic * initrd image.squashfs /image.squashfs Last initrd Appends squashfs with CPIO header to the ram data, the second argument tells which name to use in CPIO archive

As mentioned initrd= was required in EFI mode, initrd.magic is a special file in iPXE EFI since e5f025 that combines all initrd files into one CPIO archive, pcbios has done the same concatination for a long time.

Different types of combine - for historys sake

TODO investigate memory usage, what is the best way for the kernel in terms of free memory?

 1.1KB 2021-08-28 00:31:33 LICENSE
 5.8KB 2026-08-13 12:34:08 README.md
 1.5KB 2026-08-13 12:34:08 boot.ipxe
  245B 2026-08-13 12:34:08 boot/grub/grub.cfg
 489MB 2026-08-13 12:59:55 combined.igz
 5.2MB 2024-08-18 20:01:18 gentoo
 9.1MB 2024-08-18 20:06:01 gentoo.igz
 2.0KB 2026-08-13 12:34:08 gentoocd_unpack.sh
 1.9KB 2026-08-13 12:34:08 get_minimal_cd.sh
 480MB 2024-08-18 20:07:42 image.squashfs
 432MB 2021-08-08 19:56:46 install-amd64-minimal-20210808T170546Z.iso
 432MB 2021-08-15 19:47:00 install-amd64-minimal-20210815T170549Z.iso
 432MB 2021-08-22 19:49:45 install-amd64-minimal-20210822T170550Z.iso
 432MB 2021-08-29 19:48:17 install-amd64-minimal-20210829T170531Z.iso
 436MB 2021-11-30 13:20:42 install-amd64-minimal-20211128T170532Z.iso
 436MB 2021-12-10 18:12:13 install-amd64-minimal-20211205T170532Z.iso
 436MB 2022-01-06 13:18:19 install-amd64-minimal-20220102T170545Z.iso
 527MB 2026-08-10 22:50:54 install-amd64-minimal-20240818T143401Z.iso
  341B 2026-08-13 12:34:08 pxelinux.cfg/default
 2.2KB 2026-08-13 12:34:08 test_w_qemu.sh