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

​

Introduction

​

Overview

• 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.

 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

​

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

​

Decisions Before the Setup

​

HTTP Setup

​

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

​

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

• 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

​

Onboarding

​

Next Steps