Build a custom EVE-OS image

Introduction

This article describes how to build a custom EVE-OS (Edge Virtualization Engine) image before you flash it to an edge device. Most commonly you do this to point the device at a specific Edge Infrastructure Services instance, and optionally to bake in network settings (static IP, VLAN, and WiFi) or boot parameters.

There are two ways to produce a custom image:

• Method A: Build with Docker (recommended). You place your customization files in a local folder that is injected into the image at build time.
• Method B: Download and edit a prebuilt image. You download an official image and edit its configuration partition directly.

Throughout this article, replace zedcloud.example.zededa.net with the hostname of the Edge Infrastructure Services instance you want your devices to use.

Note: Every step in this article runs on your own computer (macOS, Linux, or Windows). You are preparing an image file, you do not connect to the edge device or log in to EVE-OS to customize an image. Paths like $HOME, ~/eve-overrides, and /Volumes/EVE are all on your computer, and /Volumes/EVE is a macOS mount point for the image file (see Method B), not a location on the device.

The EVE-OS Config Partition

Both methods customize the same thing: the EVE-OS config partition, which holds the files that tell the device which controller to use and how to configure its network and boot. Its layout is:

(config partition)
├── DevicePortConfig/
│   └── override.json.template
├── grub.cfg
├── grub.cfg.tmpl
├── onboard.cert.pem
├── onboard.key.pem
├── origin.2026-04-14.16.12.0
├── root-certificate.pem
├── server
└── v2tlsbaseroot-certificates.pem

• In Method B, you see these files under /Volumes/EVE after mounting the image on macOS.
• In Method A, you do not touch this partition directly. Instead, you place only the files you want to override in a local folder, and the build injects them into the image.

Prerequisites

• Docker installed and running (required for Method A).
• A Docker Hub image tag for the EVE-OS version you want. Browse tags on Docker Hub or the EVE-OS Releases page. Use a specific LTS tag. Do not use latest (it is not reproducible). Tags follow one of these forms:
  • <version>-<hypervisor>-<arch>, for example 16.0.1-lts-kvm-amd64.
  • <version>-<platform>-<hypervisor>-<arch>, for example 14.5.1-lts-nvidia-jp6-kvm-arm64.
  • where <hypervisor> is kvm (standard) or k (EVE-k), and <arch> is amd64 or arm64.
• Your device's hardware serial number, which you'll need when you onboard the device.
• Installation media (a USB drive is the simplest option).
• For a Raspberry Pi (ARM): a Raspberry Pi 4 or 5 Model B with at least 4 GB RAM, and a microSD card (16 GB or larger recommended).

Method A: Build with Docker

The build mounts your customization files from a local folder into the container at /in and injects them into the image. Run all of these commands on your own computer.

Create an Overrides Folder

On your computer, create the folder that will hold your customization files:

cd $HOME
mkdir eve-overrides

At minimum this holds your server file. It can also hold DevicePortConfig/override.json (network config) and grub.cfg (boot parameters):

eve-overrides/
├── DevicePortConfig/
│   └── override.json      <- optional: static network configuration
├── grub.cfg               <- optional: boot / kernel parameters
└── server                 <- Edge Infrastructure Services hostname

Set the Edge Infrastructure Services Endpoint

Write your Edge Infrastructure Services hostname (optionally hostname:port) into a file named server:

echo "zedcloud.example.zededa.net" > $HOME/eve-overrides/server

Build the Image

Choose the command that matches how you'll boot the device. Replace the tag with your version and architecture.

Installer image (raw disk, the usual choice for USB install):

docker run -v $HOME/eve-overrides:/in --rm lfedge/eve:<version>-kvm-amd64 installer_raw > installer.raw

Installer image (ISO, only if the BIOS/BMC cannot boot a raw disk image, for example HPE iLO / Dell iDRAC virtual media):

docker run -v $HOME/eve-overrides:/in --rm lfedge/eve:<version>-kvm-amd64 installer_iso > installer.iso

Live image (boots without installing to onboard storage, common for ARM / Raspberry Pi):

docker run -v $HOME/eve-overrides:/in --rm lfedge/eve:<version>-kvm-arm64 live > live.img

Windows: Do not use PowerShell's > redirect (it corrupts the binary image). Run the build under WSL, or add an output mount (-v <local-dir>:/out) and let the container write the file there.

Capture the Soft Serial (Live Images)

When you build a live image, the command prints a soft serial number (a UUID), for example:

681cc64f-6633-49f3-988c-b0afde4a25fc

Save it. You'll enter it in the Serial Number field when you onboard the device to Edge Infrastructure Services. (For installer images, the soft serial is generated during installation and written to the installer media's INVENTORY partition instead.)

Method B: Download and Edit a Prebuilt Image

If you prefer not to build with Docker, download an official image and edit its configuration partition directly. These steps also run on your own computer.

1. Download a prebuilt .raw (or .iso) image from the EVE-OS Releases page.
2. On macOS, mount the raw image:

hdiutil attach -imagekey diskimage-class=CRawDiskImage <version>-<arch>.raw

3. This mounts two volumes on your computer:

4. Edit the files under /Volumes/EVE. The key files are:

5. Do not modify or delete these other files on the partition: onboard.cert.pem, onboard.key.pem, root-certificate.pem, v2tlsbaseroot-certificates.pem. They are the device's identity/trust material. 
6. Eject the volume when done:

hdiutil detach /dev/diskX
# If the volume is busy:
hdiutil detach /dev/diskX -force

7. Replace diskX with the identifier assigned at mount time (for example disk4). Run diskutil list to confirm.

Advanced: Static IP, VLAN, and WiFi (override.json)

When to use this: Baking network settings into a generic image with override.json is an advanced (legacy) mechanism. If you need static IP addressing or an enterprise proxy, the recommended path is a single-use EVE-OS installer that carries a bootstrap configuration for the device. Use override.json only when you specifically need to embed network config into a generic image.

Static network settings live in DevicePortConfig/override.json. Rename the included override.json.template to override.json before editing. The authoritative field reference is the EVE-OS source: zedroutertypes.go (see Reference Links).

Example: Static IP on a VLAN, Plus WiFi Management

{
  "TimePriority": "2000-01-01T00:00:00Z",
  "Version": 1,
  "Ports": [
    {
      "IfName": "eth0",
      "IsMgmt": false,
      "IsL3Port": false
    },
    {
      "Dhcp": 1,
      "IfName": "eth0.250",
      "IsMgmt": true,
      "IsL3Port": true,
      "Type": 4,
      "AddrSubnet": "192.168.0.100/24",
      "Gateway": "192.168.0.1",
      "DnsServers": ["1.1.1.1"],
      "L2Type": 1,
      "VLAN": { "ParentPort": "eth0", "ID": 250 }
    },
    {
      "Dhcp": 4,
      "IfName": "wlan0",
      "Name": "Management2",
      "IsMgmt": true,
      "IsL3Port": true,
      "Type": 4,
      "WirelessCfg": {
        "WType": 2,
        "Wifi": [
          { "KeyScheme": 1, "Password": "<wpa-psk-hex>", "SSID": "WIFI-SSID" }
        ]
      }
    }
  ]
}

Field values used in the preceding example (verified against the EVE-OS source):

WiFi Password Format

The WiFi Password must be the pre-hashed PSK, not the plaintext passphrase. Generate it with wpa_passphrase (which computes the PBKDF2-HMAC-SHA1 hash from the passphrase and SSID):

wpa_passphrase "WIFI-SSID" "your-plaintext-password"

Copy the 64-character hex value from the psk= line into the Password field.

Note: Put the wpa_passphrase hex PSK in Password as-is. Do not base64-encode it. (Base64 encoding applies only to the separate fully-encrypted credentials mechanism, which is configured through Edge Infrastructure Services, not by hand-editing override.json.)

Next Steps

Your custom image is ready.

1. Flash an EVE-OS installer or live image to a portable storage device.
2. Install EVE-OS onto an Edge Device.
3. Onboard the device to Edge Infrastructure Services, entering the serial number when prompted.

Reference Links

• EVE-OS Networking docs: https://github.com/lf-edge/eve/blob/master/docs/NETWORKING.md
• DevicePortConfig source of truth: https://github.com/lf-edge/eve/blob/master/pkg/pillar/types/zedroutertypes.go
• EVE-OS example config files: https://github.com/lf-edge/eve/tree/master/conf