PXE server setup

Updated

Overview

This guide describes how to install and configure a preboot execution environment (PXE) server that you can use to deploy EVE-OS to a fleet of edge nodes.

Prerequisites

  • We recommend that you run your PXE server on a network dedicated to imaging.
  • Your PXE server's machine must be running Ubuntu 22.04 or later.

Setting up a PXE server for EVE-OS deployments

The following procedures are discrete, but if you haven't begun setting up your PXE server, complete them sequentially. Otherwise, skip to the procedure that you need.

After you start dnsmasq on your network in the last procedure, your PXE server will be ready.

Note that the following procedures use EVE-OS version 8.12.0 only as an example. Substitute your preferred version where necessary. Refer to the list of EVE-OS releases for options.

Install a web server

The following example is Apache, but you can use whatever web server you want.

sudo apt install -y apache2
sudo systemctl restart apache2

Download the EVE-OS source files

In this procedure, you'll download EVE-OS source files so that your PXE server will be able to deliver them without internet connectivity.

  1. Make a new directory for your EVE files. 
    sudo mkdir -p /var/www/html/eve
  2. Change the permissions of your directory to grant the owner read, write, and execute access, while the group and others have read and execute access only. 
    sudo chmod -R 755 /var/www/html/eve
  3. Install the iPXE artifacts for the version of EVE-OS specified in the EVE_VERSION variable. Make sure that the EVE-OS version is valid and that you have permissions to create a tar file.
    EVE_VERSION='13.4.0'
docker run --rm lfedge/eve:${EVE_VERSION} installer_net | sudo tar -C /var/www/html/eve -xf -
  4. The success response looks similar to the following output. Note that this particular example prompts for password because sudo was used for tar in the previous command.
    ...
Drive current: -outdev 'stdio:/tmp/disk.iso'
Media current: stdio file, overwriteable
Media status : is blank
Media summary: 0 sessions, 0 data blocks, 0 data, 31.2g free
Added to ISO image: directory '/'='/var/efiparts-33'
xorriso : UPDATE :      18 files added in 1 seconds
xorriso : UPDATE :      18 files added in 1 seconds
libisofs: NOTE : Cannot arrange content of data files in surely reproducible way
xorriso : UPDATE :  17.20% done
ISO image produced: 226285 sectors
Written to medium : 226285 sectors at LBA 0
Writing to 'stdio:/tmp/disk.iso' completed successfully.

./
./installer.iso
./ipxe.efi.cfg
./EFI/
./EFI/BOOT/
./EFI/BOOT/BOOTX64.EFI
./EFI/BOOT/grub.cfg

Password: YOUR_PWD

442+1 records in
442+1 records out
464476160 bytes (464 MB, 443 MiB) copied, 710.686 s, 654 kB/s
%

Set a static IP address for your PXE server

  1. Create a config file called 00-installer-config.yaml. Depending on your permissions, the file might be read-only. You might need to use sudo or change the file permissions.  
    sudo vi /etc/netplan/00-installer-config.yaml
  2. Paste the following code into your installer config file. 
    # This is the network config written by 'subiquity'
    network:
      ethernets:
        ens160:
          dhcp4: true
      ens192:
        addresses:
          - 192.168.1.10/24
        nameservers:
          addresses: [8.8.8.8, 8.8.4.4]
    version: 2
  3. Apply your new network configuration. 
    sudo netplan apply
  4. Run the following command. 
    ip addr sh
  5. Use the output of the previous command. Verify that your IP addresses are assigned to the correct interfaces and can ping each interface.

Configure your tftpboot directory structure

  1. Install the ipxe server software. 
    sudo apt install ipxe -y
  2. Create a tftp boot directory for your PXE and EVE files. 
    sudo mkdir -p /tftpboot
  3. Copy the tftpt boot files from the ipxe installation into your tftpboot directory. 
    sudo cp /usr/lib/ipxe/{undionly.kpxe,ipxe.efi} /tftpboot
  4. Update your iPXE boot script /var/www/html/eve/ipxe.efi.cfg to include the URL to your local http server. 
  5. # dhcp
#
# set url https://github.com/lf-edge/eve/releases/download/8.12.0/amd64.
# change to local
set url http://192.168.1.10/eve/

# rest unchanged
# Uncomment ntp lines for devices without RTC (RPI for example)
    # echo Getting the current time from ntp...
    # :retry_ntp
    # ntp pool.ntp.org || goto retry_ntp
    #
    # you may want to add the following to the kernel command line arguments:
    #   * eve_install_disk=XXX (e.g. XXX=mmcblk0)
    #   * eve_install_server=XXX (e.g. XXX=zedcloud.hummingbird.zededa.net)
    #   * eve_persist_disk=XXX (e.g. XXX=mmcblk0, you can set multiple values
    #     here with comma delimiter to use multiple disks).
    #
    # chain --autofree https://github.com/lf-edge/eve/releases/download/1.2.3/ipxe.efi.cfg
    # set url https://foo.bar/
    # set url https://github.com/lf-edge/eve/releases/download/8.12.0/amd64.

    set url tftp://192.168.1.10/eve/8.12.0/amd64.
    set console console=ttyS0 console=ttyS1 console=ttyS2 console=ttyAMA0 console=ttyAMA1 console=tty0
    set eve_args eve_soft_serial=${mac:hexhyp} eve_reboot_after_install
    set installer_args root=/initrd.image find_boot=netboot overlaytmpfs fastboot

    # a few vendor tweaks
    iseq ${smbios/manufacturer} Huawei && set console console=ttyAMA0,115200n8 ||
    iseq ${smbios/manufacturer} Huawei && set platform_tweaks pcie_aspm=off pci=pcie_bus_perf crashkernel=auto ||

    :start
    menu PXE Boot Options
    item eve-8.12.0-amd64 EVE 8.12.0 AMD64
    item shell iPXE shell
    item exit  Exit to BIOS
    choose --default eve-8.12.0-amd64 --timeout 10000 option && goto ${option}

    :eve-8.12.0-amd64
    kernel ${url}kernel ${eve_args} ${installer_args} ${console} ${platform_tweaks} initrd=amd64.initrd.img initrd=amd64.installer.img initrd=amd64.initrd.bits initrd=amd64.rootfs.img initrd=initrd.bits initrd=rootfs.img
    initrd ${url}initrd.img
    initrd ${url}installer.img
    initrd ${url}initrd.bits
    initrd ${url}rootfs.img

    boot

    :shell
    shell

    :exit
    exit

Configure dnsmasq for your network

  1. Install dnsmasq. 
    sudo apt install -y dnsmasq
  2. Create the dnsmasq configuration file. 
    sudo vi /etc/dnsmasq.conf
  3. Copy the following content into your configuration file. 
    # enable logs if required
#log-queries
#lo-dhcp

# disable DNS server
port=0

# listen on PXEBOOT
listen-address=192.168.1.10
interface=ens192

# enable built-in tftp server
enable-tftp
tftp-root=/tftpboot

# DHCP range 192.168.1.100 - 192.168.1.250
dhcp-range=192.168.1.100,192.168.1.250,255.255.255.0,24h

# Default gateway
dhcp-option=3,192.168.1.1

# Domain name - zededalab.net
dhcp-option=15,zededalab.net

# Broadcast address
dhcp-option=28,192.168.1.255

# Set interface MTU to 9000 bytes (jumbo frame)
# Enable only when your network supports it
# dhcp-option=26,9000

# Tag dhcp request from iPXE
dhcp-match=set:ipxe,175

# inspect the vendor class string and tag BIOS client
dhcp-vendorclass=BIOS,PXEClient:Arch:00000

# 1st boot file - Legacy BIOS client
dhcp-boot=tag:!ipxe,tag:BIOS,undionly.kpxe,192.168.1.10

# 1st boot file - EFI client
# at the moment all non-BIOS clients are considered

# EFI client
dhcp-boot=tag:!ipxe,tag:!BIOS,ipxe.efi,192.168.1.10

# 2nd boot file
dhcp-boot=tag:ipxe,https://192.168.1.10/eve/ipxe.efi.cfg
  4. Start dnsmasq. 
    sudo systemctl dnsmasq
Was this article helpful?
6 out of 8 found this helpful