Gentoo-iPXE

Example on Minimal Gentoo PXE boot with focus on using iPXE

Background

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=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 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

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

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

(cat gentoo.igz; (echo image.squashfs | cpio -H newc -o)) > combined.igz
- simplest and fastest boot, ~390M file
(cat gentoo.igz; (echo image.squashfs | cpio -H newc -o | xz --check=crc32 -vT0)) > combined.igz
- compress squashfs, ~360M file, black screen while kernel decompress these parts
(xz -d gentoo.igz -c; (echo image.squashfs | cpio -H newc -o)) | xz --check=crc32 -vT0 > combined.igz
- recompress everything, ~359M file, black screen while decompressing

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

NiKiZe / Gentoo-iPXE

readme