From Gentoo Wiki
Jump to:navigation Jump to:search

This page is about using Gentoo as a PXE server to boot just about any operating system or bootable tool. Please extend it with your own experience. The primary focus is to boot live images and the page can get renamed once we have a better name for it.

TFTP server

Create TFTP root directory, this is where the chosen bootloader will be served from. Also make /tftproot owned by a user to not have to be root to do modifications

root #mkdir /tftproot
root #chown user:usergroup /tftproot

Then chose TFTP server, pick one of these:


One of the easiest TFTP servers to setup on Gentoo is net-ftp/atftp.

root #emerge --ask net-ftp/atftp

Add to default startup, and start service

root #rc-update add atftp default
root #/etc/init.d/atftp restart


Many have best experience with net-ftp/tftp-hpa.

root #emerge --ask net-ftp/tftp-hpa

To run it temporarily, use the following command line.

root #in.tftpd -L --secure /tftproot


The article about Diskless nodes contains plenty of useful information on how to setup a PXE environment.


For client configuration, see for example: Setup PXE boot with EFI Using Grub2 from openSUSE kiwi

You probably already have sys-boot/grub installed verify that it was installed with GRUB_PLATFORMS efi-32, efi-64, pc

Next "install" needed grub files to /tftproot

user $grub-mknetdir --net-directory /tftproot
Netboot directory for i386-pc created. Configure your DHCP server to point to /tftproot/boot/grub/i386-pc/core.0
Netboot directory for i386-efi created. Configure your DHCP server to point to /tftproot/boot/grub/i386-efi/core.efi
Netboot directory for x86_64-efi created. Configure your DHCP server to point to /tftproot/boot/grub/x86_64-efi/core.efi


There is a few different options to get the iPXE bootloaders

The quickest way:

CODE Grabbing prebuilt binaries
cd /tftproot
for i in ipxe.efi snponly.efi undionly.kpxe ipxe.pxe; do wget -nc http://boot.ipxe.org/$i; done

But building from source (highly recommended from iPXE folks) is not hard, and allows for easy modifications.

Verify that some needed dependencies is installed:

root #emerge --ask --oneshot dev-vcs/git
CODE lets get going
git clone git://git.ipxe.org/ipxe.git
cd ipxe/src

# pcbios files
make -j8 bin/undionly.kpxe bin/ipxe.pxe
cp bin/undionly.kpxe bin/ipxe.pxe /tftproot/

# x86_64 efi files
make -j8 bin-x86_64-efi/snponly.efi bin-x86_64-efi/ipxe.efi
cp bin-x86_64-efi/snponly.efi bin-x86_64-efi/ipxe.efi /tftproot/

# x86_32 efi files
make -j8 bin-i386-efi/snponly.efi bin-i386-efi/ipxe.efi
cp bin-i386-efi/snponly.efi /tftproot/snponlyx32.efi
cp bin-i386-efi/ipxe.efi /tftproot/ipxex32.efi

Package sys-firmware/ipxe can be used, but needs USE flags such as efi, undi and still does not give all files we want.


Exists as sys-boot/syslinux in portage and can be installed with

root #emerge --ask sys-boot/syslinux

And copy over needed files to our /tftproot this is only basic files for pcbios kernel boot, other files might be needed for other platforms

user $cp /usr/share/syslinux/pxelinux.0 /tftproot
user $cp /usr/share/syslinux/ldlinux.c32 /tftproot

DHCP server

Bootable images

Gentoo installation

See Installation Alternatives - Diskless install using PXE for a guide on Gentoo.

Some projects exists to help setup such environment

Fedora installation

The following script creates a TFTP directory tree, downloads kernel and initrd images from a Fedora mirror and configures a netbootable instance of GRUB.

FILE ~/bin/fedora-pxe-install
#!/bin/bash -xe

# Mirror URL
# Releases
[ $# -eq 0 ] && releases="22 21/Server 21-Alpha/Workstation 20/Fedora" || releases="$*"
# Architecture: x86 | x86_64 | ...
architectures="x86_64 i386"
# TFTP directory path

test -n "$prefix"

menuentry() { cat << EOF
menuentry "Install Fedora $release $arch ($state)" {
    linux /boot/$kernel repo=$repo
    initrd /boot/$initrd

check() {

    curl --silent --fail --head "$repo/" >/dev/null

download() {
    test -e "$1" && { echo "Skipping: $1" >&2; return 0; }
    echo "Downloading: $1 from $2" >&2
    curl --silent --fail --output "$1" "$2"

grub2-mknetdir --net-directory "$prefix"
for release in $releases; do
    for arch in $architectures; do
        check releases || check development || check releases/test || { echo "# Check failed for $release $arch"; break; }

        kernel="fedora-$(echo "$release" | tr / -)-$arch-kernel"
        initrd="fedora-$(echo "$release" | tr / -)-$arch-initrd"

        download "$prefix/boot/$kernel" "$pxerepo/vmlinuz" || { echo "# Couldn't download kernel for $release $arch"; break; }
        download "$prefix/boot/$initrd" "$pxerepo/initrd.img" || { echo "# Couldn't download initrd for $release $arch"; break; }
done | tee "$prefix/boot/grub/grub.cfg"

Adjust it to your needs and then run it without parameters.

root #fedora-pxe-install

Now you just need to configure TFTP and DHCP so that /tftproot is available to the netbooted machine and it that it requests /boot/grub/i386-pc/core.0 via TFTP.

Ubuntu installation

To install Ubuntu to a device via PXE, simply download an Ubuntu netboot image for the appropriate architecture. Note that most of the files in the release and architecture-specific directory are unnecessary, you simply need netboot.tar.gz (about 40MB).

Extract that file to an appropriate TFTP-served directory and configure your DHCP server with the filename directive to point at pxelinux.0 for the machine or subnet in question.

Note that you will also need to give the host(s) internet access as the netboot images are configured to pull packages down from the internet.