Example on Minimal Gentoo PXE boot with focus on using iPXE

iPXE booting Gentoo sample screen


This is to show and use how Gentoo can be booted over PXE since Gentoo bug #396467 was resolved in 24ad50

Quick start

Quick QEMU test: qemu-system-x86_64 -enable-kvm -M q35 -m 1024 -cpu host -nic user,model=virtio,tftp=.,bootfile= -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

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 root=/dev/ram0 init=/linuxrc dokeymap looptype=squashfs loop=/image.squashfs cdroot initrd=initrd.magic vga=791 - download gentoo kernel image, and append standard cmdline as seen in isolinux/grub, the initrd= is required for the kernel to find the init file in EFI mode boot * initrd combined.igz - downloads combined.igz into memory - you can give the full path over http or tftp if you want to. * boot - boot


Script to simplify testing: 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 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$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


BOOTP/DHCP service

Use one of these, not both


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

# Configure proxy mode and interface

# Enable PXE menu for non iPXE clients

# Send script to valid iPXE clients

Alternative client side CPIO combine

Above server side generated combined.igz has been used. It is also possible to do this client side. * initrd gentoo.igz * kernel gentoo {insert options} 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= is 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

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

 1.1KB 2021-12-10 08:12:35 LICENSE
 5.7KB 2021-12-10 08:12:35
 2.2KB 2021-12-10 08:12:35 altcombine.ipxe
 1.4KB 2021-12-10 08:15:26 boot.ipxe
  276B 2021-12-10 10:18:13 boot/grub/grub.cfg
 394MB 2022-01-06 13:25:20 combined.igz
  982B 2021-12-10 09:12:27 combined.ipxe
 4.1MB 2022-01-02 19:26:07 gentoo
 8.8MB 2022-01-02 19:33:48 gentoo.igz
 2.7KB 2022-01-06 13:22:34
 385MB 2022-01-02 19:35:33 image.squashfs
 436MB 2021-12-10 10:26:49 install-amd64-minimal-20211205T170532Z.iso
 434MB 2021-12-13 20:02:08 install-amd64-minimal-20211212T170613Z.iso
 436MB 2022-01-06 13:24:59 install-amd64-minimal-20220102T170545Z.iso
  403B 2021-12-10 08:08:51 pxelinux.cfg/default
 1.5KB 2021-12-10 08:08:51