Install EVE-OS 6.3.0 to 13.3.0 over the Network with PXE

Updated

Introduction

With PXE, an edge device installs EVE-OS over the network instead of from a USB drive. This is useful for testing EVE-OS versions, where devices are reinstalled regularly, and for deploying EVE-OS to many edge devices.

This article describes how to set up a PXE server for EVE-OS 6.3.0 through 13.3.0 on 64-bit x86 (amd64) edge devices with UEFI. For EVE-OS 13.4.0 and greater, refer to Install EVE-OS 13.4.0 and Greater over the Network with PXE. EVE-OS versions before 6.3.0 do not support network installation.

Overview

The PXE server needs:

  • Three services: DHCP (Kea), TFTP (tftp-hpa), and HTTP (NGINX), running as Docker containers.
  • Seven files from the EVE-OS netboot archive, copied to the folders of the TFTP server and the web server.
  • One changed file: ipxe.efi.cfg, which contains the web server address and all installation settings.

The edge device requests the files in this order:

 Edge device
   │
   ├─ PXE    DHCP ──► IP address, next-server, boot file ipxe.efi
   │         TFTP ──► ipxe.efi
   │
   ├─ iPXE   DHCP ──► IP address, next-server, boot file ipxe.efi
   │         TFTP ──► ipxe.efi.cfg
   │         HTTP ──► kernel
   │         HTTP ──► initrd.img, installer.img, initrd.bits, rootfs.img
   ▼
 Installer runs

Important: All installation settings come from ipxe.efi.cfg. No GRUB and no installer.iso are involved.

Prerequisites

  • A PXE server host running Linux, with a static IP address on the imaging network. The containers use network_mode: host, which gives them direct access to the host network. DHCP and TFTP require this. Docker Desktop on macOS and Windows does not provide host networking in the same way, so it is not suitable for the PXE server.
  • Docker Engine 23.0 or greater on the PXE server host. That release and later include Docker Compose v2, which provides the docker compose command used in this article. The older docker-compose command with a hyphen is Compose v1 and is not supported.
  • Network access from the PXE server host to Docker Hub, to download the EVE-OS netboot archive and the container images.
  • The EVE-OS version to install, 6.3.0 through 13.3.0.
  • An edge device with 64-bit x86 (amd64) architecture and UEFI firmware, able to boot from the network or from a hard disk that you can write to.

Values Used in the Examples

All examples in this article use the following values. Replace them with the values of your network.

Value Example Used in
IP address of the PXE server 192.168.104.2 ipxe.efi.cfg, kea-dhcp4.conf
EVE-OS version 11.0.12-lts-kvm-amd64 Download command
Edge Infrastructure Services cluster zedcloud.zededa.net ipxe.efi.cfg
Installation disk sda ipxe.efi.cfg

Decisions Before the Setup

The decisions on boot order (testing or fleet deployment) and network (single network or staged) are the same as for EVE-OS 13.4.0 and greater. Refer to "Decisions Before the Setup" in Install EVE-OS 13.4.0 and Greater over the Network with PXE.

HTTP Setup

Services: Docker Compose with Kea, tftp-hpa, and NGINX

The directory structure, docker-compose.yml, custom.conf, and kea-dhcp4.conf are the same as for EVE-OS 13.4.0 and greater. Refer to "Services: Docker Compose with Kea, tftp-hpa, and NGINX" and "DHCP: Kea configuration" in Install EVE-OS 13.4.0 and Greater over the Network with PXE.

Files: netboot archive, placement, and changes

  1. Change to the artifacts folder, then download and extract the netboot archive.

    cd pxe/artifacts
docker run --rm lfedge/eve:11.0.12-lts-kvm-amd64 installer_net | tar -xf -

  2. Copy the files to the following folders.

     Archive content           Copy to
 ──────────────────────    ─────────────────────────────────────
 ./ipxe.efi.cfg       ───► ./tftp/tftpboot/ipxe.efi.cfg (adapted)
 ./ipxe.efi           ───► ./tftp/tftpboot/ipxe.efi
 ./kernel             ───► ./nginx/www/kernel
 ./initrd.img         ───► ./nginx/www/initrd.img
 ./initrd.bits        ───► ./nginx/www/initrd.bits
 ./installer.img      ───► ./nginx/www/installer.img
 ./rootfs.img         ───► ./nginx/www/rootfs.img

  3. In ./tftp/tftpboot/ipxe.efi.cfg, set the following lines. Leave all other lines unchanged, in particular the kernel line and the four initrd lines that follow it.

    set url http://192.168.104.2/
set console console=ttyS0 console=tty0
set eve_args eve_soft_serial=${mac:hexhyp} eve_reboot_after_install getty eve_install_server=zedcloud.zededa.net eve_install_disk=sda eve_persist_disk=sda
set installer_args root=/initrd.image find_boot=netboot overlaytmpfs fastboot

Note the following about these lines.

  • set url ships commented out as # set url https://foo.bar/. Add the line or uncomment it. The trailing slash is required, because iPXE appends each artifact name directly to this value.
  • set console ships with a longer list that covers more serial ports: console=ttyS0 console=ttyS1 console=ttyS2 console=ttyAMA0 console=ttyAMA1 console=tty0. Keep the console that your hardware uses. The example narrows the list to two.
  • getty starts a login shell on the consoles during installation, which is useful for diagnosing a failed install. It is part of the shipped default. Remove it only if you do not want console login during installation.

Start and install

  1. In the pxe folder, start the containers.

    docker compose up -d
docker compose ps
  2. Start the edge device.

Troubleshooting

Symptom Cause
The device never requests a boot file next-server or boot-file-name is missing from the Kea configuration, or the reservation does not match the device MAC address.
The boot stops after ipxe.efi.cfg loads The set url line is missing, still commented out, or has no trailing slash.
iPXE reports a not found error on kernel or one of the image files The files are not in the web root. Confirm all five artifacts are directly in ./nginx/www/, not in a subfolder.
The installer runs but the serial console shows nothing The set console value does not include the serial port your hardware uses.

For more diagnostics, refer to Troubleshoot EVE-OS Installation.

Onboarding

Onboarding is the same as for EVE-OS 13.4.0 and greater. Refer to "Onboarding" in Install EVE-OS 13.4.0 and Greater over the Network with PXE.

Related Articles

Was this article helpful?
0 out of 0 found this helpful